首页 / 结构化输出与函数调用

结构化输出与函数调用

苏姆卡皮 · OpenAI 兼容 AI API 网关 · Base URL https://sub.sumcapi.top/v1

让模型稳定返回可解析结果，靠的不是"请求它输出 JSON"，而是响应模式、字段约束、示例与校验四件套。这一页给出在苏姆卡皮上的具体做法。

结构化输出与函数调用

三种落地方式，按可控性排序

JSON 模式示例

curl -N https://sub.sumcapi.top/v1/chat/completions \
  -H "Authorization: Bearer $SUMCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-mini",
    "temperature": 0,
    "response_format": {"type": "json_object"},
    "messages": [
      {"role": "system", "content": "只输出 JSON，字段：brand(字符串), price(数字), risks(字符串数组)"},
      {"role": "user", "content": "从下面这段商品描述里抽取字段：……"}
    ]
  }'

配合 temperature: 0 与逐字段说明，可显著降低同输入不同输出的抖动。

函数调用（工具编排）

{
  "tools": [{
    "type": "function",
    "function": {
      "name": "search_orders",
      "description": "按用户与时间范围查询订单，用于回答历史相关问题",
      "parameters": {
        "type": "object",
        "properties": {
          "user_id": {"type": "string"},
          "days": {"type": "integer", "description": "回溯天数，默认 30，最大 365"}
        },
        "required": ["user_id"]
      }
    }
  }],
  "tool_choice": "auto"
}

工程约定：

1. 工具描述写"什么时候用"，比写"这是什么"更能减少误调用；
2. 枚举与单位写进 description，不要让模型猜口径；
3. 执行前本地校验：参数不合法就把错误信息回传给模型自纠，不要静默修正；
4. 限制最大步数：Agent 循环要设步数上限与总预算，防止互相调用停不下来；
5. 保持幂等：外部动作携带请求 ID，重试不会重复下单。

解析失败的三级兜底

• 一级：用括号匹配截取 JSON 主体，处理偶发的前后缀说明文字；
• 二级：把具体报错回灌给模型要求重写一次，通常一次即可收敛；
• 三级：切换更听话的模型，或降级为模板化输出；
• 全程记录失败率与脱敏后的原始片段，它是提示词迭代的唯一依据。

成本注意

结构化输出的输出 token 常被忽略：字段冗余、数组元素重复都会推高成本。只要求必要字段、用数组替代重复对象、给出长度上限，通常能省下三成以上，见 长上下文与缓存。

下一步

• 选具体模型的参数支持：模型指南
• 计费口径：模型定价 · 计费与退款政策
• 错误码与限流：API 文档

常见问题