Way Back Home

• # 🚀 回家的路

一个沉浸式的人工智能工作坊平台，参与者可以在这里学习构建智能代理，同时营救一名搁浅的太空探险家。

《回家之路》是一个实践性的研讨会体验，通过引人入胜的叙述来教授谷歌云人工智能技术。参与者迫降在一个外星星球上，必须使用人工智能来识别自己、分析周围环境并协调救援工作。

🎮 体验

你是一名太空探险家，他的飞船坠毁在一个未知的星球上。你的救援信标已离线，你和其他幸存者分散在水面上。要回家，你必须：

🛠️ 技术栈

🚀 快速开始

研讨会参与者

1. 访问云外壳 在 console.cloud.google.com

1. 克隆和设置：

   git clone https://github.com/google-americas/way-back-home.git
   cd way-back-home

1. 从0级开始：

   ./scripts/setup.sh
   cd level_0

1. 遵循代码实验室： 0级指令

研讨会主持人

看 部署指导 下面是运行您自己的实例。

📚 文档

🏗️ 架构概述

┌─────────────────────────────────────────────────────────────────────────┐
│                           Way Back Home                                  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   Participant Journey                                                    │
│   ───────────────────                                                    │
│                                                                          │
│   ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐         │
│   │ Level 0  │───▶│ Level 1  │───▶│ Level 2  │───▶│ Level 3  │         │
│   │ Identity │    │ Location │    │   SOS    │    │  Rescue  │         │
│   └──────────┘    └──────────┘    └──────────┘    └──────────┘         │
│        │               │                                                 │
│        ▼               ▼                                                 │
│   ┌─────────────────────────────────────────────────────────────┐       │
│   │                    Backend API (Cloud Run)                   │       │
│   │  • Participant registration    • Evidence storage            │       │
│   │  • Location confirmation       • Event management            │       │
│   └─────────────────────────────────────────────────────────────┘       │
│        │               │                                                 │
│        ▼               ▼                                                 │
│   ┌──────────┐    ┌──────────┐    ┌──────────────────────────┐         │
│   │Firestore │    │ Firebase │    │      Frontend (Next.js)   │         │
│   │          │    │ Storage  │    │  • 3D planet visualization │         │
│   │• events  │    │• avatars │    │  • Real-time participant   │         │
│   │• users   │    │• evidence│    │    tracking                │         │
│   └──────────┘    └──────────┘    └──────────────────────────┘         │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

🌐 部署

部署您自己的实例

1. 先决条件：

- 启用计费的Google Cloud项目 - Firebase项目（火库+存储+身份验证） - 域名（可选，用于自定义URL）

1. 克隆和配置：

   git clone https://github.com/google-americas/way-back-home.git
   cd way-back-home

   # Configure your project
   gcloud config set project YOUR_PROJECT_ID

1. 运行基础结构设置：

   ./scripts/setup-infrastructure.sh

1. 部署所有服务：

> 注： 在您首次部署时，Cloud Run将为您的服务生成唯一的URL。构建完成后，您 必须 使用这些特定的URL再次重新部署前端，以确保3D地图可以与API通信。

   # First deployment (to generate URLs)
   gcloud builds submit --config cloudbuild.yaml

   # Get and save your URLs
   export API_BASE_URL=$(gcloud run services describe way-back-home-api --format='value(status.url)')
   export MAP_BASE_URL=$(gcloud run services describe way-back-home-frontend --format='value(status.url)')

   # Redeploy frontend with the actual URLs
   gcloud builds submit --config cloudbuild.yaml \
     --substitutions=_API_BASE_URL=$API_BASE_URL,_MAP_BASE_URL=$MAP_BASE_URL,_DEPLOY_BACKEND=false

环境配置

创建一个 set_env.sh 在项目根目录中：

export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
export REGION="us-central1"
export API_BASE_URL=$(gcloud run services describe way-back-home-api --format='value(status.url)')
export MAP_BASE_URL=$(gcloud run services describe way-back-home-frontend --format='value(status.url)')

🎓 工作坊主办指南

研讨会前

1. 将后端和前端部署到您的GCP项目中。确保将Cloud Run服务URL传递给 substitutions 旗在 gcloud builds submit.

1. 配置管理员访问权限：

API要求在 admins 消防仓库收藏。

- 首选 Firebase控制台 > 四大. - 创建一个名为的集合 admins. - 创建一个文档，其中 文档编号 是您的电子邮件（例如。， your-name@google.com). - 添加字段 active: true （布尔值）。

1. 使用以下方法之一创建事件：

方法A：Firestore（手动-建议快速启动）

在中创建文档 events 具有以下结构的集合：

• 收藏： events
• 文档ID: bwai-mycity （或您选择的事件代码）
• 领域：

- active: true （布尔值） - code: "bwai-mycity" （字符串） - created_at: [Current Timestamp] （时间戳） - created_by: "admin" （字符串） - description: "" （字符串） - max_participants: 500 （编号） - name: "Build With IA - GDG SJC" （字符串） - participant_count: 0 （编号）

方法B:CLI（建议用于自动设置）

使用提供的Python脚本，使用您的身份验证直接在Firestore中创建事件 gcloud 资格证书：

python3 scripts/create_event.py your-event-code "Your Workshop Name" --project YOUR_PROJECT_ID

方法C：API

1. 从终端检索Firebase ID令牌：

   # 1. Get your Google Identity Token
   ID_TOKEN=$(gcloud auth print-identity-token)

   # 2. Exchange it for a Firebase ID Token (requires Firebase Web API Key)
   # You can find your API Key in the Firebase Console > Project Settings
   API_KEY="YOUR_FIREBASE_WEB_API_KEY"

   curl -s -X POST "https://identitytoolkit.googleapis.com/v1/accounts:signInWithIdp?key=${API_KEY}" \
     -H "Content-Type: application/json" \
     -d "{\"postBody\": \"id_token=${ID_TOKEN}&providerId=google.com\", \"requestUri\": \"http://localhost\", \"returnIdpCredential\": true, \"returnSecureToken\": true}" | jq -r .idToken

1. 调用管理员API：

   curl -X POST https://api.yourdomain.dev/admin/events \
     -H "Authorization: Bearer $FIREBASE_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"code": "your-event-code", "name": "Your Workshop Name"}'

1. 生成指向您活动URL的二维码。

1. 用样本参与者测试整个流程。

工作坊期间

1. 与参与者共享事件代码
2. 引导他们到 0级代码实验室
3. 在以下位置监控实时地图 https://yourdomain.dev/e/your-event-code
4. 当灯塔照亮整个星球时，庆祝吧！

成本估算

🤝 贡献

欢迎投稿！请在提交PR之前阅读我们的投稿指南。

开发设置

# Backend
cd dashboard/backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8080

# Frontend
cd dashboard/frontend
npm install
npm run dev

📄 许可证

Apache 2.0-请参阅 许可证 了解详情。

🙏 致谢

• 建于 谷歌ADK （代理开发工具包）
• 由...驱动 顶点AI 和 双子座
• 3D可视化 React三纤维

______________________________________________________________________

准备好回家了吗？ 从...开始 级别0 🚀