# highway_ier_agent

**Repository Path**: aigcJia/highway_ier_agent

## Basic Information

- **Project Name**: highway_ier_agent
- **Description**: Highway Intelligent Emergency Response Agent，高速智能应急响应智能体
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-02
- **Last Updated**: 2026-09-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 豫途护航 · 高速交通智能应急智能体问答系统

面向高速公路运营管理公司、路网指挥中心与一线处置人员的高速公路突发事件智能应急问答系统。
围绕 **事前监测预警 — 事中处置决策 — 事后复盘沉淀** 全链路，以自然语言为入口，提供应急态势问答、
决策辅助（影响评估 / 资源调度 / 绕行分流 / 情报板文案 / 相似案例）、多条件数据查询、
法规预案知识问答与评测回归能力。

- 无大模型密钥、无网络也可运行：内置 **Mock 离线回放模式**
- 多智能体编排、决策动作人工确认（HITL）、事实输出强制引用溯源
- 全部 demo 数据为**确定性合成**（同 seed 可复现），内置 18 项数据质量校验

## 目录速览

```
backend/                 FastAPI 后端（LLM 适配、RAG、MCP 工具、Skill、LangGraph 智能体、接口）
  app/
    llm/                 大模型适配层：deepseek/qwen/openai 兼容/ollama/mock
    rag/                 文档解析切片、向量化、BM25、RRF 融合、Rerank、引用封装
    mcp/                 工具注册表与实现（只读可并行、写操作强制 HITL）
    skills/              Skill 定义与编排（影响评估/绕行/调度/情报板/案例匹配）
    agents/              intent/data_query/knowledge/decision/review 子智能体
    graph/               状态图编排（Supervisor + 领域子智能体 + 校验节点 + 中断）
    api/                 REST / SSE 接口
    db/                  SQLite（只读白名单 + 必带 LIMIT）安全访问层
    services/            影响评估、资源调度、绕行、情报板、报表、评测
    schemas/             Pydantic 请求/响应契约
frontend/               React 18 + TS + Vite + Tailwind（五页）
data/
  dict/data_dictionary.yaml   数据字典（全字段口径）
  generated/*.csv             合成 demo 数据集
  knowledge/                  知识源文档（法规/预案/规程/案例/指标口径）
  index/                      RAG 向量索引
  warehouse.db                SQLite 数据库（自动生成）
eval/                   评测集与评测执行器（core.jsonl / run_eval.py / reports/）
scripts/                 gen_data / gen_knowledge / load_db / build_kb / gen_eval / quality_check / smoke
docs/                    建设方案文档（00-06）
```

## 一键启动（开发预览）

```bash
# 1) 后端依赖（Python 3.11+）
cd backend && python3 -m pip install -r requirements.txt && cd ..

# 2) 一键初始化：生成数据 → 装载 SQLite → RAG 索引 → 评测集
bash scripts/smoke.sh --skip-gen          # 首次可去掉 --skip-gen 连数据一起生成

# 3) 启动后端
cd backend && python3 -m uvicorn app.main:app --reload --port 8000

# 4) 启动前端
cd frontend && npm install && npm run dev
# 浏览器打开 http://localhost:5173（已代理 /api → 127.0.0.1:8000）
```

## 界面预览

![对话问答](img/高速-问答1.png "对话问答")
![应急决策1](img/高速-应急决策2-1.png "应急决策1")
![应急决策2](img/高速-应急决策2-2.png "应急决策2")
![数据查询](img/高速-查数3.png "数据查询")
![知识库](img/高速-RAG4.png "知识库")
![评测看板](img/高速-评测5.png "评测看板")


## 冒烟自检

```bash
bash scripts/smoke.sh     # 生成→装载→知识库→评测集→启动→curl 自检
```

数据质量与口径：见 `docs/01-数据规格与demo数据构造.md` 与 `scripts/quality_check.py`。

## 常用命令

| 命令 | 说明 |
| --- | --- |
| `python3 scripts/gen_data.py` | 确定性合成 demo 数据并输出 18 项质量校验报告 |
| `python3 scripts/gen_knowledge.py` | 由结构化真值派生历史案例文档与指标口径文档 |
| `python3 scripts/load_db.py` | 全量装载 CSV 到 SQLite（幂等） |
| `python3 scripts/build_kb.py --force` | 构建 RAG 知识索引（标题感知切片 + 向量化） |
| `python3 scripts/gen_eval.py` | 生成评测集 `eval/datasets/core.jsonl` |
| `python3 eval/run_eval.py --dataset core --limit 40` | 运行评测并输出报告 |
| `python3 scripts/smoke.sh` | 端到端冒烟 |

## 配置云端模型（可选）

复制 `.env.example` 为 `.env`，设置 `LLM_PROVIDER` / `LLM_API_KEY` 与
`EMBED_PROVIDER` / `EMBED_API_KEY` 即可切换到云端（DeepSeek / 通义 OpenAI 兼容协议）。
未设置密钥时自动进入 Mock 离线回放模式。

## 评测与治理

- 评测集由结构化真值自动派生（确定性、可判定、可回归），叠加人工标注知识类用例；
- 指标：意图准确率、工具调用准确率、事实关键词命中、引用溯源命中、LLM-as-Judge 综合分、时延；
- 看板：后端 `GET /api/eval/...`，前端「评测看板」页可视化最近运行；
- 所有事实性输出在服务端校验后带引用编号 `[n]`，未检索到依据会显式降级提示。

## 安全与治理约定

- 数据查询仅允许 SELECT、表/字段白名单、强制 LIMIT；写操作（落工单 / 发情报板）必须人工确认；
- 检索/生成过程不打印密钥与检索正文；日志记录 session_id / 工具名 / 耗时 / 错误码。