JEen-wang / Adaptive-rag

Adaptive RAG · 电商客服工作流 
 让简单问题直接回答，让复杂问题找到证据，让业务操作停在确认之前。 
 FastAPI × LangGraph × 混合检索 · API、流式对话与 ChatGPT 风格 Web 工作台 
 项目亮点 · 快速开始 ·
 系统架构 · 实测结果 ·
 简历写法 ·
 完整文档 · 使用边界 ·
 后续路线图 
---
## ✨ 一眼看懂
> **Adaptive RAG** 的核心决策是：这个问题需要直接回答、检索一条证据、交叉核对多条证据、调用业务工具，还是拒绝处理？
电商客服里的问题跨度很大。「你好」无需查知识库；退货政策需要可靠出处；「定制商品超过七天但有质量问题」要同时判断定制、时效与质量例外；取消订单则必须检查订单状态、权限与确认。项目用明确的路由策略处理这些差异，避免把所有输入都塞进同一条向量检索链路。
| 能力 | 你能看到什么 | 关键实现 |
|:---|:---|:---|
| 🧭 **按复杂度路由** | 每次回答带有 `strategy`，便于追踪实际路径 | Graph 与节点 · 策略枚举 |
| 🔎 **有出处的检索** | BM25、稠密向量、RRF 融合与精排；回答可带 `citations` | 检索模块 |
| 🧩 **多跳与自纠错** | 复合问题拆分检索，答案经过忠实度检查 | 智能体节点 |
| 🛡️ **人工确认** | 高风险写操作先返回 `pending_action`，确认后才执行 | 工具与权限 |
| 💬 **Web 对话工作台** | 流式显示、引用、本地会话搜索、深色模式与确认卡片 | 前端 |
| 📈 **可测可观测** | 离线评测、回归测试、结构化日志与 Prometheus 指标 | 评测 · 可观测性 |
### 五条处理路径
| 策略 | 适合的问题 | 处理方式 |
|:---:|:---|:---|
| `DIRECT` | 问候、闲聊 | 直接生成，不做知识检索 |
| `SINGLE` | 单一政策问题 | 一轮混合检索与精排 |
| `MULTI` | 多条件、跨条款问题 | 查询改写、多路检索与自纠错 |
| `AGENT` | 查询订单、物流或发起业务操作 | 规划后调用受权限约束的工具 |
| `REFUSE` | 越权、注入或证据不足 | 拒答或引导人工处理 |
> [!TIP]
> 第一次了解项目，可以先看架构图，再按快速开始提问。想看每条路径怎样落到代码，读智能体与工具。
## 🚀 快速开始
默认使用 SQLite 和内存检索组件，不要求先部署 Redis 或 Qdrant。需要 **Python 3.11+**；Web 开发另需满足前端 Node.js 要求。
### 1. 安装并启动 API
 [code] 
Windows PowerShell 激活虚拟环境可使用 `.venv\Scripts\Activate.ps1`。首次启用本地 Embedding / Cross-Encoder 时可能需要下载模型；需要完整的本地精排依赖可安装 `pip install -e ".[rerank]"`。更多选项见配置参考。
`.env` 中的 `DEEPSEEK_API_KEY` 可留空：此时系统进入离线演示模式，展示检索原文或可核对的订单状态，不会假装生成完整答案。要体验生成式回答，需要配置可用的 DeepSeek 密钥。**不要提交 `.env` 或密钥。**
### 2. 发送第一条消息
 [code] 
响应包含 `answer`、`strategy`、`trace_id`，需要检索时还会带 `citations`。也可以运行 `python -m app.cli` 进入终端对话；流式接口为 `POST /api/v1/chat/stream`，完整字段见 API 参考。
### 3. 打开 Web 工作台
保持 API 运行，另开终端：
 [code] 
访问 **http://127.0.0.1:5173**。开发服务器会把 `/api` 代理到本地 FastAPI。执行 `npm run build` 后，FastAPI 检测到 `frontend/dist` 也会在根路径提供页面；Docker 镜像会自动构建前端。前端会话列表存于浏览器本地，详见前端 README。
 🧪 想体验订单工具与人工确认？展开查看演示数据步骤 
当前分支默认启动**不会自动写入**演示订单。先停止 API，在仓库根目录、已激活虚拟环境的终端执行：
 [code] mermaid
flowchart LR
 U["用户 · Web / CLI / HTTP"] --> API["FastAPI · JSON / SSE"]
 API --> S["ChatService"]
 S --> G["LangGraph：护栏 → 意图 → 复杂度路由"]
 G --> D["DIRECT"]
 G --> R["SINGLE / MULTI"]
 G --> A["AGENT"]
 G --> F["REFUSE"]
 R --> H["BM25 + 向量 → RRF → 精排"]
 A --> T["权限校验 → 工具 → 人工确认"]
 D --> O["生成 / 忠实度检查"]
 H --> O
 T --> O
 F --> O
 O --> X["回答 + 引用 + trace_id"]
 [code] bash
python -m pytest -q
python -m eval.runner --task retrieval
cd frontend && npm test && npm run build
 [code] text
app/
 api/ HTTP 路由、校验、SSE
 services/ ChatService、依赖容器、演示数据
 agents/ LangGraph 状态机与节点
 retrieval/ 解析、切块、混合检索、精排与自纠错
 tools/ 业务工具、注册表与权限
 repositories/ 订单、会话与幂等
 providers/ 生成、Embedding 与 Rerank
 guardrails/ 注入、边界与忠实度检查
 memory/ 上下文预算与压缩
 observability/ 日志、指标与请求上下文
frontend/ React + TypeScript Web 工作台
knowledge/ 政策文档
eval/ 离线评测与口径
tests/ 单元、集成与端到端测试
docs/ 技术手册与教学文档
```
## ⚠️ 使用边界
这是可运行的工程示例，**目前不应直接面向不可信用户开放**：
- API 尚未认证请求中的 `user_id`；前端默认 `u_demo` 仅供本地演示。部署前应由可信服务端认证并绑定身份。
- 订单与物流来自本地仓储演示数据，没有连接真实承运商或支付网关。
- Web 会话列表保存在当前浏览器的 `localStorage`，清除站点数据或换设备后不会恢复。
- 知识库启动时