Pydantic AI 是什麼、怎麼用：安裝、結構化輸出、工具與依賴注入入門

本文根據 Pydantic AI 官方倉庫 README 和官方安裝文檔整理，資料核對於 2026-10-11。文中代碼取自官方 README，沒有在本機運行驗證。

適用於誰

• 搜「pydantic ai 是什麼」「pydantic ai 教學」「pydantic ai 怎麼樣」的人；
• 用 Python 寫智能體，受夠了從模型返回的文本里手動摳字段的人；
• 已經在用 Pydantic 或 FastAPI，希望智能體代碼也有類型檢查的人。

結論先說

1. Pydantic AI 是 Pydantic 團隊出的 Python 智能體框架。官方的一句話定位是：一個帶類型、可擴展的智能體循環，換模型只需要改一個字符串。
2. 安裝：pip install pydantic-ai 或 uv add pydantic-ai，需要 Python 3.11 及以上。
3. 最有特色的是結構化輸出：給 Agent 傳一個 Pydantic 模型作為 output_type，拿到的 result.output 就是校驗過的對象，字段類型和取值範圍都有保證。
4. 工具就是加了裝飾器的函數：函數簽名和文檔字符串自動變成給模型看的工具定義。
5. 依賴注入：數據庫連接、當前用戶這類運行時才有的東西，通過 RunContext 傳進工具和指令裏，而不是用全局變量。

一、它主打什麼

README 的「為什麼用 Pydantic AI」裏列的幾項：

二、安裝

完整版

bash
pip install pydantic-ai

bash
uv add pydantic-ai

官方說明完整版包含 pydantic_ai 包、核心依賴，以及 OpenAI、Anthropic、Google 三家模型所需的庫，還帶上了命令行、MCP、Evals、Web 介面和 Logfire 的集成。其他模型和集成需要加附加項，例如 pydantic-ai[bedrock,temporal]。

slim 版：只裝需要的

bash
pip install "pydantic-ai-slim[openai]"

bash
pip install "pydantic-ai-slim[openai,google,logfire]"

pydantic-ai-slim 只安裝你選的附加項。常用的可選組名有 openai、anthropic、google、groq、mistral、bedrock、openrouter、mcp、evals、logfire、cli 等，完整列表見官方安裝文檔。

想讓依賴盡量少（做成鏡像、放進函數計算）時用 slim 版；本地學習直接裝完整版。

然後把對應廠商的 API Key 設成環境變量，例如用 OpenAI 的模型就設 OPENAI_API_KEY。

三、第一個智能體：結構化輸出加一個工具

README 裏最短的完整示例：

python
from typing import Literal

from pydantic import BaseModel, Field

from pydantic_ai import Agent, RunContext


class Sentiment(BaseModel):
    label: Literal['positive', 'negative', 'neutral']
    score: float = Field(ge=-1, le=1)


agent = Agent('openai:gpt-6-sol', output_type=Sentiment)


@agent.tool
def recent_reviews(ctx: RunContext, product: str) -> list[str]:
    """Fetch recent review snippets for a product."""
    return ['The new release fixed everything I complained about!']


result = agent.run_sync('How are people feeling about the Extract app?')
print(result.output)
#> label='positive' score=0.9

逐段看：

• Sentiment：一個普通的 Pydantic 模型。label 只能是三個值之一，score 必須在 -1 到 1 之間；
• Agent('openai:gpt-6-sol', output_type=Sentiment)：第一個參數是 '廠商:模型' 形式的模型字符串，換模型就改這裏；output_type 聲明最終結果必須是一個 Sentiment；
• @agent.tool：把函數註冊為工具。函數簽名和文檔字符串成為工具的參數定義和說明。模型需要評論數據時會調用它；
• agent.run_sync(...)：同步運行。框架負責「調用模型 → 執行工具 → 再調用模型」的循環；
• result.output：拿到的是一個 Sentiment 對象，可以直接用 result.output.label。

模型返回的內容不符合 Sentiment 的約束時，校驗會失敗，而不是把一個不合格的結果悄悄交給你的業務代碼。這就是它相對「在提示詞裏要求輸出 JSON」的主要好處，原理見《如何讓大模型穩定輸出 JSON》。

四、依賴注入是什麼

實際的工具往往需要外部資源：數據庫連接、HTTP 客戶端、當前登入的用戶。README 的銀行客服示例展示了這套機制，涉及的幾個概念：

好處有兩個：一是類型檢查器能發現「工具裏用了依賴上不存在的屬性」這類錯誤；二是測試時可以傳入假的依賴，不必連真的數據庫。

README 裏還提到 Capabilities：把工具、指令、鉤子和設定打包成可以複用的單元。入門階段可以先不管。

五、看得見運行過程

README 把可觀測性放在很靠前的位置：框架按 OpenTelemetry 標準輸出追蹤數據，接 Pydantic 自家的 Logfire 只需要一行代碼，也可以接其他支持 OTel 的後端。slim 版需要加 logfire 附加項：

bash
pip install "pydantic-ai-slim[logfire]"

之後按官方的 Logfire 設定指南配置。智能體多步運行時，哪一步調用了哪個工具、每次請求和響應是什麼，都能在追蹤裏看到。

六、適合誰，不適合誰

適合：

• 需要把模型輸出交給下游代碼使用的場景：抽取、分類、填表、生成配置；
• 團隊已有 Pydantic、類型標註的習慣；
• 希望不綁定某一家模型廠商。

可以先不用：

• 只是寫個腳本調一次模型，直接用廠商的 SDK 更省事，見《OpenAI API Python 快速上手》、《Claude API Python 快速上手》；
• 項目是 TypeScript 的，看《Vercel AI SDK 是什麼》或《Mastra 是什麼》。

常見問題

Q：和 Pydantic 是什麼關係？

同一個團隊的作品。Pydantic 是做數據校驗的庫，Pydantic AI 用它來定義和校驗模型的輸出、工具的參數。

Q：能用國內的模型嗎？

官方的可選依賴組裏列了十幾家廠商，包括 openrouter、zai 等。具體哪些模型受支持、怎麼配置，以官方模型文檔為準。

Q：和 OpenAI Agents SDK 怎麼選？

主要用 OpenAI 的模型、想要官方的交接和追蹤，選前者，見《OpenAI Agents SDK 教學》；看重類型安全和跨廠商，選 Pydantic AI。

Q：result.output 校驗失敗會怎樣？

會報校驗錯誤。框架對重試的處理方式和配置項，以官方文檔為準。

參考資料

• pydantic/pydantic-ai（官方倉庫）：https://github.com/pydantic/pydantic-ai
• Installation（官方文檔）：https://pydantic.dev/docs/ai/install/