CookHero：把 LLM、RAG 與 Subagent 裝進 Docker，自架一套會記錄三餐的開源飲食管理 Agent

用 AI 摘要這篇文章：

ChatGPT Claude Perplexity Google Grok

廚房新手、減脂期、健身族群、過敏體質、在家下廚的雙薪家庭，或多或少都遇過同一組問題：今天到底吃什麼、昨天那頓到底熱量超標多少、上週那道喜歡的菜譜在哪、用手動輸入的方式把照片裡的食物換成數字太麻煩。多數既有飲食 App 解了條碼與品項這一題，卻沒解「我今晚想用冰箱剩下的雞腿與番茄做點低脂高蛋白的晚餐」這種意圖混合的需求。CookHero（GitHub：Decade-qiu/CookHero）這個 2025 年 11 月開源、Apache 2.0 授權的專案，把這幾個問題裝進一個用 LLM、RAG 與多模態 Subagent 構成的飲食管理 Agent 裡，可以 Docker 自架，作者把它定位為「智能烹飪與飲食管理助手」。這篇把它跟市面飲食 App 的差別、Agent 在裡面到底跑什麼、自架的代價與限制一次講清楚。

重點先看：CookHero 是 Apache 2.0、Python 3.12 + FastAPI + LangChain 1.1 + LangGraph 1.0 + Milvus 2.6 的全棧飲食管理 Agent，截至 2026-07 在 GitHub 有 580 stars、88 forks、33 個 open issues（多數是 dependabot 自動依賴更新），最後一次 commit 落在 2026-03；特色是把 RAG 混合檢索、ReAct Agent、Subagent 專家體系、多模態飲食記錄、RAGAS 評估線全串起來，但預設仰賴 OpenAI、Anthropic、Tavily、DALL·E、imgbb 等雲端 API，要做到「資料完全不出本地」必須自己改接 Ollama、停用圖片生成與 Web 搜尋。

三個讀者最常問的問題

關於 CookHero，最常被問到的三個問題是：第一，它跟 MyFitnessPal、薄荷健康這類已經成熟的飲食記錄 App 差在哪？第二，LLM、RAG、Subagent 在這套系統裡各自跑什麼、真的有比傳統檢索更有感嗎？第三，自己用 Docker 部署需要哪些服務、隱私是不是真的留在本機？這三題答完，要不要裝的判斷就會很明確。如果你只想看結論，可以直接跳到最後一段「適合誰、不適合誰」；如果想理解它為什麼被視為當代 LLM 應用的完整範本，請跟著下面三段技術拆解一起看。

它跟 MyFitnessPal、薄荷健康的差別：Agent 取代清單

市面飲食 App 的核心是「資料庫＋條碼＋手動輸入」：你掃一條條碼、選一份預設份量、再自己微調，營養數字靠後台資料庫配對。CookHero 把核心換成 Agent：你用一句話問它「我今晚想吃低脂高蛋白的晚餐、不想再吃雞胸了」，它會先做意圖判斷（你是要查食譜、推薦、還是閒聊），再去 RAG 知識庫檢索，接著用 ReAct 推理循環呼叫對應工具，例如飲食計畫管理、飲食記錄、營養分析、Web 搜尋（Tavily）、AI 圖片生成（DALL·E 3）、計算機、日期時間；最後用 SSE 串流把推理過程與答案一起吐回前端。差別不是「它也能記錄」，而是它把記錄、計畫、查詢、分析包進一個會自己決策的 Agent，使用者面對的是對話而不是表單。

Pin

