结构化输出 - APIONE AI

结构化输出适合分类、信息抽取和工作流参数生成。是否支持 response_format、JSON Schema 或其他格式约束取决于模型参数。

基本策略

查询模型是否支持结构化输出。
使用尽量小、明确的结构。
在服务端做 JSON 解析和 Schema 校验。
校验失败时有限重试，或降级为普通文本解析。

JSON 对象示例

{
  "model": "YOUR_APIONE_MODEL_ID",
  "messages": [
    {"role": "system", "content": "只返回 JSON，不要添加 Markdown。"},
    {"role": "user", "content": "从文本中提取产品名和数量：订购 3 个蓝色键盘。"}
  ],
  "response_format": {"type": "json_object"}
}

不要只依赖提示词保证格式。即使 HTTP 200，也要捕获空内容、截断 JSON、类型错误和缺失字段。

服务端校验

function parseOrder(text) {
  const value = JSON.parse(text);
  if (typeof value.product !== "string") throw new Error("product is required");
  if (!Number.isInteger(value.quantity) || value.quantity < 1) {
    throw new Error("quantity must be a positive integer");
  }
  return value;
}

截断与结束原因

当 finish_reason 表示长度限制，JSON 可能缺少结尾括号。不要尝试静默拼接不可信 JSON；提高合理的输出上限、缩小 Schema 或重新请求。工具调用场景应读取工具参数，而不是把正文当成 JSON。

Schema 设计建议

字段名简短、含义明确；
枚举控制在必要范围；
避免深层嵌套和无限数组；
对金额、时间和标识使用字符串并单独验证格式；
明确哪些字段允许 null；
不让模型决定权限、最终价格或安全策略。

下一步：工具调用、Chat Completions、模型参数、请求跟踪、超时与重试。