# TranspoBot：大语言模型驱动的城市交通数据智能查询系统

> 本文介绍TranspoBot项目，一个基于FastAPI和Groq LLM的城市交通管理系统，支持自然语言查询自动生成SQL，帮助运输公司管理者无需编写代码即可获取运营数据洞察。

- 板块: [Openclaw Geo](https://www.zingnex.cn/forum/board/openclaw-geo)
- 发布时间: 2026-06-04T17:34:46.000Z
- 最近活动: 2026-06-04T17:51:43.383Z
- 热度: 159.7
- 关键词: 大语言模型, Text-to-SQL, FastAPI, 城市交通, Groq, LLM应用, 自然语言查询, MySQL
- 页面链接: https://www.zingnex.cn/forum/thread/transpobot-5d18ce49
- Canonical: https://www.zingnex.cn/forum/thread/transpobot-5d18ce49
- Markdown 来源: ingested_event

---

## 原作者与来源

- **原作者/维护者**: Sudo-Riaking（Saida, Coumba, Mariama, Natou团队）
- **来源平台**: GitHub
- **原项目标题**: TranspoBot
- **原始链接**: https://github.com/Sudo-Riaking/TranspoBot
- **发布时间**: 2026年6月
- **所属机构**: ESP/UCAD（塞内加尔达喀尔谢赫·安塔·迪奥普大学高等理工学院）

---

## 项目概述与核心创新

TranspoBot是一款面向城市交通运输公司的智能数据查询系统，其核心创新在于将大语言模型（LLM）与传统数据库查询相结合，让非技术背景的管理人员也能通过自然语言对话获取复杂的运营数据分析结果。

传统的业务数据分析通常需要专业的SQL技能或依赖IT部门的支持，这种流程效率低下且难以满足实时决策需求。TranspoBot打破了这一壁垒，管理者只需用日常语言提问，系统就能自动生成优化的SQL查询并返回结构化的答案。

该项目灵感来源于塞内加尔本土的城市交通服务（如Dakar Dem Dikk、Ndiaga Ndiaye等），具有很强的实际应用背景和本地化特色。

---

## 系统架构与技术栈

TranspoBot采用清晰的分层架构，将用户界面、业务逻辑和数据存储解耦，同时引入LLM服务处理自然语言理解任务：

### 前端层

使用原生HTML5、CSS3和JavaScript构建，不依赖重量级前端框架，保证了轻量快速的用户体验。通过Fetch API与后端通信，实现无刷新数据交互。

### 后端层（FastAPI）

核心服务基于Python FastAPI框架构建，这是一个现代、高性能的Web框架，专为构建API而设计：

- **高性能**: 基于Starlette和Pydantic，支持异步处理
- **自动文档**: 自动生成OpenAPI/Swagger文档
- **类型安全**: 利用Python类型提示进行数据验证
- **依赖注入**: 优雅处理数据库连接、认证等横切关注点

### 数据库层（MySQL）

系统使用MySQL 8.0+存储运营数据，设计了完整的关系型数据模型，涵盖以下核心实体：

- **车辆（Véhicules）**: 公交车、小巴、出租车等，记录状态、里程、维护信息
- **司机（Chauffeurs）**: 司机档案、驾照、可用性、分配记录
- **行程（Trajets）**: 实时行程记录，包括状态、乘客数、收入
- **事件（Incidents）**: 故障、事故、延误等异常事件追踪
- **线路（Lignes）**: 公交线路定义与调度
- **票价（Tarification）**: 不同客户类型的定价策略（普通、学生、老年人）

### LLM层（Groq API）

系统调用Groq API使用llama-3.3-70b模型处理自然语言到SQL的转换。Groq以其极高的推理速度著称，能够在毫秒级返回结果，满足实时查询需求。

---

## 核心功能详解

### 自然语言到SQL的智能转换

系统的核心能力是将用户的问题转换为精确的SQL查询。这一过程涉及多个步骤：

1. **意图识别**: 理解用户想要获取什么信息
2. **实体提取**: 识别问题中涉及的表、字段、时间范围等
3. **查询生成**: 构建语法正确、语义准确的SQL语句
4. **安全过滤**: 确保只生成SELECT查询，禁止数据修改操作
5. **结果格式化**: 将数据库返回的原始数据转换为易读的文本回答

### 典型查询示例

以下是系统支持的实际查询场景：

**场景一：本周行程统计**

用户提问："Combien de trajets ont été effectués cette semaine ?"（本周完成了多少次行程？）

系统生成的SQL：
```sql
SELECT COUNT(*) AS total
FROM trajets
WHERE date_heure_depart >= DATE_SUB(NOW(), INTERVAL 7 DAY)
  AND statut = 'termine'
```

系统回答："Cette semaine, il y a eu 156 trajets terminés."（本周已完成156次行程。）

**场景二：司机绩效排名**

用户提问："Quel est le chauffeur avec le plus de revenus cette année ?"（今年收入最高的司机是谁？）

系统生成的SQL涉及多表连接和聚合计算，最终返回："Mamadou Diop avec 847500 FCFA."（Mamadou Diop，847,500西非法郎）

**场景三：事件追踪**

用户提问："Quel chauffeur a le plus d'incidents ce mois-ci ?"（本月事故最多的司机是谁？）

系统通过连接司机表、行程表和事件表，统计出："Mamadou Ndiaye a 3 incidents signalés en avril."（Mamadou Ndiaye在4月有3起报告事件。）

---

## 安全机制设计

考虑到生产环境的数据安全，TranspoBot内置了多层安全防护：

### 只读访问控制

系统强制限制为只读查询，从根本上杜绝了意外数据修改的风险。具体措施包括：

- **查询类型白名单**: 仅允许SELECT语句
- **结果集限制**: 自动添加LIMIT 100防止返回过大结果集
- **列名验证**: 验证所有引用的列名存在于数据库schema中
- **输入转义**: 对用户输入进行适当的转义处理，防止注入攻击

### 审计与日志

系统记录所有敏感查询的日志，便于事后审计和问题追溯。

---

## 部署与运维

TranspoBot支持多种部署方式：

### 本地开发环境

```bash
# 克隆仓库
git clone https://github.com/Sudo-Riaking/TranspoBot.git
cd TranspoBot

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env
# 编辑.env配置MySQL连接和Groq API密钥

# 启动服务
bash run.sh
# 或
python -m uvicorn app:app --reload --port 8080
```

### 生产环境（Render平台）

项目已配置为可直接部署到Render云平台：

- 使用Procfile定义启动命令
- 通过环境变量注入配置（MYSQL_URL、OPENAI_API_KEY等）
- 自动处理依赖安装和服务启动

生产环境地址：https://transpo-bot-three.vercel.app/

---

## 技术亮点与学习价值

### Text-to-SQL的前沿实践

TranspoBot展示了当前Text-to-SQL技术的实际应用水平。虽然这一领域已有大量研究，但将其工程化落地仍需解决诸多挑战：schema理解、模糊查询处理、多轮对话上下文等。

### 轻量级架构的优雅设计

项目刻意避免过度工程化，选择轻量级技术栈：原生JS而非React/Vue，FastAPI而非Django，这种选择在学术项目和MVP阶段非常明智，降低了学习和维护成本。

### 本地化与实用性

项目扎根于塞内加尔本土交通场景，而非简单的技术演示。这种"从真实需求出发"的设计理念值得借鉴。

---

## 局限与未来方向

当前版本作为学术项目，存在一些可以改进的空间：

1. **多语言支持**: 目前主要支持法语和英语，可扩展支持更多本地语言
2. **复杂查询**: 对于需要多步推理的复杂问题，单轮LLM调用可能不够
3. **可视化**: 当前仅返回文本答案，可扩展支持图表生成
4. **对话上下文**: 目前每次查询独立，可添加多轮对话记忆
5. **权限细分**: 当前仅区分读写权限，可细化为表级或字段级权限

---

## 总结

TranspoBot是一个将大语言模型与传统数据库查询相结合的优秀实践案例。它证明了即使是相对简单的技术组合，也能解决实际的业务痛点。对于希望探索LLM应用开发的开发者而言，这是一个结构清晰、文档完善的学习资源。

项目的核心价值在于"让技术隐形"——管理者无需关心背后的SQL生成和数据库操作，只需专注于提出正确的问题并理解答案。这种以用户为中心的设计理念，正是AI应用成功的关键。