# tangdou-rag

**Repository Path**: weedlu/tangdou-rag

## Basic Information

- **Project Name**: tangdou-rag
- **Description**: 基于「BM25 关键词 + 向量语义 → RRF 融合 → Rerank 精排 → LLM 生成带引用回答」的检索增强问答系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-22
- **Last Updated**: 2026-10-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RAG 知识问答系统

基于 **「BM25 关键词 + 向量语义 → RRF 融合 → Rerank 精排 → LLM 生成带引用回答」** 的检索增强问答系统。Vue3 前端 + FastAPI 后端全栈实现，完整方案见 [doc/srs-v1.0.md](doc/srs-v1.0.md)。

![问答会话](doc/imgs/1-1.png)
![知识管理](doc/imgs/1-2.png)
![配置参数](doc/imgs/1-3.png)

## 技术架构

```
用户提问
   │
   ▼
① 混合召回（BM25 + 向量语义，RRF 融合）── 粗筛候选
   │
   ▼
② Rerank 精排（bge-reranker）── 取 Top-K 引用块
   │
   ▼
③ 拼接 Prompt ──► LLM ──► 流式生成带 [n] 引用的回答
```

## 功能特性

- **问答**：流式回答（SSE）、`[n]` 引用与来源面板联动、检索过程四阶段可视化（BM25 / 向量 / RRF / Rerank）、失败重试（复用检索结果）、本地会话历史（50 条回放）
- **知识库**：界面上传 txt / pdf / docx，自动解析 → 切块 → 向量化入库；MD5 去重、状态跟踪、级联删除、全量重建、双路检索调试
- **配置**：LLM / 检索参数 / 切块参数 / 模型路径全部界面化管理，检索参数保存即生效，模型变更支持热重载；API Key 脱敏

## 技术栈

| 模块    | 技术                                            |
| ----- | --------------------------------------------- |
| 前端    | Vue 3 + Vite + Pinia + Element Plus           |
| 后端    | Python + FastAPI + uvicorn                    |
| 向量化   | sentence-transformers（bge-small-zh-v1.5，本地离线） |
| 关键词检索 | BM25 + jieba 分词                               |
| 向量库   | Chroma（持久化落盘 + 元数据过滤）                         |
| 重排    | bge-reranker-base（本地离线）                       |
| 生成    | 任意 OpenAI 兼容接口（界面可配）                          |
| 元数据   | SQLite（配置 + 文档/块管理）                           |

## 快速开始

### 1. 环境准备

- Python 3.10+，Node.js 18+

### 2. 手工下载模型

模型不从 HuggingFace 自动下载，需手工下载到 `backend/models/`（在 `backend` 目录下执行以下命令）：

```
backend/models/bge-small-zh-v1.5    # embedding 模型
backend/models/bge-reranker-base    # 精排模型
```

下载方式（二选一）：

```bash
# 方式一：HuggingFace 镜像
pip install -U huggingface_hub
$env:HF_ENDPOINT = "https://hf-mirror.com"    # PowerShell
huggingface-cli download BAAI/bge-small-zh-v1.5 --local-dir models/bge-small-zh-v1.5
huggingface-cli download BAAI/bge-reranker-base --local-dir models/bge-reranker-base

# 方式二：魔搭 ModelScope（国内直连）
pip install modelscope
modelscope download --model BAAI/bge-small-zh-v1.5 --local_dir models/bge-small-zh-v1.5
modelscope download --model BAAI/bge-reranker-base --local_dir models/bge-reranker-base
```

### 3. 配置 LLM

直接在系统「配置」页填写（要求任意 OpenAI 兼容接口）。

### 4. 启动后端（端口 8088）

```bash
cd backend
python -m venv venv                          # 已有 venv 可跳过
venv\Scripts\python.exe -m pip install -r requirements.txt
venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8088
```

> 首次启动需加载两个本地模型，约需数十秒；就绪后 `GET /api/health` 返回 `engine: ready`。

### 5. 启动前端（http://localhost/rag-web，另开终端）

```bash
cd frontend
npm install
npm run dev
```

浏览器打开 `http://localhost/rag-web`：先在「知识库」页上传文档，再到「问答」页提问。

> 生产构建方式：`npm run build && npm run preview`，同样在 `http://localhost/rag-web` 提供服务。

> 如果将来要脱离 vite、用 Nginx 之类直接托管 dist，记得同样配置 `location /rag-web/` 和 `location /ragapi/`（后者转发到后端时把前缀重写为 `/api/`）两条规则。

## 项目结构

```
tangdou-rag/
├── backend/                  # FastAPI 后端（检索引擎 + 知识库 + 配置中心）
│   ├── app/
│   │   ├── main.py           # 入口：CORS / 路由挂载 / 统一响应
│   │   ├── routers/          # config / kb / qa 三组 REST + SSE 接口
│   │   ├── services/         # rag_engine（管线）/ ingestion（入库）/ config_service
│   │   └── db.py             # SQLite（配置 + 文档/块元数据）
│   ├── models/               # 本地模型目录（bge-small-zh-v1.5、bge-reranker-base）
│   ├── venv/                 # Python 虚拟环境
│   ├── data/                 # 上传文件 + app.db（运行时生成）
│   └── chroma_db/            # Chroma 向量落盘（运行时生成）
├── frontend/                 # Vue3 + Vite + Element Plus
│   └── src/views/            # QaChat（问答）/ KbManage（知识库）/ ConfigManage（配置）
├── doc/srs-v1.0.md           # 软件需求规格说明书（架构/功能/接口/数据设计）
└── .env                      # LLM 配置（仅首次启动迁移用）
```

## 主要接口

| 方法        | 路径                 | 说明                                                        |
| --------- | ------------------ | --------------------------------------------------------- |
| GET       | /api/health        | 健康检查（引擎状态 / 块数 / 文档数）                                     |
| POST      | /api/qa/ask        | 问答（SSE 流式：stage / trace / delta / sources / done / error） |
| POST      | /api/qa/ask/sync   | 问答（非流式，供集成）                                               |
| POST      | /api/kb/documents  | 上传文档（multipart，异步入库）                                      |
| POST      | /api/kb/search     | 双路检索调试（BM25 / 向量 / RRF 三组排名）                              |
| GET / PUT | /api/config        | 读取 / 保存配置                                                 |
| POST      | /api/config/reload | 重载模型引擎                                                    |

完整接口定义见 [doc/srs-v1.0.md](doc/srs-v1.0.md#7-接口设计)。