Structured Outputs 與資料模型

模型輸出進入資料庫、表單或後續程式時,欄位是否完整、缺值如何表示、巢狀資料如何組合,以及資料是否符合業務規則,都需要明確定義。Chat Completions 的 Structured Outputs 以 JSON Schema 約束輸出結構,Pydantic 則提供型別定義與解析。文字、JSON mode 和 Structured Outputs 的基本差異見系列(二)的功能實作。

程式使用 Python 3.11 以上、Pydantic 2 與目前的 OpenAI Python SDK,模型為 gpt-6-sol。reasoning_effort="none" 與函式工具範例採用相同設定;模型能力與參數搭配見模型文件。金鑰由環境變數 OPENAI_API_KEY 讀取,下方程式共用同一個 client 與函式定義。

pip install -U openai "pydantic>=2,<3"

Pydantic:Schema、請求與解析

extract() 集中處理請求、回應狀態與解析,每個情境提供自己的資料模型、任務說明與輸入。extra="forbid" 會在 object Schema 產生 additionalProperties: false;回應中必須出現的欄位不設預設值。拒絕、輸出截斷和內容過濾在解析前處理。json_schema.name 可使用英文字母、數字、底線或連字號,最長 64 字元,程式直接採用 Python 類別名稱。

from typing import Literal, TypeVar
from openai import OpenAI
from pydantic import BaseModel, ConfigDict

client = OpenAI(timeout=60.0, max_retries=1)
T = TypeVar("T", bound=BaseModel)

class StrictModel(BaseModel):
    model_config = ConfigDict(extra="forbid")

class ModelOutputError(RuntimeError):
    pass

def extract(result_type: type[T], instruction: str, source: str) -> T:
    response = client.chat.completions.create(
        model="gpt-6-sol",
        reasoning_effort="none",
        store=False,
        max_completion_tokens=8192,
        messages=[
            {"role": "developer", "content": instruction},
            {"role": "user", "content": source},
        ],
        response_format={
            "type": "json_schema",
            "json_schema": {
                "name": result_type.__name__,
                "strict": True,
                "schema": result_type.model_json_schema(),
            },
        },
    )
    choice = response.choices[0]
    message = choice.message
    if message.refusal:
        raise ModelOutputError(f"模型拒絕本次請求:{message.refusal}")
    if choice.finish_reason != "stop":
        raise ModelOutputError(f"回應未正常完成:{choice.finish_reason}")
    if not message.content:
        raise ModelOutputError("回應沒有可供解析的內容。")
    return result_type.model_validate_json(message.content)

連線、HTTP 與 Pydantic 例外保留原本型別,由呼叫端決定是否重試或回報;ModelOutputError 表示已收到 API 回應,但無法取得完整的結構化結果。若將這些失敗都轉成空物件,下游程式就無法區分「沒有資料」與「資料取得失敗」。

SDK 的自動解析介面目前是 client.chat.completions.parse(..., response_format=ResultType),早期範例使用的 client.beta.chat.completions.parse() 已不必沿用。parse() 負責 Schema 生成與型別解析,並可能針對長度或內容過濾拋出專用例外。下方範例使用 create() 配合 model_validate_json(),分別處理 API 回應狀態與資料驗證。

結構化輸出的使用情境

數學解題、研究資料抽取和內容分類共用 extract(),各自定義資料結構與指令。這些模型使用較小的欄位集合,client、請求及狀態檢查則沿用同一份程式。

class MathStep(StrictModel):
    explanation: str
    output: str

class MathReasoning(StrictModel):
    steps: list[MathStep]
    final_answer: str

class ResearchPaper(StrictModel):
    status: Literal["extracted", "not_applicable"]
    title: str | None
    authors: list[str]
    abstract: str | None
    keywords: list[str]

class ContentReview(StrictModel):
    is_violating: bool
    category: Literal["violence", "sexual", "self_harm"] | None
    explanation: str | None

