# 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-05-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RAG知识库系统

基于LangChain框架和ChromaDB向量数据库构建的测试领域RAG知识库系统，支持智能文档管理、语义检索和Web界面操作。

---

## 📖 使用流程（推荐顺序）

### 第一次使用 - 完整流程

```
第1步: 创建conda环境 → 第2步: 安装依赖 → 第3步: 配置环境 → 第4步: 构建知识库 → 第5步: 开始使用
```

---

## 🛠️ 环境准备

### 推荐：使用 Conda 环境（支持 GPU 加速）

本项目使用 `pytorch_cuda` conda 环境，已配置 CUDA 12.4 支持，可充分利用 NVIDIA GPU 进行加速。

#### 第1步：创建 Conda 环境

```bash
# 创建 Python 3.11 的 conda 环境（避免 Python 3.14 与 PyTorch 的兼容性问题）
conda create -n pytorch_cuda python=3.11

# 激活环境
conda activate pytorch_cuda

# 安装 PyTorch CUDA 12.4 版本
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
```

#### 第2步：安装依赖

```bash
# 安装项目依赖
pip install -r requirements.txt
```

#### 第3步：配置环境

```bash
# 复制环境变量模板
copy .env.example .env
```

编辑 `.env` 文件，配置以下必要参数：

```bash
# DeepSeek API 配置（用于 LLM 生成答案）
DEEPSEEK_API_KEY=your_deepseek_api_key_here

# API 认证（可选，留空则禁用认证）
API_KEY=your_api_key_here

# 嵌入模型配置（默认 Qwen3-Embedding-0.6B）
EMBEDDING_MODEL=./models/Qwen-Qwen3-Embedding-0.6B

# LLM 提供商配置（deepseek 或 ollama）
LLM_PROVIDER=deepseek
```

#### 第4步：下载模型（如需要）

模型已预先下载到 `models/` 目录，如需重新下载：

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

**新电脑？使用一键下载脚本：**

```bash
python scripts/download_all.py
```

此脚本会自动下载：
1. Qwen2-VL GGUF 模型（约 2.2GB）
2. llama.cpp 预编译版本（约 15MB）

#### 第5步：构建知识库

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

---

## 🚀 快速开始

### 启动 API 服务（推荐）

```bash
# 激活 conda 环境
conda activate pytorch_cuda

# 进入项目目录
cd rag_knowledge_base

# 启动服务
python start_api.py
```

启动后显示：
```
Starting API service...
Running command: D:\Miniconda3\envs\pytorch_cuda\python.exe -m uvicorn rag_system.api:app --host 127.0.0.1 --port 8000
Working directory: D:\PyCharm 2025.2.2\my_project\rag_knowledge_base

Server output:
============================================================
[启动] RAG 知识库 API 服务正在初始化...
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
[预热] 所有组件预热完成，服务已就绪！（耗时 6.45s）
```

### 服务地址

- **API 地址**: http://127.0.0.1:8000
- **API 文档**: http://127.0.0.1:8000/docs
- **健康检查**: http://127.0.0.1:8000/health
- **就绪检查**: http://127.0.0.1:8000/ready

---

## 💻 交互式启动

使用简化启动器 `run.py`：

```bash
conda activate pytorch_cuda
python run.py
```

显示交互式菜单：
```
==================================================
       RAG 知识库系统
==================================================

请选择操作:
  1. 构建知识库（首次使用或更新文档后）
  2. 提问（单次查询）
  3. 交互模式（连续对话）
  4. 启动 Web 界面
  5. 启动 API 服务
  6. 查看知识库状态
  0. 退出
```

---

## ⚙️ 核心配置说明

