---
title: Adaptive RAG
emoji: 🐢
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false
app_port: 7860
---

# 自适应RAG系统 - 技术总结文档

## 📋 项目概述

本项目是一个**自适应检索增强生成（Adaptive RAG）**系统，实现了智能查询路由、多源信息检索、质量保证流水线等核心功能。系统能够根据查询内容自动选择最佳信息源（本地向量数据库或网络搜索），并通过多层验证机制确保生成答案的准确性和相关性。

---

## 🏗️ 系统架构

### 整体架构流程

```
用户查询
  ↓
智能路由 (route_question)
  ↓
[向量存储路径] ←→ [网络搜索路径]
  ↓                    ↓
查询分解           网络搜索
(decompose_query)   (web_search)
  ↓                    ↓
向量检索           生成答案
(retrieve)          (generate)
  ↓                    ↓
文档评分           质量检查
(grade_documents)   (grade_generation)
  ↓                    ↓
决策判断            [有用/无用/不支持]
(decide_to_generate)    ↓
  ↓                    ↓
生成答案 ←──────────────┘
(generate)
  ↓
质量检查
(grade_generation)
  ↓
最终答案
```

---

## 🔧 技术栈详细分析

### 1. 核心框架层

#### 1.1 LangChain & LangGraph
- **技术点**:
  - `LangChain`: LLM应用程序编排框架
  - `LangGraph`: 复杂工作流的状态图实现
  - `StateGraph`: 管理复杂RAG工作流状态
  - `TypedDict`: 类型安全的状态管理
- **应用场景**:
  - 工作流节点定义和编排
  - 状态管理和传递
  - 条件分支和决策逻辑
- **关键代码位置**: `main.py`, `workflow_nodes.py`

#### 1.2 状态管理
- **技术点**:
  - `GraphState` (TypedDict): 定义工作流状态结构
  - 状态字段包括: `question`, `generation`, `documents`, `retry_count`, `retrieval_metrics`, `sub_queries`, `current_query_index`, `original_question`
- **应用场景**: 在工作流节点间传递和更新状态

---

### 2. 语言模型层

#### 2.1 Ollama (本地LLM推理)
- **技术点**:
  - 本地部署的LLM推理引擎
  - 支持Mistral、Phi、TinyLlama等多种模型
  - 通过HTTP API提供服务 (默认端口11434)
- **应用场景**:
  - 查询路由决策
  - 文档相关性评分
  - 答案质量评估
  - 查询分解和重写
  - RAG答案生成
- **关键配置**: `config.py` 中的 `LOCAL_LLM = "mistral"`
- **关键代码位置**: `routers_and_graders.py`, `workflow_nodes.py`

#### 2.2 ChatOllama
- **技术点**: LangChain对Ollama的封装
- **应用场景**: 统一的LLM调用接口

---

### 3. 文档处理层

#### 3.1 文档加载
- **技术点**:
  - `WebBaseLoader`: 从URL加载网络内容
  - `BeautifulSoup4`: HTML解析和内容提取
- **应用场景**: 从指定URL加载知识库文档
- **关键代码位置**: `document_processor.py` 的 `load_documents()` 方法

#### 3.2 文本分块
- **技术点**:
  - `RecursiveCharacterTextSplitter`: 递归字符文本分割器
  - `tiktoken`: 基于BPE的编码器，用于精确计算token数量
  - 分块策略: `chunk_size=250`, `chunk_overlap=50`
- **应用场景**:
  - 将长文档分割成适合向量化的块
  - 保持上下文连贯性（通过重叠）
- **关键代码位置**: `document_processor.py` 的 `split_documents()` 方法

#### 3.3 向量嵌入
- **技术点**:
  - `HuggingFaceEmbeddings`: 使用HuggingFace的嵌入模型
  - 模型: `sentence-transformers/all-MiniLM-L6-v2` (轻量级，384维)
  - 设备自动选择: GPU (CUDA) 或 CPU
  - 嵌入标准化: `normalize_embeddings=True`
- **应用场景**: 将文本转换为向量表示，用于相似度搜索
- **关键代码位置**: `document_processor.py` 的 `__init__()` 方法

---

### 4. 向量数据库层

