想象旅行
概述
想象旅行 是一个基于人工智能的代理应用程序，可以将你的原始旅行记忆（例如，“我去了东京吃了寿司”）转化为丰富、生动的日记条目。它结合了现实世界的基础、历史背景和创意生成，构建了一个有凝聚力的故事，并配有视觉记忆和经过事实核查的判决。
这个项目展示了一个复杂的 顺序工作流 带有嵌入式 反馈循环，使用自定义构建 代理开发工具包（ADK）它整合了多种外部工具来验证、丰富和可视化您的体验。一个关键的改进是 渐进渲染，地图、故事和其他元素一旦从后端获得数据就会出现，从而提供更灵敏的用户体验。
目标
- 接地：使用谷歌地图将用户记忆锚定到现实世界的位置，确保准确提取姓名和地址。
- 富集：使用维基百科用历史事实补充故事。
- 创意制图：使用LLM生成高质量、令人回味的日记条目，并进行迭代改进。
- 可视化：创建代表故事的一致视觉记忆（图像）。
- 质量保证：使用LLM法官根据原始数据对生成的内容进行事实检查，如果发现不准确，则对草稿进行迭代。
使用的工具和API
此应用程序集成 3个不同的外部API:
- 谷歌地图平台:
- 地点API（新增）：由代理用于查找用户内存的确切位置、地址和详细信息（通过 GoogleMapsMCP).现在，代理被特别指示提取一致的地名和完整的地址，以实现稳健的映射。 - 映射嵌入API：由前端用于显示位置的交互式地图。
- 维基百科API：用于获取位置的历史背景和摘要。
- Google Gemini API:
- 双子座2.0闪光灯：授权法学硕士起草期刊、判断内容和提取位置关键字。 - 图4.0：生成记忆的“宝丽来风格”视觉表示。
项目结构
backend/：Python FastAPI后端。
- agents/：包含特定的代理逻辑(travel_imagination.py)和工具集成(tools.py). - server.py：处理WebSocket连接和代理执行的FastAPI服务器。
frontend/：React/Vite前端。
- src/App.jsx：主UI逻辑，处理WebSocket流、渐进式渲染和布局。 - src/components/：可重用的UI组件，如 LogPane.
如何建造和运行
先决条件
- Python 3.9+ （与
uv建议用于包管理和虚拟环境） - Node.js （推荐LTS）和
npm - API密钥:
- 谷歌地图API密钥：必须有 地点API（新增） 和 映射嵌入API 启用。 - Google Gemini API密钥：用于访问Gemini 2.0和Imagen型号。
1.设置环境变量
创建 .env 文件在 backend/ 目录（您可以复制 .env.template 如果存在或创建新的）。确保 load_dotenv() 早在 backend/server.py 加载这些。
# Example content for backend/.env
GOOGLE_MAPS_API_KEY=your_google_maps_key
VITE_GOOGLE_MAPS_API_KEY=your_frontend_maps_key
GOOGLE_API_KEY=your_gemini_api_key
# VITE_API_BASE_URL is set by Cloud Run or defaults to localhost for dev2.后端设置
- 创建和激活虚拟环境 （推荐）：
# From the project root
python -m venv .venv
source .venv/bin/activate- 再进行 （使用
uv):
首先，确保 uv 安装（例如。， pip install uv).然后：
# From the project root
uv pip install -r backend/requirements.txt- 启动后端服务器:
我们在根目录中提供了一个帮助脚本，用于正确设置路径：
*（注意：Dockerfile现在使用直接的uvicorn命令进行部署，但这对本地开发仍然有效。）*
# From the project root
./run_backend.sh后端将在上运行 http://0.0.0.0:8000.
3.前端设置
在新终端中，导航到 frontend/ 目录：
cd frontend安装依赖项：
npm install启动开发服务器（日志将被重定向到 frontend.log 在项目根目录中）：
npm run dev前端通常会在 http://localhost:3000 （如果取3000，则为3001/5173）。检查 frontend.log 输出文件。
4.使用方法
- 打开浏览器到前端URL（例如。，
http://localhost:3000).
- 输入一个旅行记忆（例如，“日落时分，带着一块披萨走过布鲁克林大桥”）。
- 点击 走吧.
- 看 执行日志 （底部面板）代理根据您的请求，研究并迭代地起草您的故事。地图和故事将逐步呈现。
- 查看最终结果：日记条目、交互式地图、生成的图像和事实核查结论。
截图
着陆页
结果页面
部署（谷歌云运行）
此应用程序已容器化，可以部署到 谷歌云运行 作为单一服务（前端+后端）。
先决条件
- 谷歌云项目：你需要一个积极的GCP项目。
- gcloud命令行界面：已安装并经过身份验证(
gcloud auth login,gcloud config set project YOUR_PROJECT_ID). - API已启用：云运行API，云构建API，工件注册API， Vertex AI API （对于Imagen型号），以及 谷歌地图平台（MCP）服务.
# Enable the Maps MCP service
gcloud beta services enable mapstools.googleapis.com --project=$PROJECT_ID部署步骤
- 运行部署脚本:
此脚本构建Docker镜像（React+Python的多阶段构建）并将其部署到Cloud Run。确保您的 gcloud 项目设置正确（例如。， gcloud config set project smcghee-ai-playground).
./deploy.sh*如果脚本由于权限或API限制而失败，则可以使用以下方法手动部署：*
*（注意：Dockerfile的CMD现在直接使用uvicorn，确保它正确绑定到Cloud Run PORT。）*
gcloud run deploy imagine-travel --source . --platform managed --region us-central1 --allow-unauthenticated --update-env-vars="GOOGLE_MAPS_API_KEY=your_key,GOOGLE_API_KEY=your_key"- 访问应用程序:
命令输出将提供服务URL（例如。， https://imagine-travel-xyz-uc.a.run.app).在浏览器中打开此URL。
可观测性（开放遥测）
该项目已配备 开放遥测 为代理的执行提供全面的跟踪和可观察性，包括LLM调用、工具使用和网络交互。
特性
- 汽车仪表：FastAPI、Requests、HTTPX和Google GenAI库会自动跟踪。
- 手动仪表：关键自定义逻辑，例如
generate_images工具（顶点AI+GCS）和research_location（维基百科）已经手动安装了自定义跨度，以实现细粒度可见性。 - 双导出模式:
- 本地开发：将跟踪导出到本地OpenTetry收集器（通过OTLP），然后可以转发到控制台或其他后端。 - 云运行：支持直接导出到 谷歌云追踪 没有sidecar收集器。
配置
可观测性设置在中进行管理 backend/otel_setup.py.
环境变量：
ENABLE_TELEMETRY：设置为false完全禁用遥测（默认值：true).USE_GCP_EXPORTER：设置为true以启用直接导出到Google Cloud Trace（建议用于Cloud Run）。OTEL_CONSOLE_EXPORTER：设置为true将跟踪打印到控制台（对调试有用）。
使用遥测技术在本地运行
- 启动收集器:
使用提供的帮助脚本运行本地OpenTetry收集器（需要Docker）。这将配置收集器以导出到Google Cloud（使用您的本地凭据）和控制台。
./run_local_collector.sh- 运行后端:
./run_backend.sh云运行部署先决条件（遥测）
为了在Cloud Run上部署时将遥测数据直接导出到Google Cloud Trace和Logging 服务账户 与您的Cloud Run服务关联的IAM角色必须如下：
- 云跟踪代理 (
roles/cloudtrace.agent)：允许服务写入跟踪。 - 日志写入器 (
roles/logging.logWriter)：允许服务写入日志。 - 监控指标编写器 (
roles/monitoring.metricWriter)：允许服务写入指标（如果已配置）。
您可以使用以下方式授予这些角色 gcloud CLI。替换 YOUR_SERVICE_ACCOUNT_EMAIL （例如。， service-PROJECT_NUMBER@serverless-robot-prod.iam.gserviceaccount.com)以及 YOUR_PROJECT_ID 根据您的实际值：
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
--member="serviceAccount:YOUR_SERVICE_ACCOUNT_EMAIL" \
--role="roles/cloudtrace.agent"
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
--member="serviceAccount:YOUR_SERVICE_ACCOUNT_EMAIL" \
--role="roles/logging.logWriter"
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
--member="serviceAccount:YOUR_SERVICE_ACCOUNT_EMAIL" \
--role="roles/monitoring.metricWriter"