GreenDish-人工智能素食菜单分析仪

一个基于微服务的智能系统，处理餐厅菜单照片，使用OCR、LangGraph AI代理、LLM分类、RAG和MCP架构识别和计算素食菜肴的总价。

概述

GreenDish结合了尖端的人工智能技术，帮助用户从菜单照片中识别素食选项：

OCR（Tesseract） -通过预处理从菜单图像中提取文本
结构化解析 -将OCR输出转换为规范 {name, price, raw_text} JSON
LangGraph代理 -协调菜肴分类、RAG回退和MCP工具使用
LLM分类 -使用Groq(openai/gpt-oss-20b)使用OpenRouter回退
RAG（检索增强生成） -ChromaDB+句子转换器增强信心
MCP服务器 -通过模型上下文协议进行确定性价格计算
朗史密斯 -完全可观察性和跟踪
交互式用户界面 -带LLM聊天平台的Streamlit测试界面

系统架构

┌─────────────────────────┐
│    Streamlit UI         │  (Testing + LLM Playground)
│  - Image Upload         │
│  - Results Viewer       │
│  - Chat Interface       │
└───────────┬─────────────┘
            │ HTTP
            ▼
┌───────────────────────────────────────────────┐
│           REST API Service                    │
│                                               │
│  ┌─────────────────────────────────────────┐ │
│  │      LangGraph Agent Workflow           │ │
│  │  ┌──────────┐  ┌──────────┐  ┌────────┐│ │
│  │  │Classifier│→ │RAG Check │→ │MCP Tool││ │
│  │  │  Node    │  │  Node    │  │  Node  ││ │
│  │  └──────────┘  └──────────┘  └────────┘│ │
│  └─────────────────────────────────────────┘ │
│                                               │
│  - OCR Service (Tesseract)                   │
│  - Parser Service (Structured JSON)          │
│  - LLM Router (Groq → OpenRouter)            │
└───────────┬───────────────────────────────────┘
            │ HTTP (MCP Protocol)
            ▼
┌───────────────────────────┐
│    MCP Server Service     │
│  - calculate_vegetarian   │
│    _total tool            │
│  - Deterministic logic    │
└───────────────────────────┘
            │
            ▼
┌───────────────────────────┐
│  LangSmith Observability  │
│  - Trace requests         │
│  - Token usage            │
│  - Performance metrics    │
└───────────────────────────┘

项目结构

GreenDish/
├── api/                          # REST API service (FastAPI)
│   ├── agents/                   # LangGraph agent workflows
│   │   ├── menu_processor.py    # Main agent state machine
│   │   └── nodes/                # Agent node implementations
│   │       ├── classifier_node.py
│   │       ├── rag_node.py
│   │       └── calculator_node.py
│   ├── llm/                      # LLM client utilities
│   │   ├── groq_client.py        # Groq integration (primary)
│   │   ├── openrouter_client.py  # OpenRouter fallback
│   │   └── router_client.py      # LLM router with auto-fallback
│   ├── routers/                  # API endpoints
│   ├── services/                 # Business logic
│   │   ├── ocr_service.py
│   │   ├── parser_service.py
│   │   └── classifier_service.py
│   ├── models/                   # Pydantic schemas
│   ├── data/                     # Seed data (vegetarian_db.json)
│   ├── rag_db/                   # ChromaDB persistent storage
│   ├── config.py                 # Centralized configuration
│   └── main.py                   # FastAPI app entry point
├── mcp-server/                   # MCP calculation service
│   ├── tools/                    # MCP tool implementations
│   └── server.py                 # MCP server entry point
├── streamlit-ui/                 # Interactive testing UI
│   ├── pages/                    # Multi-page app
│   │   ├── 1_OCR_Test.py
│   │   ├── 2_Parser_Test.py
│   │   └── ...
│   └── app.py                    # Main dashboard
├── tests/                        # Pytest test suite
│   ├── fixtures/images/          # Test menu images
│   ├── api/                      # API tests
│   ├── mcp/                      # MCP tests
│   └── services/                 # Service layer tests
├── scripts/                      # Utility scripts
│   └── test_ocr.py               # Quick OCR validation
├── docs/                         # Documentation
│   ├── phases/                   # Phase-wise planning docs
│   ├── architecture.md           # Detailed architecture
│   └── requirements.md           # Original requirements
├── docker-compose.yml            # Docker orchestration
├── .env.example                  # Environment template
└── CLAUDE.md                     # AI assistant guidelines

