智能烹饪与饮食管理助手 · 你的个性化饮食英雄

简体中文 | English

---

---

📖 项目简介

CookHero（烹饪英雄）是一个融合 LLM、RAG、Agent、多模态与营养数据分析的个性化饮食管理平台。它不仅是菜谱库，更是一位能陪你做计划、做记录、看数据、给建议的“饮食管理英雄助手”，帮助你把烹饪与健康目标变成可执行的日常。

• 🔍 智能问答：解答烹饪技巧、食材搭配、营养知识等问题
• 🍽️ 个性化推荐：根据口味、目标和限制提供更贴合的菜品选择
• 🗓️ 饮食计划：按周规划三餐与加餐，形成可执行的饮食节奏
• 🧾 AI 记录：文字/图片一键记录，自动估算热量与宏量营养
• 📊 营养分析：每日/每周统计与计划偏差分析，持续优化习惯
• 🧠 深度理解：多轮对话理解用户意图，输出精准行动建议
• 🌐 实时搜索：结合 Web 搜索获取最新烹饪资讯和趋势

CookHero 面向厨房新手、健身/减脂/控糖人群、健康饮食倡导者、过敏体质用户及家庭场景，致力于让烹饪更专业、更智能、更可持续。

内部自带的食谱来源于Anduin2017/HowToCook，感谢该项目的贡献者！

---

⚡ 技术亮点

• LLM + RAG 混合检索：向量 + BM25 + Reranker 组合，配合多级缓存提速
• Agent ToolHub：ReAct 推理 + 工具调用，支持 MCP 动态扩展
• Subagent 专家体系：内置 + 用户自定义子代理，按需启用与编排
• 多模态解析：图片识别与饮食记录联动，覆盖烹饪与记录场景
• 评估与可观测性：RAGAS 质量评估 + LLM 使用统计 + 可视化看板
• 安全与合规：提示词注入防护、速率限制、结构化审计日志
• 现代化全栈：FastAPI + React + PostgreSQL + Milvus + Redis + MinIO

✨ 核心功能

1. Agent 智能饮食管家

• ReAct 模式：实现推理 + 行动循环，支持自主决策和工具调用
• 多模态支持：支持上传图片，图片自动上传到 imgbb 持久化存储
• 用户画像集成：自动读取用户画像和长期指令，提供个性化饮食管理服务
• Subagent 子代理：内置/自定义专家可作为工具被调用，独立 system prompt 与工具集
• Subagent 管理：个人中心创建/启用/禁用，工具选择器支持 Agents 面板
• 内置工具：
  • 饮食工具：计划管理、饮食记录、营养分析
  • 知识库检索：调用内置 RAG 检索并返回可引用来源
  • Web 搜索：集成 Tavily 搜索引擎，联网查询实时信息
  • AI 图片生成：基于 DALL-E 3 等模型生成图片，自动上传到 imgbb 持久化
  • 计算器：数学计算
  • 日期时间：获取当前时间、时区转换
• MCP 协议支持：支持用户自定义 MCP 服务器并配置鉴权头
• 可扩展架构：通过 AgentHub 统一管理 Agent、Tool 和 Provider
• 上下文压缩：自动压缩长对话历史，减少 Token 消耗
• 实时反馈：SSE 事件流，实时展示工具调用过程和结果
• 执行追踪：主 Agent 与 Subagent 轨迹分层展示，支持调试分析
• 工具选择：前端可动态选择工具与子代理

2. 饮食计划与记录

• 周视图管理早餐/午餐/晚餐/加餐，形成可执行的饮食计划
• 计划餐次自动汇总热量与宏量营养
• 一键标记已吃，计划自动转化为真实记录
• AI 解析文字/图片饮食描述，自动估算营养信息
• 支持餐次更新、复制与备注管理

3. 营养分析与目标追踪

• 每日/每周营养总览（热量、蛋白、脂肪、碳水）
• 计划 vs 实际偏差分析，识别饮食习惯波动
• 目标管理：卡路里/蛋白/脂肪/碳水目标
• 数据来源标记：手动、AI 文本、AI 图片

4. 智能对话式菜谱查询

• 自然语言理解用户需求（如"我想做一道低脂高蛋白的晚餐"）
• 支持多轮对话，记录上下文历史
• 自动识别用户意图（查询、推荐、闲聊等）
• 流式响应，支持实时显示生成内容

5. 个性化知识库

• 用户可上传私人食谱，系统自动分析并索引
• 全局食谱库（来自 HowToCook）与个人食谱融合查询
• 支持 Markdown 格式食谱的智能解析

