datapizza-ai：把 provider 換成設定項，而不是重寫業務邏輯

它想解決的是框架替你決定太多這件事

多數 GenAI 框架的賣點是幫你處理掉編排、記憶、工具呼叫的細節，代價是當你想改其中一環，得先讀懂框架的抽象。datapizza-ai 走反方向，README 把它寫成 no-fluff，強調 less abstraction、more control。這個定位決定了它的使用者輪廓：已經寫過 LLM 應用、知道 prompt 與工具鏈怎麼接、只想找一層薄薄的黏著層把 provider、工具與追蹤串起來的工程師。

反過來說，如果你是第一次做 RAG，或期待框架幫你決定 chunk 大小、retriever 策略與 agent 何時該呼叫哪個工具，這個專案給的預設值不多。它的 Agent 需要你明確傳入 client、tools 與 system_prompt，planner_agent.can_call([weather_agent, web_search_agent]) 這種寫法代表多 agent 的呼叫關係由你手工宣告，不是框架自動推導。少抽象等於少驚喜，也等於少保護。

Client、Agent、Tool 三層，資料流是顯式的

從 README 的範例可以看出三層結構。最底層是 client，例如 OpenAIClient(api_key="YOUR_API_KEY")，負責單次 invoke，回傳物件帶有 .text 屬性。中間層是 Agent，把 client、tools 與 system_prompt 綁在一起，對外提供 run()。最上層是工具，用 @tool 裝飾器把普通 Python 函式轉成模型可呼叫的形式，函式的型別註記（city: str）就是模型看到的參數描述。

多 agent 的組合方式是把 agent 當成另一個 agent 的可呼叫對象，planner_agent.can_call([weather_agent, web_search_agent]) 之後，planner 在 run 的過程中可以要求這兩個子 agent 做事。這是一種顯式的階層關係，不是自由廣播。文件沒有說明子 agent 的輸出如何合併回主 agent 的上下文，這部分得看 docs.datapizza.ai 的完整說明，README 只給到能跑起來的程度。

工具生態被拆成套件，DuckDuckGoSearchTool 來自獨立的 datapizza-ai-tools-duckduckgo，文件處理則提到 Azure AI 與 Docling。這種模組化讓核心保持輕，代價是你必須自己確認每個工具套件的版本與核心是否對得上。

安裝與最小可跑範例

核心安裝只有一行：pip install datapizza-ai。provider 與工具另外裝，README 列出 pip install datapizza-ai-clients-openai、pip install datapizza-ai-clients-google、pip install datapizza-ai-clients-anthropic，搜尋工具是 pip install datapizza-ai-tools-duckduckgo。Python 版本要求 3.10 以上，這是 README 徽章明示的。

最小範例是建立 client 後直接 invoke：client = OpenAIClient(api_key="YOUR_API_KEY")，result = client.invoke("Hi, how are u?")，再讀 result.text。要接工具就用 @tool 裝飾函式，把函式放進 Agent 的 tools 參數。追蹤則用 with ContextTracing().trace("my_ai_operation") 包住 agent.run()，README 展示的輸出是一張表，欄位包含 Model、Prompt Tokens、Completion Tokens、Cached Tokens，以及 Total Spans 與 Duration。

這裡有個實務細節值得注意：README 的範例把 api_key 直接寫在建構子裡，正式環境請改用環境變數或你的 secret manager，框架本身不負責這件事。另外追蹤範例中 client 用的是字串 "OPENAI_API_KEY" 而非實際金鑰，兩種寫法混在同一份文件裡，第一次照抄容易搞混。

追蹤是這個專案最實的部分，但別把它當成完整可觀測性

ContextTracing 的設計是包住一段操作，收集期間產生的 span，最後印出摘要。README 說明它基於 OpenTelemetry，並提供 client I/O tracing 的開關，可以記錄輸入、輸出與記憶體中的上下文。對除錯來說，能直接看到 token 用量與快取命中，比在日誌裡翻找便宜得多。

需要分清楚的是，這是追蹤，不是評估。它告訴你這次跑了多少 span、花了多久、用了多少 token，不會告訴你回答品質好不好。文件也沒有提到內建的 eval 流程或資料集管理。如果你的品質驗證目前靠人工抽查，換到這個框架後仍然要靠人工抽查，只是抽查時多了 token 與延遲的數字可看。