#### 4.1 Milvus (向量数据库)
- **技术点**:
  - **Milvus Lite**: 本地文件模式，适合开发和测试
  - **Milvus Server**: Docker/K8s部署，支持分布式
  - **Zilliz Cloud**: 云服务模式
  - 索引类型: `HNSW` (高性能), `IVF_FLAT` (平衡), `AUTOINDEX` (自动)
  - 索引参数: `M=8`, `efConstruction=64`
  - 搜索参数: `ef=10` (搜索范围)
- **应用场景**:
  - 存储文档向量
  - 高效相似度搜索
  - 支持百万级数据
- **关键代码位置**: `document_processor.py` 的 `initialize_vectorstore()` 方法

#### 4.2 连接管理
- **技术点**:
  - `pymilvus`: Milvus Python客户端
  - 连接别名管理: `alias="default"`
  - 持久化存储: `drop_old=False`
- **应用场景**: 管理向量数据库连接和集合

---

### 5. 检索层

#### 5.1 基础向量检索
- **技术点**:
  - 余弦相似度搜索
  - Top-K检索 (默认k=5)
  - 异步检索: `asimilarity_search()`
- **应用场景**: 根据查询向量找到最相似的文档

#### 5.2 混合检索 (Hybrid Search)
- **技术点**:
  - **向量检索**: 基于语义相似度
  - **BM25检索**: 基于关键词匹配
  - **权重融合**: `vector: 0.5, keyword: 0.5`
  - `rank-bm25`: BM25算法实现
  - `CustomEnsembleRetriever`: 自定义集成检索器
- **应用场景**:
  - 结合语义和关键词匹配
  - 提高检索召回率
- **关键代码位置**: `document_processor.py` 的 `CustomEnsembleRetriever` 类

#### 5.3 查询扩展 (Query Expansion)
- **技术点**:
  - 使用LLM生成相关扩展查询
  - 提示模板: `QUERY_EXPANSION_PROMPT`
  - 多查询并发检索
  - 结果去重和合并
- **应用场景**:
  - 从不同角度探索查询主题
  - 提高检索覆盖率
- **关键代码位置**: `document_processor.py` 的 `expand_query()` 方法

#### 5.4 多模态检索
- **技术点**:
  - `CLIP模型`: 图像-文本联合嵌入
  - 模型: `openai/clip-vit-base-patch32`
  - 图像编码: 将图像转换为512维向量
  - 跨模态检索: 文本查询图像，图像查询文本
- **应用场景**:
  - 支持图像和文本混合检索
  - 图像相似度搜索
- **关键代码位置**: `document_processor.py` 的 `multimodal_retrieve()` 方法

#### 5.5 多跳检索 (Multi-hop Retrieval)
- **技术点**:
  - 查询分解: 将复杂问题分解为子问题序列
  - 桥接实体提取: 从上一跳结果中提取实体用于下一跳
  - 上下文累积: 合并多跳检索结果
  - 早期终止: 检查是否已获得足够信息
- **应用场景**:
  - 回答需要多步推理的复杂问题
  - 例如: "A的作者在哪个大学工作？" → 分解为 "A的作者是谁？" + "该作者在哪个大学？"
- **关键代码位置**: `workflow_nodes.py` 的 `decompose_query()`, `prepare_next_query()` 方法

---

### 6. 重排序层 (Reranking)

#### 6.1 CrossEncoder重排器
- **技术点**:
  - 模型: `cross-encoder/ms-marco-MiniLM-L-6-v2`
  - 联合编码: 查询和文档一起编码
  - 准确率提升: 相比Bi-Encoder提升15-20%
  - 适用场景: 精排阶段 (Top 20-100文档)
- **应用场景**: 对初始检索结果进行精确重排
- **关键代码位置**: `reranker.py` 的 `CrossEncoderReranker` 类

#### 6.2 其他重排策略
- **TF-IDF重排**: 基于词频-逆文档频率
- **BM25重排**: 基于BM25算法
- **语义重排**: 基于嵌入向量相似度
- **混合重排**: 融合多种策略
- **多样性重排**: MMR算法，避免结果重复

---

### 7. 路由与评分层

#### 7.1 查询路由 (Query Routing)
- **技术点**:
  - LLM-based路由决策
  - 二进制选择: `web_search` 或 `vectorstore`
  - 基于查询内容语义分析
