大模型应用开发 / 系统课时

设计服务接口

设计服务接口

本节把大模型能力整理成可长期维护的服务接口:明确请求字段、同步与流式响应、错误码和会话标识。完成后,你可以给前端、Agent 或其他后端提供稳定契约,而不是让调用方依赖模型供应商的原始返回格式。

学习目标

  • 设计稳定的请求与响应数据结构
  • 统一同步响应、流式事件和错误返回规则
  • 正确处理会话标识、请求标识和接口演进

先确定接口边界

面向业务调用方时,接口应暴露“业务需要的能力”,不要直接透传模型厂商全部参数。常见最小请求包括输入消息、会话标识、是否流式,以及少量受控生成参数;模型名称、路由策略、重试和密钥通常留在服务端管理。

请求标识与会话标识职责不同。requestId 用于追踪一次调用,适合日志、链路和故障排查;sessionId 用于关联多轮上下文。客户端可以提交已有 sessionId,首次调用则由服务端生成并在响应中返回。

定义同步请求与响应

下面用一个最小 HTTP 契约描述聊天接口。请求只保留业务方真正需要的字段,响应统一返回服务自己的标识和结果,避免上游模型切换时破坏客户端。示例中的域名和令牌是接口设计占位,需要替换为实际部署值后验证。

bash
curl -sS -X POST "https://api.example.com/v1/chat" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{
    "sessionId": "sess-123",
    "message": "解释什么是向量检索",
    "stream": false
  }'

预期结果为 HTTP 200 OK,响应体遵循以下结构:

json
{
  "requestId": "<ID>",
  "sessionId": "sess-123",
  "message": {
    "role": "assistant",
    "content": "向量检索会把查询与候选内容映射到向量空间,再按相似度寻找最相关结果。"
  },
  "usage": {
    "inputTokens": "<VALUE>",
    "outputTokens": "<VALUE>"
  }
}

requestId 和 Token 数量是动态值,实际结果会不同。客户端只应依赖文档承诺的字段;供应商原始响应可以记录到内部受控日志,但不要作为公共契约的一部分。

统一错误码而不是暴露内部异常

HTTP 状态码描述传输层和通用语义,业务错误码描述调用方应该如何处理。两者应同时存在。例如参数错误返回 400,鉴权失败返回 401,限流返回 429,上游模型暂时不可用可以返回 503。

json
{
  "requestId": "<ID>",
  "error": {
    "code": "MODEL_UNAVAILABLE",
    "message": "model service is temporarily unavailable",
    "retryable": true
  }
}

这是 HTTP 503 Service Unavailable 的响应结构片段示例。验证时要保证相同原因始终返回稳定的 error.code,同时不要把供应商堆栈、内部主机名、密钥片段或完整提示词暴露给客户端。

为流式响应定义事件协议

流式接口必须规定事件类型、顺序和结束条件,不能只说“返回文本流”。Server-Sent Events 是常见选择:每个事件包含事件名和 JSON 数据,客户端按照 delta 累积文本,收到 done 后结束本次请求。

text
event: message.start
data: {"requestId":"<ID>","sessionId":"sess-123"}

event: message.delta
data: {"delta":"向量检索"}

event: message.delta
data: {"delta":"通过相似度查找相关内容。"}

event: message.done
data: {"finishReason":"stop"}

预期结果是客户端按事件顺序拼接两个 delta,最终得到“向量检索通过相似度查找相关内容。”,并在 message.done 到达后关闭本次消息的加载状态。连接异常中断时,客户端应把该次响应标记为未完成,而不是假设已经成功结束。

给接口保留演进空间

公共接口应从一开始就有版本,例如 /v1/chat。新增可选字段通常可以向后兼容;删除字段、改变字段类型或重定义错误语义则应进入新版本。枚举字段也要考虑未知值,客户端不要因为服务端新增一个 finishReason 就直接崩溃。

接口验收至少覆盖同步成功、流式成功、参数错误、鉴权失败、限流、上游超时和客户端中断。只要请求结构、事件顺序、错误码和标识规则都稳定,底层模型、路由和供应商就可以独立演进,而不必让所有调用方跟着改代码。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计服务接口

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通