技术栈

核心框架

Python 3.11+ -带有类型提示的现代Python
快速API -高性能异步REST API
溪流 -用于测试的交互式web UI
MCP-SDK -模型上下文协议服务器
紫外线 -快速、可靠的Python包管理器

AI/ML堆栈

LangGraph -代理工作流编排
格罗克API -主要法学硕士提供者(openai/gpt-oss-20b)
开放路由 -后备LLM提供商(deepseek/deepseek-chat-v3.1)
色度数据库 -RAG矢量数据库
句子变换器 -嵌入件(all-MiniLM-L6-v2)
朗史密斯 -追踪和可观察性

OCR和处理

Tesseract OCR 5.x -文本提取
pytesseract -Python包装器
枕头（PIL） -图像预处理

基础设施

Docker&Docker编写 -集装箱化
httpx -异步HTTP客户端
皮丹提克 -数据验证
媒染剂设置 -配置管理

快速开始

先决条件

Python 3.11+ - 下载
紫外线 -快速Python包安装程序

   # Via curl (recommended)
   curl -LsSf https://astral.sh/uv/install.sh | sh

   # Via pip
   pip install uv

   # Via Homebrew (macOS)
   brew install uv

Tesseract OCR

   # macOS
   brew install tesseract

   # Ubuntu/Debian
   sudo apt-get install tesseract-ocr

   # Windows
   # Download from: https://github.com/UB-Mannheim/tesseract/wiki

Docker&Docker编写 （可选）-
API密钥 （建议使用完整功能）

- Groq API密钥- 获取密钥 - OpenRouter API密钥（可选回退）- 获取密钥 - LangSmith API密钥（可选，用于跟踪）- 获取密钥

安装

克隆存储库

   git clone https://github.com/AkkaSingh11/greendish.git
   cd greendish

设置环境变量

   cp .env.example .env
   # Edit .env with your API keys

安装依赖项

选项A：使用紫外同步（推荐）

   # API service
   cd api
   uv sync

   # MCP server
   cd ../mcp-server
   uv sync

   # Streamlit UI
   cd ../streamlit-ui
   uv sync

选项B：使用uv pip

   cd api
   uv pip install -r pyproject.toml

配置

编辑 .env 使用您的设置：

# Groq (Primary LLM Provider)
GROQ_API_KEY=your_groq_api_key_here
GROQ_BASE_URL=https://api.groq.com/openai/v1
GROQ_PRIMARY_MODEL=openai/gpt-oss-20b
GROQ_REQUEST_TIMEOUT=30

# OpenRouter (Fallback LLM Provider)
OPENROUTER_API_KEY=your_openrouter_key  # Optional
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
OPENROUTER_PRIMARY_MODEL=deepseek/deepseek-chat-v3.1
OPENROUTER_FALLBACK_MODEL=
OPENROUTER_REQUEST_TIMEOUT=30
OPENROUTER_APP_NAME=GreenDish-MenuAnalyzer

# API Configuration
MCP_SERVER_URL=http://localhost:8001
MAX_IMAGES=5
CONFIDENCE_THRESHOLD=0.4
DEBUG=false

# LangSmith (Optional - for observability)
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your_langsmith_key
LANGCHAIN_PROJECT=greendish

运行应用程序

选项1:Docker Compose（推荐用于生产环境）

# Build and start all services
docker-compose up --build

# Run in detached mode
docker-compose up -d

# View logs
docker-compose logs -f api
docker-compose logs -f streamlit

# Stop services
docker-compose down

选项2：手动启动（建议用于开发）

# Terminal 1: Start MCP Server
cd mcp-server
uv run python server.py
# Runs on http://localhost:8001

# Terminal 2: Start API Service
cd api
uv run uvicorn main:app --reload --port 8005
# Runs on http://localhost:8005

# Terminal 3: Start Streamlit UI
cd streamlit-ui
uv run streamlit run app.py
# Runs on http://localhost:8501

接入点

流线型UI: http://localhost:8501-主测试界面
LLM聊天游乐场: http://localhost:8501（侧栏：“💬 LLM聊天游乐场”）
API文档: http://localhost:8005/docs-交互式OpenAPI文档
API健康检查: http://localhost:8005/health
MCP服务器: http://localhost:8001-计算服务

