MCP查询
一个将Spice.ai与来自opendata.swiss的ZVV（苏黎世公共交通）数据相结合的应用程序，通过大型语言模型的集成，实现对公共交通信息的自然语言查询。
服务介绍
ZVV-MCP 与 SpiceAI
该项目展示了如何将 SpiceAI 集成到 Next.js 应用程序中。
本地开发
- 安装依赖项：
bash
npm install
- 安装 SpiceAI 运行时：
bash
curl https://install.spiceai.org | /bin/bash
- 启动 SpiceAI 运行时：
bash
spice run
- 启动开发服务器：
bash
npm run dev
- 在浏览器中打开 http://localhost:3000
Vercel 部署
要在 Vercel 上部署，你需要一个 Spice.ai API 密钥：
- 在 spice.ai 创建一个账户
- 创建一个应用并生成一个 API 密钥
- 将你的 GitHub 仓库与 Vercel 关联
- 在 Vercel 项目设置中将 API 密钥作为环境变量
SPICE_API_KEY添加 - 部署你的项目
功能
- 向 SpiceAI 发送 SQL 查询
- 在表格中显示结果
- 处理查询失败的错误
技术栈
- Next.js 14
- TypeScript
- SpiceAI 客户端
- Vercel 部署
概览
ZVV-MCP 是一个结合了 Spice.ai 和 opendata.swiss 数据的应用程序，通过 LLM（大语言模型）使苏黎世交通联盟 (ZVV) 的公共交通数据可查询。
特性
- Spice.ai 集成：加速数据查询以高效处理大量交通数据集
- opendata.swiss 接口：访问官方 ZVV 数据
- LLM 查询：自然语言查询交通信息
- 响应式设计：在所有设备上优化使用体验
项目结构
src/: 应用程序源代码components/: 可重用的 UI 组件pages/: Next.js 页面和 API 路由styles/: 全局 CSS 样式
public/: 静态文件docs/: 文档zvv-data/: Spice.ai 配置和数据
技术架构
系统组件
该应用程序由三个主要组件组成：
- Next.js 前端：基于 React 的用户界面
- Spice.ai 引擎：处理和分析交通数据
- OpenAI 服务：为自然语言查询提供 LLM 功能
数据流
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌──────────────┐
│ GTFS 数据 │───>│ Spice.ai │<───│ Next.js │<───│ 用户请求 │
│ (opendata) │ │ 引擎 │ │ 前端 │ │ │
└─────────────┘ └──────┬──────┘ └──────┬──────┘ └──────────────┘
│ │
│ │
│ ▼
│ ┌─────────────┐
└──────────>│ OpenAI LLM │
│ (GPT-4o) │
└─────────────┘
用户请求序列图
┌─────────┐ ┌─────────┐ ┌──────────┐ ┌────────┐
│ 用户 │ │ 前端 │ │ OpenAI │ │Spice.ai│
└────┬────┘ └────┬────┘ └─────┬────┘ └────┬───┘
│ │ │ │
│ 提出问题 │ │ │
│ 关于 ZVV 线路 │ │ │
│────────────────────>│ │ │
│ │ │ │
│ │ 查询连接状态 │ │
│ │───────────────────────────────────────────>
│ │ │ │
│ │ 数据元数据 │ │
│ │<───────────────────────────────────────────
│ │ │ │
│ │ LLM 请求带有 │ │
│ │ 上下文和问题 │ │
│ │────────────────────>│ │
│ │ │ │
│ │ LLM 回答 │ │
│ │<────────────────────│ │
│ │ │ │
│ 显示答案 │ │ │
│<────────────────────│ │ │
│ │ │ │
┌────┴────┐ ┌────┴────┐ ┌─────┴────┐ ┌────┴───┐
│ 用户 │ │ 前端 │ │ OpenAI │ │Spice.ai│
└─────────┘ └─────────┘ └──────────┘ └────────┘## 安装
前提条件
- Node.js (>= 14.x)
- npm 或 yarn
- Spice.ai CLI（参见 docs/installation.md）
- Docker（可选，用于容器化）
设置
bash
安装项目依赖
npm install
安装 Spice.ai（详情参见 docs/installation.md）
curl -fsSL https://raw.githubusercontent.com/spiceai/spiceai/trunk/install/install.sh | bash
初始化 Spice.ai 项目
spice init zvv-data
开发
bash
启动 Next.js 开发服务器
npm run dev
在另一个终端中：启动 Spice.ai 运行时
cd zvv-data
spice run
数据
ZVV GTFS 数据
该项目使用来自苏黎世交通联盟的 GTFS 数据（通用交通数据规范）。这些数据预计存放在 data/ 目录下，并在 spicepod.yaml 中配置。
注意：CSV 数据文件非常大，不会存储在 Git 仓库中。您需要单独下载并将它们放置在 data/ 目录下。
所需文件如下：
stops.csv- 站点（约 5,791 条记录）routes.csv- 路线（约 383 条记录）trips.csv- 行程（约 205,526 条记录）stop_times.csv- 时间表（约 3,456,460 条记录）calendar.csv- 运营日（约 1,695 条记录）transfers.csv- 换乘连接（约 10,342 条记录）agency.csv- 交通公司shapes.csv- 路径走向calendar_dates.csv- 额外运营日/例外情况
数据可以从 opendata.swiss 下载。
最佳实践
开发
- 组件设计：使用函数式 React 组件和 Hooks
- 类型化：使用 TypeScript 进行静态类型检查并获得更好的 IDE 支持
- 状态管理：使用 React Context 在组件间共享状态
- CSS 组织：使用 Tailwind 类实现一致的设计
数据处理
- 数据缓存：利用 Spice.ai 加速大型数据集的快速查询
- 增量加载：仅加载所需数据以优化性能
- 错误处理：为 API 调用和数据处理提供健壮的错误处理机制
LLM 集成
- 提示工程：使用精确的系统提示以获取准确的回答
- 上下文管理：将相关数据纳入 LLM 提示中
- 响应解析：结构化处理 LLM 的响应
生产环境
bash
npm run build
npm start
文档
- Spice.ai 安装
- 数据模型
- 项目计划
- LLM 集成
- API 文档 - OpenAPI/Swagger 规范
技术栈
- 前端：Next.js、React、TypeScript、Tailwind CSS
- 数据处理：Spice.ai
- 数据源：opendata.swiss (GTFS 数据)
- AI 模型：OpenAI GPT-4o 用于自然语言查询
