結構化輸出

結構化輸出確保模型生成的響應符合你定義的 JSON schema。这對於需要以編程方式解析模型輸出的可靠應用至關重要。

JSON 模式

最简單的方式是通過 response_format 請求 JSON 輸出：

from openai import OpenAI

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

response = client.chat.completions.create(
    model="deepseek/deepseek-v4-pro",
    messages=[
        {"role": "system", "content": "You are a helpful assistant that responds in JSON."},
        {"role": "user", "content": "List 3 programming languages with their use cases."}
    ],
    response_format={"type": "json_object"}
)

import json
data = json.loads(response.choices[0].message.content)
print(data)

重要： 使用 json_object 模式時，請在 system 或 user 消息中包含輸出 JSON 的指令，否則模型可能返回空內容。

JSON Schema

如需更严格的控制，可指定模型必须遵循的 JSON schema：

response = client.chat.completions.create(
    model="deepseek/deepseek-v4-pro",
    messages=[
        {"role": "user", "content": "Extract the name, age, and skills from: John is a 30-year-old Python developer."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person_info",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "skills": {
                        "type": "array",
                        "items": {"type": "string"}
                    }
                },
                "required": ["name", "age", "skills"],
                "additionalProperties": False
            }
        }
    }
)

響應將始終是符合该 schema 的有效 JSON：

{
  "name": "John",
  "age": 30,
  "skills": ["Python"]
}

使用 Pydantic（Python）

借助 OpenAI Python SDK，你可以直接使用 Pydantic 模型：

from pydantic import BaseModel

class PersonInfo(BaseModel):
    name: str
    age: int
    skills: list[str]

response = client.beta.chat.completions.parse(
    model="deepseek/deepseek-v4-pro",
    messages=[
        {"role": "user", "content": "Extract: John is a 30-year-old Python developer."}
    ],
    response_format=PersonInfo
)

person = response.choices[0].message.parsed
print(f"{person.name}, age {person.age}, skills: {person.skills}")

Schema 定義規則

定義严格 JSON schema 時：

所有字段都必须列入 required
對每個 object 設定 additionalProperties: false
使用受支援的類型：string、number、integer、boolean、array、object
按需嵌套 object 和 array
對受限的字符串取值使用 enum

常见使用場景

使用場景	schema 示例
數據抽取	從非結構化文本中抽取實體
分類	用标签和置信度對輸入分類
程式碼生成	生成結構化的程式碼配置
API 輸入	為下游 API 生成合法的 JSON

錯誤處理

当模型無法针對給定 schema 生成合法輸出時，可能返回 refusal：

message = response.choices[0].message
if message.refusal:
    print(f"Model refused: {message.refusal}")
else:
    data = json.loads(message.content)

支援的模型

基於 JSON schema 的結構化輸出在大多數模型上可用。兼容性详情請查閲模型概览中的各模型页面。