人工智能地图推荐系统
一个智能的本地食物推荐系统，利用谷歌地图API和谷歌ADK（代理开发工具包），根据位置、评分和评论的语义分析，提供个性化的餐厅和咖啡馆推荐。
问题
这是Kaggle x谷歌5天人工智能代理强化班顶点项目。这个项目试图在一个新的地区找到最好的餐馆和咖啡馆可能很有挑战性。传统的地图应用程序提供评级和评论等基本信息，但它们往往缺乏：
- 智能过滤：简单的基于评级的排序不考虑评论质量、最近度或语义含义
- 情境理解：没有对评论进行语义分析，以了解口味特征、服务质量或目标受众
- 综合评价：以有意义的方式组合多种因素（评级、评论计数、最近的反馈、价格、开放时间）的能力有限
- 个性化推荐：不考虑审查真实性或过滤掉机械/抄袭内容的通用结果
用户需要一个能够智能分析多个数据点的系统，并提供精心策划的高质量建议和清晰的解释。
解决方案
该项目实现了一个基于人工智能的推荐代理，该代理：
- 地理代码位置 从地址或坐标
- 搜索候选人 （2公里半径内有8家咖啡馆和8家餐厅）
- 检索详细信息 包括评级、评论数、价格水平、开放时间和最近的评论
- 应用多阶段评估:
- 基于规则的评分：使用加权公式 rating × log1p(user_ratings_total) - 语义分析：评估口味、一致性、环境、服务质量和最近的负面反馈的评论
- 过滤器和排名 结果，优先考虑最近的评论，减少机械/抄袭内容的权重
- 生成精心策划的建议 顶级3-5家咖啡馆和顶级3-3家餐厅，包括：
- 名称、类型、评级和评级计数 - 代表性评审总结 - 目标受众识别 - 地址和谷歌地图链接 - 排序标准简述
建筑
系统组件
┌─────────────────────────────────────────────────────────────┐
│ User Input Layer │
│ (Address or Coordinates + User ID + Search Radius) │
└──────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Google ADK Agent Framework │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ LlmAgent (Gemini 2.5 Flash Lite) │ │
│ │ - System Instruction (Food Guide Logic) │ │
│ │ - Session Management (InMemorySessionService) │ │
│ │ - Artifact Management (InMemoryArtifactService) │ │
│ └──────────────────┬───────────────────────────────────┘ │
└─────────────────────┼───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ MCP Toolset (Model Context Protocol) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Google Maps MCP Server │ │
│ │ - Geocoding │ │
│ │ - Nearby Search │ │
│ │ - Place Details │ │
│ │ - Review Retrieval │ │
│ └──────────────────┬───────────────────────────────────┘ │
└─────────────────────┼───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Google Maps API │
│ (Geocoding, Places API, Reviews) │
└─────────────────────────────────────────────────────────────┘数据流
- 输入处理：用户提供位置（地址或坐标）和可选搜索半径
- 地理编码：使用谷歌地图地理编码API将地址转换为坐标
- 候选人搜索：在指定半径内找到8家咖啡馆和8家餐馆
- 细节检索：获取每个候选人的全面信息
- 多阶段评估:
- 基于规则的初始排名评分 - 质量评估评论的语义分析
- 筛选和排名：应用权重，过滤低质量评论，优先考虑最近的反馈
- 响应生成：用解释格式化顶级建议
关键技术
- Google ADK（代理开发工具包）：构建LLM驱动代理的框架
- Gemini 2.5 Flash精简版：谷歌用于代理推理的高效LLM
- MCP（模型上下文协议）：将LLM连接到外部工具的协议
- 谷歌地图API：地理编码、地点搜索和地点详细信息
- Python 3.10+：异步/等待并发操作
- 会话管理：用户上下文的内存会话服务
安装说明
先决条件
- Python 3.10或更高版本
- Node.js和npm（用于通过npx运行MCP服务器）
- 谷歌地图API密钥
- 具有ADK访问权限的Google Cloud项目
安装
- 克隆存储库:
git clone
cd aigen-map-recommendation- 创建并激活虚拟环境:
# Using venv
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate- 安装依赖项:
pip install -r requirements.txt- 设置环境变量:
- 创建一个 .env 项目根目录中的文件：
GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here
GOOGLE_API_KEY＝your_google_api_key_here- 验证Node.js安装 （MCP服务器需要）：
- 请在此处安装node.jshttps://nodejs.org/en/download - 检查node.js安装成功。
node --version
npm --version配置
系统使用以下配置（可在中配置 agent.py):
- 模型:
gemini-2.5-flash-lite - 重试配置:
- 最大尝试次数：5 - 指数退避基数：7 - 初始延迟：1秒 - 重试HTTP状态代码：429500503504
- 默认搜索半径：2000米（2公里）
- MCP连接超时：60秒
运行应用程序
直接执行
直接使用测试查询运行代理：
python src/map_recommedation/agent.py这将执行“台湾新北市板桥区”的默认查询。
程序化使用
import asyncio
from src.map_recommedation.agent import run_query
async def main():
result = await run_query(
address="Banqiao District, New Taipei City, Taiwan",
user_id="user_123",
radius_m=2000
)
print(result)
asyncio.run(main())使用坐标
result = await run_query(
address=None,
user_id="user_123",
latitude=25.0143,
longitude=121.4637,
radius_m=2000
)日志记录
该应用程序使用Python logging 模块。根据需要配置日志记录级别：
import logging
logging.basicConfig(level=logging.INFO) # or DEBUG for more details项目结构
aigen-map-recommendation/
├── data/ # Data files (if any)
├── docs/ # Documentation
├── examples/ # Example usage scripts
├── scripts/ # Utility scripts
├── src/
│ └── map_recommedation/
│ ├── __init__.py # Package initialization
│ └── agent.py # Main agent implementation
├── tests/ # Unit tests
├── venv/ # Virtual environment (gitignored)
├── .env # Environment variables (gitignored)
├── requirements.txt # Python dependencies
└── README.md # This file特性
- ✅ 智能定位处理：支持地址和坐标
- ✅ 多阶段评估：结合基于规则和语义分析
- ✅ 审核质量筛选：检测低质量评论并减轻其权重
- ✅ 综合信息：评级、评论、价格、小时数等
- ✅ 精心策划的建议：前3-5个结果及其解释
- ✅ 会话管理：跨交互维护用户上下文
- ✅ 稳健的错误处理：API失败的重试逻辑
- ✅ 综合录井：调试和监控的详细日志
api参考
run_query()
执行推荐查询的主要功能。
参数:
address（可选\[str\]）：人类可读地址user_id（str）：会话管理的唯一用户标识符radius_m（int，默认值=2000）：搜索半径（单位：米）latitude（可选\[浮动\]）：纬度坐标longitude（可选\[float\]）：经度坐标
退货:
str：代理人回应并提出建议
提升:
ValueError：如果地址和坐标都缺失
集成示例
你可以参考这个项目，https://github.com/MengShue/line-bot-my-bunny-buddy了解如何将其整合到项目中。
故障排除
常见问题
- MCP连接超时:
- 确保Node.js已安装且可访问 - 检查网络连接 - 验证Google Maps API密钥是否有效
- API密钥错误:
- 验证 GOOGLE_MAPS_API_KEY 已设置 .env - 验证 GOOGLE_API_KEY 已设置 .env - 确保API密钥具有必要的权限（地理编码API，放置API）
- 导入错误:
- 激活虚拟环境 - 重新安装依赖关系： pip install -r requirements.txt
- 未找到结果:
- 尝试增加 radius_m 参数 - 验证位置坐标/地址是否正确 - 检查位置是否有足够的餐厅/咖啡馆
贡献
欢迎投稿！请确保：
- 所有函数都有类型注释
- 包含谷歌风格的文档字符串
- 为新功能添加了测试
- 日志记录使用得当
致谢
- 用于代理框架的Google ADK
- 谷歌地图定位服务平台
- 用于工具集成的模型上下文协议（MCP）