# langchain_rag **Repository Path**: czhilong/langchain_rag ## Basic Information - **Project Name**: langchain_rag - **Description**: 基于langchain的rag系统 - **Primary Language**: Python - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 1 - **Created**: 2026-03-31 - **Last Updated**: 2026-03-31 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 智能文档分析助手 ## 项目概述 智能文档分析助手是一个基于大语言模型（LLM）和检索增强生成（RAG）技术的智能文档分析工具，能够帮助用户快速分析和理解各种类型的文档内容，提供精准的问答服务。 ### 核心功能 - **多格式文档支持**：支持 PDF、Word、CSV、TXT、Markdown 等多种文件格式 - **智能问答**：基于文档内容进行精准问答，提供引用来源 - **知识库管理**：支持上传、管理多个知识库文档 - **混合检索**：结合向量检索与 BM25Plus 关键词检索，提升召回效果 - **本地重排序**：使用 BGE-Reranker-Large 模型对检索结果进行重排序 - **动态权重**：根据查询类型自动调整语义检索与关键词检索的权重 - **查询扩展**：支持多查询扩展，丰富检索表达 - **句子窗口检索**：可选的句子窗口检索模式，提升上下文完整性 - **流式输出**：实时显示回答内容，提升用户体验 - **参数调节**：可调节生成长度、温度等参数，控制回答风格 - **日志系统**：支持配置化日志输出，便于调试和监控 - **现代化界面**：双栏布局设计，支持头像显示 - **自动深色模式**：跟随系统设置自动切换深色/浅色模式 ## 技术架构 ### 系统架构 ``` ┌─────────────────────────────────────────────────────────┐ │ 用户界面层 │ │ Gradio Web Interface (端口 7002) │ ├─────────────────────────────────────────────────────────┤ │ 应用逻辑层 │ │ langchain_rag.py (入口) ──────> ui_components.py (UI) │ ├─────────────────────────────────────────────────────────┤ │ 核心处理层 │ │ llm.py (RAG 逻辑、文档处理、模型调用) │ │ ├── BM25PlusRetriever (关键词检索) │ │ ├── LocalReranker (本地重排序) │ │ ├── SentenceWindowRetriever (句子窗口检索) │ │ └── QueryClassifier (查询类型分类) │ ├─────────────────────────────────────────────────────────┤ │ 存储层 │ │ Chroma 向量数据库 ──────> SQLite 记录管理 │ ├─────────────────────────────────────────────────────────┤ │ 模型层 │ │ DeepSeek LLM (API 调用) ──> BGE Embedding (本地) │ │ ──> BGE Reranker (本地) │ └─────────────────────────────────────────────────────────┘ ``` ### 技术栈 | 技术/库 | 用途 | 版本 | |----------------------|--------------------------------|----------| | Python | 编程语言 | 3.12+ | | LangChain | LLM 应用开发框架 | 0.2+ | | LangChain-OpenAI | DeepSeek LLM 集成 | | | LangChain-HuggingFace | 本地 Embedding 集成 | | | Gradio | Web 界面框架 | 6.10+ | | Chroma | 向量数据库 | 0.5+ | | BGE-Large-ZH | 中文文本嵌入模型（本地） | v1.5 | | BGE-Reranker-Large | 文档重排序模型（本地） | | | DeepSeek | 大语言模型（API 调用） | | ## 快速开始 ### 环境要求 - Python 3.12 或更高版本 - Windows、macOS 或 Linux 操作系统 - 至少 4GB 内存（推荐 8GB+） - DeepSeek API Key（从 https://platform.deepseek.com/ 获取） - 本地 Embedding 和 Reranker 模型（需手动下载，详见下方说明） **模型下载说明**： > 由于国内网络访问 HuggingFace 存在障碍，建议使用 ModelScope（魔搭社区）下载模型。项目中提供了下载脚本，位于 `download/` 目录。 ### 安装步骤 1. **克隆项目** ```bash git clone <项目地址> cd langchain_rag ``` 2. **创建虚拟环境** ```bash # Windows python -m venv .venv .venv\Scripts\activate # macOS/Linux python3 -m venv .venv source .venv/bin/activate ``` 3. **安装依赖** ```bash pip install -r requirements.txt ``` 4. **下载模型（重要）** > **注意**：由于网络原因，无法直接从 HuggingFace 下载模型。请使用 ModelScope（魔搭社区）下载。 ```bash # Embedding 模型（BAAI/bge-large-zh-v1.5） python download/download_embedding.py # Reranker 模型（BAAI/bge-reranker-large） python download/download_reranker.py ``` 模型默认下载到 `C:/sft/model/` 目录。如需修改下载路径，请编辑 `download_embedding.py` 或 `download_reranker.py` 中的 `local_dir` 参数。 5. **配置环境变量** 复制 `.env.example` 为 `.env`，或创建 `.env` 文件： ``` # DeepSeek LLM 配置（必需） deepseek_api_key=your_api_key_here deepseek_base_url=https://api.deepseek.com deepseek_model=deepseek-chat # 本地 Embedding 模型路径 local_embedding_model_path=C:/sft/model/BAAI/bge-large-zh-v1___5 # 本地 Reranker 模型路径 local_reranker_model_path=C:/sft/model/BAAI/bge-reranker-large # 日志配置：是否输出到文件（true/false） LOG_TO_FILE=true ``` 6. **启动应用** ```bash python langchain_rag.py ``` 应用启动后，在浏览器中访问 `http://127.0.0.1:7002` 即可使用。 ## 使用指南 ### 基本操作 1. **界面布局**：应用采用双栏布局，左侧为聊天区域，右侧为参数设置面板 2. **上传文档**：点击右侧 "📤 上传文档" 区域，选择要分析的文档 3. **选择知识库**：在 "📚 知识库" 下拉菜单中选择要使用的文档 4. **输入问题**：在底部文本框中输入您的问题，按 Enter 发送 5. **查看回答**：AI 回复会实时显示在聊天区域，带有头像标识 6. **调整参数**：可调节 "📏 最大生成长度" 和 "🌡️ 温度参数" 滑块 7. **清除历史**：点击 "🗑️ 清空对话" 按钮可清除聊天历史 8. **深色模式**：应用会根据操作系统设置自动切换深色/浅色模式 ### 日志查看 日志默认输出到控制台。如需输出到文件： ```bash # Linux/Mac export LOG_TO_FILE=true # Windows CMD set LOG_TO_FILE=true # Windows PowerShell $env:LOG_TO_FILE="true" ``` 日志文件会保存为 `app.log`。 ## 项目结构 ``` langchain_rag/ ├── chroma/ # 向量数据库存储目录 │ └── knowledge/ # 知识库文档存储 ├── download/ # 模型下载脚本 │ ├── download_embedding.py # 下载 Embedding 模型（ModelScope） │ └── download_reranker.py # 下载 Reranker 模型（ModelScope） ├── config.py # 项目配置 ├── langchain_rag.py # 主入口文件 ├── llm.py # LLM 核心实现 │ # - BatchedLocalEmbeddings: 批量嵌入封装 │ # - DocumentLoader: 文档加载与分块 │ # - MyKnowledge: 知识库管理 │ # - MyLLM: LLM 调用与 RAG 链 ├── ui_components.py # UI 界面组件 ├── bm25_plus_retriever.py # BM25Plus 关键词检索器 ├── parent_document_retriever.py # 句子窗口检索器 ├── score_normalizer.py # 分数归一化与查询类型分类 │ # - ScoreNormalizer: Min-Max/Z-Score 归一化 │ # - QueryClassifier: 查询类型分类 ├── local_reranker.py # 本地 BGE-Reranker 封装 ├── test_rag_retrieval.py # RAG 检索能力评估脚本 ├── requirements.txt # 依赖文件 ├── .env # 环境变量配置（不提交到 git） ├── .env.example # 环境变量配置模板 ├── CLAUDE.md # Claude Code 项目指南 └── README.md # 项目文档 ``` ### 核心文件说明 | 文件 | 功能描述 | |--------------------------|----------------------------------------------------| | config.py | 项目配置管理，包括 DeepSeek API、服务器、文件类型等配置 | | langchain_rag.py | 主入口文件，启动应用程序 | | llm.py | LLM 核心实现，包括 RAG 逻辑、文档处理、检索增强 | | ui_components.py | UI 界面组件，构建 Gradio 界面 | | bm25_plus_retriever.py | BM25Plus 检索器，改进的关键词检索算法 | | parent_document_retriever.py | 句子窗口检索器，支持子文档精匹配与父文档上下文返回 | | score_normalizer.py | 分数归一化工具和查询类型分类器 | | local_reranker.py | 本地 BGE-Reranker 模型封装 | ## 配置说明 ### 环境变量配置 | 环境变量 | 说明 | 示例值 | |--------------------------|----------------------|----------------------------------------| | deepseek_api_key | DeepSeek API 密钥 | sk-xxxx | | deepseek_base_url | DeepSeek API 地址 | https://api.deepseek.com | | deepseek_model | DeepSeek 模型名称 | deepseek-chat | | local_embedding_model_path | Embedding 模型路径 | C:/sft/model/BAAI/bge-large-zh-v1___5 | | local_reranker_model_path | Reranker 模型路径 | C:/sft/model/BAAI/bge-reranker-large | | LOG_TO_FILE | 是否输出日志到文件 | true / false | ### RAG 检索优化配置 | 配置项 | 说明 | 默认值 | |--------------------------|----------------------|--------------| | child_chunk_size | 句子窗口子文档大小 | 200 | | parent_chunk_size | 句子窗口父文档大小 | 800 | | use_sentence_window | 是否启用句子窗口检索 | true | | query_expansion_enabled | 是否启用查询扩展 | true | | query_expansion_num | 查询扩展子查询数量 | 3 | | dynamic_weight_enabled | 是否启用动态权重 | true | | default_vector_weight | 默认向量检索权重 | 0.5 | | default_bm25_weight | 默认 BM25 权重 | 0.5 | | bm25_k1 | BM25Plus k1 参数 | 1.5 | | bm25_b | BM25Plus b 参数 | 0.75 | | bm25_delta | BM25Plus delta 参数 | 1.0 | | semantic_weight | Reranker 语义权重 | 0.7 | | keyword_weight | Reranker 关键词权重 | 0.3 | ### 服务器配置 在 `config.py` 文件中可配置以下服务器参数： | 配置项 | 说明 | 默认值 | |-------------|-----------|--------------| | server_name | 服务器地址 | 127.0.0.1 | | server_port | 服务器端口 | 7002 | | share | 是否共享 | False | ## RAG 检索增强 ### 检索策略 本项目采用多层检索增强策略： 1. **混合检索**：结合向量检索（Chroma/MMR）和 BM25Plus 检索 - 向量检索权重：默认 70% - BM25Plus 权重：默认 30% - 可通过 `dynamic_weight_enabled` 开启动态权重模式 2. **MMR 检索**：使用最大边际相关性增加结果多样性 - 返回文档数：10 - 候选文档数：30 - 多样性参数：0.75 3. **句子窗口检索**（可选）： - 子文档大小：200 字符（精确匹配） - 父文档大小：800 字符（完整上下文） - 适用于需要更完整上下文理解的场景 4. **查询扩展**（可选）： - 使用 MultiQueryRetriever 生成多个子查询 - 分别检索后合并结果 - 提升检索的全面性 5. **重排序**：使用本地 BGE-Reranker 模型 - 计算语义相似度分数 - 计算 BM25Plus 关键词匹配分数 - 混合评分后排序 - 返回 Top-5 文档 6. **查询类型分类**：自动识别查询类型，动态调整检索权重 - FACTUAL（事实型）：偏重关键词检索（向量权重 0.3，关键词权重 0.7） - OPINION（观点型）：偏重语义检索（向量权重 0.7，关键词权重 0.3） - LIST（列表型）：均衡权重（向量权重 0.5，关键词权重 0.5） ### 文档处理 - **分块大小**：800 字符 - **重叠大小**：150 字符 - **分隔符**：["\n\n", "\n", "。", "；", "，", " ", ""] - **支持格式**：.doc, .docx, .csv, .txt, .pdf, .md ### 检索能力评估 项目包含 RAG 检索能力评估脚本 `test_rag_retrieval.py`，可评估以下指标： - **Hit@K**：Top-K 结果命中率 - **MRR**：平均倒数排名 - **NDCG**：归一化折损累计增益 - **查询类型分类准确率** 运行评估： ```bash python test_rag_retrieval.py ``` ### 评估结果（AI/ML 主题测试数据） | 指标 | 结果 | 说明 | |------|------|------| | 总查询数 | 21 | 涵盖机器学习、深度学习、NLP、计算机视觉等领域 | | Hit@1 | 95.24% | 首个结果命中的比例 | | Hit@3 | 100.00% | Top-3 结果命中的比例 | | Hit@5 | 100.00% | Top-5 结果命中的比例 | | MRR | 0.9762 | 平均倒数排名，越接近1越好 | | NDCG | 1.0159 | 归一化折损累计增益 | | 查询类型分类准确率 | 90.48% (19/21) | FACTUAL/OPINION/LIST 三分类准确率 | **评估结论**： - 检索系统在 Top-5 召回上表现优秀，达到 100% 命中 - 首个结果命中率达 95.24%，仅 1 个查询的首个结果不是最相关的 - MRR 和 NDCG 均接近最优值，表明排序质量良好 - 查询类型分类准确率提升至 90.48%，通过扩充 FACTUAL 类型关键词（工作原理类、解决问题类、训练评估方法类）实现 ## 性能优化 ### 内存优化 - **批量处理**：文档处理采用批量方式，减少内存占用 - **流式处理**：回答生成采用流式输出，降低内存峰值 - **历史记录限制**：默认限制最多保存 6 轮对话历史 ### 速度优化 - **MMR 检索**：平衡相关性和多样性，提高检索效率 - **混合检索权重**：优化向量检索和 BM25 的权重配比 - **并行处理**：使用 Gradio 的队列机制，支持并发处理多个请求 - **批量嵌入**：每次处理 5 个文本，减少模型调用次数 ## 常见问题 ### 1. 上传文档后无法在知识库中看到 **解决方案**： - 检查文档是否成功上传到 `chroma/knowledge/` 目录 - 刷新页面或重新启动应用 - 检查文档格式是否被支持 ### 2. 回答质量不佳 **解决方案**： - 确保选择了正确的知识库 - 尝试调整 "温度值" 参数，降低温度可提高回答准确性 - 确保 DeepSeek API 正常工作 - 确保文档内容清晰可辨 ### 3. 应用启动失败 **解决方案**： - 检查 DeepSeek API Key 是否正确配置 - 检查 `.env` 配置文件是否正确 - 检查依赖是否完全安装 - 检查端口 7002 是否已被占用 - 确保 Embedding 和 Reranker 模型路径正确 - 确保模型文件已下载（检查 `C:/sft/model/BAAI/` 目录） ### 4. 模型下载失败 **解决方案**： - 由于网络原因，无法从 HuggingFace 下载时，请使用 ModelScope（魔搭社区） - 运行 `python download/download_embedding.py` 下载 Embedding 模型 - 运行 `python download/download_reranker.py` 下载 Reranker 模型 - 如 ModelScope 下载缓慢，可尝试配置代理 ### 5. 回答速度较慢 **解决方案**： - 减少文档大小，拆分大型文档 - 调整 "最大生成长度" 参数，减少生成内容 - 考虑使用 GPU 加速 Embedding/Reranker 模型 - 检查网络连接（DeepSeek API 调用） ## 扩展与定制 ### 添加新模型 1. 在 `.env` 文件中修改 DeepSeek 模型配置 2. 修改 Embedding/Reranker 模型路径 3. 重启应用 ### 支持新文件格式 1. 在 `config.py` 中的 `__FILE_TYPES` 列表中添加新文件类型（需以点号开头，如 `.xlsx`） 2. 在 `llm.py` 的 `DocumentLoader` 类中添加对应的加载器 ### 自定义检索策略 可在以下位置修改检索策略： - `.env` 文件：修改 RAG 检索优化配置参数 - `llm.py` 的 `create_indexes` 函数：修改 MMR 参数、权重配比 - `llm.py` 的 `LocalRerankerCompressor` 类：修改重排序逻辑 - `score_normalizer.py` 的 `QueryClassifier` 类：修改查询类型关键词 ### 自定义日志 - 修改 `logging.basicConfig` 可调整日志格式和输出位置 - 设置 `LOG_TO_FILE=true` 可将日志输出到文件 ## 依赖管理 项目依赖详见 `requirements.txt` 文件，主要包括： - **LangChain**：大语言模型应用框架 - **LangChain-OpenAI**：DeepSeek 模型集成 - **LangChain-HuggingFace**：本地 Embedding 模型集成 - **Gradio**：Web 界面框架 - **Chroma**：向量数据库 - **Sentence-Transformers**：文本嵌入模型 - **Transformers**：模型推理框架 ## 安全注意事项 1. **API Key 保护**： - 不要将 `.env` 文件提交到版本控制系统 - 定期更换 DeepSeek API Key 2. **文档安全**： - 仅上传和处理可信文档 - 敏感文档应在使用后及时清理 3. **网络安全**： - 默认配置下，应用仅在本地访问（127.0.0.1:7002） - 如需远程访问，确保网络环境安全 ## 未来规划 - [ ] 支持更多文件格式（如 Excel、PPT 等） - [ ] 添加文档摘要功能 - [ ] 支持多语言文档处理 - [ ] 优化模型推理速度 - [ ] 添加用户认证系统 - [ ] 支持文档版本管理 - [ ] 集成更多 LLM 模型 - [ ] 添加批量问答功能 ## 贡献指南 欢迎对项目进行贡献！贡献方式包括： 1. **提交 Issue**：报告 bug 或提出新功能建议 2. **提交 PR**：修复 bug 或实现新功能 3. **改进文档**：完善项目文档和使用指南 4. **分享反馈**：提供使用体验和改进建议 ## 许可证 本项目采用 MIT 许可证，详见 LICENSE 文件。 ## 联系方式 如有问题或建议，可通过以下方式联系： - GitHub：https://gitee.com/likai179/langchain_rag --- **版本**：3.0.0 **最后更新**：2026-03-31 **版权所有**：© 2026 智能文档分析助手团队