用法

通过Streamlit UI（推荐）

打开http://localhost:8501
导航到所需的阶段测试页面（侧栏）
上传1-5张菜单图像（JPEG、PNG、webp）
打开/关闭AI模式以比较方法
查看：

- OCR提取结果 - 解析菜单结构(parsed_menu JSON） - 带置信度评分的素食菜肴分类 - 总价计算 - LLM推理（启用AI模式时）

使用 LLM聊天游乐场 直接测试Groq/OpenRouter提示

通过API

工艺菜单（全流程）

curl -X POST "http://localhost:8005/api/v1/process-menu" \
  -F "files=@tests/fixtures/images/menu1.jpeg" \
  -F "files=@tests/fixtures/images/menu2.png" \
  -F "use_ai=true"

仅提取文本（OCR）

curl -X POST "http://localhost:8005/api/v1/extract-text" \
  -F "files=@tests/fixtures/images/menu1.jpeg"

响应格式

{
  "vegetarian_dishes": [
    {
      "name": "Veggie Burger",
      "price": 12.99,
      "is_vegetarian": true,
      "confidence": 0.95,
      "reasoning": "Contains vegetables and no meat products",
      "classification_method": "llm"
    }
  ],
  "total_vegetarian_price": 12.99,
  "total_dishes": 15,
  "vegetarian_count": 1,
  "processing_time": 2.34,
  "metadata": {
    "ai_mode": true,
    "ocr_time": 1.2,
    "classification_time": 0.8,
    "llm_provider": "groq"
  }
}

按阶段划分的功能

✅ 第1-2阶段：OCR和解析（完成）

多张图片上传（1-5张图片）
带有图像预处理的Tesseract OCR
结构化解析到规范 {name, price, raw_text} JSON
OCR结果的置信度评分

✅ 第3阶段：关键字分类（完成）

基于关键词的素食检测
非人工智能模式的回退机制
可配置的关键字列表

✅ 第4阶段：MCP集成（完成）

独立计算微服务
MCP工具： calculate_vegetarian_total
基于HTTP的服务通信

✅ 第5阶段：LLM分类（完成）

Groq API与 openai/gpt-oss-20b
OpenRouter回退 deepseek/deepseek-chat-v3.1
结构化的JSON响应，具有信心和推理能力
自动提供程序故障转移
令牌使用跟踪

✅ 第6阶段：RAG实施（完成）

ChromaDB矢量存储与持久存储
句子转换器嵌入(all-MiniLM-L6-v2)
Top-3语义相似度检索
置信度得分合并（LLM+RAG相似性）
用素食数据库播种

✅ 第7-8阶段：LangGraph代理和可观察性（完成）

LangGraph状态机编排
多节点工作流（分类器→ RAG → 计算器）
LangSmith追踪所有操作
跨服务请求ID跟踪
性能指标（OCR、解析、分类、RAG）
AI/非AI模式切换

✅ 第9阶段：测试与验证（完成）

全面的pytest套件
API终点测试
服务层测试
OCR回归测试
具有多个示例菜单的集成测试

发展

当前状态

第9+阶段：完成 -所有核心功能均已实施和测试

运行测试

# Run full test suite
pytest tests/

# Run with coverage
pytest --cov=api --cov=mcp-server tests/

# Run specific test file
pytest tests/test_ocr.py
pytest tests/test_classification.py

# Run with verbose output
pytest -v tests/

添加依赖关系

# Navigate to service directory
cd api  # or mcp-server or streamlit-ui

# Add a package
uv add package-name

# Or edit pyproject.toml and run
uv sync

重要：不要创建 requirements.txt。所有依赖关系都通过以下方式管理 pyproject.toml.

代码结构指南

相对进口 每个服务（否 api.module 进口）
服务层模式 用于业务逻辑
Pydantic模型 用于所有数据验证
键入提示 贯穿整个代码库
异步/等待 用于I/O操作

配置参考

关键环境变量

变量	描述	默认值
`GROQ_API_KEY`	Groq API密钥（主LLM）	AI模式需要
`GROQ_PRIMARY_MODEL`	Groq模型标识符	`openai/gpt-oss-20b`
`OPENROUTER_API_KEY`	OpenRouter密钥（回退）	可选
`CONFIDENCE_THRESHOLD`	分类的最小置信度	`0.4`
`MAX_IMAGES`	每次请求的最大图像数	`5`
`MCP_SERVER_URL`	MCP服务端点	`http://localhost:8001`
`LANGCHAIN_TRACING_V2`	启用LangSmith跟踪	`false`
`DEBUG`	具有自动重新加载功能的调试模式	`false`

看 .env.example 查看完整列表。

故障排除

未找到Tesseract

# Verify installation
tesseract --version

# macOS: Ensure in PATH
brew info tesseract

# Set TESSERACT_CMD in .env if needed
TESSERACT_CMD=/usr/local/bin/tesseract

API服务中的导入错误

使用 相对进口 (from services import OCRService)
非绝对进口(from api.services import OCRService)
看 CLAUDE.md 详情

Docker端口冲突

API：8005
MCP服务器：8001
流光灯：8501

# Check ports in use
lsof -i :8005
lsof -i :8001
lsof -i :8501

LLM API错误

验证中的API密钥 .env
检查Groq/OpenRouter帐户积分
审核日志： docker-compose logs api
回退到非AI模式（基于关键字）

RAG/ChromaDB问题

# Delete and rebuild vector store
rm -rf api/rag_db/
# Restart API service to reinitialize

体系结构决策

为什么选择LangGraph？

可视化工作流调试
易于状态管理
条件路由（AI与非AI模式）
内置重试和错误处理

为什么选择Groq+OpenRouter？

Groq：超快推理（亚秒）
OpenRouter：广泛的回退模型选择
通过自动故障转移实现成本优化
通过LLM路由器实现统一接口

为什么选择ChromaDB？

简单的本地设置（无外部服务）
低开销的持久存储
元数据过滤支持
DX比FAISS更好

为什么选择MCP协议？

LLM工具集成的现代标准
明确的服务边界
基于网络的多语言支持
面向未来的Claude/GPT工具使用

为什么选择混合（AI+关键词）？

关键词：快速、确定性回退
LLM：处理边缘案例（“植物性”、“无肉”）
RAG：增强对模棱两可菜肴的信心
通过可配置的AI切换进行成本控制

成本估算

开发/测试（每月）

Tesseract OCR：免费（开源）
色度数据库：免费（本地存储）
句子转换器：自由（局部推理）
朗史密斯：免费套餐（5000条/月）
格罗克API：免费套餐或每份菜单约0.005美元
开放路由：每份菜单约0.01美元（仅限备用）

预计：0-10美元/月用于开发

生产（1000份菜单/月）

格罗克API: ~$5
开放路由 （回退，10%使用率）：约1美元
朗史密斯：免费或约5美元（超出免费等级）
托管：变量（基于Docker，任何云）

预计：10-20美元/月

演出

单个菜单图像的典型处理时间：

光学字符识别：0.5-1.5秒（取决于图像质量）
解析：\<0.1秒
LLM分类：0.5-2s（Groq）或2-5s（OpenRouter）
RAG检索：0.1-0.3秒
MCP计算：小于0.05秒

端到端总计：每个菜单1-4秒

路线图

完成

✅ 基于Docker的多服务架构
✅ LangGraph代理编排
✅ Groq+OpenRouter LLM路由
✅ RAG增强分类
✅ LangSmith可观测性
✅ 全面的测试套件
✅ 带聊天室的交互式Streamlit UI

未来的增强功能

🔲 人在环审查界面（第10阶段）
🔲 多语言菜单支持
🔲 移动应用集成
🔲 饮食限制定制（纯素、无麸质等）
🔲 餐厅API集成
🔲 多家餐厅的批处理
🔲 分析仪表板

贡献

我们欢迎捐款！请遵循以下指南：

分叉存储库
创建特征分支： git checkout -b feature/your-feature
跟随代码风格（使用相对导入、类型提示）
测试彻底： pytest tests/
提交信息清晰（每个项目规则没有人工智能徽章）
推并创建一个pull请求

看文档/阶段/ 发展规划文件。

许可证

MIT许可证-请参阅许可证文件以获取详细信息。

致谢

Tesseract OCR -谷歌的开源OCR引擎
LangGraph -基于LangChain的代理工作流框架
Groq -超快速LLM推理
色度数据库 -开源矢量数据库
句子转换器 -最先进的嵌入技术

联系

GitHub问题: 报告错误或请求功能
讨论: 提问或分享想法

______________________________________________________________________

greendish (Akka Singh11)

快速接入

详细介绍