怎样让LLM看懂你的接口？

为什么要关注接口设计？

如果你正在开发一个能调用外部服务的 LLM 应用，你肯定期望 LLM 能准确调用正确的接口。要达到这个目标，前提是 LLM 理解你设计的接口，否则，再好的创意也是徒劳，没有用户能够忍受一个行为不符合期望的产品。因此，好的接口设计是首要任务。

那么，如何设计出能让 LLM 看懂的接口呢？诀窍在于：把 LLM 当小学生看待，确保你的接口定义清晰、简单。 在这里，我将介绍 SMART 原则。这些原则专为开发类 GPTs 平台的 Actions（或插件）而设计，当然，也适用于直接的 LLM Function Calling。

SMART原则

Simple Inputs

保持输入参数简单明了，对于 LLM 理解和处理命令至关重要。复杂的输入可能会让模型产生误解，导致错误或不完整的参数构造。比如，创建日历事件的接口，可以有两种类型：全天事件和特定时间段的事件。如果用一个接口处理这两种类型，输入参数可能会是这样的：

{
"title": "Meeting", // event title, required
"description": "Discuss project roadmap",// event description, not required, default null
"is_full_day": false,// set true if user doesn't offer absolute time range
"start_time": "2023-08-15 13:00",// required if is_full_day is false
"end_time": "2023-08-15 14:00",// required if is_full_day is false
"start_date": "2023-08-15",// required if is_full_day is true
"end_date": "2023-08-15"  // required if is_full_day is true, same as start_date if only one day
}

这个接口的参数需要根据两种情况分别选择不同的字段组合，这无疑增加了理解难度。实践表明，即使是 GPT-4 模型，也会在构造这个接口的参数时犯错。

但是，如果我们将接口拆分成两个，每个处理一种特定类型的事件，输入就变得简单多了，更容易让 LLM 理解：

对于特定时间段的事件：

{
"title": "Meeting",// event title, required
"description": "Discuss project roadmap", // event description, not required, default null
"start_time": "2023-08-15 13:00", // start time of the event, in format 2006-01-02 15:04
"end_time": "2023-08-15 14:00"// end time of the event, in format 2006-01-02 15:04
}

对于全天事件：

{
"title": "Holiday", // event title, required
"description": "National holiday",// event description, not required, default null
"start_date": "2023-08-15", // start date of the event, in format 2006-01-02
"end_date": "2023-08-15"// end date of the event, in format 2006-01-02, same as start_date if only one day
}

你可能觉得这种分拆的方法有点反常识，没错，确实如此。这就是与 LLM 打交道的奇妙之处：你需要跳出已有的思维定势。通过这种方式，可以简化输入的内在逻辑，使得 LLM 更轻松、更准确地理解并应用。

Meaningful Strings

使用意义明确的字符串，不要使用数字枚举！这很重要！数字枚举需要额外的上下文映射，这会让 LLM 的理解过程变得复杂。而意义明确的字符串是自解释的。记住，对于 LLM 来说，越简单，行为就越可预测。

比如，对于事件的分类标签，如果使用数字枚举，可能会是这样的：

{
"label": 1
}

这种情况下，LLM 需要额外的上下文来理解“1”代表“工作”。这增加了复杂性和误解的可能性。而使用有意义的字符串，可以让数据立刻变得清晰：

{
"label": "work"
}

对于真人的前端工程师来说，数字枚举当然不是问题，但对 LLM 来说，有意义的字符串可以显著提高稳定性和性能。

另外有一个 trick：返回运行时信息，比如服务器时间和用户时区。通过这种方式注入必要的实时信息，可以帮助 LLM 提供更合理的响应。尤其是在 GPTs 等平台上，这些平台不会自动在对话上下文中包含这些信息。例如：

{
"server_time": "2024-06-27 11:20",
"user_timezone": "Asia/Shanghai"
}

Avoid Headers

在 GPTs 平台上，避免使用 Headers 传递参数（Authorization 除外）。因为 GPTs 平台不允许使用除 Authorization 外的任何 Header 参数，并且你不能直接在 OpenAPI 格式的接口描述里设置 Header 参数，而是必须使用标准的 securitySchemes 来配置授权。具体如下：

在paths中：

security:
- BearerAuth: []

在components中：

securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT

在其他平台（如 Coze）上，你可能能够直接指定 Header 参数。但我仍然建议不要过度使用 Headers，以保持与 GPTs 平台的一致性并减少复杂性。通过将参数保留在请求体或查询字符串中，可以使接口更简单透明，更易于 LLM 处理，减少误解的风险，确保更可靠和准确的响应。

