# RAG-Agent

**Repository Path**: yichench/rag-agent

## Basic Information

- **Project Name**: RAG-Agent
- **Description**: 基于检索增强生成（RAG）技术的本地文档智能处理系统。通过 Agent 架构 实现用户意图识别与技能路由，同时支持文档问答与文档摘要两大核心功能。
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-30
- **Last Updated**: 2026-06-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RAG-Agent：基于 Agent 智能路由的本地文档问答系统

基于检索增强生成（RAG）技术的本地文档智能处理系统。通过 **Agent 架构** 实现用户意图识别与技能路由，同时支持**文档问答**与**文档摘要**两大核心功能。

---

## 目录

- [系统架构](#系统架构)
- [功能特性](#功能特性)
- [技术栈](#技术栈)
- [快速开始](#快速开始)
- [项目结构](#项目结构)
- [核心流程](#核心流程)
- [使用指南](#使用指南)
- [配置手册](#配置手册)
- [API 参考](#api-参考)
- [开发指南](#开发指南)
- [常见问题](#常见问题)

---

## 系统架构

```
┌─────────────────────────────────────────────────────────┐
│                    用户输入                              │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│                    Agent 层                              │
│                                                         │
│   ┌──────────────┐     ┌──────────────────────────┐     │
│   │ 意图分类 LLM │────▶│  技能路由 (Skill Router)  │     │
│   └──────────────┘     └──────────┬───────────────┘     │
└───────────────────────────────────┼─────────────────────┘
                                    │
            ┌───────────────────────┼───────────────────────┐
            │                       │                       │
            ▼                       ▼                       ▼
┌───────────────────────┐ ┌───────────────────────┐
│   Skill 1: 文档问答    │ │   Skill 2: 文档摘要    │
│                       │ │                       │
│  1. Query 重写        │ │  1. 向量检索 (Top-8)   │
│  2. 向量检索 (Top-4)  │ │  2. 摘要 Prompt 生成   │
│  3. 重排序             │ │  3. LLM 结构化输出     │
│  4. Prompt + 历史组装  │ │                       │
│  5. LLM 生成          │ │                       │
└───────────┬───────────┘ └───────────┬───────────┘
            │                         │
            └─────────────┬───────────┘
                          ▼
            ┌─────────────────────────┐
            │   回答 + 来源 + 技能标签   │
            └─────────────────────────┘
```

### 设计要点

| 层次 | 职责 | 关键设计 |
|------|------|----------|
| **Agent 层** | 意图分类 + 路由分发 | 基于 LLM 对用户输入进行二分类（qa/summarize），支持自动/手动模式切换 |
| **Skill 层** | 技能独立执行 | 每个 Skill 继承 `BaseSkill` 抽象基类，实现统一的 `execute()` 接口 |
| **Pipeline 层** | 检索与生成 | `RAGPipeline` 作为底层引擎，被各 Skill 按需调用 |

---

## 功能特性

### 核心功能

| 功能 | 说明 | 状态 |
|------|------|------|
| 🧠 **Agent 智能路由** | LLM 自动识别用户意图（问答/摘要），路由到对应技能 | ✅ |
| 💬 **文档问答** | 针对文档具体问题进行精确回答，支持多轮对话与引用溯源 | ✅ |
| 📋 **文档摘要** | 对文档内容生成结构化摘要（概述、关键要点、结论） | ✅ |
| 🔄 **三种运行模式** | 自动模式（AI 判断）/ 文档问答 / 文档摘要，侧边栏一键切换 | ✅ |
| 🏷️ **技能标签展示** | 每条助手消息自动标注当前使用的技能名称 | ✅ |

### 增强功能

| 功能 | 说明 | 状态 |
|------|------|------|
| ✏️ **Query 重写** | 自动优化问题表述，支持 expand/decompose/hyde 策略 | ✅ |
| 🔄 **结果重排序** | 对检索结果进行相关性重排序，提高回答质量 | ✅ |
| 💬 **多轮对话记忆** | 保留对话上下文，支持代词指代等连贯对话 | ✅ |
| 📎 **引用溯源** | 标注答案来源文档及内容预览，支持点击展开 | ✅ |
| 📤 **文档上传** | 支持 PDF/DOCX/TXT/MD 格式在线上传 | ✅ |
| 📄 **报告生成** | 一键生成课程设计报告（含架构图、流程图、对比图表） | ✅ |

---

## 技术栈

### 后端核心
| 组件 | 技术选型 | 用途 |
|------|----------|------|
| 应用框架 | LangChain | RAG 流程编排 |
| 向量检索 | FAISS | 高效相似度搜索 |
| 嵌入模型 | BGE-small-zh-v1.5 | 中文文本向量化 |
| 大语言模型 | OpenAI / Qwen / Deepseek | 答案生成与意图分类 |

### 前端与文档解析
| 组件 | 技术选型 | 用途 |
|------|----------|------|
| Web 界面 | Streamlit | 交互式前端 |
| PDF 解析 | PyPDF2 | PDF 文档提取 |
| Word 解析 | python-docx | DOCX 文档提取 |
| 通用解析 | Unstructured | 多格式文档预处理 |

---

## 快速开始

### 前置条件

- Python 3.10+
- 至少一个 LLM API 密钥（OpenAI / 通义千问 / Deepseek）

### 安装步骤

```bash
# 1. 克隆项目
git clone <repository-url>
cd RAG-Agent

# 2. 安装依赖
pip install -r requirements.txt

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填写 API 密钥

# 4. 准备文档
# 将 PDF/DOCX/TXT/MD 文件放入 data/ 目录

# 5. 启动应用
streamlit run app.py
```

### 首次使用

1. 打开浏览器访问 Streamlit 界面
2. 点击侧边栏「构建索引」按钮，等待索引构建完成
3. 在对话框输入问题开始使用
4. 可在侧边栏随时切换技能模式

---

## 项目结构

```
RAG-Agent/
│
├── 📁 report/                     # 📊 报告生成脚本与图片
│   ├── generate_report.py         #   课程设计报告生成器
│   ├── generate_diagrams.py       #   架构图/流程图绘制脚本
│   └── report_images/             #   生成的图片资源
│
├── 📁 data/                       # 文档数据目录（用户文档存放处）
├── 📁 vector_store/               # 向量索引持久化存储
├── 📁 model/                      # 模型文件缓存
│
├── 📁 skills/                     # 🔧 技能模块
│   ├── __init__.py                #   包初始化，统一导出
│   ├── base.py                    #   BaseSkill 抽象基类
│   ├── qa_skill.py                #   文档问答技能
│   └── summarize_skill.py         #   文档摘要技能
│
├── agent.py                       # 🧠 Agent 主类（意图分类 + 路由分发）
├── app.py                         # 🌐 Streamlit 前端应用
│
├── rag_pipeline.py                # 🔗 RAG 主流程编排
├── loader.py                      # 📄 文档加载器
├── splitter.py                    # ✂️ 文档切分器
├── embedding.py                   # 🔢 Embedding 模型封装
├── retriever.py                   # 🔍 向量检索器（FAISS）
├── generator.py                   # 🤖 LLM 生成器
├── reranker.py                    # 📊 重排序器
├── query_rewriter.py              # ✏️ Query 重写器
│
├── config.py                      # ⚙️ 全局配置
├── utils.py                       # 🛠️ 工具函数
│
├── requirements.txt               # 📦 依赖清单
├── .env.example                   # 🔐 环境变量模板
└── README.md                      # 📖 项目文档
```

---

## 核心流程

### 文档问答流程（qa）

```
用户问题 → Query重写 → FAISS检索(Top-4) → 重排序 → Prompt组装(含历史) → LLM生成 → 回答+来源
```

使用 `RAGPipeline.query()` 全链路，支持 query rewriting、rerank、memory 等所有增强功能。

### 文档摘要流程（summarize）

```
用户输入 → FAISS检索(Top-8) → 摘要Prompt → LLM结构化生成 → 结构化摘要+来源
```

独立于问答流程，使用更大 `top_k`（8个文档块），通过专用 Prompt 生成包含"概述-关键要点-结论"的结构化摘要。

### 意图分类流程（auto mode）

```
用户输入
    │
    ▼
LLM 分类 Prompt ──→ "qa" → QASkill.execute() → 文档问答流程
    │               "summarize" → SummarizeSkill.execute() → 文档摘要流程
    ▼
分类结果缓存（单次请求内）
```

分类 Prompt 示例：
```
判断用户问题的意图类型：
- qa: 用户想询问具体问题、寻求解释、获取事实
- summarize: 用户想了解整体内容、要求总结或摘要

用户问题：{query}

只返回 qa 或 summarize：
```

---

## 使用指南

### 技能模式说明

| 模式 | 行为 | 适用场景 |
|------|------|----------|
| 🔄 **自动模式** | Agent 用 LLM 判断意图后路由 | 通用场景，系统自动处理 |
| 💬 **文档问答** | 全部走问答流程 | 明确需要精确回答时 |
| 📋 **文档摘要** | 全部走摘要流程 | 需要整体概览时 |

### 交互界面说明

- **侧边栏**：技能切换、索引管理、文档上传、系统配置展示
- **主区域**：对话历史、技能标签、来源引用
- **消息气泡**：助手消息顶部显示当前技能标签（💬 文档问答 / 📋 文档摘要）

---

## 配置手册

### 基础配置（.env 文件）

#### LLM 提供商配置

| 变量 | 说明 | 可选值 |
|------|------|--------|
| `LLM_PROVIDER` | LLM 提供商 | `openai` / `qwen` / `deepseek` |
| `OPENAI_API_KEY` | OpenAI API 密钥 | - |
| `OPENAI_API_BASE` | OpenAI API 地址 | 默认 `https://api.openai.com/v1` |
| `OPENAI_MODEL_NAME` | OpenAI 模型 | 默认 `gpt-3.5-turbo` |
| `DASHSCOPE_API_KEY` | 通义千问 API 密钥 | - |
| `QWEN_MODEL_NAME` | Qwen 模型 | 默认 `qwen-turbo` |
| `DEEPSEEK_API_KEY` | Deepseek API 密钥 | - |
| `DEEPSEEK_API_BASE` | Deepseek API 地址 | 默认 `https://api.deepseek.com/v1` |
| `DEEPSEEK_MODEL_NAME` | Deepseek 模型 | 默认 `deepseek-chat` |

#### 模型参数

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `LLM_TEMPERATURE` | 生成温度（0-1） | `0.7` |
| `LLM_MAX_TOKENS` | 最大生成 token 数 | `2048` |
| `EMBEDDING_MODEL_NAME` | Embedding 模型 | `BAAI/bge-small-zh-v1.5` |
| `EMBEDDING_DEVICE` | 运行设备 | `cpu` |

#### 检索与切分

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `CHUNK_SIZE` | 文档切分大小 | `500` |
| `CHUNK_OVERLAP` | 切分重叠大小 | `50` |
| `TOP_K` | 检索文档数量 | `4` |

#### 功能开关

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `QUERY_REWRITE_ENABLED` | 启用 Query 重写 | `true` |
| `QUERY_REWRITE_STRATEGY` | 重写策略 | `expand` |
| `RERANK_ENABLED` | 启用重排序 | `true` |
| `RERANK_TOP_K` | 重排序保留数量 | `3` |
| `MEMORY_ENABLED` | 启用多轮记忆 | `true` |
| `MAX_HISTORY_TURNS` | 保留对话轮次 | `6` |
| `SHOW_CITATION_SCORES` | 显示引用分数 | `true` |

#### Agent / Skill 配置

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `AGENT_ENABLED` | 启用 Agent | `true` |
| `AGENT_DEFAULT_MODE` | 默认技能模式 | `auto` |
| `SUMMARIZE_TOP_K` | 摘要检索文档数 | `8` |

---

## API 参考

### Agent API

```python
from agent import Agent

# 初始化（自动初始化 RAGPipeline）
agent = Agent()

# 自动模式：Agent 判断意图
result = agent.execute("什么是RAG？")
print(result["skill"])       # "qa"
print(result["answer"])      # 回答内容
print(result["sources"])     # 来源引用列表

# 指定模式（手动路由）
result = agent.execute("总结文档的主要内容", mode="summarize")
print(result["skill"])       # "summarize"

# 携带对话历史（多轮对话）
result = agent.execute(
    "它有哪些优势？",
    mode="qa",
    chat_history=[{"role": "user", "content": "什么是RAG？"},
                  {"role": "assistant", "content": "..."}]
)
```

### execute() 返回格式

```python
{
    "answer": str,          # 生成的回答或摘要
    "sources": list[dict],  # 来源引用列表
    "skill": str,           # 实际使用的技能名称（qa/summarize）
    "rewritten_query": str  # (可选) 重写后的查询
}
```

### 直接使用 RAGPipeline

```python
from rag_pipeline import RAGPipeline

# 初始化
pipeline = RAGPipeline()
pipeline.initialize()

# 构建索引
pipeline.build_index()

# 查询
result = pipeline.query("什么是RAG？")
print(result["answer"])
print(result["sources"])
```

### 扩展自定义 Skill

```python
from skills.base import BaseSkill

class MyCustomSkill(BaseSkill):
    @property
    def name(self) -> str:
        return "my_skill"

    @property
    def description(self) -> str:
        return "自定义技能描述"

    def execute(self, query: str, **kwargs) -> dict:
        # 实现自定义逻辑
        return {
            "answer": "自定义回答",
            "sources": [],
            "skill": self.name
        }

# 注册到 Agent
agent.register_skill(MyCustomSkill(pipeline))
```

---

## 开发指南

### 添加新技能

1. 在 `skills/` 下创建新文件，继承 `BaseSkill`
2. 实现 `name`、`description` 属性和 `execute()` 方法
3. 在 `Agent` 中通过 `register_skill()` 注册
4. 在 `app.py` 侧边栏添加对应的 UI 选项

### 环境要求

- Windows / Linux / macOS
- Python 3.10+
- 建议 8GB+ 内存（Embedding 模型加载约需 2GB）

### 扩展建议

| 方向 | 具体建议 |
|------|----------|
| 更多技能 | 代码分析、数据可视化、关键词提取 |
| 性能优化 | 异步文档加载、批量向量化、增量索引更新、缓存机制 |
| 检索增强 | 混合检索（BM25 + 向量）、多路召回 |
| 文档支持 | OCR 图片文字提取、HTML 解析、邮件解析 |

---

## 常见问题

**Q: 构建索引时内存不足？**
A: 减小 `CHUNK_SIZE`（如改为 300）或分批处理文档。

**Q: 检索结果不相关？**
A: 尝试增大 `TOP_K`（如改为 8），或调整 `CHUNK_SIZE` 优化文档切分粒度。

**Q: LLM 响应缓慢？**
A: 检查网络连接，或切换到更快的模型（如 `gpt-3.5-turbo` 而非 `gpt-4`）。

**Q: Agent 分类不准确？**
A: 可在侧边栏手动选择技能模式，绕过自动分类直接路由。

**Q: 如何切换 LLM 提供商？**
A: 修改 `.env` 中的 `LLM_PROVIDER` 为 `openai` / `qwen` / `deepseek`，并配置对应 API 密钥。

---

## 许可证

MIT License