Pydantic AI 整合 Logfire 監控

當你的 AI 應用程式正式上線部署後，真正的挑戰才剛開始。「模型為什麼突然產生了錯誤的答案？」、「這次的對話消耗了多少 Token？花了多少 API 費用？」、「某個工具的執行速度是不是變慢了？」

為了回答這些問題，你需要可觀測性 (Observability)。Pydantic 團隊為此打造了強大的監控平台：Pydantic Logfire。而 Pydantic AI 框架對 Logfire 提供了原生且無縫的深度整合。

為什麼選擇 Logfire？

Logfire 是一個建立在標準 OpenTelemetry (OTel) 協定之上的可觀測性平台。它具備以下專為 AI 應用設計的優勢：

  1. 無縫整合：因為同屬 Pydantic 家族，Pydantic AI 的每一個內部動作（包含 Agent 的啟動、工具的呼叫、重試機制、Pydantic 模型驗證的成功與失敗）都已經內建了 Logfire 的追蹤埋點。你幾乎不需要寫任何額外的 Logging 程式碼。
  2. 視覺化追蹤 (Tracing)：在 Logfire 的儀表板上，你可以看到每次 run_sync 產生的完整瀑布圖 (Waterfall Chart)。你能清楚看見模型思考花了幾秒鐘、呼叫外部資料庫工具花了幾秒鐘，藉此精準找出效能瓶頸。
  3. 成本追蹤 (Cost Tracking)：Logfire 會自動解析不同模型提供商回傳的 Token 使用量，並換算成實際的花費，讓你可以即時監控專案的 API 成本。
  4. 結構化查詢：你可以使用類似 SQL 的語法去過濾與搜尋特定的對話紀錄，例如：「找出所有拋出 ModelRetry 的對話」，這對除錯極度有幫助。

如何整合 Logfire？

要在 Pydantic AI 中啟用 Logfire 非常簡單。首先，確保你已經安裝了包含 logfire 的依賴項 (pip install 'pydantic-ai[logfire]')，並且已經取得了 Logfire 的專案 Token。

import logfire
from pydantic_ai import Agent

# 第一步：初始化並設定 Logfire 專案
# 如果你已經在環境變數中設定了 LOGFIRE_TOKEN，這裡甚至不需傳入任何參數
logfire.configure()

# 第二步：讓 Logfire 自動攔截並記錄 Pydantic AI 的所有活動
logfire.instrument_pydantic() 

# 以下是一般的 Agent 開發邏輯
agent = Agent('openai:gpt-4o')

@agent.tool
def calculate_complex_math() -> float:
    # 這裡面的執行時間、變數狀態，都會自動被 Logfire 記錄並呈現成圖表
    return 42.0

result = agent.run_sync("請幫我計算那道複雜的數學題。")
print(result.data)

加上這兩行 logfire.configure() 與 instrument_pydantic()，你的終端機就不再只會印出單調的文字。所有的執行細節都會被即時傳送到 Logfire 的網頁主控台上。

支援替代的觀測平台

由於 Logfire 底層完全相容於 OpenTelemetry 標準，這也帶來了一個巨大的好處：如果你們公司已經在使用 Datadog、Honeycomb 或是自建的 Jaeger 等觀測平台，你可以非常輕易地將 Pydantic AI 的監控資料導流到這些現有的系統中。Pydantic AI 並不會將你綁死在特定的監控平台上。

為 AI 系統加上監控，是從「玩具專案」邁向「企業級生產系統」不可或缺的一步，而 Pydantic AI 與 Logfire 的組合，讓這一步走得無比輕鬆。