Grounding Lite示例应用程序
概述
此存储库包含一个示例应用程序，演示了 接地精简版 随着 API双子星 使用谷歌地图平台数据提供基于空间的响应。该应用程序使用代理进行对话，并使用配套的3D谷歌地图。
请参阅官方文件了解更多详细信息： 接地精简版文档.
建筑
该应用程序采用客户端-服务器架构，其中Node.js后端托管模型上下文协议（MCP）服务器，允许Gemini模型通过谷歌地图平台工具动态访问实时地理信息。
关键组件
- 客户端（Web应用程序）：使用Vite和Lit构建，处理用户聊天交互并显示动态3D地图（使用Maps JavaScript API）。
- 后端服务器（节点/Express）：充当中央代理，管理客户、Gemini API和MCP服务器之间的通信。
- 接地Lite MCP服务器：向Gemini模型提供一组自定义工具，使其能够将响应基于现实世界的地理数据。
- MCP工具：MCP服务器定义的自定义函数，用于将自然语言请求转换为结构化的谷歌地图平台API调用(
Places API,Routes API,Elevation API). - API双子星：大型语言模型（LLM），利用提供的MCP工具进行地理上准确、有根据的响应。
数据流图（接地精简版）
graph TD
subgraph Client/UI
C[Client Web App]
end
style Client/UI fill:#FFFFFF
subgraph Backend Services
B[Backend Server]
end
subgraph Gemini and APIs
G[AI API]
P[Maps Platform other APis]
end
subgraph Grounding Lite
M[MCP Server] --> T[MCP Tools]
end
C --> B("User Query")
%% Combined edges to prevent overwriting in some renderers
B --> G("Send Query + Tool Schema
Send Tool Results")
G --> B("Model Decision (Tool Call)
Final Grounded Response")
B --> M("Execute MCP Tool")
T --> P("Call Specific GMP API")
P --> T("Return Data")
T --> B("Return Tool Results")
B --> C("Display Response")先决条件
- 启用了必要API的Google Cloud项目
- 创建API密钥
- 服务器API密钥： - 接地精简版 MCP服务 - Gemini API（又称生成语言API） - 管理3D地图的补充API： - 为多段线路由API - 将企业名称的API（新增）放置在标记上 - 高程API将摄像机高度调整到地图位置 - 客户端API密钥： - 映射JavaScript API - 放置UI工具包
- 安装了Node.js和npm。
安装
关键依赖关系
- 维特：一个快速、现代的web项目开发服务器和构建工具。
- @谷歌/genai：用于与Google Gemini API交互的官方SDK。
- @模型上下文协议/sdk：用于创建模型上下文协议（MCP）服务器并与之交互的SDK。
- 点亮：一个用于构建快速、轻量级web组件的简单库。
- Tailwind CSS：一个实用程序优先的CSS框架，用于快速构建自定义用户界面。
- 快速：用于后端服务器的最小且灵活的Node.js web应用程序框架。
- Dotenv。：一个零依赖模块，从
.env文件。
- 安装依赖项：
npm install- 配置您的环境：
创建 .env 文件，并添加您的API密钥。
对于前端（Google Maps JavaScript API加载），请使用：
GOOGLE_MAPS_API_KEY="YOUR_GOOGLE_MAPS_API_KEY"对于服务器端（Maps Platform MCP调用和Gemini API调用），请使用：
SERVER_API_KEY="YOUR_SERVER_API_KEY_HERE"建筑
运行应用程序
此应用程序使用 concurrently 运行Vite前端服务器和Node.js后端服务器（承载模型上下文协议（MCP）服务器）。
发展模式
在开发模式下运行应用程序：
npm run dev此命令执行： concurrently "vite" "npm run dev:server:watch"
- 前端（Vite）通常在
http://localhost:5173. - 后端服务器（Node.js/Express）处理MCP服务器设置和API路由。
生产建设
- 构建应用程序：
npm run build- 启动生产服务器：
npm start
# or
npm run start:prod云运行部署
通过直接从源代码构建和部署，可以将此应用程序部署到Google Cloud Run。
- 确保满足先决条件：您必须安装并验证Google Cloud CLI。
- 部署应用程序：运行以下命令，将环境变量占位符和项目ID替换为您的值。
> 备注：要使此示例应用程序正常运行，您必须传递 SERVER_API_KEY （适用于服务器端的谷歌地图平台和Gemini API）以及 GOOGLE_MAPS_API_KEY （用于客户端Maps JavaScript API）作为环境变量。
- 使用部署脚本：我们提供了一个通用的部署脚本，
deploy.sh，内容如下SERVER_API_KEY和GOOGLE_MAPS_API_KEY直接从当地.env文件并将其安全地传递给gcloud run deploy命令。
通用脚本需要GCP项目ID和区域作为参数：
./deploy.sh YOUR_GCP_PROJECT_ID us-central1服务条款
这是一个用于演示的示例应用程序。
此示例应用程序不是谷歌地图平台核心服务。因此，谷歌地图平台服务条款（如技术支持服务、服务水平协议和弃用政策）不适用于此解决方案中的代码。
支持
此示例应用程序是通过开源许可证提供的。它不受谷歌地图平台的管理 技术支持服务指南，the 服务级别协议，或 弃用政策 （但是，示例应用程序使用的任何谷歌地图平台服务仍受谷歌地图平台的服务条款约束）。