Responsibility

尽可能让每个接口遵循单一职责原则（SRP），这意味着每个接口应该专注于单一的特定任务。这不仅有助于 LLM 正确判断该选用哪个接口，同时也简化了接口调试和维护。

例如，对于用户管理接口，与其使用一个 endpoint 处理多个操作（如创建、更新和删除用户），不如为每个操作使用单独的 endpoint：

• 创建用户：

POST /api/users
{
"name": "John Doe",
"email": "john.doe@example.com"
}

• 更新用户：

PUT /api/users/123
{
"email": "new.email@example.com"
}

• 删除用户：

DELETE /api/users/123

Transparent Descriptions

清晰的描述可以提高 LLM 准确理解和调用接口的概率。每个接口的用途及其入参和出参的含义都应该用准确的语言描述，避免使用自定义的技术术语或模棱两可的词语。另外，对于国外的模型以及国内的大多数模型，请使用英文描述，效果会更好。

例如，一个表示事件跨越天数的参数，不明确的描述可能会是这样的：

• 不明确的描述： Number of days the event spans.

这种描述不能说它是错的，但对于这个稍微复杂的概念，LLM 往往不能正确地理解它。这时，你需要更详细的说明，帮助 LLM 理解，例如：

• 更详细的描述：

cross_days:
minimum: 0
type: integer
description: |-
Number of days the event spans overnight. Use this parameter for events that span multiple days.
For example, if the event starts at 11 PM and ends at 6 AM the next day, set this to 1.
Note: This value should be one less than the total number of days for events that span multiple days.
For example, if an event spans from July 1st to July 3rd (3 days), set this value to 2.

清晰详细的描述有助于 LLM 理解每个参数的确切用途和使用方法。但也并非越详细越好，注释文本会占用上下文的 token 数，所以需要在这里找到平衡。

构建GPTs Actions的工程方法

要有效地为 GPTs 构建 Actions，一个系统化的工程方法是必不可少的。下面以 Calendar EVA Now 为例，介绍构建 GPTs Actions 的步骤。Calendar EVA Now 是一个 AI 助理，可以通过自然对话帮用户管理日程，比如查日程、安排单次或重复事件、调整日程等。

步骤1：准备测试集

第一步是创建一个覆盖常见用户指令的测试集，测试 GPT 模型对不同输入的理解和处理能力。

实际上，调教 LLM 通常不会一蹴而就。有时，为了让某条指令正常工作，我们可能需要修改接口描述或者指令，但这会不会影响到其他已调通的指令呢？当模型版本发生变化甚至更换模型时，我们同样需要进行回归测试。

以下是 Calendar EVA Now 的一个示例测试集：

步骤2：设计和测试接口定义

按照 SMART 原则设计接口定义，并生成符合 OpenAPI 3.0 规范的 YAML 文档。

但是先别着急实现接口，因为你不会愿意推翻接口重写。相反，你应该先在 GPTs 平台上根据测试集测试你设计的接口，检查模型是否选择了正确的接口，是否构建了正确的参数。

步骤3：实现接口

一旦你有了一个定义良好且经过测试的接口，就可以着手实现它了。这一步包括编写后端代码来处理API请求。

步骤4：部署测试环境和生产环境

显然，你需要一个测试环境。毕竟，当你开发新功能或修改 bug 时，需要先验证它确实可行，然后才部署到生产环境，否则可能会影响用户体验。

通过遵循这些步骤，你可以为 GPTs 构建可靠的 Actions，提升应用的整体用户体验和功能。

后话

从我的实践来看，国外的gpt-4/gpt-4o是几乎完美通过所有测试项的。

而至于国内，我在扣子(coze.cn)上测试了一轮它支持的几个国内模型，只有Baichuan4勉强可以通过大部分的测试项，只能说看到了希望，仍任重而道远。当然，这里仅限于不利用Finetune手段的情况，至于Finetune能带来多少正收益以及产生多少负影响，以后有机会尝试了再给朋友们分享。

就我而言，我体验过各种日程管理工具，但无一例外，每次要临时修改安排时，一想到必须在工具上点点点的操作，总是让我感到无比抗拒。我不想为了省时间做日程管理，却浪费时间在修改日程上。有人说，我其实需要的是雇佣一个小助理 ?。

Anyway，于是我开发了上面作为例子的 EVA Now。访问 https://evanow.chat 可以亲自体验一下 Calendar EVA Now。主页包含 GPTs 和 Coze 体验入口，来感受一下用自然对话管理日程是否适合你吧～