6. 混合检索与重排序

• 向量检索：语义相似度匹配（基于 Milvus）
• BM25 检索：关键词精确匹配
• 元数据过滤：根据烹饪时间、难度、营养成分等筛选
• 智能重排序：使用 Reranker 模型（如 Qwen3-Reranker）对结果二次精排
• 多级缓存：Redis + Milvus 双层缓存，提升响应速度

7. 多模态支持

• 图片识别：支持上传食材/菜品/饮食图片进行智能识别
• 意图理解：结合图片和文字理解用户完整意图
• 多种场景：菜品识别、食材识别、烹饪指导、饮食记录、食谱查询
• 灵活接入：支持 OpenAI 兼容的视觉模型 API
• 图片限制：最多 4 张、单张 10MB（Agent/饮食记录场景）

8. RAG 评估系统

• 质量监控：基于 RAGAS 框架的自动化评估
• 核心指标：忠实度（Faithfulness）、答案相关性（Answer Relevancy）
• 异步评估：后台异步执行，不影响响应速度
• 趋势分析：支持评估趋势查看和质量告警
• 数据持久化：评估结果存储于 PostgreSQL

9. LLM 使用统计

• 实时监控：跟踪每个请求的 Token 使用量
• 性能指标：记录响应时间、思考时间、生成时间
• 统计分析：按用户、会话、模块统计使用情况
• 工具追踪：记录 Agent 工具调用名称
• 可视化展示：前端提供 LLM 统计数据页面

10. 安全防护体系

• 多层防护：输入验证 → 模式检测 → LLM 深度检测
• 提示词注入防护：基于规则和 AI 的双重检测机制
• 速率限制：Redis 滑动窗口算法，按端点类型区分限制
• 账户安全：登录失败锁定、JWT 过期策略、安全响应头
• 敏感数据保护：日志脱敏、API Key 过滤
• 安全审计：结构化 JSON 审计日志，支持 SIEM 系统对接

📖 详细安全架构请参阅 安全策略文档

---

🚀 快速开始

前置要求

• Python：>= 3.12
• Node.js：>= 18
• Docker 和 Docker Compose（推荐）

方法一：Docker 一键部署（推荐）

1. 克隆项目

   git clone https://github.com/Decade-qiu/CookHero.git
   cd CookHero

2. 配置环境变量

   cp .env.example .env
   # 编辑 .env 文件，填入必要的 API Key

3. 启动基础设施

   cd deployments
   docker-compose up -d

   这将启动：

   • PostgreSQL (端口 5432)
   • Redis (端口 6379)
   • Milvus (端口 19530)
   • MinIO (端口 9001)
   • Etcd (内部使用)

4. 安装 Python 依赖并启动后端

   cd ..
   python -m venv .venv
   source .venv/bin/activate  # Windows: .venv\Scripts\activate
   pip install -r requirements.txt
   
   # 初始化数据库
   python -m scripts.howtocook_loader
   
   # 启动后端服务
   uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

5. 启动前端

   cd frontend
   npm install
   npm run dev

6. 访问应用

   • 前端：http://localhost:5173
   • 饮食管理：http://localhost:5173/diet
   • 后端 API：http://localhost:8000
   • API 文档：http://localhost:8000/docs

---

⚙️ 配置说明

1. 环境变量 (.env)

创建 .env 文件（参考 .env.example）：

# ==================== LLM API 配置 ====================
# 主 API Key（所有模块的默认 Key）
LLM_API_KEY=your_main_api_key

# 快速模型 API Key（用于意图识别、查询改写等）
FAST_LLM_API_KEY=your_fast_model_api_key

# 视觉模型 API Key（用于多模态分析）
VISION_API_KEY=your_vision_model_api_key

# Reranker API Key（用于结果重排序）
RERANKER_API_KEY=your_reranker_api_key

# ==================== 数据库配置 ====================
DATABASE_PASSWORD=your_postgres_password

# Redis 密码（可选）
REDIS_PASSWORD=your_redis_password

# Milvus 认证（可选）
MILVUS_USER=root
MILVUS_PASSWORD=your_milvus_password

# ==================== Web 搜索 ====================
WEB_SEARCH_API_KEY=your_tavily_api_key

# ==================== MCP 集成 ====================
# 高德地图 MCP 服务 API Key
AMAP_API_KEY=your_amap_api_key

# ==================== 图片生成 ====================
# OpenAI 兼容的图片生成 API Key（DALL-E 3 等）
IMAGE_GENERATION_API_KEY=your_openai_api_key
# imgbb 图床 API Key（用于图片持久化存储）
IMGBB_STORAGE_API_KEY=your_imgbb_api_key

