---
title: RouteOpt Agent
emoji: 🧭
colorFrom: blue
colorTo: green
sdk: gradio
python_version: 3.11
app_file: app.py
pinned: false
short_description: Tool-calling route optimizer
---

# RouteOpt Agent

基于公开大模型 API + 轻量工具调用的小规模路线优化智能体。它把用户自然语言转成路线优化任务，调用地理编码和路径矩阵工具，再用本地算法求解访问顺序，并自动生成 PDF 报告。

## 一键运行

```bash
chmod +x run.sh
./run.sh
```

启动后打开：

```text
http://localhost:7860
```

首次运行会创建 conda 环境 `routeopt-agent` 并安装依赖。脚本会先尝试使用 `environment.yml` 创建标准环境；如果 conda 镜像下载不稳定，会自动克隆本机 base 环境，再用 pip 安装 `requirements.txt`。

## LLM 配置

默认配置不需要你注册任何网站，也不需要提供 API token：

- LLM：Pollinations OpenAI-compatible API，无需 token。失败时系统自动切换到本地解析和本地报告模板。
- 地理编码：OpenStreetMap Nominatim 公共接口，内置缓存并限制请求频率。
- 路径矩阵：OSRM public demo server。失败时自动切换到直线距离近似矩阵。
- 部署：Hugging Face Spaces 免费 Gradio Space。

如果本机出现 `ProxyError('Unable to connect to proxy')`，说明 Python 请求走了不可用代理。默认 `LLM_IGNORE_PROXY=1` 会让 LLM 请求忽略系统代理；如果你的网络必须使用代理访问外网，可在 `.env` 中改成：

```bash
LLM_IGNORE_PROXY=0
```

更稳定的做法是使用正规 API key 服务，并把 key 放到 `.env` 或 Hugging Face Secrets。老师访问公开页面时不需要知道 token。

复制配置模板：

```bash
cp .env.example .env
```

推荐方案：

```bash
# Groq：国际网络通常较稳，OpenAI-compatible
LLM_PROVIDER=groq
GROQ_API_KEY=gsk_xxx
GROQ_MODEL=openai/gpt-oss-20b
```

```bash
# SiliconFlow：国内网络通常更友好，OpenAI-compatible
LLM_PROVIDER=siliconflow
SILICONFLOW_API_KEY=sk-xxx
SILICONFLOW_MODEL=THUDM/GLM-Z1-9B-0414
```

```bash
# Gemini：Google 官方免费额度，国内网络可能需要代理
LLM_PROVIDER=gemini
GEMINI_API_KEY=AIza...
GEMINI_MODEL=gemini-2.5-flash
```

也可以用 `LLM_PROVIDER=auto`，程序会按已配置的 key 自动选择：Groq -> SiliconFlow -> Gemini -> OpenRouter；没有 key 时退回 Pollinations。

## 推荐演示输入

自然语言需求：

```text
我从上海交通大学闵行校区出发，想一天内逛完徐家汇、人民广场、外滩、陆家嘴，最后回到起点，尽量总时间短。
```

起点：

```text
上海交通大学闵行校区
```

目的地：

```text
徐家汇
人民广场
外滩
陆家嘴
```

这个样例的上海地点内置了离线坐标兜底，所以即使 Nominatim 临时限流，也能完成演示。

也可以使用北京样例：

```text
我从北京邮电大学出发，想一天内逛完国家大剧院、鼓楼、北海、国家植物园，最后回到起点，尽量总时间短。
```

## 输入失败时如何处理

页面不会直接抛出 Python 错误；如果任务无法完成，会说明失败发生在哪个工具，以及应该如何修改输入。

常见原因：

- 起点或目的地为空。
- 目的地里只有起点，或者重复地点过多。
- 地点不在内置演示坐标中，同时在线地理编码服务超时、限流或找不到结果。
- 地名太泛，例如只写“鼓楼”“植物园”，在某些城市可能有多个匹配。

当前内置演示城市：上海、北京。

如果要演示其他城市，建议把地点写得更完整，例如“南京夫子庙”“广州塔”“深圳大学粤海校区”。如果在线地理编码仍然失败，可以直接输入坐标：

```text
某景点@39.9042,116.4074
```

## Agent Workflow

1. `LLM tool_call: submit_route_task`：把自然语言和表单提示抽取成结构化任务。
2. `geocode_places`：把地点转换为经纬度。
3. `build_route_matrix`：调用 OSRM 获取距离/时间矩阵。
4. `solve_route`：用 Held-Karp 动态规划精确求解小规模 TSP。
5. `LLM compose_summary`：生成中文解释。
6. `generate_pdf_report`：输出包含问题定义、工具调用轨迹、算法和结果的 PDF。

## 公开部署到 Hugging Face Spaces

1. 打开 Hugging Face，新建一个 Space。
2. Space SDK 选择 `Gradio`。
3. Visibility 可选 `Public`。
4. 上传本仓库所有文件，或把仓库推送到 Space。
5. Space 会根据 `requirements.txt` 自动安装依赖，入口文件是 `app.py`。

老师访问 Space 链接即可运行，不需要知道任何 token。

## 文件结构

```text
app.py                     # Gradio 页面入口
routeopt_agent/agent.py    # Agent 编排和工具调用轨迹
routeopt_agent/geo_tools.py# 地理编码、OSRM 矩阵、兜底矩阵
routeopt_agent/solver.py   # Held-Karp 路线优化
routeopt_agent/report.py   # PDF 报告生成
routeopt_agent/parsing.py  # 本地自然语言解析兜底
routeopt_agent/viz.py      # SVG 路线示意图
environment.yml            # 本地 conda 环境
requirements.txt           # Hugging Face Spaces 依赖
run.sh                     # 一键运行脚本
```