结构化输出

TopRouter 支持兼容模型的结构化输出，确保响应遵循特定的 JSON Schema 格式。当您需要应用程序可以可靠解析的一致、格式良好的响应时，此功能特别有用。

概述

结构化输出允许您：

在模型响应上强制执行特定 JSON Schema 验证
获取一致的、类型安全的输出
避免解析错误和幻觉字段
简化应用程序中的响应处理

使用结构化输出

要使用结构化输出，请在请求中包含 response_format 参数，将 type 设置为 json_schema，并在 json_schema 对象中包含您的模式：

{
  "messages": [
    { "role": "user", "content": "伦敦的天气怎么样？" }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "weather",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "城市或位置名称"
          },
          "temperature": {
            "type": "number",
            "description": "摄氏温度"
          },
          "conditions": {
            "type": "string",
            "description": "天气状况描述"
          }
        },
        "required": ["location", "temperature", "conditions"],
        "additionalProperties": false
      }
    }
  }
}

模型将使用严格遵循您模式的 JSON 对象进行响应：

{
  "location": "伦敦",
  "temperature": 18,
  "conditions": "局部多云并有小雨"
}

模型支持

结构化输出受到精选模型的支持。

您可以在模型页面上找到支持结构化输出的模型列表。

OpenAI 模型（GPT-4o 及更新版本）文档
所有 Fireworks 提供的模型文档

为确保您选择的模型支持结构化输出：

在模型页面上检查模型支持的参数
在您的提供商首选项中设置 require_parameters: true（参见 [提供商路由]）
在必需参数中包含 response_format 并设置 type: json_schema

最佳实践

包含描述：在您的模式属性中添加清晰的描述以指导模型
使用严格模式：始终设置 strict: true 以确保模型完全遵循您的模式

示例实现

这是一个使用 Fetch API 的完整示例：

使用 TypeScript
const response = await fetch('https://TopRouter.ai/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer {{API_KEY_REF}}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: '{{MODEL}}',
    messages: [
      { role: 'user', content: '伦敦的天气怎么样？' },
    ],
    response_format: {
      type: 'json_schema',
      json_schema: {
        name: 'weather',
        strict: true,
        schema: {
          type: 'object',
          properties: {
            location: {
              type: 'string',
              description: '城市或位置名称',
            },
            temperature: {
              type: 'number',
              description: '摄氏温度',
            },
            conditions: {
              type: 'string',
              description: '天气状况描述',
            },
          },
          required: ['location', 'temperature', 'conditions'],
          additionalProperties: false,
        },
      },
    },
  }),
});

const data = await response.json();
const weatherInfo = data.choices[0].message.content;

使用 Python
import requests
import json

response = requests.post(
  "https://TopRouter.ai/api/v1/chat/completions",
  headers={
    "Authorization": f"Bearer {{API_KEY_REF}}",
    "Content-Type": "application/json",
  },

  json={
    "model": "{{MODEL}}",
    "messages": [
      {"role": "user", "content": "伦敦的天气怎么样？"},
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "weather",
        "strict": True,
        "schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "城市或位置名称",
            },
            "temperature": {
              "type": "number",
              "description": "摄氏温度",
            },
            "conditions": {
              "type": "string",
              "description": "天气状况描述",
            },
          },
          "required": ["location", "temperature", "conditions"],
          "additionalProperties": False,
        },
      },
    },
  },
)

data = response.json()
weather_info = data["choices"][0]["message"]["content"]

结构化输出的流式传输

流式响应也支持结构化输出。模型将流式传输有效的部分 JSON，当完成时，形成与您的模式匹配的有效响应。

要启用结构化输出的流式传输，只需在请求中添加 stream: true：

{
  "stream": true,
  "response_format": {
    "type": "json_schema",
    // ... 您模式的其余部分
  }
}

错误处理

使用结构化输出时，您可能会遇到这些情况：

模型不支持结构化输出：请求将失败，错误指示不支持
无效模式：如果您的 JSON Schema 无效，模型将返回错误

概述​

使用结构化输出​

模型支持​

最佳实践​

示例实现​

结构化输出的流式传输​

错误处理​

概述