在 `.env` 文件中可以配置以下参数：

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `DEEPSEEK_API_KEY` | DeepSeek API 密钥 | - |
| `API_KEY` | API 认证密钥 | - |
| `EMBEDDING_MODEL` | 嵌入模型路径 | `./models/Qwen-Qwen3-Embedding-0.6B` |
| `EMBEDDING_DEVICE` | 运行设备（auto/cpu/cuda） | `auto` |
| `LLM_PROVIDER` | LLM 提供商 | `deepseek` |
| `LLM_MODEL` | LLM 模型名称 | `deepseek-chat` |
| `API_HOST` | API 服务地址 | `127.0.0.1` |
| `API_PORT` | API 服务端口 | `8000` |

### GPU 自动检测

系统自动检测 GPU，**无需手动切换配置**：

```
启动 → get_embedding_device()
       ├── 有 GPU（torch.cuda.is_available() = True）→ 用 CUDA 加速
       └── 无 GPU → 全自动降级为 CPU
```

- **嵌入模型**（Qwen3-Embedding-0.6B）自动在 GPU/CPU 间切换
- **重排序模型**（Qwen3-Reranker-0.6B）自动在 GPU/CPU 间切换
- 完全不需要改代码或配置

> 如需手动固定设备，在 `.env` 中设置：
> ```
> EMBEDDING_DEVICE=cpu    # 强制 CPU
> EMBEDDING_DEVICE=cuda   # 强制 GPU
> ```

---

## 📁 项目结构

```
rag_knowledge_base/
├── run.py                    # ⭐ 交互式启动器（推荐）
├── main.py                   # CLI 入口脚本，支持所有功能
├── start_api.py              # ⭐ API 服务启动脚本（推荐）
├── scripts/                  # 工具脚本
│   ├── download_model.py     # 模型下载工具
│   └── generate_test_cases.py # 测试用例生成
├── rag_system/               # 核心系统模块
│   ├── api.py               # FastAPI 应用
│   ├── config.py            # 配置管理
│   ├── vector_store.py      # 向量存储
│   ├── retriever.py         # 检索器
│   ├── rag_chain.py         # RAG 链
│   ├── document_loader.py   # 文档加载
│   ├── text_splitter.py     # 文本分割
│   ├── dependencies.py      # 懒加载依赖
│   ├── routers/             # API 路由
│   └── ...
├── documents/                # 知识库文档
│   ├── product_design/      # 产品设计文档
│   ├── technical/           # 技术文档
│   └── test_rules/          # 测试规则文档
├── knowledge_data/           # 原始知识数据
├── models/                   # 嵌入模型
├── vector_db/                # 向量数据库
├── database/                 # 文档注册表
├── logs/                     # 日志文件
└── web/                     # Web 界面
```

---

## 💬 使用方式

### 方式一：API 接口（推荐）

```bash
python start_api.py
# 访问 http://127.0.0.1:8000/docs 查看 API 文档
```

### 方式二：命令行查询

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

