# rag-knowledge-base

**Repository Path**: samoukris/rag-knowledge-base

## Basic Information

- **Project Name**: rag-knowledge-base
- **Description**: 企业知识库问答系统 - 基于 RAG 技术，支持多格式文档检索与问答
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-03-31
- **Last Updated**: 2026-04-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

```markdown
# RAG 企业知识库问答系统 - 完整技术文档


## 一、项目概述

### 1.1 核心目标

| 问题 | 解决方案 |
|------|---------|
| 企业文档多、查找难 | 语义检索 + 问答，直接返回答案而非文档列表 |
| 文档格式不统一 | 支持 PDF、Word、Markdown、TXT 等多种格式 |
| 传统关键词搜索不准 | 基于 BGE 向量的语义检索，理解意图而非匹配关键词 |
| 大模型数据隐私风险 | 本地部署 Qwen-7B，数据不上云 |
| 检索结果不精准 | 支持重排序（Cross-Encoder）精排 |
| 多轮对话上下文丢失 | 会话管理，保留对话历史 |
| Java 系统调用困难 | 提供标准化 REST API，与 Java 解耦 |
| 部署复杂 | Docker Compose 一键启动 Milvus |

### 1.2 技术架构与选型缘由

| 组件 | 技术选型 | 选型缘由 |
|------|---------|---------|
| RAG 框架 | LangChain（部分组件） | 生态成熟，文本切分、Embedding、向量存储等基础组件稳定可靠；流程编排自研以保持灵活性 |
| 向量数据库 | Milvus (Standalone / Lite) | 支持百万级向量毫秒检索；提供 Lite 版本便于本地开发，Standalone 版本无缝迁移到生产 |
| Embedding 模型 | BAAI/bge-small-zh-v1.5 | 中文语义理解效果优秀；512 维向量平衡精度与性能；支持本地部署 |
| 大语言模型 | Qwen-7B-Chat (GGUF, Q4_K_M) | 中文能力领先；GGUF 量化格式降低显存占用（约 4-5GB）；支持 CPU/GPU 混合推理 |
| 后端服务 | FastAPI + Uvicorn | 异步高性能；自动生成 API 文档；类型提示支持完善 |
| 前端界面 | Streamlit | 快速构建交互界面；无需前端开发经验；支持实时调试 |
| 文档解析 | PyPDF2, python-docx | 纯 Python 实现，无额外依赖；支持主流办公文档格式 |
| 部署方式 | Docker / 本地进程 | Docker 保证环境一致性；本地进程便于开发调试 |

**LangChain 使用边界说明**：
- ✅ 使用：`RecursiveCharacterTextSplitter`（文本切分）、`HuggingFaceEmbeddings`（Embedding封装）、`Milvus`（向量存储）
- ❌ 自研：RAG 流程编排、Prompt 模板、对话记忆、检索重排序

**自研缘由**：LangChain 的 Chain 编排黑盒化严重，不利于调试和定制化调优；自研流程控制在 200 行代码以内，逻辑清晰，便于后续扩展混合检索、重排序等高级功能。

### 1.3 架构设计

```
┌─────────────────────────────────────────────────────────────┐
│                    前端层（Streamlit）                       │
│                  可替换为 React/Vue/小程序                    │
└─────────────────────────────────────────────────────────────┘
                              ↓ API