- **应用场景**: 决定使用本地知识库还是网络搜索
- **关键代码位置**: `routers_and_graders.py` 的 `QueryRouter` 类

#### 7.2 文档相关性评分
- **技术点**:
  - LLM-based评分
  - 二进制评分: `yes` (相关) 或 `no` (不相关)
  - 逐文档评分和过滤
- **应用场景**: 过滤掉不相关的检索文档
- **关键代码位置**: `routers_and_graders.py` 的 `DocumentGrader` 类

#### 7.3 答案质量评分
- **技术点**:
  - LLM-based评分
  - 评估答案是否解决了问题
  - 二进制评分: `yes` (有用) 或 `no` (无用)
- **应用场景**: 验证生成答案的质量
- **关键代码位置**: `routers_and_graders.py` 的 `AnswerGrader` 类

#### 7.4 答案可回答性评分
- **技术点**:
  - 评估当前检索文档是否足够回答问题
  - 支持早期终止决策
- **应用场景**: 判断是否需要继续检索
- **关键代码位置**: `routers_and_graders.py` 的 `AnswerabilityGrader` 类

---

### 8. 幻觉检测层

#### 8.1 NLI模型检测
- **技术点**:
  - 模型: `cross-encoder/nli-deberta-v3-xsmall` (轻量级)
  - 自然语言推理 (Natural Language Inference)
  - 三种关系: `entailment` (蕴含), `contradiction` (矛盾), `neutral` (中立)
  - 逐句检测 + 最大蕴含策略
- **应用场景**: 检测生成内容是否与源文档一致
- **关键代码位置**: `hallucination_detector.py` 的 `NLIHallucinationDetector` 类

#### 8.2 Vectara检测模型
- **技术点**:
  - 模型: `vectara/hallucination_evaluation_model` (HHEM)
  - 专门训练的幻觉检测模型
  - 输出: `factuality_score`, `hallucination_score`
- **应用场景**: 高精度幻觉检测
- **关键代码位置**: `hallucination_detector.py` 的 `VectaraHallucinationDetector` 类

#### 8.3 混合检测
- **技术点**:
  - 结合Vectara和NLI模型
  - 投票机制: 多个模型结果综合判断
  - 置信度计算
- **应用场景**: 提供最可靠的幻觉检测
- **关键代码位置**: `hallucination_detector.py` 的 `HybridHallucinationDetector` 类

---

### 9. 查询优化层

#### 9.1 查询分解 (Query Decomposition)
- **技术点**:
  - LLM-based分解
  - 将复杂多跳问题分解为子问题序列
  - JSON格式输出: `{"sub_queries": [...]}`
- **应用场景**: 处理需要多步推理的复杂查询
- **关键代码位置**: `routers_and_graders.py` 的 `QueryDecomposer` 类

#### 9.2 查询重写 (Query Rewriting)
- **技术点**:
  - LLM-based重写
  - 基于上下文优化查询表述
  - 提取桥接实体并注入到下一查询
- **应用场景**:
  - 改进检索效果
  - 多跳检索中的查询优化
- **关键代码位置**: `routers_and_graders.py` 的 `QueryRewriter` 类

---

### 10. 知识图谱层 (GraphRAG)

#### 10.1 图谱构建
- **技术点**:
  - `NetworkX`: 图结构管理
  - 实体提取: 使用LLM从文档中提取实体
  - 关系提取: 提取实体间关系
  - 图谱持久化: JSON格式存储
- **应用场景**: 构建结构化知识图谱
- **关键代码位置**: `knowledge_graph.py` 的 `KnowledgeGraph` 类

#### 10.2 社区检测
- **技术点**:
  - `python-louvain`: Louvain社区检测算法
  - 其他算法: `greedy`, `label_propagation`
  - 社区摘要: 为每个社区生成摘要
- **应用场景**:
  - 发现知识图谱中的主题社区
  - 支持全局查询
- **关键代码位置**: `knowledge_graph.py` 的社区检测相关方法

#### 10.3 图谱检索
- **技术点**:
  - 本地查询: 基于图遍历 (最大跳数: 2)
  - 全局查询: 基于社区摘要
  - 实体链接: 将查询中的实体链接到图谱节点
- **应用场景**: 利用结构化知识进行检索
- **关键代码位置**: `graph_retriever.py`