# 交互模式
python main.py --interactive
```

### 方式三：Web 界面

在 API 服务运行后，打开浏览器访问 http://127.0.0.1:8000

---

## 📚 添加新文档

1. 将文档放入以下目录：
   - `documents/test_rules/` - 测试规则
   - `documents/product_design/` - 产品设计
   - `documents/technical/` - 技术文档
   - `knowledge_data/` - 其他知识数据

2. 支持的格式：Markdown (.md)、PDF (.pdf)、Word (.docx)、Excel (.xlsx)、TXT (.txt)

3. 重新构建知识库：
   ```bash
   python main.py --build
   ```

---

## 🔧 常用命令

| 命令 | 说明 |
|------|------|
| `python start_api.py` | 启动 API 服务（推荐） |
| `python main.py --api` | 启动 API 服务 |
| `python main.py --build` | 构建知识库 |
| `python main.py --rebuild` | 重建知识库（删除旧数据）|
| `python main.py --query "问题"` | 单次查询 |
| `python main.py --interactive` | 交互模式 |
| `python run.py` | 交互式菜单 |
| `python scripts/download_model.py` | 下载模型 |

### 知识库管理命令

| 命令 | 说明 |
|------|------|
| `python main.py --kb-create --kb-name "产品说明书" --kb-docs "knowledge_data/产品说明书.docx"` | 创建知识库 |
| `python main.py --kb-list` | 列出所有知识库 |
| `python main.py --kb-query --kb-name "产品说明书" --kb-question "产品的主要功能有哪些？"` | 查询知识库 |
| `python main.py --kb-evaluate --kb-name "产品说明书" --kb-test-cases "test_cases.json"` | 评估知识库 |
| `python main.py --kb-delete --kb-name "产品说明书"` | 删除知识库 |

---

## 🔌 API 接口

启动 API 服务后，访问 http://127.0.0.1:8000/docs 查看完整文档。

主要接口：
- `POST /v2/chat` - 对话查询
- `POST /v2/documents/upload` - 上传文档
- `GET /v2/documents` - 获取文档列表
- `GET /health` - 健康检查
- `GET /ready` - 就绪检查

---

## 📋 知识库完整工作流程

```mermaid
flowchart TD
    subgraph 知识收集
        A[文档输入] --> B[文档扫描]
        B --> C[格式识别]
        C --> D[初步验证]
    end

    subgraph 知识处理
        D --> E[文档加载]
        E --> F[文档分类]
        F --> G[文本分割]
        G --> H[元数据提取]
        H --> I[内容验证]
    end

    subgraph 知识存储
        I --> J[向量存储]
        I --> K[文档注册表]
        I --> L[缓存系统]
    end

    subgraph 知识检索
        M[用户查询] --> N[查询预处理]
        N --> O[向量生成]
        O --> P[相似度计算]
        P --> Q[结果排序]
        Q --> R[上下文构建]
        R --> S[答案生成]
        J --> P
        K --> R
    end

    subgraph 知识更新
        T[文档变更] --> U[检测文档变更]
        U --> V[处理变更文档]
        V --> W[更新向量存储]
        V --> X[更新文档注册表]
    end

    subgraph 错误处理与预防
        Y[系统运行] --> Z[错误监控]
        Z --> AA[错误分类]
        AA --> AB[错误恢复]
        Y --> AC[参数验证]
        Y --> AD[配置验证]
        Y --> AE[错误模式识别]
    end

    S --> Y
    W --> Y
    X --> Y
    AB --> Y
    AC --> Y
    AD --> Y
    AE --> Y
```

---

## 📖 构建过程详解

**1. 准备文档**

将文档放入以下目录：
- `documents/test_rules/` - 测试规则文档
- `documents/product_design/` - 产品设计文档
- `documents/technical/` - 技术文档
- `knowledge_data/` - 其他知识数据

支持的格式：Markdown (.md)、PDF (.pdf)、Word (.docx)、Excel (.xlsx)、TXT (.txt)

**2. 执行构建**

运行构建命令后，系统会依次执行：

| 步骤 | 操作 | 说明 |
|------|------|------|
| ① | 扫描文档 | 递归扫描指定目录中的所有支持格式文件 |
| ② | 格式识别 | 识别文件类型并选择合适的加载器 |
| ③ | 文档加载 | 提取文件内容，支持编码自动检测 |
| ④ | 文档分类 | 根据路径和内容自动分类文档 |
| ⑤ | 文本分割 | 父子模式分块，保留上下文信息 |
| ⑥ | 元数据提取 | 提取标题、分类、来源等元数据 |
| ⑦ | 向量生成 | 使用嵌入模型生成向量表示 |
| ⑧ | 存储入库 | 保存到 ChromaDB 向量数据库 |
| ⑨ | 注册文档 | 记录到 SQLite 文档注册表 |

**3. 构建完成验证**

```bash
# 查看知识库状态
python run.py
# 选择菜单项 "6. 查看知识库状态"
```

会显示：
- 文档总数
- 向量总数
- 各类文档统计
- 最后更新时间

**4. 增量更新**

添加新文档后，只需重新运行构建命令：

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

系统会自动：
- 检测新增文档
- 检测修改的文档（通过文件哈希）
- 跳过未变更的文档
- 更新向量数据库

---

## 📸 多模态大模型（Qwen2-VL-2B GGUF）

用于 RAG 的多模态理解能力，支持图片内容分析。

### 模型文件

| 文件 | 大小 | 说明 |
|------|------|------|
| `Qwen2-VL-2B-Instruct-Q4_K_M.gguf` | 0.92GB | 主模型（Q4_K_M 量化） |
| `mmproj-Qwen2-VL-2B-Instruct-f16.gguf` | 1.24GB | 视觉投影器（f16 精度） |

位置：`models/Qwen2-VL-2B-Instruct-GGUF/`

### llama.cpp 下载

#### 方法一：下载预编译版本（推荐）

1. **访问 GitHub Releases 页面**：[https://github.com/ggerganov/llama.cpp/releases/latest](https://github.com/ggerganov/llama.cpp/releases/latest)

2. **下载 Windows x64 CPU 版本**：`llama-b****-bin-win-cpu-x64.zip`

3. **解压到项目目录**：`llama.cpp/build/`

#### 方法二：从 Git 克隆

```bash
# 配置代理（如果需要）
git config --global http.proxy socks5://127.0.0.1:7890
git config --global https.proxy socks5://127.0.0.1:7890

