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);完整格式差異見遷移篇。