數學解題步驟

步驟陣列適合在畫面逐段呈現推導,但每一步仍是模型生成的內容。通過 MathReasoning 代表欄位與型別符合定義,不代表計算正確;涉及金額、庫存或計費的數值仍由程式核對。

math = extract(
    MathReasoning,
    "以繁體中文分步解題,每步列出說明與等式,最後給出答案。",
    "解方程式 8x + 7 = -23。",
)
for step in math.steps:
    print(step.explanation, step.output)
print(math.final_answer)

研究資料抽取與缺值

研究資料抽取以 status 表示輸入是否適用;沒有出現的標題與摘要使用 null,清單欄位使用空陣列。即使輸入不是研究文章,也有對應的狀態與欄位值,不需要補造內容。

paper = extract(
    ResearchPaper,
    "只抽取輸入明示的研究資訊,不補寫作者或內容。"
    "不是研究資料時用 not_applicable,標題與摘要填 null,清單填空陣列。",
    "標題:海岸潮汐觀測。作者:林青、陳禾。"
    "摘要:本文比較三個測站的潮汐紀錄。關鍵字:潮汐、測站。",
)
print(paper.model_dump_json(indent=2))

內容分類與 refusal

應用程式可以依自己的規則產生結構化的分類結果,但這是產品分類,不是 OpenAI Moderation API 的等價替代。ContentReview.is_violating 是任務結果;API 的 message.refusal 是模型拒絕執行本次請求,兩者不能共用同一個狀態欄位。

review = extract(
    ContentReview,
    "依 violence、sexual、self_harm 三類檢查輸入。"
    "未違反時 category 與 explanation 都填 null;違反時都必須填寫。",
    "明天要參加面試,想整理自我介紹。",
)
if not review.is_violating and (review.category is not None or review.explanation is not None):
    raise ValueError("未違反時不應附帶違規分類或原因。")
if review.is_violating and (review.category is None or not review.explanation):
    raise ValueError("違反時必須提供分類與原因。")
print(review.model_dump())

遞迴 UI 資料模型

樹狀選單、表單與巢狀版面可以用遞迴模型表示。UINode.children 指向同一個型別,Pydantic 透過 $defs 與 $ref 表達重複結構;外層仍以 UIResult 保持 root 為 object。model_rebuild() 用來完成向前參照。

class Attribute(StrictModel):
    name: str
    value: str

class UINode(StrictModel):
    type: Literal["div", "button", "header", "section", "field", "form"]
    label: str
    children: list["UINode"]
    attributes: list[Attribute]

UINode.model_rebuild()

class UIResult(StrictModel):
    ui: UINode

def validate_ui(root: UINode) -> None:
    pending = [(root, 0)]
    count = 0
    allowed_attributes = {"name", "placeholder", "type"}
    allowed_types = {"text", "email", "tel", "button", "submit"}
    while pending:
        node, depth = pending.pop()
        count += 1
        if count > 100 or depth > 8:
            raise ValueError("UI 超出應用程式設定的節點或深度限制。")
        for attribute in node.attributes:
            if attribute.name not in allowed_attributes:
                raise ValueError(f"不允許的 UI 屬性:{attribute.name}")
            if attribute.name == "type" and attribute.value not in allowed_types:
                raise ValueError("不允許的表單欄位或按鈕型別。")
        pending.extend((child, depth + 1) for child in node.children)

result = extract(
    UIResult,
    "輸出表單資料樹,不輸出HTML。屬性只可使用name、placeholder、type。"
    "type屬性只可用text、email、tel、button、submit。"
    "沒有子節點或屬性時填空陣列。",
    "產生姓名、電子郵件及送出按鈕的使用者資料表單。",
)
validate_ui(result.ui)
print(result.model_dump_json(indent=2))