# ==================== 安全认证 ====================
JWT_SECRET_KEY=your_secure_jwt_secret_key
JWT_ALGORITHM=HS256

# 访问令牌过期时间（分钟）
ACCESS_TOKEN_EXPIRE_MINUTES=60

# 刷新令牌过期时间（天）
REFRESH_TOKEN_EXPIRE_DAYS=7

# ==================== 速率限制 ====================
RATE_LIMIT_ENABLED=true
RATE_LIMIT_LOGIN_PER_MINUTE=5
RATE_LIMIT_CONVERSATION_PER_MINUTE=30
RATE_LIMIT_GLOBAL_PER_MINUTE=100

# ==================== 账户安全 ====================
LOGIN_MAX_FAILED_ATTEMPTS=5
LOGIN_LOCKOUT_MINUTES=15
MAX_MESSAGE_LENGTH=10000
MAX_IMAGE_SIZE_MB=5
PROMPT_GUARD_ENABLED=true

2. 主配置文件 (config.yml)

config.yml 包含应用的核心配置：

# LLM 提供商配置（分层：fast / normal / vision）
llm:
  fast:    # 快速模型（低延迟）
  normal:  # 标准模型
  vision:  # 视觉模型（多模态）

# 数据路径
paths:
  base_data_path: "data/HowToCook"

# 嵌入模型
embedding:
  model_name: "BAAI/bge-small-zh-v1.5"

# 向量存储
vector_store:
  type: "milvus"
  collection_names:
    recipes: "cook_hero_recipes"
    personal: "cook_hero_personal_docs"

# 检索配置
retrieval:
  top_k: 9
  score_threshold: 0.2
  ranker_type: "weighted"
  ranker_weights: [0.8, 0.2]

# 重排序配置
reranker:
  enabled: true
  model_name: "Qwen/Qwen3-Reranker-8B"

# 缓存配置
cache:
  enabled: true
  ttl: 3600
  l2_enabled: true
  similarity_threshold: 0.92

# Web 搜索配置
web_search:
  enabled: true
  max_results: 6

# 视觉/多模态配置
vision:
  model:
    enabled: true
    model_name: "Qwen/QVQ-72B-Preview"

# 评估配置
evaluation:
  enabled: true
  async_mode: true
  sample_rate: 1.0

# MCP 配置
mcp:
  amap:
    enabled: true

# 图片生成配置
image_generation:
  enabled: true
  model: "dall-e-3"

# 图片存储配置（imgbb）
image_storage:
  enabled: true

# 数据库连接
database:
  postgres:
    host: "localhost"
    port: 5432
  redis:
    host: "localhost"
    port: 6379
  milvus:
    host: "localhost"
    port: 19530

详细配置说明见 config.yml 文件中的注释。

---

🗺️ 未来规划 (Roadmap)

• 多模态支持：食材图片识别、菜品识别 ✅
• RAG 评估系统：基于 RAGAS 的质量监控 ✅
• 安全防护体系：输入验证、提示词注入防护、速率限制 ✅
• LLM 使用统计：Token 监控、性能分析页面 ✅
• Agent 智能模式：ReAct 推理、工具调用、会话管理 ✅
• Subagent 专家体系：内置与自定义子代理、可视化追踪 ✅
• MCP 协议支持：远程工具加载、高德地图集成 ✅
• AI 图片生成：DALL-E 3 集成、imgbb 持久化存储 ✅
• 饮食计划与记录：周计划、已吃标记、AI 记录 ✅
• 营养分析与目标追踪：每日/每周摘要、偏差分析 ✅
• 语音交互：语音输入查询、语音播报步骤
• 社区功能：用户分享、评分、评论
• 智能食材管理：冰箱清单、食材过期提醒
• AR 烹饪指导：增强现实辅助烹饪
• 更多 Agent 工具：食谱搜索、营养计算、购物清单生成

---

🤝 贡献指南

欢迎贡献代码、提出问题或建议！

1. Fork 本项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 提交 Pull Request

---

📄 开源协议

本项目基于 APACHE LICENSE 2.0 许可证开源。详情请参阅 LICENSE 文件。

---

🙏 致谢

• HowToCook - 优质的开源食谱库
• LangChain - 强大的 LLM 应用框架
• Milvus - 高性能向量数据库
• FastAPI - 现代化的 Python Web 框架
• NVIDIA NeMo Guardrails - 先进的安全防护框架
• RAGAS - RAG 评估框架

---

如果这个项目对您有帮助，请给一个 ⭐️ Star 支持一下！