┌─────────────────────────────────────────────────────────────┐
│                    API 层（FastAPI）                         │
│              可扩展：鉴权、限流、日志、监控                    │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                   RAG 编排层（自研 + LangChain）             │
│         可扩展：混合检索、HyDE、Self-RAG、Agentic RAG         │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                    组件层（各模块）                           │
│   文档加载器 → 清洗器 → 切分器 → Embedding → 检索 → 生成      │
│   每个模块都可独立替换/增强                                    │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                    基础设施层                                │
│   Milvus（向量库）│ 本地 LLM │ 文件系统 │ 缓存（可扩展Redis） │
└─────────────────────────────────────────────────────────────┘
```

### 1.4 架构优缺点分析

#### 优点

| 维度 | 说明 |
|------|------|
| **解耦清晰** | 前端/API/RAG/组件/基础设施五层分离，各层可独立替换和升级 |
| **轻量可控** | RAG 流程自研，无框架黑盒，便于调试和定制化调优 |
| **扩展性强** | 组件层每个模块可独立增强（如检索模块可扩展混合检索） |
| **本地部署** | 所有组件（含 LLM）本地运行，数据不出企业内网 |
| **开发效率** | Streamlit + FastAPI 快速迭代，无需前后端分离的复杂协作 |
| **成本可控** | 开源组件 + 本地推理，无 API 调用费用 |

#### 缺点

| 维度 | 说明 | 改进方向 |
|------|------|---------|
| **单实例部署** | 后端和 LLM 均为单实例，存在单点故障风险 | 后续可扩展多实例 + Nacos 服务注册 |
| **无用户隔离** | 所有用户共享知识库和会话 | 后续可增加用户认证和知识库隔离 |
| **检索能力有限** | 仅支持向量检索，未实现混合检索 | 后续可扩展 BM25 + 向量混合检索 |
| **无流式输出** | 答案一次性返回，用户体验待提升 | 后续可扩展 SSE 流式输出 |
| **监控不完善** | 仅有日志，无指标告警 | 后续可接入 Prometheus + Grafana |
| **无缓存机制** | 相同问题重复检索和推理 | 后续可增加 Redis 缓存 |

### 1.5 功能完成度

| 功能模块 | 完成度 | 说明 |
|---------|--------|------|
| 文档处理 | 100% | PDF、Word、Markdown、TXT 全支持 |
| 文本清洗 | 100% | RAG 专用清洗，去页眉页脚、断字 |
| 向量检索 | 100% | Milvus + BGE 语义检索 |
| LLM 推理 | 100% | Qwen-7B 本地推理 |
| GPU 加速 | 100% | CUDA 加速，2-5秒/次 |
| 多轮对话 | 100% | 会话管理，历史记忆 |
| API 服务 | 100% | FastAPI REST 接口 |
| 前端界面 | 100% | Streamlit Web 界面 |
| 日志监控 | 100% | 请求/性能/错误日志 |
| 重排序 | 可选 | 需下载 Cross-Encoder 模型 |
| 混合检索 | 0% | 规划中 |
| 流式输出 | 0% | 规划中 |
| 用户认证 | 0% | 规划中 |

**总体完成度：约 75%**


## 二、已实现功能详情

### 2.1 文档处理

| 功能 | 状态 |
|------|------|
| PDF 解析 | ✅ |
| Word (.docx) 解析 | ✅ |
| Markdown 解析 | ✅ |
| TXT 解析 | ✅ |
| 文档上传（前端界面） | ✅ |
| 批量导入目录 | ✅ |
| 清空所有文档 | ✅ |

### 2.2 文本处理

| 功能 | 状态 |
|------|------|
| RAG 专用文本清洗（去页眉页脚、页码、断字） | ✅ |
| 智能切分（语义边界） | ✅ |
| 重叠窗口 | ✅ |

### 2.3 向量化与检索

| 功能 | 状态 |
|------|------|
| BGE 中文 Embedding 模型 | ✅ |
| Milvus 向量存储 | ✅ |
| 向量相似度检索 | ✅ |
| 重排序（Cross-Encoder） | ⚠️ 可选（需下载模型）|

### 2.4 LLM 与生成

| 功能 | 状态 |
|------|------|
| Qwen-7B 本地推理 | ✅ |
| GPU 加速（CUDA） | ✅ |
| 上下文 Prompt 构建 | ✅ |

### 2.5 对话管理

| 功能 | 状态 |
|------|------|
| 多轮对话历史 | ✅ |
| 会话管理（创建/删除） | ✅ |
| 上下文增强（指代消解） | ✅ |

### 2.6 API 与界面

| 功能 | 状态 |
|------|------|
| FastAPI REST 接口 | ✅ |
| API 文档（/docs） | ✅ |
| Streamlit 前端界面 | ✅ |
| 统计信息展示 | ✅ |

### 2.7 日志与监控

| 功能 | 状态 |
|------|------|
| 请求日志 | ✅ |
| 性能日志（耗时统计） | ✅ |
| 错误日志 | ✅ |
| GPU/CPU 资源监控 | ✅ |


## 三、当前调优参数

### 3.1 文本切分参数

```python
CHUNK_SIZE = 500        # 可调整范围: 300-1000
CHUNK_OVERLAP = 100     # 建议: CHUNK_SIZE 的 10-20%
```

### 3.2 检索参数

```python
TOP_K = 5               # 可调整范围: 3-10
SIMILARITY_THRESHOLD = 0.5  # 可调整范围: 0.3-0.7
```

### 3.3 LLM 参数

```python
LLM_TEMPERATURE = 0.7   # 可调整范围: 0.1-0.9
LLM_N_CTX = 2048        # 显存允许可增加
max_tokens = 512        # 可调整
```

### 3.4 调优建议

| 问题 | 解决方案 |
|------|---------|
| 文档很长 | 增加 CHUNK_SIZE=800，CHUNK_OVERLAP=150 |
| 问答不准 | 增加 TOP_K=10，启用重排序 |
| 回答太随机 | 降低 temperature=0.3 |
| 回答太短 | 增加 max_tokens=1024 |
| 检索不到 | 降低 SIMILARITY_THRESHOLD=0.3 |


## 四、日志与监控

### 4.1 日志类型

| 日志类型 | 文件 | 格式 |
|---------|------|------|
| 应用日志 | `logs/app.log` | 文本 |
| 访问日志 | `logs/access.log` | JSON |
| 错误日志 | `logs/error.log` | 文本 |
| 性能日志 | `logs/performance.log` | JSON |

### 4.2 监控指标

| 指标 | 说明 |
|------|------|
| LLM 生成耗时 | 每次生成的秒数 |
| 生成速度 | tokens/秒 |
| CPU 内存使用 | GB 和百分比 |
| GPU 显存使用 | GB 和百分比 |
| 检索耗时 | 向量检索毫秒数 |
| API 响应时间 | 请求总耗时 |


## 五、GPU 加速配置

### 5.1 环境要求

- NVIDIA 显卡（RTX 4060 及以上）
- CUDA 驱动 11.8+
- 显存 8GB+（Qwen-7B Q4 约需 4-5GB）

### 5.2 安装命令

```bash
pip uninstall llama-cpp-python -y
pip install llama-cpp-python==0.3.4 --index-url https://abetlen.github.io/llama-cpp-python/whl/cu122 --no-cache-dir

