RAG Learn - 本地向量知识库系统

RAG Learn 是一个完整的本地向量知识库实现，基于 RAG（检索增强生成）技术，支持多种文档格式，提供强大的语义搜索和智能问答功能。

✨ 特性

🔍 强大的语义搜索：基于 Sentence Transformers 的高质量文本嵌入
📚 多格式文档支持：PDF、DOCX、XLSX、CSV、JSON、TXT、Markdown 等
🏠 完全本地化：数据安全，无需云服务
🤖 智能问答：集成 Ollama 本地大语言模型
⚡ 高性能向量存储：基于 ChromaDB 的持久化向量数据库
🎯 灵活配置：支持自定义模型、参数和存储配置
🖥️ 友好界面：提供命令行工具和 Python API
🧪 完整测试：包含单元测试和集成测试

🚀 快速开始

环境要求

Python 3.11+
uv 包管理器
Ollama (用于本地 LLM)

安装

克隆项目

git clone <repository-url>
cd rag_learn

使用 uv 安装依赖

# 安装项目依赖
uv sync

# 激活虚拟环境
source .venv/bin/activate  # Linux/macOS
# 或
.venv\Scripts\activate  # Windows

# 如果 uv 不可用，可以使用 pip
pip install -e .

安装 Ollama 并下载模型

# 安装 Ollama (请参考官方文档)
curl -fsSL https://ollama.com/install.sh | sh

# 下载推荐模型 (DeepSeek - 高质量中文支持)
ollama pull deepseek-r1:8b

# 或使用 Llama2
ollama pull llama2

初始化配置

# 创建默认配置文件
rag-learn init

这将在 ~/.rag_learn/config.yaml 创建配置文件，您可以根据需要修改。

📖 使用方法

命令行工具

1. 添加文档

# 添加单个文件
rag-learn add /path/to/document.pdf

# 添加整个目录
rag-learn add /path/to/documents/ --recursive

# 指定文件类型
rag-learn add /path/to/docs/ --patterns "*.pdf,*.txt"

2. 搜索文档

# 搜索相关文档
rag-learn search "机器学习的基本概念"

# 自定义搜索参数
rag-learn search "深度学习" --k 10 --threshold 0.8

3. 智能问答

# 交互式问答（推荐）
rag-learn query

# 单次问答
rag-learn query "什么是人工智能？"

4. 💬 智能聊天 (新功能)

# 启动交互式聊天模式
rag-learn chat

# 自定义聊天参数
rag-learn chat --max-turns 100 --save-history

# 使用 DeepSeek 配置
rag-learn --config examples/deepseek_config.yaml chat

聊天功能特性：

🧠 记忆对话: 记住上下文，支持连续对话
📚 知识融合: 自动检索相关文档内容
🎨 美观界面: 丰富的视觉反馈和状态显示
💡 智能回答: 基于 DeepSeek 等先进模型
⌨️ 便捷命令: help, clear, history, stats 等内置命令

5. 管理知识库

# 查看统计信息
rag-learn stats

# 列出所有文档来源
rag-learn list-sources

# 导出知识库
rag-learn export knowledge_base.json

# 清空知识库
rag-learn reset

Python API

基本使用

from rag_learn import KnowledgeBase, Config

# 创建知识库
kb = KnowledgeBase()

# 添加文档
kb.add_document("path/to/document.pdf")
kb.add_directory("path/to/documents/")

# 添加文本
kb.add_text("这是一段示例文本", metadata={"source": "用户输入"})

# 搜索
results = kb.search("查询内容", k=5)
for text, score, metadata in results:
    print(f"相似度: {score:.3f}")
    print(f"内容: {text[:100]}...")

# 智能问答
result = kb.query("您的问题？")
print(f"回答: {result['answer']}")
print(f"置信度: {result['confidence']:.3f}")

高级配置

from rag_learn import Config, KnowledgeBase

# 自定义配置
config = Config()
config.embedding.model_name = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
config.vector_store.persist_directory = "./my_vector_db"
config.llm.model_name = "llama2:13b"
config.text_splitter.chunk_size = 1500

# 创建知识库
kb = KnowledgeBase(config)

