# RAG

**Repository Path**: Echoza/rag

## Basic Information

- **Project Name**: RAG
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-11
- **Last Updated**: 2026-06-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🤖 RAG 智能对话助手

> 基于检索增强生成 (RAG) 技术的企业级知识问答系统

## 📋 目录
- [项目简介](#项目简介)
- [核心功能](#核心功能)
- [快速开始](#快速开始)
- [项目结构](#项目结构)
- [技术架构](#技术架构)
- [使用指南](#使用指南)
- [配置说明](#配置说明)
- [API 文档](#api 文档)
- [常见问题](#常见问题)

---

## ✨ 核心功能

### 🎯 检索能力
- **关键词检索 (BM25)**: 基于 jieba 分词的传统关键词匹配
- **向量检索**: 语义相似度匹配，理解问题意图
- **混合检索 (RRF)**: 融合两种检索方式，精度更高（推荐）
- **查询改写**: LLM 自动生成 3 个等价查询，提升召回率
- **查询补全**: 多轮对话中自动补全省略的主语和谓语

### 💬 对话能力
- **多轮对话**: 支持上下文记忆，智能补全省略问题
- **严格模式**: 无相关知识时明确告知，避免幻觉
- **来源标注**: 每个回答附带参考文档来源
- **对话历史**: 支持查看和清空对话记录

### 📚 知识库管理
- **多知识库**: 创建、删除、管理多个独立知识库
- **多格式支持**: txt、pdf、pptx、ppt 文档
- **文件上传**: Web 界面拖拽上传，自动处理
- **智能分块**: 自适应文档切分与向量化
- **实时统计**: 文件数量、向量数量一目了然

### 🖥️ 交互界面
- **Web 界面**: Gradio 构建的现代化可视化界面
- **响应式设计**: 大字体、清晰的布局
- **实时反馈**: 上传、检索、生成全过程可视化

## 📁 项目结构

```
RAG-LLM/
├── web_app.py                  # Web 界面入口 (Gradio)
├── config.py                   # 配置文件
├── requirements.txt            # 依赖包列表
├── .env.example               # 环境配置模板
├── .gitignore                 # Git 忽略规则
├── README.md                  # 项目文档
├── data/                      # 知识库文档目录
│   └── (用户上传的文档)
├── rag_engine/                # RAG 核心引擎
│   ├── __init__.py
│   ├── chatbot.py             # 对话助手主类 (命令行版)
│   ├── knowledge_manager.py   # 多知识库管理
│   ├── knowledge_base.py      # 单知识库管理
│   ├── retriever.py           # 多模式检索器 (BM25/向量/混合)
│   ├── prompt_engine.py       # Prompt 模板引擎
│   ├── conversation_manager.py # 对话历史管理
│   ├── query_completer.py     # 查询补全器 (多轮对话)
│   └── query_rewriter.py      # 查询改写器 (LLM 增强)
├── utils/                     # 工具函数
│   ├── __init__.py
│   └── llm_client.py          # LLM 客户端封装
└── chroma_db/                 # 向量数据库 (自动生成，已加入.gitignore)
```

## 🚀 快速开始

### 前置要求
- Python 3.8+
- 有效的 LLM API Key

### 安装步骤

#### 1. 克隆项目
```bash
git clone https://gitee.com/Echoza/rag.git
cd RAG-LLM
```

#### 2. 创建虚拟环境
```bash
# Windows
python -m venv .venv
.venv\Scripts\activate

# Linux/Mac
python3 -m venv .venv
source .venv/bin/activate
```

#### 3. 安装依赖
```bash
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

#### 4. 配置 API
```bash
# 复制配置模板
cp .env.example .env

# 编辑 .env 文件，填入你的配置
# Windows: notepad .env
# Linux/Mac: vim .env 或 nano .env
```

#### 5. 启动应用
```bash
python web_app.py
```

浏览器访问：**http://localhost:7860**

---

## 🎨 Web 界面功能

### 📚 知识库管理面板

| 功能 | 操作说明 |
|------|----------|
| **新建知识库** | 输入名称 → 点击"创建"按钮 |
| **上传文件** | 选择知识库 → 选择文件 → 点击"上传并处理" |
| **删除知识库** | 选择知识库 → 点击"删除选中知识库" |
| **查看统计** | 实时显示文件数和向量数 |

### 💬 对话面板

| 功能 | 说明 |
|------|------|
| **知识库选择** | 多选框，可同时使用多个知识库 |
| **检索模式** | 混合检索 (推荐)/向量检索/关键词检索 |
| **严格模式** | 开启后无相关知识时明确告知 |
| **查询改写** | 开启后 LLM 自动生成等价查询 |
| **清空历史** | 清空多轮对话上下文 |

### 🎯 使用流程

```
1️⃣ 创建知识库 → 2️⃣ 上传文档 → 3️⃣ 选择知识库 → 4️⃣ 开始对话
```

---

## 📖 使用示例

### 💬 对话示例

**场景 1: 单轮问答**
```
用户：园区食堂有哪些餐厅？

🔍 检索结果 (混合模式):
  [1] 相似度：0.089 | 园区 C 栋 1-2 层为食堂区域，共有三个餐厅和一个咖啡厅...
  [2] 相似度：0.065 | 一餐厅 (C 栋 1 层东侧) 主营中式快餐，价格区间 12-18 元...
  [3] 相似度：0.052 | 二餐厅 (C 栋 1 层西侧) 为特色档口模式，设有麻辣烫...

助手：根据园区资料，C 栋 1-2 层共有三个餐厅和一个咖啡厅：

1. 一餐厅 (C 栋 1 层东侧) - 中式快餐，12-18 元
2. 二餐厅 (C 栋 1 层西侧) - 特色档口，15-25 元  
3. 三餐厅 (C 栋 2 层) - 高端商务餐厅，50-80 元
4. 咖啡厅 (C 栋 1 层中庭) - 星巴克运营，员工 8 折

---
参考来源:
1. [园区 C 栋 1-2 层为食堂区域，共有三个餐厅和一个咖啡厅...]
2. [一餐厅 (C 栋 1 层东侧) 主营中式快餐，价格区间 12-18 元...]
3. [二餐厅 (C 栋 1 层西侧) 为特色档口模式，设有麻辣烫...]
```

**场景 2: 多轮对话 (查询补全)**
```
用户：年假有多少天？
助手：工作满 1 年不满 10 年的员工，每年享有 5 天带薪年假...

用户：那病假呢？
*（已根据上下文补全为：病假有多少天？）*
助手：员工每年享有 20 天病假...

用户：怎么申请？
*（已根据上下文补全为：如何申请病假？）*
助手：需要填写请假单并找主管审批...
```

---

## ⚙️ 技术架构

### 🔄 整体流程

```
┌─────────────┐
│  用户提问   │
└──────┬──────┘
       │
       ▼
┌─────────────────────┐
│  查询补全           │ ← 多轮对话：补全省略的主语/谓语
│  (QueryCompleter)   │
└──────┬──────────────┘
       │
       ▼
┌─────────────────────┐
│  查询改写 (可选)     │ ← LLM 生成 3 个等价查询
│  (QueryRewriter)    │
└──────┬──────────────┘
       │
       ▼
┌─────────────────────┐
│  多模式检索         │ ← keyword/vector/hybrid
│  (MultiModeRetriever)│
└──────┬──────────────┘
       │
       ▼
┌─────────────────────┐
│  Prompt 组装         │ ← 检索结果 + 对话历史
│  (PromptEngine)     │
└──────┬──────────────┘
       │
       ▼
┌─────────────────────┐
│  LLM 生成回答        │
│  (get_llm())        │
└──────┬──────────────┘
       │
       ▼
┌─────────────────────┐
│  返回结果 + 来源标注 │
└─────────────────────┘
```

### 🧩 核心模块详解

| 模块 | 功能 | 关键技术 |
|------|------|----------|
| **MultiKnowledgeBase** | 多知识库管理 | 动态创建、文件索引、向量存储 |
| **KnowledgeBase** | 单知识库管理 | 文档加载、文本切分、向量化 |
| **MultiModeRetriever** | 多模式检索 | BM25、余弦相似度、RRF 融合 |
| **QueryRewriter** | 查询改写 | LLM 生成等价查询、用语转换 |
| **QueryCompleter** | 查询补全 | 上下文理解、代词消解 |
| **ConversationManager** | 对话管理 | 历史维护、格式转换 |
| **PromptEngine** | Prompt 工程 | 模板管理、严格模式 |
| **RAGChatBot** | 对话助手 | 检索 + 生成一体化 |
| **RAGWebApp** | Web 界面 | Gradio、实时交互 |

### 📊 检索模式对比

| 模式 | 算法 | 优点 | 缺点 | 适用场景 |
|------|------|------|------|----------|
| **keyword** | BM25 + jieba | 精确匹配关键词 | 无法理解语义 | 专有名词、精确查询 |
| **vector** | 余弦相似度 | 语义理解能力强 | 可能漏掉精确词 | 模糊查询、意图理解 |
| **hybrid** | RRF 融合 | 结合两者优势 | 计算稍慢 | **通用场景 (推荐)** |

---

## 🔧 配置说明

### 📝 .env 文件

创建 `.env` 文件 (从 `.env.example` 复制):

```bash
# LLM API 配置
OPENAI_API_KEY=your-api-key-here
OPENAI_API_BASE=http://122.224.109.54:20001/spiritx-api/v1
```

### ⚙️ config.py 参数

| 参数 | 默认值 | 说明 | 调整建议 |
|------|--------|------|----------|
| **CHUNK_SIZE** | 800 | 文档切分大小 | 长文档可增大，短文档减小 |
| **CHUNK_OVERLAP** | 100 | 切分重叠部分 | 保持为 CHUNK_SIZE 的 10-20% |
| **TOP_K** | 3 | 检索返回数量 | 增加可提升召回率，但会降低速度 |
| **SIMILARITY_THRESHOLD** | 0.7 | 相似度阈值 | 降低阈值可返回更多结果 |
| **LLM_MODEL** | "ClawClaw" | LLM 模型名称 | 根据 API 提供商调整 |
| **EMBEDDING_MODEL** | "bge-m3" | 嵌入模型 | 支持 bge-m3、text-embedding-ada-002 等 |
| **TEMPERATURE** | 0 | 生成温度 | 0=确定性，1=创造性 |

---

## 📚 API 文档

### 核心类接口

#### MultiKnowledgeBase

```python
from rag_engine.knowledge_manager import MultiKnowledgeBase

kb_manager = MultiKnowledgeBase()

# 创建知识库
kb_manager.create_kb("my_kb")

# 上传文件
kb_manager.add_documents_to_kb("my_kb", "path/to/file.pdf")

# 获取向量库
vectorstore = kb_manager.get_vectorstore("my_kb")

# 列出所有知识库
kbs = kb_manager.list_knowledge_bases()

# 删除知识库
kb_manager.delete_kb("my_kb")
```

#### MultiModeRetriever

```python
from rag_engine.retriever import MultiModeRetriever

retriever = MultiModeRetriever(vectorstore, chunks)

# 关键词检索
results = retriever.keyword_search("年假制度", top_k=3)

# 向量检索
results = retriever.vector_search("年假制度", top_k=3)

# 混合检索 (推荐)
results = retriever.hybrid_search("年假制度", top_k=3)
```

#### QueryRewriter

```python
from rag_engine.query_rewriter import QueryRewriter

rewriter = QueryRewriter()
queries = rewriter.rewrite("每天上多久的班")
# 输出：["每天工作时长是多少小时", "工作时间的规定", "每日工作时段"]
```

#### QueryCompleter

```python
from rag_engine.query_completer import QueryCompleter

completer = QueryCompleter()
completed = completer.complete("那病假呢？", chat_history)
# 输出："病假有多少天？"
```

#### ConversationManager

```python
from rag_engine.conversation_manager import ConversationManager

manager = ConversationManager(max_turns=10)

# 添加对话
manager.add_turn("年假有多少天？", "年假有多少天？", "年假有 15 天")

# 获取历史
history = manager.get_history(format_type="chat")

# 清空历史
manager.clear_history()
```

---

## ❓ 常见问题

### 🚨 运行问题

**Q: 启动时提示 API Key 错误？**
```
A: 检查 .env 文件是否正确创建并填写了有效的 API 配置
   确保 OPENAI_API_KEY 和 OPENAI_API_BASE 都已设置
```

**Q: 上传文件后看不到效果？**
```
A: 1. 确保在对话时勾选了对应的知识库
   2. 检查文件是否成功上传 (查看知识库列表中的文件数)
   3. 尝试重新上传文件
```

**Q: 检索结果为空？**
```
A: 1. 检查知识库是否正确创建并上传了文件
   2. 尝试使用更通用的关键词
   3. 切换检索模式 (推荐混合模式)
   4. 降低 SIMILARITY_THRESHOLD 阈值
```

**Q: API 调用失败或超时？**
```
A: 1. 检查网络连接
   2. 确认 API_BASE 地址是否正确
   3. 验证 API Key 是否有效
   4. 检查 API 服务是否正常运行
```

### 🔧 配置问题

**Q: 如何调整文档切分大小？**
```
A: 修改 config.py 中的 CHUNK_SIZE 和 CHUNK_OVERLAP 参数
   然后删除 chroma_db 目录重新构建知识库
```

**Q: 如何更换 LLM 模型？**
```
A: 修改 config.py 中的 LLM_MODEL 参数
   确保新模型与 API_BASE 兼容
```

**Q: 如何增加检索结果数量？**
```
A: 修改 config.py 中的 TOP_K 参数 (默认 3)
   增大可返回更多结果，但会降低响应速度
```

### 💡 使用技巧

**Q: 哪种检索模式最好？**
```
A: 混合检索 (hybrid) 通常效果最好
   它结合了关键词和向量检索的优势
```

**Q: 什么时候启用查询改写？**
```
A: 当用户用语与文档用语差异较大时
   例如：口语 vs 正式文档用语
```

**Q: 如何优化回答质量？**
```
A: 1. 使用高质量的知识库文档
   2. 启用混合检索模式
   3. 适当增加 TOP_K 值
   4. 启用查询改写功能
```

---

## 🚀 扩展建议

### 短期优化
- [ ] 添加 Reranker 对检索结果重排序
- [ ] 支持更多文档格式 (docx, xlsx)
- [ ] 添加检索结果评分可视化
- [ ] 实现对话历史导出功能

### 长期规划
- [ ] 多用户权限管理
- [ ] 知识库版本控制
- [ ] 回答质量评估指标
- [ ] 批量文档处理
- [ ] 分布式向量检索

---

## 👥 作者

**RAG 课程结课作业**

- 开发者：Echoza
- 仓库：[https://gitee.com/Echoza/rag](https://gitee.com/Echoza/rag)

---

## 📄 许可证

MIT License

---

## 🙏 致谢

本项目使用了以下开源库:

- [Gradio](https://gradio.app/) - Web 界面框架
- [ChromaDB](https://www.trychroma.com/) - 向量数据库
- [LangChain](https://python.langchain.com/) - LLM 应用开发框架
- [BGE M3](https://huggingface.co/BAAI/bge-m3) - 嵌入模型
- [Jieba](https://github.com/fxsjy/jieba) - 中文分词

---

<div align="center">

**⭐ 如果本项目对你有帮助，请给一个星标！**

_最后更新：2024 年 6 月_

</div>