100 個節點與 8 層是應用程式的呈現限制,與 API 的 Schema 定義限制不同。前端將 type 映射到既有元件,只呈現允許的屬性,文字使用一般文字節點輸出。模型產生的屬性不能直接展開到 DOM,HTML、事件處理器或網址也不直接執行。

結構驗證與業務驗證

不相關輸入與不適用狀態

欄位設為必填,卻沒有不適用狀態時,模型就缺少表示「找不到資料」的方式。ResearchPaper 保留狀態與 nullable 欄位,指令也限定只能使用輸入中明示的資訊。後端仍須檢查欄位關係,例如 not_applicable 時不得附帶推測的標題、作者或摘要。

拒絕、截斷與資料驗證錯誤

不支援的 Schema 會在請求時得到 400,需修正結構;輸出達到長度限制時,需調整輸入與輸出預算,重新取得完整結果;模型拒絕則交由產品流程處理。通過 Pydantic 驗證後,日期、金額或資料關係仍可能不合理,這類結果由業務規則拒絕採用,不以猜測值補齊。

Schema 與程式型別同步

Python 類別、JSON Schema 與前端型別若各自維護,欄位容易逐漸不一致。Pydantic 或 Zod 可以作為主要定義來源,生成的 Schema 納入版本管理,測試檢查欄位名稱、required、nullable 及巢狀 object 設定。欄位變更會連帶影響儲存、API 與畫面;格式、範圍和跨欄位驗證則仍由應用程式處理。

JSON Schema 支援範圍與容量

Structured Outputs 支援的 JSON Schema 子集合包含型別、結構與容量限制。下表依官方規則整理支援範圍。

項目設計方式或限制
資料型別string、number、boolean、integer、object、array、enum,以及允許位置的 anyOf。
Root object最外層必須是 object,不能直接以 anyOf 表示多種結果;可在 object 的欄位內使用支援的 union。
必要欄位properties 中的欄位都列入 required;允許缺值時使用與 null 的 union,不省略 key。
額外欄位每個 object 都設定 additionalProperties: false,包括陣列元素、巢狀模型與 $defs 內的 object。
結構容量最多 5,000 個 object properties,Schema 最多 10 層巢狀;遞迴結構可用 $ref 表達。
總字串容量屬性名稱、定義名稱、enum 與 const 值合計最多 120,000 字元,計的是字元,不是 token。
Enum所有 enum 合計最多 1,000 個值;單一字串 enum 超過 250 個值時,其值的字串合計最多 15,000 字元。
輸出順序輸出 key 依 Schema 的定義順序排列;程式取值仍使用欄位名稱。
組合與條件不使用 allOf、not、dependentRequired、dependentSchemas、if/then/else 等未支援的規則。

目前配額已高於早期的 100 個 properties、5 層巢狀及較小 enum 上限。Fine-tuned 模型另有型別關鍵字限制,使用時需依模型文件確認;gpt-6-sol 範例不依賴這些額外功能。

Nullable 與 required

Pydantic 2 的 title: str | None 表示欄位必須存在,但值可以是 null;title: str | None = None 則同時允許省略。範例使用前者,符合 strict Schema 的 required 規則。手寫 Schema、型別生成及 SDK 自動解析也須採相同定義。

{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["title"],"additionalProperties":false}

回覆格式與工具參數

如果資料只是要回傳給使用者或交給下游程式,使用 response_format 約束結果即可;如果應用程式還要查資料庫、讀取內部服務或執行操作,則以 Tool Calling 傳遞工具名稱與參數。兩者可以共用 Pydantic 型別工具,但工具需要執行與回填流程,不能只靠一份 Schema 取代。

基本工具流程見系列(二),實際商家資料整合見系列(五)。改用 Responses 時,回覆格式移至 text.format,SDK 解析可使用 responses.parse(..., text_format=ResultType);完整格式差異見遷移篇。

參考文件

相關介面可查閱Structured Outputs、Chat Completions與Pydantic models。