pip uninstall torch -y
pip install torch --index-url https://download.pytorch.org/whl/cu121
```

### 5.3 配置

```python
# llm_client.py
_llm = Llama(
    model_path=QWEN_MODEL_PATH,
    n_ctx=LLM_N_CTX,
    n_threads=LLM_N_THREADS,
    n_gpu_layers=32,  # Qwen-7B 共 32 层
    verbose=False
)
```

### 5.4 验证

```bash
python -c "import torch; print(torch.cuda.is_available())"
```


## 六、API 接口

### 6.1 问答接口

```
POST /ask
{
  "question": "文档的后续展望是什么？",
  "top_k": 3
}
```

### 6.2 上传文档接口

```
POST /upload
Content-Type: multipart/form-data
file: 文档文件
```

### 6.3 清空文档接口

```
POST /documents/clear
```

### 6.4 统计接口

```
GET /stats
{
  "total_chunks": 20,
  "llm_available": true,
  "sessions": 0
}
```


## 七、配置说明

### 7.1 环境变量 (.env)

```ini
# Milvus 配置
MILVUS_HOST=192.168.99.101
MILVUS_PORT=19530

# 模型路径
BGE_MODEL_PATH=F:/ModelCache/BAAI/bge-small-zh-v1___5
QWEN_MODEL_PATH=F:/ModelCache/Qwen-7B-Chat.Q4_K_M.gguf

