# 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-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RAG 知识库系统

基于 DeepSeek V4 Flash + DashScope text-embedding-v4 的业务文档检索增强生成系统，为 AI 测试工具链提供高质量的知识检索服务。

---

## ⚠️ 使用前必读：环境变量配置

敏感信息（API Key、认证密钥等）**不提交到仓库**，通过 `.env` 文件提供（已 gitignore）。

**首次使用必须执行**：

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

然后编辑 `.env` 填入真实值，完整变量清单见 `.env.example`（代码读取的每个变量都有提示），必配项：

| 变量 | 必填 | 说明 |
|---|---|---|
| `AUTH_SECRET` | ✅ **必须** | token 签名密钥，`openssl rand -hex 32` 生成；**未配置服务拒绝签名（安全设计）** |
| `AUTH_USERS` | ✅ | 用户表，格式 `用户名:SHA256密码哈希`（生成：`python -m rag_system.auth <用户名> <密码>`） |
| `DASHSCOPE_API_KEY` | ✅ | 嵌入模型 text-embedding-v4 / 重排序 API 密钥 |
| `DEEPSEEK_API_KEY` | ✅ | LLM 生成 API 密钥 |
| `MIMO_API_KEY` / `OLLAMA_API_KEY` / `OPENAI_API_KEY` | 按需 | 其他 LLM/多模态提供方密钥 |
| `RAG_API_URL` | 按需 | 服务对外地址 |

> 不配置必填项会启动报错或拒绝签名，属预期行为（安全设计：拒绝无密钥运行）。

---

## 系统架构

```
用户提问 → 查询分解 → 自适应检索 → 混合检索(向量+BM25) → 场景感知提权 → CRAG → 重排序 → JSON校验 → LLM生成 → Faithfulness评估
```

### 核心技术栈

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

### Advanced RAG 特性

| 特性 | 说明 |
|:-----|:------|
| **查询分解** | 复杂问题自动拆分为多步子查询，逐步检索 |
| **上下文压缩** | 检索结果过长时自动压缩，保留关键信息 |
| **自适应检索** | 根据查询复杂度动态选择检索策略和 k 值 |
| **CRAG** | 检索质量不足时自动回退到知识库全文检索 |
| **JSON 校验** | 输出自动校验 JSON 结构和字段完整性 |
| **粒度控制** | 文档分块大小可配置，支持语义/固定双模式 |
| **场景感知架构** | 同一文档中相似校验流程的场景标签注入与提权检索 |
| **Faithfulness 评估** | 生成结果忠实度自动评分 |

### 场景感知架构

解决同一文档中多个相似校验流程的混淆问题：

```
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 主链（含场景合并格式化）
│   ├── maintenance.py     # 知识库维护（过期检测/更新建议）
│   └── config.py          # 系统配置
├── qa_results/             # QA 测试结果
│   ├── qa_test_set.md     # 32 条测试用例
│   ├── answers/           # 回答文件归档（按时间戳）
│   └── llm_eval.py        # LLM 语义评估脚本
├── scripts/                # 工具脚本
│   └── build_knowledge_base.py
├── data/                   # 运行时数据
├── web/                    # Web 服务
├── frontend/               # 前端界面
├── run_qa_test.py          # QA 回归测试
├── start_api.py            # API 启动入口
├── docker-compose.yml      # Docker 部署
└── pyproject.toml          # Python 项目配置
```

---

## 快速开始

### 环境变量（.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. 执行 32 条测试（采集回答）
python run_qa_test.py
# 3. LLM 语义评估
python qa_results/llm_eval.py
```

---

## QA 测试集

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

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

当前通过率：**84.4%**（27/32）

---

## 检索质量指标

| 指标 | 数值 | 说明 |
|:----|:----:|:------|
| 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
- **.codegraph/**：Claude Code 本地代码索引，已加入 `.gitignore`
- **运行时数据**：`data/` 目录下的 `error_patterns.json`、`parameter_correction_stats.json` 为运行时生成

---

## 版本历史

- **v1.0.0**：基础 RAG 系统（ChromaDB + 向量检索 + LLM 生成）
- **v1.1.0**：混合检索（向量 + BM25）+ DashScope 重排序
- **v1.2.0**：场景感知架构 + 场景标签注入/提权检索
- **v1.3.0**：Advanced RAG 特性（查询分解/上下文压缩/自适应检索/CRAG/JSON校验/粒度控制）
- **v1.4.0**：Faithfulness 评估 + QA 测试集（32条）+ 知识库维护模块；CodeGraph 集成

## 相关项目

- [智能测试用例生成器](https://gitee.com/YunAbove/ai-agent)
- [DOSS 接口自动化测试框架](https://gitee.com/YunAbove/api_test)