成熟 App 的優勢是資料庫厚、條碼涵蓋廣、社交與穿戴整合深；CookHero 在這些維度反而薄。它的內建食譜來源是 Anduin2017/HowToCook 這份程式員社群食譜集，本身偏家常菜與簡單料理，使用者可以上傳私人食譜做 Markdown 解析再混入檢索，但條碼掃描、連鎖餐廳套餐、超商食品這類型錄它沒有。把它想成「會推理的飲食助理」而非「條碼與品項資料庫」比較準。它真正能拉開差距的場景是「我今晚想用冰箱裡剩下的雞腿與番茄做點減脂可以吃的、順便算一下蛋白質」這種意圖混合、需要跨工具呼叫的需求，這在 MyFitnessPal 上幾乎做不到。

LLM、RAG、Subagent 各自在做什麼

多數介紹文講到「LLM 加 RAG 加 Agent」就停在那串名詞，但 CookHero 的 README 與 requirements.txt 把這三層的角色分得很清楚。LLM 負責理解使用者意圖、生成回答、做圖片辨識後的結構化提取（把「這是一盤番茄炒蛋」換成 JSON 營養欄位），預設是 OpenAI 相容 API，也能改接 Anthropic Claude 或本機 Ollama 跑 Llama 3。README 的 .env.example 同時要求 LLM_API_KEY、FAST_LLM_API_KEY、VISION_API_KEY、RERANKER_API_KEY 四組 key，也就是它把「主力模型／快模型／視覺模型／重排序模型」拆成四個可獨立替換的 provider，這在實務上比「單一 OpenAI key 跑全部」更有彈性，但部署時要準備的 key 也比較多。

RAG 在 CookHero 裡是混合檢索而非單純向量檢索：Milvus 做語意向量相似度、BM25 做關鍵字精確匹配、Reranker（預設接 Qwen3-Reranker 這類模型）做第二階段精排、Redis 加 Milvus 雙層快取加速重複查詢。它的食譜知識庫是 HowToCook 預設集加上使用者私人上傳的 Markdown 食譜，兩者融合後再被檢索；這意味著你寫的私人食譜不會被公開倉庫收走，但會被向量化後存在本機 Milvus 裡。Agent 採 ReAct 模式（Reasoning + Acting 迴圈），每一步先推理「我該不該用某個工具」再呼叫工具，再根據工具回傳結果決定下一步；這套結構由 LangGraph 負責編排，README 提到長對話會被自動壓縮以控制 token 消耗（未明說底層實作細節，requirements.txt 同時裝了 langgraph-checkpoint 與 langgraph-prebuilt 兩個套件）。

Subagent 是 CookHero 比較少被討論但設計得有想法的一層。每個 Subagent 是一個有獨立 system prompt 與獨立工具集的專家，主 Agent 可以把它當工具呼叫；使用者能在個人中心自建 Subagent、決定它的工具集合、啟用停用。這個設計讓 CookHero 不只是「一個會查食譜的機器人」，而是「一個能被你擴充的飲食助理框架」：你可以做一個「媽媽的私房菜 Subagent」只檢索你上傳的家族食譜，或做一個「減脂期嚴格把關 Subagent」專門拒絕高油請求。這個模式跟 Refly 那種能匯出給 Cursor 與 Claude Code 的 Agent Skills 構建器概念相近，差別在 CookHero 的 Subagent 只在自身平台內生效，並不會產出跨工具的 skill 檔。

自架需要哪些服務、隱私真的留在本機嗎

CookHero 的部署是「重裝」等級。docker-compose 一次起 PostgreSQL（業務資料）、Redis（快與限流）、Milvus 2.6 加上 etcd 與 MinIO（向量與物件儲存）、再起 FastAPI 後端與 React 前端，所以你至少要準備一台 4GB 以上 RAM 的機器，建議 8GB；Milvus 與嵌入模型本身吃資源較重。Python 後端要求 Python 3.12、Node 18 以上、再裝一份 requirements.txt，整套跑起來包含資料庫初始化、HowToCook 食譜載入、User schema 建表等幾個步驟，沒有一鍵啟動那麼輕，但也稱不上難；作者在 README 把 Docker Compose 列為推薦路徑，並提供 scripts/howtocook_loader 這個初始化腳本。

Pin

