Hugging Face's logo

Spaces:
fht5
/
alg-agent
Sleeping

App Files Community
alg-agent / README.md
fenghantong
Deploy RouteOpt Agent
ffda755
preview code
|
Raw
History Blame Contribute Delete
5.24 kB

A newer version of the Gradio SDK is available: 6.19.0

Upgrade
metadata 
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 报告。

一键运行 

chmod +x run.sh
./run.sh

启动后打开：

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 中改成：

LLM_IGNORE_PROXY=0

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

复制配置模板：

cp .env.example .env

推荐方案：

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

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

# 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。

推荐演示输入

自然语言需求：

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

起点：

上海交通大学闵行校区

目的地：

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

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

也可以使用北京样例：

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

输入失败时如何处理

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

常见原因：

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

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

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

某景点@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。

文件结构 

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                     # 一键运行脚本