Skip to content

v0.2.0

Choose a tag to compare

View all tags
@leonyangdev leonyangdev released this 06 Nov 15:17
· 12 commits to main since this release
stage_02
03a1841

📦 v0.2.0 - RAG 知识库模块完整实现

🎯 版本概述

v0.2.0 版本完成了 第 2 阶段：RAG 知识库模块（向量库 + Retrievers + RAG Agent） 的全部开发，实现了一个功能完整、生产可用的 RAG（Retrieval-Augmented Generation）系统。

✨ 核心特性

1. 📄 多格式文档加载系统

  • 支持 5 种文档格式：PDF、Markdown、TXT、HTML、JSON
  • 单文件加载和目录批量加载
  • 自动格式检测和元数据提取
  • 完善的错误处理机制

2. ✂️ 智能文本分块

  • 4 种分块策略：
    • RecursiveCharacterTextSplitter（递归字符分块，推荐）
    • CharacterTextSplitter（简单字符分块）
    • MarkdownTextSplitter（Markdown 专用）
    • TokenTextSplitter（Token 分块）
  • 可配置的分块参数（chunk_size、chunk_overlap）
  • 分块统计和分析功能

3. 🔢 向量化与向量存储

  • OpenAI Embeddings 封装（text-embedding-3-small/large）
  • FAISS 高性能向量库支持
  • InMemoryVectorStore 支持
  • 向量库的创建、保存、加载、更新
  • 成本估算功能

4. 🗂️ 索引管理系统

  • 统一的索引管理接口（IndexManager）
  • 索引的 CRUD 操作
  • JSON 格式的元数据管理
  • 索引列表和统计信息
  • 智能增量更新：自动跟踪已索引文件，仅处理新文档

5. 🔍 多策略检索器

  • 3 种检索策略：
    • Similarity（相似度检索）
    • MMR（最大边际相关性）
    • Similarity Score Threshold（阈值过滤）
  • 检索器封装为 LangChain Tool
  • 检索结果测试和验证

6. 🤖 RAG Agent 智能问答

  • 基于 LangChain 1.0.3 最新 API（create_agent）
  • 集成 retriever tool 实现知识库问答
  • 支持流式和非流式输出
  • 自动引用来源文档
  • 对话历史支持
  • 专用的 RAG 提示词优化

7. 🌐 HTTP API 接口

  • 完整的 RESTful API（FastAPI）
  • 8 个核心端点：
    • POST /rag/index - 创建索引
    • GET /rag/index/list - 列出索引
    • GET /rag/index/{name} - 获取索引信息
    • DELETE /rag/index/{name} - 删除索引
    • POST /rag/query - RAG 查询
    • POST /rag/query/stream - 流式查询
    • POST /rag/search - 纯检索
    • GET /rag/health - 健康检查
  • Pydantic 模型验证
  • SSE 流式响应支持
  • 自动生成 Swagger UI 文档

8. 💻 CLI 命令行工具

  • 基于 Click 框架的友好命令行界面
  • Rich 库美化输出（表格、进度条、彩色文本）
  • 完整的命令集：
    • index create/list/info/delete - 索引管理
    • query - RAG 查询
    • search - 纯检索
    • interactive - 交互式问答模式
  • 详细的帮助信息和错误提示

9. 🔄 智能索引更新工具

  • update_index.py 脚本实现智能增量更新
  • 自动跟踪已索引文件（tracked_files.json）
  • 仅处理新增文档，避免重复索引
  • 支持 --rebuild 选项强制重建索引
  • 详细的更新日志和统计信息

🛠️ 技术实现

LangChain 1.0.3 兼容性

  • ✅ 使用最新的 create_agent API 替代已弃用的 create_tool_calling_agent
  • ✅ 正确的导入路径：langchain_core.tools.retriever
  • ✅ Agent 输入格式适配：{"messages": [...]}
  • ✅ 流式输出处理优化

模块化架构

backend/rag/
├── loaders.py          # 文档加载器（~350 行）
├── splitters.py        # 文本分块器（~350 行）
├── embeddings.py       # Embeddings 封装（~250 行）
├── vector_stores.py    # 向量存储（~350 行）
├── index_manager.py    # 索引管理器（~400 行）
├── retrievers.py       # 检索器（~350 行）
└── rag_agent.py        # RAG Agent（~350 行）

