跳转到主要内容
结构化输出强制模型返回符合您定义的结构的 JSON 对象。这消除了解析、验证或重试非结构化模型输出的需要。 ARouter 支持两种结构化输出模式:
模式说明
json_object保证输出有效 JSON;不强制执行结构
json_schema保证输出与您的精确结构匹配的 JSON

使用结构化输出

在请求体中传入 response_format

JSON Object 模式

{
  "model": "openai/gpt-5.4",
  "messages": [
    {
      "role": "user",
      "content": "Return information about the planet Mars as JSON"
    }
  ],
  "response_format": { "type": "json_object" }
}
模型返回有效 JSON,但不强制执行结构:
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "{\"name\":\"Mars\",\"diameter_km\":6779,\"moons\":2,\"habitable\":false}"
      }
    }
  ]
}

JSON Schema 模式

使用 json_schema 强制执行严格结构:
{
  "model": "openai/gpt-5.4",
  "messages": [
    {
      "role": "system",
      "content": "You are a data extraction assistant."
    },
    {
      "role": "user",
      "content": "Extract the planet information: Mars is a terrestrial planet with 2 moons and a diameter of 6779 km."
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "planet_info",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "diameter_km": { "type": "number" },
          "moons": { "type": "integer" },
          "habitable": { "type": "boolean" }
        },
        "required": ["name", "diameter_km", "moons", "habitable"],
        "additionalProperties": false
      }
    }
  }
}
响应:
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "{\"name\":\"Mars\",\"diameter_km\":6779,\"moons\":2,\"habitable\":false}"
      },
      "finish_reason": "stop"
    }
  ]
}

完整示例

import json
from openai import OpenAI
from pydantic import BaseModel

client = OpenAI(
    base_url="https://api.arouter.ai/v1",
    api_key="lr_live_xxxx",
)

# 使用 Pydantic 定义结构
class PlanetInfo(BaseModel):
    name: str
    diameter_km: float
    moons: int
    habitable: bool

# 使用 OpenAI 的 parse() 方法(推荐)
response = client.beta.chat.completions.parse(
    model="openai/gpt-5.4",
    messages=[
        {"role": "system", "content": "You are a data extraction assistant."},
        {"role": "user", "content": "Tell me about Mars."},
    ],
    response_format=PlanetInfo,
)

planet = response.choices[0].message.parsed
print(planet.name)        # "Mars"
print(planet.moons)       # 2
print(planet.diameter_km) # 6779.0

# 或手动使用 response_format dict
response = client.chat.completions.create(
    model="openai/gpt-5.4",
    messages=[
        {"role": "user", "content": "Tell me about Mars as JSON."},
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "planet_info",
            "strict": True,
            "schema": PlanetInfo.model_json_schema(),
        },
    },
)
data = json.loads(response.choices[0].message.content)
planet = PlanetInfo(**data)

模型支持

支持 strict: truejson_schema 模式的模型包括:
  • openai/gpt-5.4, openai/gpt-5.4-pro, openai/o3, openai/o4-mini
  • anthropic/claude-sonnet-4.6, anthropic/claude-opus-4.5
  • google/gemini-2.5-flash, google/gemini-2.5-pro
json_object 模式(无结构强制)的支持范围更广。请查看 GET /v1/models 获取最新的能力信息。

流式结构化输出

结构化输出支持流式传输。JSON 内容增量传递,由客户端进行组装:
const stream = await client.chat.completions.create({
  model: "openai/gpt-5.4",
  messages: [{ role: "user", content: "Tell me about Mars." }],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "planet_info",
      strict: true,
      schema: { /* ... */ },
    },
  },
  stream: true,
});

let jsonBuffer = "";
for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) jsonBuffer += content;
}

const data = JSON.parse(jsonBuffer);

最佳实践

  1. 使用 strict: true — 这可以保证结构遵从性。否则模型可能返回不完全符合结构的有效 JSON。
  2. 设置 additionalProperties: false — 严格模式必须设置。防止模型添加额外的键。
  3. 明确列出所有必填字段 — 在严格模式下,properties 中的每个字段都应在 required 中。
  4. 包含系统提示 — 告知模型作为数据提取或结构化输出助手的角色,可提高可靠性。

错误处理

如果模型无法生成与您的结构匹配的有效 JSON(如提示与结构根本冲突),响应的 finish_reason 将为 "length""content_filter"。解析内容前始终检查 finish_reason
response = client.chat.completions.create(...)

choice = response.choices[0]
if choice.finish_reason != "stop":
    raise ValueError(f"Unexpected finish reason: {choice.finish_reason}")

data = json.loads(choice.message.content)