⚙️ 配置选项

配置文件示例（~/.rag_learn/config.yaml）：

# 嵌入模型配置
embedding:
  model_name: "sentence-transformers/all-MiniLM-L6-v2"
  device: "cpu"  # cpu, cuda, mps
  max_seq_length: 512

# 向量存储配置
vector_store:
  persist_directory: "./vector_db"
  collection_name: "knowledge_base"
  distance_function: "cosine"

# 文本分割配置
text_splitter:
  chunk_size: 1000
  chunk_overlap: 200
  separators: ["\n\n", "\n", " ", ""]

# 语言模型配置
llm:
  model_name: "llama2"
  base_url: "http://localhost:11434"
  temperature: 0.7
  max_tokens: 2048

# 搜索配置
max_search_results: 5
search_score_threshold: 0.7

📁 项目结构

rag_learn/
├── rag_learn/              # 主包
│   ├── __init__.py         # 包初始化
│   ├── config.py           # 配置管理
│   ├── embeddings.py       # 嵌入模型
│   ├── vector_store.py     # 向量存储
│   ├── document_loader.py  # 文档加载
│   ├── knowledge_base.py   # 知识库核心
│   └── cli.py             # 命令行界面
├── examples/              # 示例代码
│   ├── basic_usage.py     # 基本使用示例
│   ├── document_processing.py  # 文档处理示例
│   └── config_example.yaml     # 配置示例
├── tests/                 # 测试文件
├── docs/                  # 文档目录
├── main.py               # 主入口
├── pyproject.toml        # 项目配置
└── README.md            # 本文件

🔧 开发

安装开发依赖

uv sync --dev

运行测试

# 运行所有测试
pytest

# 运行特定测试
pytest tests/test_config.py

# 运行测试并显示覆盖率
pytest --cov=rag_learn

代码格式化

# 格式化代码
black rag_learn/ tests/ examples/

# 检查代码风格
flake8 rag_learn/

# 类型检查
mypy rag_learn/

📚 示例

示例 1：基本文档问答

from rag_learn import KnowledgeBase

# 创建知识库并添加文档
kb = KnowledgeBase()
kb.add_document("research_paper.pdf")

# 问答
result = kb.query("这篇论文的主要贡献是什么？")
print(result['answer'])

示例 2：多文档知识库

from rag_learn import KnowledgeBase, Config

# 配置更大的块大小以处理长文档
config = Config()
config.text_splitter.chunk_size = 1500
config.text_splitter.chunk_overlap = 300

kb = KnowledgeBase(config)

# 添加整个文档目录
kb.add_directory("./documents/", recursive=True)

# 交互式查询循环
while True:
    question = input("请输入您的问题 (输入 'quit' 退出): ")
    if question.lower() == 'quit':
        break
    
    result = kb.query(question)
    print(f"\n回答: {result['answer']}\n")
    print(f"置信度: {result['confidence']:.3f}\n")

示例 3：自定义元数据和过滤

# 添加带有元数据的文档
kb.add_document(
    "financial_report.pdf", 
    metadata={"category": "finance", "year": 2023}
)

# 基于元数据过滤搜索
results = kb.search(
    "营收增长", 
    filter_metadata={"category": "finance"}
)

🤝 贡献

欢迎贡献代码！请遵循以下步骤：

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

贡献指南

确保所有测试通过
添加新功能时请包含测试
遵循现有的代码风格
更新相关文档

📝 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

LangChain - 强大的语言模型应用开发框架
ChromaDB - 高性能向量数据库
Sentence Transformers - 优秀的文本嵌入模型
Ollama - 本地大语言模型运行平台
Click - 命令行界面框架
Rich - 美观的终端输出

📞 支持

如果您遇到问题或有建议，请：

查看故障排除指南
运行验证脚本：python verify_setup.py
查看 Issues 页面
创建新的 Issue
参考示例代码和测试用例

🔄 更新日志

v0.1.0

初始版本发布
基本的RAG功能实现
多格式文档支持
命令行工具
完整的测试覆盖

RAG Learn - 让本地知识库更智能！ 🚀

leoomo/rag_learn