具有智能错误恢复功能的Google Maps MCP评估器
一个用于测试基于LLM的函数调用的综合评估框架 谷歌地图模型上下文协议（MCP）服务器使用RAG（检索增强生成）进行事件位置解析和基于LLM的参数校正，实现智能错误恢复。
🎯 概述
本项目评估不同LLM在以下方面的表现：
- 为给定的查询选择正确的Google Maps API工具
- 为API调用生成适当的参数
- 使用RAG或错误感知重试机制从错误中恢复
- 处理涉及事件、位置和方向的复杂查询
主要特点
- 混合错误恢复：在RAG（针对位置/事件错误）和基于LLM的错误恢复（针对参数/API错误）之间智能路由
- RAG事件解决方案：使用BM25检索+LLM提取从本地PDF/文档中提取事件位置
- 法学硕士作为法官：自动评估工具选择、参数和结果质量
- 多模型支持：与OpenAI、Ollama或大学主办的法学硕士进行测试
- 综合录井：每个查询的详细JSONL输出，带有成功/失败跟踪
______________________________________________________________________
📁 项目结构
.
├── src/ # Main source code
│ ├── evaluators/ # Batch evaluation scripts
│ │ ├── maps_evaluator.py # Basic evaluator (no recovery)
│ │ ├── maps_evaluator_error.py # Error recovery with LLM
│ │ ├── maps_evaluator_rag.py # RAG fallback for events
│ │ └── maps_evaluator_hybrid.py # 🌟 Hybrid (RAG + Error recovery)
│ │
│ ├── judges/ # Result evaluation
│ │ ├── maps_llm_judge.py # General tool-calling judge
│ │ └── maps_hybrid_judge.py # RAG-aware judge with ground truth
│ │
│ ├── agents/ # Interactive agents
│ │ ├── maps_direct_flow.py # Interactive single-query agent
│ │ └── maps_direct_flow_rag.py # Interactive agent with RAG
│ │
│ └── utils/ # Helper modules
│ ├── error_recovery.py # LLM-based error correction
│ ├── rag_location_resolver.py # RAG location extraction
│ ├── rag_demo.py # RAG testing demo
│ └── maps_dataset_generator.py # Generate test queries
│
├── Dataset/ # Organized test queries
│ ├── MCP-GoogleMaps/ # Google Maps evaluation queries
│ │ ├── maps_queries.txt # Main query set
│ │ └── Test-Data/ # Additional test sets
│ └── RAG-Location/ # RAG-specific queries and ground truth
│ ├── rag_queries.txt # Event-based queries
│ ├── rag_expected_locations.csv # Ground truth for RAG evaluation
│ └── Test-Data/ # Extended RAG test queries
│
├── PDFs/ # Mock event documents for RAG testing
│ ├── TUM_Robotics_Expo.pdf
│ ├── Berlin_Startup_Fair.pdf
│ └── ... (more event PDFs)
│
├── DATA-EVAL/ # Raw evaluation results (JSONL)
├── Data-Sumary/ # Processed summaries and statistics
├── results_rag/ # RAG-specific results
│
├── README.md
├── requirements.txt
└── uv.lock入门指南
先决条件
- Python 3.10+
- Node.js（用于谷歌地图MCP服务器）
- 谷歌地图API密钥
- OpenAI API密钥或Ollama安装
安装
- 创建并激活虚拟环境
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate- 安装Python依赖项
pip install -r requirements.txt- 设置环境变量
创建一个 .env 根目录中的文件：
# Required
GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here
# Choose one LLM provider:
# Option 1: OpenAI
OPENAI_API_KEY=your_openai_api_key_here
# Option 2: University LLM endpoint
UNIVERSITY_LLM_API_KEY=your_university_api_key_here
OPENAI_API_BASE=https://llms-inference.innkube.fim.uni-passau.de
# Option 3: Ollama (local)
# Just ensure Ollama is running: ollama serve- 安装谷歌地图MCP服务器
该项目使用 谷歌地图MCP服务器 其通过模型上下文协议提供对谷歌地图API的访问。
npx -y @modelcontextprotocol/server-google-maps📖 使用指南
1.生成测试查询
为评估创建一组多样化的测试查询：
python -m src.utils.maps_dataset_generator \
--num 200 \
--output Dataset/MCP-GoogleMaps/my_queries.txt \
--format txt______________________________________________________________________
2.运行评估
选项A：混合评估器
在RAG和错误恢复之间具有智能路由的最复杂的评估器：
python -m src.evaluators.maps_evaluator_hybrid \
--queries-file Dataset/MCP-GoogleMaps/maps_queries.txt \
--output results_hybrid.jsonl \
--rag-dir PDFs它的作用：
- 初始尝试：LLM生成工具调用→ 在MCP上执行
- 失败时：路由到RAG（如果位置问题）或错误恢复（如果参数问题）
- 交叉重试：如果第一次恢复失败，错误类型不同，则尝试其他路由
- 记录所有内容：初始尝试、恢复尝试、最终成功/失败
选项：
--queries-file：查询路径（每行一个）--query：用于测试的单个查询（可重复）--queries-csv：带查询列的CSV文件--output：输出JSONL路径（默认值：maps_eval_results_hybrid.jsonl)--rag-dir：包含事件PDF的目录（默认：PDFs)--rag-file：特定PDF文件（可重复）--stream：填写完成后的结果
选项B：仅RAG评估员
对于具体涉及事件位置的查询：
python -m src.evaluators.maps_evaluator_rag \
--queries-file Dataset/RAG-Location/rag_queries.txt \
--output results_rag.jsonl \
--rag-dir PDFs选项C：错误恢复评估器
对于一般参数/API错误测试：
python -m src.evaluators.maps_evaluator_error \
--queries-file Dataset/MCP-GoogleMaps/maps_queries.txt \
--output results_error.jsonl选项D：基本评估员
基线未恢复（用于衡量改善情况）：
python -m src.evaluators.maps_evaluator \
--queries-file Dataset/MCP-GoogleMaps/maps_queries.txt \
--output results_basic.jsonl______________________________________________________________________
3.与法学硕士评审一起评估结果
混合法官 （用于基于地面实况的RAG评估）
python -m src.judges.maps_hybrid_judge \
--input results_hybrid.jsonl \
--expected-locations Dataset/RAG-Location/rag_expected_locations.csv \
--output judged_hybrid.jsonl \
--summary hybrid_summary.json \
--model gpt-4o-mini评估：
- ✅ RAG触发器：是否在需要时触发RAG？
- ✅ RAG决议：RAG找到正确的位置了吗？
- ✅ RAG用法：重试时是否使用了解析位置？
- ✅ 最终结果：查询成功了吗？
选项：
--model gpt-4o-mini：使用OpenAI模型--model ollama:phi4:14b：使用当地Olama模型--limit 10：仅判断前10条记录--max-concurrency 8：并行LLM调用
一般法官 （用于工具选择评估）
python -m src.judges.maps_llm_judge \
--input results_hybrid.jsonl \
--output judged_general.jsonl \
--summary general_summary.json评估：
- 刀具选择正确性
- 参数适当性
- 结果与查询的相关性
______________________________________________________________________
4.交互式测试
使用直接流代理交互式测试单个查询：
基本直流
python -m src.agents.maps_direct_flow
# Then enter queries interactivelyRAG增强型直流
python -m src.agents.maps_direct_flow_rag --rag-dir PDFs
# Test event queries with RAG fallback🔧 高级用法
测试RAG位置分辨率
独立测试RAG：
python -m src.utils.rag_demo \
--query "Where is the TUM Robotics Expo?" \
--dir PDFs \
--top-k 6自定义事件PDF
将您自己的活动PDF添加到 PDFs/ 目录。包括：
- 文档中的事件名称
- 完整的地址或位置详细信息
- 日期/时间信息
修改LLM模型
编辑评估器文件以更改模型：
对于OpenAI：
self.llm = ChatOpenAI(
openai_api_key=os.getenv("OPENAI_API_KEY"),
model_name="gpt-4o", # or "gpt-4o-mini"
temperature=0.0,
)对于Ollama：
from langchain_community.chat_models import ChatOllama
self.llm = ChatOllama(
base_url="http://localhost:11434",
model="phi4:14b", # or "llama3.1", "qwen2"
temperature=0.0,
)______________________________________________________________________
📊 了解输出文件
评估结果（JSONL）
每行包含：
{
"query": "Get directions to TUM Robotics Expo from Munich HBF",
"tool_call": {
"tool_name": "maps_directions",
"parameters": {"origin": "Munich HBF", "destination": null},
"reasoning": "Event detected, setting destination to null"
},
"tool_response": "Error: destination required",
"success": false,
"error": "Missing destination",
"rag_used": true,
"rag_resolved_location": "TUM Main Campus, Mechanical Engineering Building",
"retry_tool_call": {
"tool_name": "maps_directions",
"parameters": {
"origin": "Munich HBF",
"destination": "TUM Main Campus, Mechanical Engineering Building"
}
},
"retry_success": true,
"final_success": true
}统计摘要（JSON）
{
"count": 100,
"initial_success": 65,
"rag_attempts": 30,
"rag_recovered": 25,
"error_recovery_attempts": 10,
"error_recovered": 8,
"final_success": 98,
"pass_rate": 0.98,
"avg_scores": {
"rag_trigger": 0.95,
"rag_resolution": 0.88,
"rag_usage": 0.90,
"overall": 0.91
}
}______________________________________________________________________
🎓 关键概念
混合错误恢复
混合评估器智能地路由错误：
- 注意_发现/位置错误 → RAG决议
- 示例：“TUM Robotics Expo”未被识别 - 操作：在PDF中搜索活动地点 - 重试：使用解析的地址重新生成工具调用
- 参数/API错误 → 错误恢复
- 示例：参数格式错误，缺少字段 - 动作：LLM分析错误并纠正参数 - 重试：使用更正的参数执行
- 交叉重试逻辑
- 如果RAG重试失败并出现参数错误→ 尝试错误恢复 - 如果错误恢复失败，并显示NOT_FOUND→ 尝试RAG - 最大限度地提高恢复成功率
RAG位置分辨率
- 使用BM25检索索引事件PDF
- 检索前k个相关块以进行查询
- LLM从块中提取位置信息
- 返回：地址、置信度得分、推理、来源
______________________________________________________________________
📈 典型工作流程
# 1. Generate diverse test queries
python -m src.utils.maps_dataset_generator --num 200 --output Dataset/MCP-GoogleMaps/queries_200.txt
# 2. Run hybrid evaluation
python -m src.evaluators.maps_evaluator_hybrid \
--queries-file Dataset/MCP-GoogleMaps/queries_200.txt \
--output results.jsonl \
--rag-dir PDFs
# 3. Judge results with ground truth
python -m src.judges.maps_hybrid_judge \
--input results.jsonl \
--expected-locations Dataset/RAG-Location/rag_expected_locations.csv \
--output judged.jsonl \
--summary summary.json
# 4. View summary
cat summary.json | jq
# 5. Analyze in notebook
jupyter notebook table.ipynb🐛 故障排除
“找不到Google Maps API密钥”
# Check your .env file
cat .env | grep GOOGLE_MAPS_API_KEY
# Or export directly
export GOOGLE_MAPS_API_KEY="your_key_here"“MCP服务器连接失败”
# Test MCP server manually
npx -y @modelcontextprotocol/server-google-maps
# Check if it responds (Ctrl+C to exit)其他帮助： 请参阅 谷歌地图MCP服务器文档 有关故障排除和配置详细信息。
“未找到RAG文件”
# Ensure PDFs directory exists and contains files
ls -la PDFs/
# Verify PDF format
file PDFs/TUM_Robotics_Expo.pdf“找不到Olama模型”
# List available models
ollama list
# Pull model if needed
ollama pull phi4:14b