OpenRouter 平台功能

结构化输出

3 分钟阅读

结构化输出

让模型返回结构化数据

OpenRouter 为兼容模型支持结构化输出，确保响应遵循特定的 JSON Schema 格式。当你需要一致、格式良好、能被应用可靠解析的响应时，此功能尤其有用。

概述

结构化输出可以让你：

对模型响应强制执行特定的 JSON Schema 校验
获得一致、类型安全的输出
避免解析错误和虚构字段
简化应用中的响应处理

使用结构化输出

要使用结构化输出，请在请求中包含 response_format 参数，将 type 设为 json_schema，并在 json_schema 对象中放入你的 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
      }
    }
  }
}

模型会返回严格遵循你 schema 的 JSON 对象：

{
  "location": "London",
  "temperature": 18,
  "conditions": "局部多云，有小雨"
}

模型支持

结构化输出由部分精选模型支持。

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

支持按端点判定，而不仅仅按模型：同一模型可能由多个模型服务提供商提供，其中只有部分提供商支持结构化输出。端点支持情况也可能随时间变化。要查看特定模型有哪些提供商支持结构化输出，请查看该模型页面「服务提供商」部分中的 structured_outputs 参数。

各提供商实现的细节见其文档，例如：

要确保请求只路由到支持结构化输出的端点：

在模型页面上查看该模型支持的参数
在模型服务提供商偏好中设置 require_parameters: true（参见模型服务提供商路由）
包含 response_format，并在所需参数中设置 type: json_schema

最佳实践

包含描述：为 schema 属性添加清晰描述，以引导模型
使用严格模式：设置 strict: true，以便具有原生严格模式的提供商精确强制执行你的 schema。强制执行因提供商而异：有的保证符合 schema 的输出，有的会把你的 schema 转换成他们自己的结构化输出格式，或将其视为强提示，因此并非每个端点都能保证完全合规。严格模式也可能限制你可以使用的 JSON Schema 功能。详情见提供商文档

实现示例

以下是使用 Fetch API 的完整示例：

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const response = await openRouter.chat.send({
  model: 'openai/gpt-4o',
  messages: [
    { role: 'user', content: '伦敦的天气怎么样？' },
  ],
  responseFormat: {
    type: 'json_schema',
    jsonSchema: {
      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,
      },
    },
  },
  stream: false,
});

const weatherInfo = response.choices[0].message.content;

结构化输出的流式传输

结构化输出也支持流式响应。模型会流式返回有效的部分 JSON，完成后构成匹配你 schema 的有效响应。

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

{
  "stream": true,
  "response_format": {
    "type": "json_schema",
    // ... 其余 schema
  }
}

错误处理

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

模型不支持结构化输出：请求会失败，并返回表示不支持的错误
无效 schema：如果 JSON Schema 无效，模型会返回错误

响应修复

对于使用 response_format 且 type: "json_schema" 的非流式请求，可以启用响应修复插件，以降低模型返回不完美格式时出现无效 JSON 的风险。详情见响应修复文档。