# rag_knowledge_base

**Repository Path**: hankaizhou/rag_knowledge_base

## Basic Information

- **Project Name**: rag_knowledge_base
- **Description**: 基于LangChain和ChromaDB的RAG知识库系统，专为测试领域设计，支持多格式文档（PDF/Markdown/Excel等）智能处理、语义检索、混合检索、RAGAS评估、Web可视化界面和RESTful API，助力高效知识管理与智能问答。
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-02-06
- **Last Updated**: 2026-07-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RAG 知识库系统

基于 LangChain + ChromaDB 的测试领域 RAG 知识库，支持语义检索、智能文档管理。

支持 **云端 API**（默认，无需 GPU）和 **本地模型**（需 GPU）两种模式，一键切换。

---

## 🚀 快速开始

### 云端模式（推荐，无需 GPU）

**第 1 步：安装依赖**

```bash
pip install -r requirements.txt
```

**第 2 步：创建配置**

```bash
cp .env.example .env
```

然后编辑 `.env` 文件：

- **`DEEPSEEK_API_KEY`** — 填入你的 DeepSeek API Key（**必须**）
- `PROVIDER_MODE` — 保持 `cloud`（默认就是云端模式）
- `DASHSCOPE_API_KEY` — 已设系统环境变量的话跳过，否则填阿里云 Key

**第 3 步：启动服务**

```bash
python start_api.py
```

启动后访问：

| 地址 | 说明 |
|------|------|
| `http://127.0.0.1:8000` | API 服务 |
| `http://127.0.0.1:8000/docs` | API 文档（Swagger） |
| `http://127.0.0.1:8000/health` | 健康检查 |

### 本地模型模式（需要 GPU）

**第 1 步：安装依赖**

```bash
pip install -r requirements.txt
```

**第 2 步：下载模型**

```bash
python scripts/download_model.py
```

> 脚本自动从 ModelScope 下载嵌入模型和重排序模型（国内速度快）。
> 如需下载多模态 GGUF 模型：`$env:DOWNLOAD_GGUF="true"; python scripts/download_model.py`

**第 3 步：创建配置**

```bash
cp .env.example .env
```

编辑 `.env`：

- **`DEEPSEEK_API_KEY`** — 填入你的 DeepSeek API Key（**必须**）
- **`PROVIDER_MODE=local`** — 切换到本地模式

**第 4 步：构建知识库**

```bash
python main.py --build
```

**第 5 步：启动服务**

```bash
python start_api.py
```
python scripts/download_model.py   # 自动从 ModelScope 下载

# 2. 配置
cp .env.example .env
# 编辑 .env：设置 PROVIDER_MODE=local

# 3. 构建知识库 + 启动
python main.py --build
python start_api.py
```

---

## ⚙️ 配置

### 一键切换模式

```env
# .env 里改这一行就行
PROVIDER_MODE=cloud   # 嵌入 + 重排 + 多模态全走阿里云 API（月费 ≈ ¥3）
# PROVIDER_MODE=local  # 全走本地模型（需要 GPU，不产生 API 费用）
```

各组件也可单独覆盖：

```env
# 全局走 API，但重排序用本地模型
PROVIDER_MODE=cloud
RERANKER_PROVIDER=local
```

### 主要配置项

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `PROVIDER_MODE` | 总开关：`cloud` / `local` | `cloud` |
| `DEEPSEEK_API_KEY` | DeepSeek API 密钥（**必填**） | - |
| `LLM_PROVIDER` | LLM 提供商：`deepseek` / `ollama` | `deepseek` |
| `EMBEDDING_PROVIDER` | 嵌入模型：`dashscope` / `local` / `openai` | 跟随 `PROVIDER_MODE` |
| `RERANKER_PROVIDER` | 重排序：`local` / `dashscope` | 跟随 `PROVIDER_MODE` |
| `MULTIMODAL_PROVIDER` | 多模态图片描述：`local` / `dashscope` | 跟随 `PROVIDER_MODE` |
| `CHUNK_SIZE` | 文本分块大小（字符数） | `512` |
| `HYDE_ENABLED` | 启用 HyDE 检索增强 | `true` |
| `API_HOST` / `API_PORT` | 服务地址和端口 | `0.0.0.0:8000` |

### 三种运行模式对比

| 模式 | PROVIDER_MODE | 费用 | GPU 要求 | 推荐场景 |
|------|-------------|------|---------|---------|
| 🌐 **全云端** | `cloud` | ≈ ¥3/月 | 不需要 | 日常使用 |
| 🔀 **混合** | `cloud` + 个别设 `local` | 介于之间 | 部分需要 | 省 API 费 |
| 💻 **全本地** | `local` | ¥0 | 需要 | 离线/保密场景 |

---

## 📖 使用指南

### API 服务

```bash
python start_api.py
```

主要接口：

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/v2/chat` | 对话查询 |
| POST | `/v2/retrieve` | 纯检索（不含 LLM） |
| POST | `/v2/documents/upload` | 上传文档 |
| GET | `/v2/documents` | 文档列表 |

