模型 API 与结构化输出

调用模型 API 是 AI 应用的起点，不是终点。稳定调用需要明确消息角色、模型参数、输出协议、超时重试和可观测信息。

一次请求包含什么

典型请求包含：

• 模型名称和版本。
• System 指令、用户输入和必要上下文。
• 最大输出长度。
• Temperature 等采样参数。
• 输出 schema 或可用工具定义。
• 请求标识和业务用户信息。

模型服务返回文本、结构化对象、工具调用请求或流式增量，同时附带 Token 使用量和停止原因。

消息层级

• System：应用长期规则、角色和安全边界。
• User：当前用户目标和输入。
• Assistant：历史模型输出。
• Tool：外部工具执行结果。

规则应放在稳定层，当前资料应作为明确上下文传入。不要把所有业务知识写成一段不断膨胀的 System Prompt。

采样参数

Temperature 提高时，低概率 Token 更容易被选中，输出通常更有变化；降低时更稳定。它不能保证事实正确，也不能修复错误检索。

需要稳定抽取、分类和工具参数时使用较低随机性；创意生成可以适当提高，但仍要通过内容和格式检查。

结构化输出

程序需要消费结果时，应定义 schema，而不是要求模型“返回一段 JSON”：

{
  "type": "object",
  "required": ["category", "confidence", "reason"],
  "properties": {
    "category": { "type": "string", "enum": ["refund", "logistics", "other"] },
    "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
    "reason": { "type": "string" }
  }
}

应用仍要做解析和业务校验，例如置信度范围、订单是否存在、用户是否有权操作。

流式输出

流式返回能降低用户感知的首字延迟，但会增加处理复杂度：

• 中途断开后如何恢复。
• 未完成 JSON 如何解析。
• 内容审核在生成前还是生成后执行。
• 工具调用和普通文本如何区分。
• 用户取消后如何终止后端请求。

超时、重试与幂等

网络错误和服务拥塞可以有限重试；参数错误、权限错误和内容拒绝不应盲目重试。写操作必须通过业务工具设置幂等键，模型请求重试不能导致重复下单或重复发送。

可观测信息

每次请求至少记录：

• Trace ID 和业务场景。
• 模型及版本。
• Prompt 或模板版本。
• 输入输出 Token、首字延迟和总延迟。
• 检索、工具和模型各阶段耗时。
• 停止原因、错误类型和重试次数。

日志要脱敏，不应直接记录密码、密钥和完整个人隐私。

最小质量检查

建立包含正常、边界、无答案、恶意输入和超长输入的测试集。每次更换模型或 Prompt 都自动检查格式正确率、任务准确率、延迟和成本，而不是只在控制台试几个问题。