隱私這題必須分兩個層次看。結構化資料（你的飲食記錄、計畫、Subagent 設定、使用者畫像）確實儲存在你本機的 PostgreSQL，第三方雲服務拿不到；MinIO 存你上傳的食材與菜盤照片、Redis 做快取、Milvus 存向量化後的食譜與私人筆記，這四個儲存層都可以鎖在私有網路內，這點符合 Docker 自架的承諾。但推理與生成這條資料流向預設是雲端：你問 CookHero 一個問題、上傳一張菜盤照片、請它生成一張示意圖，預設會把請求送到 OpenAI 或 Anthropic、視覺模型 provider、DALL·E 3、Tavily，imgbb 也會被用來持久化 AI 生成的圖片。換句話說，「資料完全不出本地」並不是 CookHero 的預設行為，而是你必須額外設定才能達成的進階配置：把 LLM_API_KEY 改接 Ollama、停用圖片生成、把視覺模型也改成本地模型、停用 Tavily Web 搜尋，這條鏈全改完，才會接近作者在 README 裡聲稱的「0 資料出境」。把這點看清楚再決定要不要部署，會比開箱後才發現 API 帳單與雲端依賴來得實際。

與其他自架 AI 工具的定位比較

把 CookHero 跟幾個 TechMoon 寫過的自架 AI 工具擺在一起看，定位會更清楚。跟 QuantDinger 這種 Docker 自架的開源 AI 量化交易工作台相比，兩者都把「研究、執行、紀錄」三件事留在自己伺服器，差別是 QuantDinger 服務金融決策、CookHero 服務生活決策，部署複雜度相近（都需要 PostgreSQL 加專屬資料庫）。跟 MimiClaw 那種用 5 美元 ESP32 跑一台本地 AI 助理相比，MimiClaw 走的是極輕量邊緣部署、靠 Claude 雲端推理但本地當閘道；CookHero 走的是完整 Agent 框架、所有組件都能本機化但代價是機器規格與維護成本。跟一般自架 RAG 知識庫（Paperless-ngx、AnythingLLM 等）相比，CookHero 把飲食與營養的 domain logic 直接做進 Agent，不是通用文件庫，因此對「飲食管理」這個垂直場景更上手，但對「我要管理發票或合約」這種通用需求反而不適合。

已知限制：API key 數量、雲端依賴、無正式 release

實際看 GitHub 倉庫與 README，CookHero 目前有幾個明顯限制。第一，它依賴大量外部 API key：LLM_API_KEY、FAST_LLM_API_KEY、VISION_API_KEY、RERANKER_API_KEY、WEB_SEARCH_API_KEY（Tavily）、OPENAI_IMAGE_API_KEY、AMAP_API_KEY（高德地圖，這個會把地理查詢送到中國大陸服務），還有 PostgreSQL / Redis / Milvus 三組服務密碼與 JWT_SECRET_KEY，初學者部署要花時間理解每一把 key 的用途與替換策略。第二，截至 2026-07 倉庫沒有正式 release tag，所有更新都靠 main 分支的 commit 與 dependabot 自動依賴 bump，最近的提交落在 2026-03，頻率不算密集，適合「想自己改」的人、不適合「等穩定版」的人。第三，33 個 open issues 大多是 dependabot 機器人發的依賴升級 PR，真正的功能 issue 與 bug 量級不大，但也意味著社群討論度還在起步。

另一個更尖銳的限制是營養數字的準確性。RAG 能降低 LLM 的幻覺，但 CookHero 對「這盤番茄炒蛋熱量多少」這類估算，仍是 LLM 結合視覺模型與常識資料庫的近似值，不是實驗室測定；README 整體精神也強調 AI 估算僅供資訊參考、不構成專業領域建議。如果你是糖尿病、腎臟病、孕期、嬰幼兒飲食、過敏嚴格控制的族群，CookHero 可以幫你記錄與查詢，但營養目標與飲食處方仍應回到專業營養師與醫師，這條界線在 self-hosted AI 工具上尤其要畫清楚，否則很容易把「AI 給的數字」當成「臨床數字」。

