# rag_knowledge_base

**Repository Path**: YunAbove/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**: 2
- **Forks**: 0
- **Created**: 2026-02-06
- **Last Updated**: 2026-07-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RAG 知识库系统

基于 DeepSeek V4 Flash + DashScope text-embedding-v4 的业务文档检索增强生成系统。

---

## 系统架构

```
用户提问 → 查询改写 → 混合检索(向量+BM25) → 场景感知提权 → 重排序 → LLM生成 → Faithfulness评估
```

### 核心技术栈

| 组件 | 选型 |
|:-----|:------|
| LLM | DeepSeek V4 Flash / V3 |
| 嵌入模型 | DashScope text-embedding-v4 |
| 向量数据库 | ChromaDB + HNSW |
| 重排序 | DashScope qwen3-rerank |
| 检索模式 | 混合检索（向量 + BM25） |

### 特色优化

**场景感知架构** — 解决同一文档中多个相似校验流程的混淆问题：
1. 场景标签注入 → 2. 场景提权检索 → 3. 完整流程注入 → 4. 章节注入

支持场景：`click_add`（点击新增）、`batch_import`（批量导入）、`submit`（转款提交）

---

## 目录结构

```
rag_knowledge_base/
├── documents/              # 文档源文件
│   ├── 01-design/         # 产品设计文档
│   ├── 02-rules/          # 测试规则文档
│   ├── 03-tech/           # 技术文档
│   └── 05-incoming/       # 待处理暂存区
├── rag_system/             # 核心代码
│   ├── retriever/         # 检索器（混合检索、重排序、场景提权）
│   ├── vector_store/      # 向量数据库
│   ├── routers/           # API 路由
│   ├── document_loader.py # 文档加载（含场景检测）
│   ├── text_splitter.py   # 文本分块（含场景标签注入）
│   ├── rag_chain.py       # RAG 主链（含场景合并格式化）
│   └── config.py          # 系统配置
├── qa_results/             # QA 测试结果
│   ├── qa_test_set.md     # 38 条测试用例
│   ├── answers/           # 回答文件归档（按时间戳）
│   └── llm_eval.py        # LLM 语义评估脚本
├── scripts/                # 工具脚本
│   └── build_knowledge_base.py
├── run_qa_test.py          # QA 回归测试
└── start_api.py            # API 启动入口
```

---

## 快速开始

### 环境变量（.env）

```ini
DEEPSEEK_API_KEY=sk-xxx
DASHSCOPE_API_KEY=sk-xxx
CRAG_ENABLED=true
ADAPTIVE_RETRIEVAL=true
FAITHFULNESS_ENABLED=true
```

### 启动 API

```bash
python start_api.py
# API 地址: http://localhost:8000
# 文档地址: http://localhost:8000/docs
```

### 构建知识库

```bash
python scripts/build_knowledge_base.py     # 增量构建
```

### 运行 QA 回归测试

```bash
# 1. 确保 API 在运行
# 2. 执行 38 条测试（采集回答）
python run_qa_test.py
# 3. LLM 语义评估
python qa_results/llm_eval.py
```

---

## QA 测试集

当前 **38 条**测试用例，覆盖 7 份业务文档：

| 文档 | 条数 | 覆盖维度 |
|:-----|:---:|:---------|
| 自动化充值V4.0 | 16 | 校验树、转款提交、资金池、充值状态 |
| 智企ERP | 3 | 字段规则、搜索逻辑 |
| 测试用例设计方法 | 3 | 等价类、场景法、错误推测法 |
| 功能测试定义 | 3 | 特点、步骤、与性能测试关系 |
| 测试用例编写规范 | 3 | 必填字段、优先级、编写原则 |
| 测试工程师测试内容 | 3 | 安全性、边界值、业务流程 |
| AI大模型测试专项 | 3 | 功能性测试、涌现特性、完成度测试 |
| 测试场景分类指南 | 2 | 功能测试场景、金融系统场景 |
| 自动化充值校验规则 | 2 | 单据维度、账户维度 |

---

## 检索质量指标

| 指标 | 数值 | 说明 |
|:----|:----:|:------|
| Recall@10 | 0.657 | Top-10 中相关 chunk 占比 |
| MRR | 0.806~0.917 | 首个相关结果的排名质量 |
| HitRate@10 | 0.917 | 至少找到一个相关结果的比例 |
| 向量库 | 1249 chunks | 22 份文档 |

---

## 文档管理规范

### 目录分类

```
documents/
├── 01-design/         # 产品设计文档（PRD、产品规格）
├── 02-rules/          # 测试规则文档（用例模板、测试标准）
├── 03-tech/           # 技术文档（架构、方案）
├── 04-other/          # 其他类型文档
└── 05-incoming/       # 待处理暂存区
```

### 支持格式

Markdown (.md)、PDF (.pdf)、Word (.docx)、Excel (.xlsx)、文本 (.txt)

### 添加文档

1. 放入对应分类目录或 `05-incoming/`
2. 运行 `python scripts/build_knowledge_base.py`

---

## 注意事项

- **同名文件覆盖**：重建索引时同文件名会覆盖旧数据
- **双格式文档**：同一份文档的 DOCX 和 PDF 同时存在时，DOCX 优先
- **日志**：日志文件在 `logs/` 目录，单个文件最大 10MB