Pydantic AI¶

概述¶

Pydantic AI 係一個建構結構化 LLM 代理（structured LLM agents）嘅 Python framework，由 Pydantic 團隊維護。佢同一般「直接 call LLM」嘅做法唔同，核心係用 Pydantic Schema 驗證模型輸出，令代理回傳嘅唔止係自然語言，而係型別安全、可以直接畀程式用嘅結構化數據。

本機呢套部署將 Pydantic AI 放入 Docker 容器，並連接 LiteLLM 同 FastMCP，令代理可以經 MCP 呼叫外部工具。由於佢係私有雲內部服務，Docker Compose 刻意唔開 host port，只喺 cf_network 網絡內部運作。

架構¶

由真實 Compose 節選可見，pydantic-ai 服務有以下特性：

container_name: pydantic-ai
image: pydantic-ai:latest
網絡使用外部 cf_network，並設定固定 IP 172.21.0.57
唔對外開放 port，ports 段落被註解
容器內部聆聽 8100，其他服務可用 http://pydantic-ai:8100 訪問
healthcheck 每 30 秒檢查一次 127.0.0.1:8100/health

實際請求流程如下：

n8n 或其他內部服務向 http://pydantic-ai:8100 發出請求。
Pydantic AI 根據 MODEL 決定要使用 openai:deepseek-first。
佢經 OPENAI_BASE_URL=http://litellm:4000/v1 將請求送往 LiteLLM。
LiteLLM 再將請求轉發至對應實際模型，例如 DeepSeek。
若代理需要工具，Pydantic AI 會經 FASTMCP_URL=http://fastmcp:8000/mcp 連接 FastMCP。

呢種設計令 Pydantic AI 同外界完全隔離。若果要對外提供服務，通常係經 Cloudflare Tunnel 接入 n8n，再由 n8n 喺內部網絡呼叫 Pydantic AI。

部署¶

部署前必須確認 cf_network 已經存在，因為 Compose 使用 external: true，唔會自動建立：

docker network inspect cf_network >/dev/null 2>&1 || \
  docker network create --subnet=172.21.0.0/24 cf_network

準備 .env：

OPENAI_API_KEY=sk-...
PYDANTIC_AI_API_KEY=my-internal-secret
SYNC_TIMEOUT=180

然後建立並啟動服務：

docker compose up -d --build pydantic-ai

如果之後要更新鏡像：

docker compose build --pull pydantic-ai
docker compose up -d pydantic-ai

要留意固定 IP 172.21.0.57 必須未被其他容器佔用，可以用 docker network inspect cf_network 檢查。

配置¶

主要環境變數：

變數	預設值	作用
`TZ`	`Asia/Hong_Kong`	設定容器時區
`MODEL`	`openai:deepseek-first`	LiteLLM 嘅模型 alias，唔一定等於實際 provider 名稱
`OPENAI_BASE_URL`	`http://litellm:4000/v1`	LiteLLM 提供嘅 OpenAI-compatible endpoint
`OPENAI_API_KEY`	由 `.env` 傳入	用嚟向 LiteLLM 認證
`FASTMCP_URL`	`http://fastmcp:8000/mcp`	MCP server 地址
`API_KEY`	`${PYDANTIC_AI_API_KEY}`	其他服務呼叫 Pydantic AI 時需要提供嘅 token
`SYNC_TIMEOUT`	`180`	同步等待 LLM / MCP 回應嘅 timeout

MODEL 嘅 openai:deepseek-first 格式表示 Pydantic AI 用 OpenAI SDK 型式經 LiteLLM 存取模型；實際模型名稱要喺 LiteLLM config 對應好，否則會出現 model not found。

維運與監控¶

日常建議用以下指令檢查：

docker logs --tail=100 -f pydantic-ai
docker exec pydantic-ai python -c \
  "import urllib.request;print(urllib.request.urlopen('http://127.0.0.1:8100/health',timeout=3).status)"

由於 Pydantic AI 冇 host port mapping，喺主機直接 curl localhost:8100 必然失敗。應該由同一個 cf_network 內嘅容器測試：

docker exec -it n8n curl -i http://pydantic-ai:8100/health

restart: unless-stopped 確保容器異常退出時會自動重試。若容器持續重啟，優先檢查 LiteLLM 是否正常、OPENAI_BASE_URL 是否正確，以及 cf_network 內 DNS 解析。

Healthcheck 參數 interval: 30s、timeout: 5s、retries: 3、start_period: 10s 代表容器起動後有 10 秒寬限期，之後先開始計數。連續 3 次失敗，Docker 就會重啟容器。

常見問題¶

Q：點解主機連唔到 localhost:8100？

因為 Compose 註解咗 ports，服務只存在於 Docker cf_network 內部。要由其他容器用 http://pydantic-ai:8100 存取。

Q：Healthcheck 持續失敗，容器會點？

Docker 會根據 retries 重啟容器。若果 litellm 或 fastmcp 唔可用，/health 可能都受影響，需要檢查上游服務。

Q：回傳 model not found？

MODEL 入面嘅 openai:deepseek-first 必須喺 LiteLLM 入面有對應 model entry。檢查 LiteLLM 設定同 logs，確認 alias 正確。

Q：FastMCP 工具冇反應？

確認 FASTMCP_URL 正確，而且 Pydantic AI 容器可以用 fastmcp:8000 連接到 FastMCP。可以用 docker exec 入容器內測試網絡連通性。

來源¶

自動生成（2026-08-19 容器覆蓋率補完第二批）

Pydantic AI¶

概述¶

架構¶

部署¶

配置¶

維運與監控¶

常見問題¶

相關鏈接¶

來源¶