| 模式 | 說明 |
|---|---|
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" }
}
{
"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"
}
]
}
完整範例
- Python (OpenAI)
- Node.js (OpenAI)
- cURL
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)
import OpenAI from "openai";
import { zodResponseFormat } from "openai/helpers/zod";
import { z } from "zod";
const client = new OpenAI({
baseURL: "https://api.arouter.ai/v1",
apiKey: "lr_live_xxxx",
});
// 使用 Zod 定義結構
const PlanetInfo = z.object({
name: z.string(),
diameter_km: z.number(),
moons: z.number().int(),
habitable: z.boolean(),
});
// 使用 parse() 配合 Zod（推薦）
const response = await 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: zodResponseFormat(PlanetInfo, "planet_info"),
});
const planet = response.choices[0].message.parsed;
console.log(planet?.name); // "Mars"
console.log(planet?.moons); // 2
console.log(planet?.diameter_km); // 6779
// 或直接使用 response_format
const rawResponse = 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: {
type: "object",
properties: {
name: { type: "string" },
diameter_km: { type: "number" },
moons: { type: "integer" },
habitable: { type: "boolean" },
},
required: ["name", "diameter_km", "moons", "habitable"],
additionalProperties: false,
},
},
},
});
const data = JSON.parse(rawResponse.choices[0].message.content ?? "{}");
curl https://api.arouter.ai/v1/chat/completions \
-H "Authorization: Bearer lr_live_xxxx" \
-H "Content-Type: application/json" \
-d '{
"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": {
"type": "object",
"properties": {
"name": {"type": "string"},
"diameter_km": {"type": "number"},
"moons": {"type": "integer"},
"habitable": {"type": "boolean"}
},
"required": ["name", "diameter_km", "moons", "habitable"],
"additionalProperties": false
}
}
}
}'
模型支援
支援strict: true 的 json_schema 模式的模型包括：
openai/gpt-5.4,openai/gpt-5.4-pro,openai/o3,openai/o4-minianthropic/claude-sonnet-4.6,anthropic/claude-opus-4.5google/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);
最佳實踐
-
使用
strict: true— 這可以保證結構遵從性。否則模型可能回傳不完全符合結構的有效 JSON。 -
設定
additionalProperties: false— 嚴格模式必須設定。防止模型新增額外的鍵。 -
明確列出所有必填欄位 — 在嚴格模式下，
properties中的每個欄位都應在required中。 - 包含系統提示 — 告知模型作為資料提取或結構化輸出助手的角色，可提高可靠性。
錯誤處理
如果模型無法生成與您的結構匹配的有效 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)