RAGAS 評估、安全防護與多模態細節

除了 Agent 主流程，CookHero 還內建了三個對企業部署有感的附屬系統。第一是 RAGAS 評估：README 第 8 節寫到它用 RAGAS 框架做非同步的離線品質評估，追蹤 Faithfulness（忠實度，衡量回答有沒有超出檢索內容）與 Answer Relevancy（答案相關性，衡量回答有沒有命中問題），評估結果存在 PostgreSQL、前端有視覺化頁面可以看趨勢與告警，requirements.txt 實際安裝的是 0.4.x（README badge 標的 0.2 已過時）；這對自架者來說等於自帶一套 RAG 品質監控，不是「跑起來就擺著」。第二是安全防護：README 第 10 章列出多層防護（規則偵測加 LLM 深度偵測），requirements.txt 含 NeMo Guardrails（README badge 標 0.12 已過時，實際為 0.19.x），並用 Redis 滑動視窗做速率限制（依端點類型不同）、JWT 過期策略與登入失敗鎖定、結構化 JSON 審計日誌（可對接 SIEM）、API Key 在 log 中自動脫敏。這套安全設計在個人 side project 等級的 RAG 應用裡並不常見。

第三是多模態細節與限制。CookHero 的圖片處理在 Agent 與飲食記錄兩個場景都做了限制：單次最多 4 張圖、單張 10MB（README 寫的值，但 .env.example 預設的 MAX_IMAGE_SIZE_MB 是 5，實際部署要先看 .env 怎麼設），AI 生成的圖片會自動上傳到 imgbb 做持久化（這也是另一條預設外送路徑，要停用就得關掉圖片生成功能，imgbb 也需要額外一把 IMGBB_STORAGE_API_KEY）。視覺模型走 OpenAI 相容 API，可以改接其他視覺模型 provider；要支援本機視覺模型，必須自己架一套相容 OpenAI Vision endpoint 的服務。這些技術選型與限制在 README 的「安全防護體系」與「多模態支援」兩節都有說明，對照原始碼 app/main.py 與 app/agents/ 目錄可以進一步驗證。把 RAGAS、安全與多模態這三層加起來看，CookHero 比較接近「一個設計完整的 LLM 應用範本」而不是「快速記熱量的玩具 App」。

部署流程與必要的調校

如果你看完上面的限制仍想自架，流程大致是這樣：先 clone 倉庫，把 .env.example 複製成 .env，把上述七八把 key 與密碼填好；走進 deployments 目錄執行 docker-compose up -d 起 PostgreSQL、Redis、Milvus、MinIO 與 etcd；回到根目錄建 Python 3.12 virtualenv、裝 requirements.txt、跑 python -m scripts.howtocook_loader 把 HowToCook 食譜塞進資料庫與向量庫；最後 uvicorn app.main:app --host 0.0.0.0 --port 8000 起後端、進 frontend 跑 npm install && npm run dev 起前端。整套跑完在 8GB 機器上大約十分鐘內可以起來，瓶頸通常卡在 Milvus 首次下載 embedding 模型。

想做到真正的隱私優先，部署完後還要做三個調校：把 LLM provider 改接 Ollama（在 .env 指向本機 endpoint）、把視覺模型也改成本機或停用圖片記錄功能、停用 Tavily 與 DALL·E 圖片生成。如果你不在意雲端推理、只在意結構化資料落地，那就只要保留原本 API key 配置、把 PostgreSQL 與 MinIO 的 volume 掛到本機磁碟即可。但請務必把 AMAP_API_KEY 留空，否則當你觸發地圖相關查詢時會把查詢送到高德地圖伺服器，這在隱私分析裡通常被忽略、卻是預設啟用的一條外送路徑。

適合誰、不適合誰