另一個未在 README 交代的點是 span 的匯出方式。既然標榜 OpenTelemetry 標準，理論上可以接到既有的 collector，但匯出設定、取樣率、與既有 APM 的整合方式，材料裡都沒有範例，這部分必須查官方文件才能判斷能不能接進你現有的觀測堆疊。

版本節奏與維護成本要先算清楚

從 release 列表看，v0.0.7 在 2025 年 10 月底，v0.0.9 在 11 月初，v0.1.0 到 2026 年 3 月中，最近一次 push 是 2026 年 5 月。這個節奏說明專案還在 0.x 階段，且並非每週都在動。0.x 意味著介面有調整空間，官方也沒有承諾語意化版本。

對採用者的實際影響是：核心與週邊套件（clients、tools）分開發版，升級時要一起看。如果某個工具套件落後於核心，可能出現介面不匹配。建議在 requirements 或 lock 檔中把 datapizza-ai 與各 datapizza-ai-* 套件都釘住版本，而不是只釘核心。

授權是 MIT，這對商業使用相對寬鬆，可以修改、散布、用於閉源產品，但必須保留著作權與授權聲明。這是授權條款的通則，不是法律意見，實際條文仍應以 opensource.org 上的 MIT 全文與你組織的法務判斷為準。

什麼情況下它會是錯的工具

第一種情況是你需要框架幫你做決策。datapizza-ai 的 Agent 不做自動工具選擇策略的抽象，多 agent 的呼叫關係要你用 can_call 手工宣告。任務一複雜，這份宣告清單就會變成你要自己維護的拓樸圖。

第二種情況是你的流程有大量分支與狀態持久化需求。README 提到 memory management 與 persistent conversations，但沒有給出儲存後端、序列化格式或跨程序恢復的說明。如果對話狀態必須存活於服務重啟，你得自己接一層儲存，框架給的幫助有限。

第三種情況是你需要內建評估。前面提過，追蹤與評估是兩件事。要做回歸測試或 A/B 比較 prompt，這個專案沒有對應模組，你得自己搭。

還有一種容易被忽略的情況：如果你的團隊已經深度使用某個 provider 的原生 SDK，而且用到了該 SDK 特有的功能（例如特定的檔案上傳或助理 API），換到統一介面反而會失去這些能力。抽象層只保留共通的部分，這是所有多 provider 框架的共通代價。

和 LangChain 的差別在抽象深度，不在功能清單

拿 LangChain 對比最直接。LangChain 提供大量預建的 chain、retriever 與 agent 類型，你組裝的是它定義好的積木；datapizza-ai 提供的是 client、Agent、tool 三個基本件，組裝方式由你決定。前者的學習曲線在於理解它的抽象，後者的學習曲線在於你自己設計流程。

這個差異在除錯時最明顯。LangChain 的呼叫堆疊深，出錯時要沿著 chain 往回找；datapizza-ai 的堆疊淺，搭配 ContextTracing 印出的 span 摘要，比較容易定位是哪一次模型呼叫或哪個工具出問題。反過來說，LangChain 的生態系與現成元件多，當你的需求剛好落在它既有積木上時，開發速度會快很多。

選擇的判準不是哪個比較好，而是你的團隊想不想自己擁有流程的定義權。想要現成積木就選生態大的，想要自己掌控就選薄的。datapizza-ai 明確站在後者。

編輯結論

如果你已經知道自己要什麼樣的 agent 流程，只是不想被某一家的模型 API 綁死，datapizza-ai 的 client 抽象與 ContextTracing 值得放進評估清單，安裝就是 pip install datapizza-ai 加上對應的 client 套件。如果你需要的是自動規劃、複雜狀態機或內建 eval 平台，這個專案目前沒有提供，硬套只會讓你補更多自製層。動手前先確認兩件事：你的 Python 版本是否達到 3.10 以上，以及你打算用的 provider 是否已有對應的 datapizza-ai-clients-* 套件，否則就得自己接。

官方來源

1. datapizza-labs/datapizza-ai on GitHub
2. License: MIT
3. Project website
4. README
5. Releases