# 克隆仓库
git clone https://github.com/ggerganov/llama.cpp

# 编译（CPU 版本）
cd llama.cpp
mkdir build && cd build
cmake .. -DGGML_CUDA=OFF
cmake --build . --config Release -j 8
```

编译产物位置：`llama.cpp/build/`（Windows）或 `llama.cpp/`（Linux/macOS）

### 使用方法

```bash
# 进入 llama.cpp build 目录
cd llama.cpp/build

# CPU 推理（推荐用于公司电脑）
.\llama-mtmd-cli.exe ^
    -m "..\..\models\Qwen2-VL-2B-Instruct-GGUF\Qwen2-VL-2B-Instruct-Q4_K_M.gguf" ^
    --mmproj "..\..\models\Qwen2-VL-2B-Instruct-GGUF\mmproj-Qwen2-VL-2B-Instruct-f16.gguf" ^
    --image "your_image.jpg" ^
    -p "描述这张图片" ^
    -c 2048 ^
    -ngl 0 ^
    -t 8

# 或使用已废弃但仍可用的 llama-qwen2vl-cli
.\llama-qwen2vl-cli.exe ^
    -m "..\..\models\Qwen2-VL-2B-Instruct-GGUF\Qwen2-VL-2B-Instruct-Q4_K_M.gguf" ^
    --mmproj "..\..\models\Qwen2-VL-2B-Instruct-GGUF\mmproj-Qwen2-VL-2B-Instruct-f16.gguf" ^
    --image "your_image.jpg" ^
    -p "描述这张图片" ^
    -c 2048 ^
    -ngl 0 ^
    -t 8