代码质量

  • 详细的中文注释（每个函数、类都有完整文档字符串）
  • 遵循 PEP 8 代码规范
  • 完整的类型提示
  • 多层次的异常处理
  • 详细的日志记录（loguru）

📦 新增依赖

langchain-text-splitters>=0.3.5
faiss-cpu>=1.9.0
pypdf>=5.1.0
unstructured>=0.16.14
markdown>=3.7
beautifulsoup4>=4.12.3
lxml>=5.3.0
python-multipart>=0.0.20
aiofiles>=24.1.0
click>=8.1.8
rich>=13.9.4

📖 文档更新

新增文档

  • docs/stage_02/STAGE2_PLAN.md - 详细的开发计划
  • docs/stage_02/README.md - 完整的使用指南（517 行）
  • docs/stage_02/LEARNING_SUMMARY.md - 学习总结和知识点
  • docs/stage_02/STAGE2_COMPLETION.md - 完成报告（490 行）
  • docs/stage_02/LANGCHAIN_1.0.3_FIXES.md - API 兼容性修复说明
  • docs/stage_02/QUICK_FIX.md - 快速修复指南
  • docs/stage_02/INDEX_UPDATE_GUIDE.md - 索引更新详细指南（731 行）
  • docs/stage_02/FINAL_FIX_SUMMARY.md - 最终修复总结

测试文档

  • data/documents/test/machine_learning.md - 机器学习基础（~3000 字）
  • data/documents/test/deep_learning.md - 深度学习入门（~4000 字）
  • data/documents/test/python_basics.txt - Python 编程基础（~3000 字）
  • data/documents/test/neural_networks.md - 神经网络介绍

🚀 快速开始

# 1. 安装依赖
cd backend
pip install -r requirements.txt

# 2. 配置环境变量
echo "OPENAI_API_KEY=your_key_here" > .env

# 3. 创建索引
python scripts/rag_cli.py index create test_index data/documents/test

# 4. 查询
python scripts/rag_cli.py query test_index "什么是机器学习？"

# 5. 交互模式
python scripts/rag_cli.py interactive test_index

# 6. 启动 API 服务器
python api/http_server.py

🧪 测试验证

  • ✅ 文档加载正常（PDF、Markdown、TXT、HTML、JSON）
  • ✅ 文本分块正常（4 种策略）
  • ✅ Embeddings 创建成功
  • ✅ 向量库创建、保存、加载成功
  • ✅ 索引管理功能完整
  • ✅ 检索功能准确
  • ✅ RAG Agent 回答准确并引用来源
  • ✅ API 接口正常（包括流式输出）
  • ✅ CLI 工具功能完整
  • ✅ 智能增量更新正常

🎓 学习要点

LangChain 核心概念

  • Document Loaders - 文档加载和元数据管理
  • Text Splitters - 文本分块策略和参数调优
  • Embeddings - 向量化模型的选择和使用
  • Vector Stores - 向量数据库的操作和持久化
  • Retrievers - 检索策略和优化
  • RAG Pattern - RAG 模式的实现和最佳实践
  • Tool Integration - 将 Retriever 集成到 Agent

RAG 最佳实践

  • 文本分块策略选择（chunk_size: 1000, overlap: 200）
  • Embedding 模型选择（small vs large）
  • 检索优化（相似度搜索 vs MMR vs 阈值过滤）
  • 上下文管理（控制检索到的文档数量）
  • 来源引用（在回答中引用来源文档）
  • 性能优化（批处理、FAISS 索引）

🐛 已知问题修复

  1. LangChain 1.0.3 API 兼容性

    • 修复 create_tool_calling_agent 已弃用问题
    • 修复 langchain.tools.retriever 导入路径问题
    • 修复 Agent 输入格式问题

  2. 依赖管理

    • 修复 unstructured 模块导入问题
    • 修复 faiss-cpu 安装问题
    • 修复 rich 和 click 缺失问题

  3. Pydantic 类型错误

    • 修复 IndexInfo 模型中 any 类型定义错误

📊 代码统计

  • 新增代码：约 3,500 行（不含注释和空行）
  • 文档：约 2,500 行
  • 测试数据：4 个文档，约 13,000 字
  • 新增文件：20+ 个

🔗 相关链接

🙏 致谢

感谢 LangChain 社区提供的优秀框架和文档！

完整变更日志: v0.1.0...v0.2.0

Assets 2
Loading