2024 LLM接口设计指南：5个技巧让AI秒懂你的API

接口设计虽是后端工程师的常规任务，但在LLM应用开发中，它直接决定智能体的响应质量。许多开发者过度关注Prompt调优和模型选型，却忽略接口本身——你提供给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
}

问题在于参数之间存在“条件依赖”——到底传哪些字段取决于is_full_day的值。实测中，即使是GPT-4，构造这类参数时也容易出错。

解决方式很简单：拆成两个接口，各负责一种场景。对于特定时间段事件，参数一目了然：

{
"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
}

这种拆分方式可能看似“反常识”——传统API设计往往推崇“一个接口处理多种情况”以保持优雅。但与LLM打交道，必须跳出惯性思维。简化输入逻辑，换来的是LLM更轻松、更准确的识别和理解。

Meaningful Strings

这一原则尤其关键：使用语义明确的字符串，避开数字枚举。数字枚举需要额外的上下文映射，而LLM最怕的就是“自己猜语义”。

例如，为事件打标签时，若写成数字枚举：

{
"label": 1
}

模型需要额外知道“1”代表“工作”，多了一层理解成本。若换成有意义的字符串：

{
"label": "work"
}

自解释性直接拉满。对人类前端工程师而言，数字枚举不是问题；但对LLM而言，清晰的字符串能显著提升稳定性和性能。

另外分享一个实用技巧：在返回结果中注入运行时信息，比如服务器时间和用户时区。这些动态信息在很多平台（如GPTs）上不会自动出现在对话上下文中，需要你主动提供。例如：

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

有了这些信息，LLM在涉及时间计算的场景中表现会好很多。

A void Headers

在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同时处理创建、更新和删除，不如拆成单独的接口：

• 创建用户：

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

• 更新用户：

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

• 删除用户：

DELETE /api/users/123

每个接口的意图清晰，LLM选错的概率自然大大降低。

Transparent Descriptions

清晰的描述是LLM准确理解的最后一道保障。每个接口的用途、每个参数的含义，都应用准确的语言写清楚，尽量避免自定义术语或模棱两可的表述。另外，对于国外的模型以及国内的大多数模型，使用英文描述效果会更好。

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

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

说它错倒也不算，但这种模糊的描述往往会被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.

不过也要注意，描述并非越详细越好——注释文本会占用上下文token，需要在清晰度和Token成本之间找到平衡点。

构建GPTs Actions的工程方法

理论讲完，来点实际的。要有效地为GPTs构建Actions，一个系统化的工程方法必不可少。下面以Calendar EVA Now为例，分享具体的构建步骤。这款AI助理可以帮助用户通过自然对话管理日程，包括查日程、安排事件、调整日程等。

步骤1：准备测试集

动手之前，先创建一个覆盖常见用户指令的测试集。这件事比想象中更重要——因为调教LLM通常不会一蹴而就。有时为了修通某条指令，可能会修改接口描述或Prompt，但这些改动会不会影响其他已调通的指令？当模型版本更新甚至换模型时，回归测试又该怎么做？

以下是Calendar EVA Now的一个示例测试集，直接拿来就能用：

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

按照SMART原则设计接口定义，并生成符合OpenAPI 3.0规范的YAML文档。但这里有个关键提醒：先别着急写后端代码。 你肯定不想辛辛苦苦写完接口再推翻重来。正确的做法是，先在GPTs平台上用测试集跑一遍你设计的接口，观察模型是否选对了接口、是否构建了正确的参数。确认无误后，再进入下一步。

步骤3：实现接口

当接口定义已经经过验证，就可以动手实现后端代码了。这一步相对标准化，核心是保证接口功能和你的OpenAPI文档完全一致。

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

测试环境几乎是必需品。无论开发新功能还是修Bug，总得先在测试环境验证通过，再部署到生产环境。跳过这一步，直接在生产环境上调试，用户体验往往很难保障。

遵循这四个步骤，就能为GPTs构建出可靠且易用的Actions，最终让应用的整体体验和功能都提升一个台阶。

后话

从实际测试结果来看，国外的GPT-4和GPT-4o几乎能完美通过上面测试集里的所有项目。国内方面，在扣子（coze.cn）上测试了几个模型后，只有Baichuan4勉强能通过大部分测试——算看到了希望，但也确实任重道远。当然，这里仅限于不借助Finetune的手段。至于Finetune能带来多大正收益、又会带来多少负影响，有机会尝试了再聊。

从个人体验的角度说，市面上各类日程管理工具试了不少，但每次临时修改安排时，一想到要在界面上点点点，就忍不住抗拒。本意是想省时间，结果花在修改日程上的时间反而更多了。大概这就是为什么最后决定自己动手做Calendar EVA Now的初衷——用自然对话管理日程，才是真正顺手的方案。