Router-based RAG (Agent + Semantic Search)

Retrieval uses chunk-level semantic vector search cached in SQLite table chunk_embeddings, with optional Cross-Encoder rerank (set RERANK_ENABLED=1, configure RERANK_MODEL). Embeddings come from OpenAI (set OPENAI_API_KEY, optionally OPENAI_EMBEDDING_MODEL).

一个从零搭建的多源异构数据路由检索示例，包含：

• 多源路由：SQL / 内部知识库 / 外部资讯（模拟 API）
• 混合检索：向量（TF-IDF 近似语义）+ BM25 融合
• 可扩展数据源：前端可上传 TXT、创建/编辑数据表、抓取网页入库
• Agent 前端：左侧路由（问答、上传文本、数据表管理、在线网址新增）

项目结构

.
├─backend/         # FastAPI 后端 + 路由/检索逻辑
├─data/            # 示例数据（wiki 文档、模拟 API、SQLite）
├─frontend/        # 纯静态前端（HTML/CSS/JS）
├─requirements.txt # 依赖
└─README.md

快速开始

1. 安装依赖（建议虚拟环境）

pip install -r requirements.txt

2. 设置 LLM Key（必需，否则后端直接报错）

export OPENAI_API_KEY=sk-xxxx         # Windows: set OPENAI_API_KEY=...
# 如果用代理/自建网关，可设置 OPENAI_API_BASE，例如 https://api.openai.com/v1
# export OPENAI_API_BASE=https://your-proxy/v1

3. 生成示例数据库

python backend/seed_db.py

4. 启动后端

uvicorn backend.main:app --reload --port 8000

5. 打开前端
   直接在浏览器打开 frontend/index.html。如果浏览器拦截本地文件请求，可用任意静态服务器（如 python -m http.server 3000 -d frontend）。

LLM 模型默认 gpt-4o-mini，可在 backend/llm_client.py 调整。

示例问句

• 「6 月销量/销售额怎么样？」→ 路由到 SQL，汇总销量与收入
• 「库存有没有预警？」→ 路由到 SQL，查询低库存
• 「混合检索是什么？」→ 路由到 wiki，使用 TF-IDF+BM25 混排
• 「最新大促复盘？」→ 路由到模拟外部 API（news 数据）
• 上传 TXT / 抓取 URL 后，可直接问新内容；创建新表后可提问该表名

路由与检索逻辑

• 意图识别（backend/agent.py + backend/llm_client.py）：优先用 LLM 输出路由计划（无 key 时回退到 backend/router.py 的启发式）。
• 混合检索（backend/retrievers.py）：
  • TF-IDF 余弦近似语义匹配
  • BM25（rank-bm25）关键词匹配
  • 两者按权重融合为 hybrid 分数
• 数据源
  • data/sample.db：SQLite；内含 products/orders 以及 documents（wiki 语料、上传 TXT、URL 抓取内容）
  • data/news_api.json：模拟外部 API 的资讯

API

• GET /health：健康检查
• POST /query：{"question": "...", "top_k": 4, "mode": null | "semantic_all"}
  返回路由决策与分源结果。

课堂/作业可讲的点

• 混合搜索：倒排（BM25）与向量（TF-IDF 近似）融合
• 路由式 Agent：意图识别 + 工具调用 + 结果聚合
• 数据源异构：SQL vs. 文档库 vs. 外部资讯

后续可扩展

• 替换 TF-IDF 为真实向量模型（如 BGE/SGPT） - 增加 rerank/裁剪、答案生成模块
• 将意图分类改为轻量模型或 prompt 方案
• 为 URL 抓取加入异步队列/去重/清洗；为表管理增加 schema 编辑和更多安全校验