---

### 11. 网络搜索层

#### 11.1 Tavily API
- **技术点**:
  - `tavily-python`: Tavily搜索API客户端
  - 实时网络搜索
  - 结果数量: `WEB_SEARCH_RESULTS_COUNT=3`
- **应用场景**: 获取最新信息和通用知识
- **关键代码位置**: `workflow_nodes.py` 的 `web_search()` 方法

---

### 12. 评估与监控层

#### 12.1 检索评估
- **技术点**:
  - **Precision@K**: 前K个结果中相关文档的比例
  - **Recall@K**: 前K个结果覆盖的相关文档比例
  - **MAP (Mean Average Precision)**: 平均精度均值
  - **MRR (Mean Reciprocal Rank)**: 平均倒数排名
  - **NDCG**: 归一化折损累积增益
  - **Latency**: 检索延迟
- **应用场景**: 评估检索系统性能
- **关键代码位置**: `retrieval_evaluation.py` 的 `RetrievalEvaluator` 类

#### 12.2 可视化
- **技术点**:
  - `matplotlib`: 绘制评估指标图表
  - `seaborn`: 统计可视化
  - `pandas`: 数据处理
- **应用场景**: 展示评估结果和性能分析

---

### 13. 异步处理层

#### 13.1 异步检索
- **技术点**:
  - `asyncio`: Python异步编程
  - `asimilarity_search()`: 异步相似度搜索
  - `ainvoke()`: 异步调用
  - 并发查询: `asyncio.gather()`
- **应用场景**:
  - 提高系统响应速度
  - 并发处理多个查询
- **关键代码位置**: `document_processor.py` 的 `async_enhanced_retrieve()` 方法

#### 13.2 线程池执行
- **技术点**:
  - `run_in_executor()`: 在线程池中执行CPU密集型任务
  - 重排任务异步化
- **应用场景**: 避免阻塞主事件循环

---

### 14. 配置管理层

#### 14.1 环境变量管理
- **技术点**:
  - `python-dotenv`: 加载.env文件
  - `getpass`: 安全输入API密钥
  - 环境变量验证
- **应用场景**: 安全管理API密钥和配置
- **关键代码位置**: `config.py` 的 `setup_environment()` 方法

#### 14.2 配置参数
- **技术点**:
  - 模型配置: `LOCAL_LLM`, `EMBEDDING_MODEL`
  - 分块配置: `CHUNK_SIZE`, `CHUNK_OVERLAP`
  - 向量库配置: `MILVUS_*` 参数
  - 功能开关: `ENABLE_GRAPHRAG`, `ENABLE_HYBRID_SEARCH`, `ENABLE_QUERY_EXPANSION`, `ENABLE_MULTIMODAL`
- **应用场景**: 集中管理系统配置

---

## 🔄 工作流节点详解

### 节点1: route_question
- **功能**: 智能路由决策
- **技术**: LLM-based路由
- **输出**: `"web_search"` 或 `"vectorstore"`

### 节点2: decompose_query
- **功能**: 查询分解
- **技术**: LLM-based分解
- **输出**: 子问题列表

### 节点3: retrieve
- **功能**: 文档检索
- **技术**:
  - 混合检索 (向量 + BM25)
  - 查询扩展
  - 多模态检索
  - 重排序
- **输出**: 检索到的文档列表

### 节点4: grade_documents
- **功能**: 文档相关性评分
- **技术**: LLM-based评分
- **输出**: 过滤后的相关文档

### 节点5: decide_to_generate
- **功能**: 决策是否生成答案
- **技术**:
  - 检查文档是否足够
  - 检查是否还有子查询
  - 早期终止判断
- **输出**: `"generate"`, `"prepare_next_query"`, `"transform_query"`, 或 `"web_search"`

### 节点6: prepare_next_query
- **功能**: 准备下一个子查询
- **技术**: 查询重写 + 桥接实体提取
- **输出**: 优化后的下一个查询

### 节点7: transform_query
- **功能**: 查询转换
- **技术**: LLM-based重写
- **输出**: 改进后的查询

### 节点8: generate
- **功能**: 生成答案
- **技术**: RAG链 (Prompt + LLM)
- **输出**: 生成的答案

