Spaces:

ahaahaaha
/

adaptive_rag

Paused

App Files Files Community

adaptive_rag / README.md

lanny xu

Force rebuild: Change Python version and metadata

05e46dd 10 days ago

preview code

raw

history blame contribute delete

18.3 kB

metadata

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: 数值计算

🎯 核心技术亮点

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

📈 系统性能指标

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

🔮 技术演进方向

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

📝 总结

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