gbh1234 / Adaptive-rag

# Adaptive-RAG 电商客服
针对多条件政策咨询中证据不充分、回答缺乏依据的问题，实现具备自适应检索能力的电商客服系统。项目采用 FastAPI、LangGraph 和 React，通过动态检索路由、多轮证据补充与忠实度校验提升回答质量，支持政策引用、订单查询与人工确认。
意图识别支持 **TypeSafe Jev 与 DeepSeek 两种后端**：可使用 Jev 的结构化 choice 接口识别业务意图，由后续工作流完成检索、工具调用和回答；Jev 不可用时回退至原有分类链路。
> 当前适合本地演示、学习与工程验证。订单和物流来自演示数据，API 尚未验证请求中的 `user_id`，部署到公网前需要接入可信身份认证。
## 核心能力
- **Jev 意图识别**：支持 TypeSafe System One 接口，按预定义的 14 类业务意图返回标签、置信度与类别概率，使用 Pydantic 校验响应，并可通过规则覆盖层修正易混淆意图。
- **自适应路由**：结合意图与问题复杂度，选择直接回答、单轮检索、多轮检索、工具执行或拒答路径。
- **混合检索**：BM25 + 稠密向量召回，经 RRF 融合与可选 Cross-Encoder 精排。
- **证据校验**：查询改写、多轮补充检索、回答忠实度检查与自纠错。
- **文档入库**：支持 Markdown；安装可选依赖与系统工具后可解析 PDF、Office 等格式。
- **切块与引用**：按文档结构分段，普通文本采用 500 字符窗口、60 字符重叠；Unstructured 识别出的表格单独成块。切片携带标题、章节、来源等元数据。
- **工具执行**：提供订单等业务工具，包含权限检查、执行降级、人工确认与幂等机制，可接入 MCP。
- **聊天界面**：React 前端支持来源引用、本地会话管理和确认卡片；SSE 在答案完成校验后分段发送。
- **工程支持**：会话记忆压缩、结构化日志、Prometheus 指标、健康检查与自动化测试。
切片 ID 由文档路径和切片序号确定：相同路径和切分结果重复入库时可保持一致；文件迁移、内容编辑或切块策略变化后，不保证历史引用仍指向相同内容。
## 工作流程
 [code] 
## 模型分工
| 组件 | 模型或实现 | 职责 |
| --- | --- | --- |
| 意图识别 | 可选 TypeSafe Jev，配置默认 `jev-1.13.0`；默认后端为 DeepSeek | 识别退款、退换货、物流、转人工等业务诉求 |
| 工作流中的 LLM | DeepSeek，默认 `deepseek-chat` | 复杂度判断、查询改写、任务规划、回答生成、忠实度检查与记忆摘要 |
| 稠密召回 | 本地 `BAAI/bge-small-zh-v1.5`，或配置的远程向量接口 | 将文本与查询编码为向量 |
| 精排 | 可选本地 `BAAI/bge-reranker-base` | 对召回片段重新评分 |
Jev 仅替换意图分类节点，切换后其余 LLM 节点仍使用 DeepSeek；未配置 DeepSeek 密钥时，其余流程使用离线演示逻辑。
## 本地快速开始
需要 Python 3.11+。Web 前端需要 Node.js 20.19+ 或 22.12+ 及 npm。本地默认使用 SQLite 和内存检索组件，无需先启动 Docker。
以下命令在项目根目录执行，适用于 Windows PowerShell：
 [code] 
已有 `.env` 时保留原文件，跳过复制步骤。macOS / Linux 可在创建虚拟环境后执行 `source .venv/bin/activate`，再使用 `python`、`pip` 与 `cp` 对应命令。
编辑本地 `.env`：
| 配置 | 说明 |
| --- | --- |
| `DEEPSEEK_API_KEY` | 启用 DeepSeek 工作流及默认意图分类；真实 API 调用可能产生费用 |
| `INTENT_BACKEND` | `deepseek`（默认）或 `jev`，只切换意图识别后端 |
| `JEV_API_KEY` | 使用 Jev 意图分类时需要，仅填写在本地 `.env` |
| `JEV_MODEL` | Jev 模型名，当前项目配置默认 `jev-1.13.0` |
| `DATABASE_URL` | 默认 `sqlite+aiosqlite:///./data/local/app.db` |
| `KNOWLEDGE_DIR` | 默认 `knowledge`，启动时入库 |
| `LOCAL_EMBEDDING_ENABLED` | 本地语义向量开关 |
| `CROSS_ENCODER_ENABLED` | 本地精排开关 |
| `REDIS_URL` / `QDRANT_URL` | 可选外部缓存与向量服务地址 |
不配置 DeepSeek 密钥时，系统使用离线演示逻辑，回答质量与真实模型模式不同。完整变量见 配置参考 与 .env.example。
### 启用 Jev 意图识别
在本地 `.env` 中修改以下配置，并填入自己的密钥；下面的值仅为占位示例：
 [code] 
修改后重启后端。恢复原有意图分类只需将 `INTENT_BACKEND` 改回 `deepseek`。
Jev 接入通过 HTTP 请求完成，无需额外安装专用 SDK。请求使用预定义的意图选项，响应经 Pydantic 校验后转换为统一的分类结果。密钥缺失、请求失败或响应不合法时，自动回退至原有 `IntentClassifier`；该链路优先使用配置的 DeepSeek，离线或模型调用失败时采用规则分类。可重试错误使用指数退避，`JEV_MAX_RETRIES` 在实现中表示最大尝试次数。
`JEV_INTENT_APPLY_OVERLAY` 控制 Jev 成功分类后的规则纠偏，默认开启；它不控制回退分类器自身的覆盖层。实现见 Jev 分类器 与 工作流接入。
### 可选模型与文档解析
 [code] 
`rerank` 依赖用于本地稠密向量模型与 Cross-Encoder，模型默认分别为 `BAAI/bge-small-zh-v1.5` 和 `BAAI/bge-reranker-base`。首次加载可能下载权重；本地模型不可用时会降级，检索效果不能与完整模型配置等同。
`docs` 依赖用于 Unstructured 文档解析。PDF、OCR、Office 等格式还可能需要 Poppler、Tesseract（含中文语言包）、LibreOffice，具体见 解析与检索说明。
### 启动 Web 前端
保持后端运行，在另一个终端执行：
 [code] 
访问 聊天页面。开发服务器将 `/api` 请求代理到本机 8000 端口。
运行 `npm run build` 后，FastAPI 会在检测到 `frontend/dist` 时从根路径提供页面。更多说明见 前端 README。
## 体