### 命令行

```bash
# 单次查询
python main.py --query "什么是功能测试？"

# 交互模式（连续对话）
python main.py --interactive

# 构建/更新知识库
python main.py --build
```

### 添加文档

将文档放入对应目录，然后重新构建：

```
documents/test_rules/       # 测试规则
documents/product_design/   # 产品设计
documents/technical/        # 技术文档
```

支持格式：`.md` `.pdf` `.docx` `.xlsx` `.txt`

```bash
python main.py --build   # 增量构建，自动检测新增/修改的文档
```

---

## 📁 项目结构

```
rag_knowledge_base/
├── start_api.py              # API 服务启动（推荐入口）
├── main.py                   # CLI 入口
├── run.py                    # 交互式菜单
├── .env                      # 环境变量配置
├── .env.example              # 配置模板（新电脑复制用）
│
├── rag_system/               # 核心代码
│   ├── api.py               # FastAPI 应用
│   ├── config.py            # 配置管理
│   ├── vector_store/        # 向量存储（ChromaDB）
│   ├── retriever/           # 检索器（向量 + BM25 混合）
│   │   ├── hybrid_retriever.py
│   │   ├── bm25_retriever.py
│   │   ├── dashscope_reranker.py  # API 重排序
│   │   └── ...
│   ├── rag_chain.py         # RAG 链路
│   ├── document_loader.py   # 文档加载
│   ├── text_splitter.py     # 自适应分块
│   ├── multimodal_processor.py  # 多模态图片描述
│   ├── qwen3_reranker.py    # 本地重排序模型
│   ├── corrective_rag.py    # CRAG 纠错
│   ├── self_rag.py          # Self-RAG
│   ├── routers/             # API 路由
│   └── agent/               # AI Agent 模块
│
├── scripts/                  # 工具脚本
│   ├── download_model.py    # 模型下载（ModelScope/HuggingFace）
│   └── ...
├── models/                   # 本地模型文件
├── documents/                # 知识库文档
├── vector_db/                # 向量数据库（ChromaDB）
├── database/                 # 文档注册表（SQLite）
├── data/                     # 缓存和统计数据
├── tests/                    # 单元测试
└── logs/                     # 日志文件
```

### 检索链路

```
用户查询 → HyDE 重写 → 向量检索 + BM25 关键词 → 混合融合
         → CrossEncoder 重排序 → CRAG 纠错 → 答案
```

> 注：Self-RAG（自反思生成）默认关闭，每次回答会额外调 LLM 多次验证，按需启用。

---

## 🔧 命令参考

| 命令 | 说明 |
|------|------|
| `python start_api.py` | 启动 API 服务 |
| `python start_gpu.py` | 启动 API（GPU 预加载模式） |
| `python main.py --build` | 构建/更新知识库 |
| `python main.py --rebuild` | 重建知识库（清空旧数据） |
| `python main.py --query "问题"` | 单次查询 |
| `python main.py --interactive` | 交互式命令行 |
| `python run.py` | 交互式菜单 |
| `python scripts/download_model.py` | 下载本地模型（ModelScope） |
| `python setup.py` | 一键初始化（新电脑） |

---

## 💡 常见问题

**新电脑怎么部署？**
```
1. pip install -r requirements.txt
2. cp .env.example .env
3. 编辑 .env 填入 DEEPSEEK_API_KEY
4. python start_api.py        # 云端模式，直接启动
```

**本地模型怎么下载？**
```bash
pip install modelscope    # 国内下载必备
python scripts/download_model.py   # 自动从 ModelScope 下载
```

**如何换回本地模型？**
在 `.env` 中设 `PROVIDER_MODE=local`，确保模型已下载即可。

**API 调用费用高吗？**
云端模式（PROVIDER_MODE=cloud）月费约 ¥3（嵌入 + 重排 + 多模态），比一杯奶茶便宜。

**有 GPU 但用不上？**
`start_api.py` 自动检测 GPU。如需强制 CPU，设 `EMBEDDING_DEVICE=cpu`。

---

## 📦 依赖

核心依赖在 `requirements.txt`，新电脑 `pip install -r requirements.txt` 即可。

主要依赖：`langchain` `chromadb` `sentence-transformers` `fastapi` `dashscope` `modelscope`

---

## 许可证

AGPL v3