建立 2026-10-11 更新 2026-10-11

LLM 結構化輸出

LLM 結構化輸出（structured output）是指讓大型語言模型回傳符合固定格式的 JSON，而不是自由文字。Pydantic 在這裡負責兩件事：用模型產生 JSON Schema 告訴 LLM 要輸出什麼格式，再驗證 LLM 回傳的內容是否真的符合。OpenAI、Anthropic SDK、Pydantic AI、Instructor、LangChain 都採用這個模式。本頁說明基本原理、與 SDK 無關的通用寫法，以及 Pydantic AI 的用法。

為什麼不直接解析 LLM 回傳的文字？

LLM 的自由文字輸出格式不穩定：有時多一句「好的，以下是結果」、有時欄位名稱拼錯、有時數字變成「約三百」。用正規表示式或 split 解析既脆弱又難維護。結構化輸出的流程是：

用 Pydantic 模型定義需要的資料。
把 model_json_schema() 交給 LLM（或由 SDK 代勞），要求依此格式輸出。
用 model_validate_json() 驗證回傳內容；失敗時可把錯誤訊息回饋給 LLM 重試。

通用寫法：定義模型、驗證輸出

不論使用哪家的 SDK，核心都是一個帶有清楚 description 的模型：

from typing import Literal

from pydantic import BaseModel, Field, ValidationError


class ReviewAnalysis(BaseModel):
    """一則商品評論的分析結果。"""

    sentiment: Literal["positive", "neutral", "negative"] = Field(description="整體情緒")
    score: int = Field(ge=1, le=5, description="推估的星等，1 到 5")
    keywords: list[str] = Field(max_length=5, description="評論中提到的重點，最多 5 個")


schema = ReviewAnalysis.model_json_schema()  # 交給 LLM 的格式規格

# 假設這是 LLM 回傳的 JSON 字串
llm_output = '{"sentiment": "positive", "score": 5, "keywords": ["出貨快", "包裝完整"]}'

try:
    result = ReviewAnalysis.model_validate_json(llm_output)
    print(result.sentiment, result.score)  # positive 5
except ValidationError as e:
    # 實務上把 e 的內容附在下一輪提示中，請 LLM 修正後重試
    print(e)

description 是寫給 LLM 看的欄位說明，寫得越具體，輸出品質越好，見 JSON Schema。Literal 與 Field 的範圍限制會變成 Schema 中的 enum、minimum、maximum，大幅減少 LLM 自由發揮的空間。

Pydantic AI 是什麼？

Pydantic AI 是 Pydantic 團隊開發的 AI Agent 框架，把「模型定義輸出格式、自動驗證、失敗重試」整合成一行設定。支援 OpenAI、Anthropic、Google Gemini 等多家模型：

uv add pydantic-ai

from pydantic import BaseModel
from pydantic_ai import Agent


class CityInfo(BaseModel):
    city: str
    country: str
    population: int


agent = Agent("anthropic:claude-sonnet-5-5", output_type=CityInfo)
result = agent.run_sync("台灣人口最多的城市是哪裡？")
print(result.output)  # CityInfo 物件，已經過 Pydantic 驗證

執行前需要設定對應服務的 API 金鑰環境變數（例如 ANTHROPIC_API_KEY）。output_type 指定輸出模型後，Pydantic AI 會把 Schema 交給 LLM，驗證失敗時自動把錯誤回饋給 LLM 重試。Pydantic AI 也支援工具呼叫：把 Python 函式註冊成工具，函式的型別提示會自動轉成 JSON Schema。

還有哪些常用工具？

工具	特色
Pydantic AI	Pydantic 官方的 Agent 框架，型別安全，可搭配 Logfire 觀察執行過程
Instructor	輕量函式庫，包裝既有 SDK，加上 `response_model` 參數與自動重試
各家官方 SDK	OpenAI、Anthropic 等 Python SDK 也可以直接傳入 Pydantic 模型或 JSON Schema 取得結構化輸出

選擇原則：只需要「一次呼叫、拿到結構化結果」時，用官方 SDK 或 Instructor 就夠；需要多步驟推理、工具呼叫與相依注入時，考慮 Pydantic AI。

LLM 結構化輸出

為什麼不直接解析 LLM 回傳的文字？

通用寫法：定義模型、驗證輸出

Pydantic AI 是什麼？

還有哪些常用工具？

推薦影音

Real Python：用 Pydantic AI 建立型別安全的 LLM Agent

BugBytes：Instructor 與 Pydantic 結構化資料擷取

Pydantic 官方（PyCon US）：Building AI Applications the Pydantic Way

相關資料