# 功能开关
ENABLE_RERANKER=false

# LLM 配置
LLM_N_CTX=2048
LLM_N_THREADS=4

# 日志配置
LOG_LEVEL=INFO
```

### 7.2 启动命令

```bash
# 启动 Milvus
docker-compose up -d

# 启动后端
python app.py

# 启动前端
streamlit run streamlit_app.py --server.address 127.0.0.1 --server.port 8501
```


## 八、项目结构

```
rag-knowledge-base/
├── data/                      # 文档存放目录
├── logs/                      # 应用运行日志
├── milvus_data/               # Milvus Lite 数据
├── src/
│   ├── cleaner.py             # 文本清洗
│   ├── chunker.py             # 文档切分
│   ├── config.py              # 配置管理
│   ├── conversation.py        # 多轮对话
│   ├── document_loader.py     # 文档加载
│   ├── embedding.py           # Embedding 模型
│   ├── llm_client.py          # LLM 客户端
│   ├── logger.py              # 日志处理
│   ├── rag_pipeline.py        # RAG 流程
│   ├── reranker.py            # 重排序
│   └── vector_store.py        # Milvus 存储
├── app.py                     # FastAPI 入口
├── streamlit_app.py           # 前端界面
├── batch_import.py            # 批量导入
├── requirements.txt           # 依赖清单
├── docker-compose.yml         # Milvus 部署
└── .env.example               # 配置示例
```


## 九、未来规划

本章节将未来要建设的功能按优先级分为三个版本，逐版本规划。

### 9.1 v2.0 - 检索质量与体验优化（10-15天）

本版本聚焦于提升检索准确率和用户体验，是当前系统最急需的改进方向。

#### 9.1.1 混合检索

| 项目 | 说明 |
|------|------|
| **功能描述** | 向量检索 + BM25 关键词检索，通过 RRF 算法融合结果 |
| **预期收益** | 召回率提升 10-20%，解决纯向量检索语义漂移问题 |
| **技术方案** | 集成 `rank_bm25` 库，新增 `hybrid_retriever.py` 模块 |
| **工作量** | 2 天 |

#### 9.1.2 重排序

| 项目 | 说明 |
|------|------|
| **功能描述** | 使用 Cross-Encoder 模型对检索结果精排 |
| **预期收益** | 首条命中率提升 15-25% |
| **技术方案** | 下载 `BAAI/bge-reranker-v2-m3` 模型，集成到 `reranker.py` |
| **工作量** | 1 天（需下载模型）|

#### 9.1.3 流式输出

| 项目 | 说明 |
|------|------|
| **功能描述** | SSE 逐字推送，实现"打字机"效果 |
| **预期收益** | 用户体验显著提升 |
| **技术方案** | FastAPI `StreamingResponse` + 前端 EventSource |
| **工作量** | 1 天 |

#### 9.1.4 离线评估脚本

| 项目 | 说明 |
|------|------|
| **功能描述** | 计算召回率、命中率、MRR 等指标 |
| **预期收益** | 量化调优效果，指导迭代方向 |
| **技术方案** | 新增 `evaluate.py`，支持测试集批量评估 |
| **工作量** | 2 天 |

### 9.1.5 动态切分策略

| 功能 | 优先级 | 说明 |
|------|--------|------|
| 标题层级检测 | 高 | 按 Markdown/HTML 标题切分，提升语义完整性 |
| 代码块/表格保护 | 高 | 避免截断结构化内容 |
| 文档类型自动识别 | 中 | 根据内容选择切分策略 |
| 自适应 chunk_size | 中 | 根据段落长度动态调整 |
| 语义边界检测 | 中 | 检测段落边界，合并相似内容 |
| **工作量** | 4 天 |

### 9.2 v3.0 - 系统化与智能化（10-15天）

本版本聚焦于系统完善和智能化能力提升。

#### 9.2.1 查询改写与 HyDE

| 项目 | 说明 |
|------|------|
| **功能描述** | 对用户问题进行同义转述，或生成假设答案进行检索 |
| **预期收益** | 改善模糊查询，提升复杂问题的召回率 |
| **技术方案** | 调用 LLM 进行查询改写，集成 `hyde.py` 模块 |
| **工作量** | 2 天 |

#### 9.2.2 用户认证与权限管理

| 项目 | 说明 |
|------|------|
| **功能描述** | JWT 鉴权，多用户知识库隔离 |
| **预期收益** | 企业级安全合规 |
| **技术方案** | FastAPI 添加 `HTTPBearer` 依赖，知识库按用户 ID 隔离 |
| **工作量** | 2 天 |

#### 9.2.3 文档增量更新

| 项目 | 说明 |
|------|------|
| **功能描述** | 支持 upsert 操作，无需清空重建 |
| **预期收益** | 降低维护成本，支持动态知识库 |
| **技术方案** | `vector_store.py` 新增 `upsert` 方法 |
| **工作量** | 1 天 |

#### 9.2.4 长期个性化记忆

| 项目 | 说明 |
|------|------|
| **功能描述** | 跨会话存储用户偏好和重要事实 |
| **预期收益** | 实现"越用越懂你"的个性化体验 |
| **技术方案** | 新增 `long_term_memory.py`，使用向量库存储记忆 |
| **工作量** | 3 天 |

### 9.3 v4.0 - 多模态与复杂推理（长期愿景）

本版本面向更复杂的业务场景和更高阶的 AI 能力。

#### 9.3.1 Agentic RAG

| 项目 | 说明 |
|------|------|
| **功能描述** | 多轮推理，模型自主判断是否需要检索、检索什么 |
| **预期收益** | 处理需要多步推理的复杂问题 |
| **技术方案** | 引入 LangGraph 构建 Agent 工作流 |
| **工作量** | 1-2 周 |

#### 9.3.2 Graph RAG

| 项目 | 说明 |
|------|------|
| **功能描述** | 知识图谱增强多跳推理 |
| **预期收益** | 处理高度关联的复杂知识 |
| **技术方案** | 引入 Neo4j，构建实体关系图谱 |
| **工作量** | 2-3 周 |

#### 9.3.3 多模态 RAG

| 项目 | 说明 |
|------|------|
| **功能描述** | 支持图表、图片的理解和问答 |
| **预期收益** | 扩展业务场景 |
| **技术方案** | 引入多模态 Embedding 模型（如 CLIP）|
| **工作量** | 2-3 周 |

### 9.5 架构缺陷改进计划

针对 1.4 节列出的架构缺点，改进计划如下：

| 缺点 | 改进版本 | 改进方案 |
|------|---------|---------|
| 单实例部署 | v3.0 | 多实例 + Nacos 服务注册 |
| 无用户隔离 | v3.0 | JWT 认证 + 知识库隔离 |
| 检索能力有限 | v2.0 | 混合检索 + 重排序 |
| 无流式输出 | v2.0 | SSE 流式输出 |
| 监控不完善 | v3.0 | Prometheus + Grafana |
| 无缓存机制 | v3.0 | Redis 缓存 |


## 十、更新日志

### v1.0.0 (2026-03-31)

- 初始版本发布
- 支持多格式文档加载
- 实现 RAG 完整流程
- 提供 FastAPI 接口
- 支持多轮对话
- GPU 加速支持
- 完整日志监控
```