CookHero 適合三種人：一是會 Docker 與 Python、想在自己的 NAS 或小伺服器上跑一套「有 Agent 邏輯的私人飲食助理」的技術玩家；二是健身、減脂、控糖族群中已經對 MyFitnessPal 與薄荷健康的條碼資料庫厭倦、想要更客製化推理邏輯的人；三是正在學 LangChain、LangGraph、Milvus、RAGAS，想用一個真實非玩具專案當學習範本的開發者，CookHero 的 README 與程式碼結構完整、涵蓋 Agent ToolHub、Subagent、混合檢索、RAGAS 評估、安全防護（提示詞注入偵測、速率限制、結構化審計日誌）等多個現代 LLM 應用必學的主題。

不適合的也清楚：只想掃條碼、看連鎖餐廳熱量、跟 Apple Health 或 Garmin 同步的人，請留在 MyFitnessPal；要的是臨床級營養處方的人，請找營養師；不能接受「沒有正式 release tag、要自己追 main 分支」的人，請等專案成熟再回來。CookHero 真正的賣點不是「比 MyFitnessPal 厲害」，而是「把 LLM、RAG 與 Subagent 這三個當代 AI 應用最關鍵的技術，用一個可運作、可自架、可改作的飲食場景全部串起來」，對應用層的學習價值高於純工具價值。把它放對位置，它會是一個值得定期回來看的專案。

常見問題

CookHero 是免費的嗎？專案本身 Apache 2.0 開源、免費、可商業改作，但執行時呼叫的 OpenAI、Anthropic、Tavily、DALL·E 等服務會按你自己的方案計費，改接 Ollama 後這條費用可降至零（但要自付 GPU 電費）。

CookHero 有手機 App 嗎？沒有原生 App，是網頁應用（FastAPI 後端加 React 前端），透過瀏覽器開啟，並提供 SSE 串流回應。手機使用需要你自己做內網穿透或部署到有 HTTPS 的網域。

CookHero 支援繁體中文嗎？預設走簡體中文（README 與 HowToCook 食譜來源都是簡體），但因為底層是 LLM，用繁體中文發問也能正常回應；食譜知識庫若要全面繁體化需要自己做一次 s2tw 轉換或上傳繁體食譜。

跟 OpenClaw、Claude Code 這類通用 Agent 框架相比，CookHero 的不可替代性在哪？通用 Agent 框架什麼都能做、但什麼都要你自己接；CookHero 把飲食計畫、營養分析、食譜 RAG、飲食記錄的 Subagent 都先寫好，這是垂直整合的價值。如果你的需求就是飲食管理，從 CookHero 改起會比從通用框架拼起快很多。

CookHero 的營養數字能當醫療參考嗎？不行。即使有 RAG 與視覺模型，CookHero 的營養估算仍是 AI 近似值，README 整體精神也強調僅供資訊參考、不構成醫療或營養專業建議。臨床需求請回到專業人員。

最後回到一開始那三個問題。CookHero 與 MyFitnessPal 的差別是 Agent 取代清單、是混合 RAG 與 Subagent 取代條碼資料庫；LLM、RAG、Subagent 三層各自負責理解、檢索、專家分工，並透過 LangGraph 編排成可除錯的推理鏈；自架需要 PostgreSQL、Redis、Milvus、MinIO 等服務一起跑、資料結構確實落在本機、但推理與生成預設還是走雲端 API，要做到零外送必須額外改接 Ollama 並停用 Tavily、DALL·E、AMAP 三條外送路徑。把它放對位置：它是「用飲食場景展示當代 AI Agent 全套技術」的可自架學習範本，不是 MyFitnessPal 的殺手，把它當成這樣用，它的價值會比單純比功能清單來得高。

CookHero GitHub 倉庫：github.com/Decade-qiu/CookHero（Apache 2.0、Python 3.12、580 stars，對應 2026-07 倉庫狀態）。