### 节点9: grade_generation_v_documents_and_question
- **功能**: 答案质量检查
- **技术**:
- 幻觉检测
  - 答案质量评分
- **输出**: `"useful"`, `"not useful"`, 或 `"not supported"`

### 节点10: web_search
- **功能**: 网络搜索
- **技术**: Tavily API
- **输出**: 网络搜索结果

---

## 📊 性能优化技术

### 1. 索引优化
- **HNSW索引**: 高性能近似最近邻搜索
- **索引参数调优**: M=8, efConstruction=64
- **搜索参数调优**: ef=10

### 2. 检索优化
- **混合检索**: 结合语义和关键词匹配
- **查询扩展**: 多角度检索
- **重排序**: 精确排序Top-K结果

### 3. 异步处理
- **异步检索**: 提高并发性能
- **线程池**: CPU密集型任务异步化

### 4. 缓存机制
- **向量库持久化**: 避免重复向量化
- **文档去重**: 避免重复处理

---

## 🛡️ 质量保证机制

### 1. 多层验证
- **文档相关性评分**: 过滤不相关文档
- **答案质量评分**: 验证答案有用性
- **幻觉检测**: 确保答案基于源文档

### 2. 迭代改进
- **查询转换**: 改进检索效果
- **重试机制**: 最大重试次数限制
- **回退策略**: 网络搜索作为备选

### 3. 早期终止
- **答案可回答性检查**: 避免不必要的检索
- **多跳检索优化**: 提前终止已完成的任务

---

## 📦 依赖库总结

### 核心框架
- `langchain>=0.1.0`: LLM应用编排
- `langgraph>=0.0.40`: 工作流管理
- `langchain-community>=0.0.20`: 社区集成
- `langchain-ollama>=0.1.0`: Ollama集成

### 向量数据库
- `pymilvus[milvus_lite]>=2.4.2`: Milvus客户端

### 嵌入模型
- `sentence-transformers>=2.2.0`: 嵌入模型
- `transformers>=4.30.0`: Transformer模型

### 文档处理
- `tiktoken>=0.5.0`: Token编码
- `beautifulsoup4>=4.12.0`: HTML解析
- `rank-bm25>=0.2.2`: BM25检索

### 网络搜索
- `tavily-python>=0.3.0`: Tavily API

### 图处理
- `networkx>=3.1`: 图结构
- `python-louvain>=0.16`: 社区检测

### 评估与可视化
- `scikit-learn>=1.3.0`: 机器学习工具
- `matplotlib>=3.7.0`: 可视化
- `pandas>=2.0.0`: 数据处理

### 工具库
- `python-dotenv>=1.0.0`: 环境变量
- `pydantic>=2.0.0`: 数据验证
- `numpy>=1.24.0,<2.0`: 数值计算

---

## 🎯 核心技术亮点

1. **自适应路由**: 智能选择信息源
2. **混合检索**: 语义 + 关键词双重匹配
3. **多跳检索**: 支持复杂推理查询
4. **专业幻觉检测**: NLI + Vectara模型
5. **查询优化**: 分解 + 扩展 + 重写
6. **重排序**: CrossEncoder精确排序
7. **多模态支持**: 文本 + 图像检索
8. **异步处理**: 提高系统性能
9. **质量保证**: 多层验证机制
10. **GraphRAG**: 结构化知识检索

---

## 📈 系统性能指标

- **检索准确率**: Precision@3, Recall@3, MAP
- **响应延迟**: 检索延迟、生成延迟
- **幻觉检测准确率**: 85-95% (使用专业模型)
- **支持数据规模**: 百万级文档
- **并发处理**: 异步架构支持

---

## 🔮 技术演进方向

1. **更强大的嵌入模型**: 支持更大规模的嵌入
2. **更智能的路由**: 基于历史数据的路由优化
3. **实时学习**: 从用户反馈中学习
4. **多语言支持**: 扩展到更多语言
5. **分布式部署**: 支持大规模分布式部署

---

## 📝 总结

本项目实现了一个功能完整、技术先进的自适应RAG系统，涵盖了从文档处理、向量化、检索、重排序、生成到质量保证的完整技术栈。系统采用了多种先进技术，包括混合检索、多跳检索、专业幻觉检测、查询优化等，确保了高质量、高准确率的答案生成。