Imagine Travel

想象旅行

概述

想象旅行 是一个基于人工智能的代理应用程序，可以将你的原始旅行记忆（例如，“我去了东京吃了寿司”）转化为丰富、生动的日记条目。它结合了现实世界的基础、历史背景和创意生成，构建了一个有凝聚力的故事，并配有视觉记忆和经过事实核查的判决。

这个项目展示了一个复杂的 顺序工作流 带有嵌入式 反馈循环，使用自定义构建 代理开发工具包（ADK）它整合了多种外部工具来验证、丰富和可视化您的体验。一个关键的改进是 渐进渲染，地图、故事和其他元素一旦从后端获得数据就会出现，从而提供更灵敏的用户体验。

目标

1. 接地：使用谷歌地图将用户记忆锚定到现实世界的位置，确保准确提取姓名和地址。
2. 富集：使用维基百科用历史事实补充故事。
3. 创意制图：使用LLM生成高质量、令人回味的日记条目，并进行迭代改进。
4. 可视化：创建代表故事的一致视觉记忆（图像）。
5. 质量保证：使用LLM法官根据原始数据对生成的内容进行事实检查，如果发现不准确，则对草稿进行迭代。

使用的工具和API

此应用程序集成 3个不同的外部API:

1. 谷歌地图平台:

- 地点API（新增）：由代理用于查找用户内存的确切位置、地址和详细信息（通过 GoogleMapsMCP).现在，代理被特别指示提取一致的地名和完整的地址，以实现稳健的映射。 - 映射嵌入API：由前端用于显示位置的交互式地图。

1. 维基百科API：用于获取位置的历史背景和摘要。
2. 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 dev

2.后端设置

1. 创建和激活虚拟环境 （推荐）：

   # From the project root
   python -m venv .venv
   source .venv/bin/activate

1. 再进行 （使用 uv):

首先，确保 uv 安装（例如。， pip install uv).然后：

   # From the project root
   uv pip install -r backend/requirements.txt

1. 启动后端服务器:

我们在根目录中提供了一个帮助脚本，用于正确设置路径：

*（注意：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.使用方法

1. 打开浏览器到前端URL（例如。， http://localhost:3000).

1. 输入一个旅行记忆（例如，“日落时分，带着一块披萨走过布鲁克林大桥”）。

1. 点击 走吧.

1. 看 执行日志 （底部面板）代理根据您的请求，研究并迭代地起草您的故事。地图和故事将逐步呈现。

1. 查看最终结果：日记条目、交互式地图、生成的图像和事实核查结论。

截图

着陆页

结果页面

部署（谷歌云运行）

此应用程序已容器化，可以部署到 谷歌云运行 作为单一服务（前端+后端）。

先决条件

1. 谷歌云项目：你需要一个积极的GCP项目。
2. gcloud命令行界面：已安装并经过身份验证(gcloud auth login, gcloud config set project YOUR_PROJECT_ID).
3. API已启用：云运行API，云构建API，工件注册API， Vertex AI API （对于Imagen型号），以及 谷歌地图平台（MCP）服务.

   # Enable the Maps MCP service
   gcloud beta services enable mapstools.googleapis.com --project=$PROJECT_ID

部署步骤

1. 运行部署脚本:

此脚本构建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"

1. 访问应用程序:

命令输出将提供服务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 将跟踪打印到控制台（对调试有用）。

使用遥测技术在本地运行

1. 启动收集器:

使用提供的帮助脚本运行本地OpenTetry收集器（需要Docker）。这将配置收集器以导出到Google Cloud（使用您的本地凭据）和控制台。

   ./run_local_collector.sh

1. 运行后端:

   ./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"

文件参考

• OpenTetry Python文档
• Google Cloud Trace与OpenTetry
• 仪器化人工智能代理（谷歌云）