```

### 参数说明

| 参数 | 说明 | 推荐值 |
|------|------|--------|
| `-m` | 主模型文件路径 | Qwen2-VL-2B-Instruct-Q4_K_M.gguf |
| `--mmproj` | 视觉投影器路径 | mmproj-Qwen2-VL-2B-Instruct-f16.gguf |
| `--image` | 图片路径 | 支持 jpg/png/webp 等 |
| `-p` | 提示词 | 中文或英文描述 |
| `-c` | 上下文长度 | 2048 |
| `-ngl` | GPU 层数（0=纯CPU） | 0（公司）/ 99（家用GPU） |
| `-t` | CPU 线程数 | 8（根据CPU核心数调整） |

### 注意事项

1. **模型兼容性**：Q4_K_M 主模型只能搭配 f16 版本的 mmproj，不能混用
2. **内存需求**：纯 CPU 运行约需 2-3GB 内存
3. **GPU 加速**：家用 GPU 可设置 `-ngl 99` 启用 GPU 加速
4. **图片尺寸**：建议图片分辨率不超过 1280x1280

---

## ❓ 常见问题

**Q: 首次使用需要做什么？**
A: 按顺序执行：创建 conda 环境 → 安装依赖 → 配置 .env → 构建知识库 → 开始使用

**Q: 如何更新知识库？**
A: 添加新文档到 documents/ 目录后，运行 `python main.py --build`

**Q: GPU 未被检测到？**
A: 确保已激活 pytorch_cuda 环境，并安装了 CUDA 版本的 PyTorch

**Q: 启动脚本报错 "ModuleNotFoundError"?**
A: 确保在 pytorch_cuda 环境中运行，并已安装所有依赖

**Q: 构建速度慢？**
A: 首次构建需要处理所有文档，耐心等待；后续使用增量构建

**Q: 内存不足？**
A: 减少 `CHUNK_SIZE` 或关闭重排序模型

**Q: 文档未识别？**
A: 检查文件格式是否在支持列表中

**Q: 编码错误？**
A: 系统会自动检测编码，如遇问题可手动转换文件为 UTF-8

---

## 📋 环境依赖清单

### 核心依赖

| 包名 | 版本 | 说明 |
|------|------|------|
| torch | 2.5.1+CUDA 12.4 | PyTorch 深度学习框架 |
| transformers | 4.46.3+ | Hugging Face  Transformers |
| sentence-transformers | 2.6.1+ | 句子嵌入模型 |
| langchain | 0.3.x | LangChain 框架 |
| langchain-core | 0.3.x | LangChain 核心 |
| langchain-community | 0.3.x | LangChain 社区集成 |
| chromadb | 0.5.x | 向量数据库 |
| fastapi | 0.115.x | FastAPI Web 框架 |
| uvicorn | 0.32.x | ASGI 服务器 |
| pydantic | 2.x | 数据验证 |
| pydantic-settings | 2.x | 配置管理 |

### 其他依赖

| 包名 | 版本 | 说明 |
|------|------|------|
| jieba | 0.42+ | 中文分词（BM25 检索） |
| rank-bm25 | 0.2+ | BM25 算法实现 |
| python-multipart | 0.0.x | 表单数据处理 |
| pyarrow | 20.x | Apache Arrow 支持 |
| rapidfuzz | 3.x | 模糊字符串匹配 |

### 可选依赖

| 包名 | 说明 |
|------|------|
| python-docx | Word 文档支持 |
| python-pptx | PPT 文档支持 |
| openpyxl | Excel 文档支持 |
| pdfplumber | PDF 文档支持 |

---

## 🐛 已知问题修复记录

### 2026-04-25 修复的问题

#### 1. sentence-transformers 与 transformers 5.x 兼容性 ✅
**问题**: `sentence-transformers 5.4.1` 与 `transformers 5.6.2` 在 Windows 上存在 DLL 加载顺序冲突，导致 `import sentence_transformers` 时 segfault。
**修复**: 降级 `transformers` 至 `4.57.6`，并确保 `pyarrow` 在 `datasets`/`sklearn` 之前导入。

#### 2. Qwen3-Reranker 推理崩溃 ✅
**问题**: `sentence-transformers.CrossEncoder` 不支持 Qwen3 的 QK-Norm 注意力架构，推理时报 `RuntimeError: cannot reshape tensor of 0 elements`。
**修复**: 新增 `rag_system/qwen3_reranker.py`，使用 HuggingFace transformers 的 `AutoModelForCausalLM` 直接加载 Qwen3-Reranker。retriever.py 自动检测 Qwen3 模型并切换到自定义加载器。

#### 3. 环境冲突问题 ✅
**问题**: 多个 conda 环境导致依赖混乱，pytorch_cuda 环境的包未正确使用。
**修复**: 修改 `start_api.py` 直接使用 pytorch_cuda 环境的 Python 解释器，避免环境激活问题。

#### 4. GPU 检测失败 ✅
**问题**: VectorStore 初始化时报告 "配置中指定使用GPU，但未检测到可用GPU"。
**修复**: 确保使用 pytorch_cuda 环境，其中 PyTorch 已正确配置 CUDA 支持。

#### 5. 日志系统优化 ✅
- 按日期创建日志文件（如 `app_20260424.log`）
- 添加启动和关闭时的水平分界线
- 添加请求追踪中间件
- 优化日志格式，包含文件路径和行号

#### 6. 预热功能优化 ✅
- 实现后台线程预热机制
- 按顺序预热 VectorStore → Retriever → RAGChain
- `/ready` 接口正确反映服务就绪状态

### 2026-04-24 修复的问题

#### 1. 变量名错误修复 ✅
**问题**: `corrective_rag.py` 中使用了未定义的变量 `documents_section`
**修复**: 将变量名修改为正确的 `docs_section`

#### 2. HNSW配置错误修复 ✅
**问题**: `vector_store.py` 中尝试修改已创建集合的距离函数，Chroma不支持此操作
**修复**: 移除距离函数参数，只修改其他HNSW参数

#### 3. 集合维度错误修复 ✅
**问题**: `vector_store.py` 中在布尔上下文中使用NumPy数组导致错误
**修复**: 添加详细的类型检查和安全验证

#### 4. LLM服务配置修复 ✅
**问题**: `retriever.py` 测试Ollama服务但配置使用DeepSeek
**修复**: 修改为直接使用配置的LLM模型

### 2026-04-03 新增功能

#### 1. AI Agent 模块 ✅
**新增模块**: `rag_system/agent/`
- `rag_agent.py`: RAG Agent 核心实现，支持意图识别和任务执行
- `intent_parser.py`: 用户意图解析器，自动识别查询类型
- `task_executor.py`: 任务执行器，支持知识库问答、文档查询等任务
- `agent_router.py`: Agent API 路由，提供 `/v2/agent/chat` 接口

**前端集成**:
- 侧边栏新增 "AI Agent" 导航入口
- Agent 视图支持意图类型展示、置信度显示
- 聊天视图新增 "显示引用来源" 和 "流式输出" 复选框

### 2026-04-03 修复的问题

#### 1. 测试文件枚举值不匹配 ✅
**问题**: `tests/test_retriever.py` 引用了不存在的 `RetrievalMode.FULLTEXT` 和 `RetrievalMode.BALANCED`
**修复**: 更新为实际存在的枚举值 `RetrievalMode.BM25`

#### 2. VectorStore 参数不匹配 ✅
**问题**: `knowledge_base_manager.py` 调用 `VectorStore()` 时传递了 `collection_name` 参数，但 `VectorStore.__init__` 未定义该参数
**修复**: 在 `VectorStore.__init__` 中添加 `collection_name` 参数支持

#### 3. API 变量作用域问题 ✅
**问题**: `api.py` 中异常处理代码引用 `validated_params` 变量，但如果验证失败该变量可能未定义
**修复**: 在 try 块之前初始化 `validated_params = None`

#### 4. 删除知识库缺少确认参数 ✅
**问题**: `knowledge_base_manager.py` 第629行调用 `delete_knowledge_base(name)` 缺少 `confirm=True` 参数
**修复**: 添加 `confirm=True` 参数，避免在 API 场景中阻塞等待用户输入

#### 5. main.py 枚举值引用错误 ✅
**问题**: `main.py` 第206行引用了不存在的 `RetrievalMode.FULLTEXT`
**修复**: 更新为 `RetrievalMode.BM25`，并同步更新用户提示文本

#### 6. DocumentLoader 属性命名不一致 ✅
**问题**: `tests/test_document_loader.py` 期望 `SUPPORTED_EXTENSIONS`（大写），但实现使用 `supported_extensions`（小写）
**修复**: 将属性名改为大写 `SUPPORTED_EXTENSIONS` 以兼容测试

---

## 许可证

AGPL v3