DocRAG-人工智能文档RAG系统
一个轻量级的、可安装的Python包，通过MCP（模型上下文协议）服务器提供RAG（检索增强生成）对技术文档的访问。这使LLM能够按需搜索和检索相关文档。
特性
- 🚀 带有CLI和MCP服务器的单点安装包
- 📚 基于项目的文档集合（BrightSign、Venafi、Qumu、web框架）
- 🔍 使用LanceDB高效嵌入的本地矢量数据库
- 📥 从本地文件或抓取的来源轻松获取文档
- 🤖 设计用于通过MCP与Claude Code一起使用
安装
先决条件
- Python 3.10+
- pipx（推荐）或pip
- git（用于更新）
推荐：使用pipx进行全局安装
# Install globally with pipx in editable mode (keeps dependencies isolated)
pipx install -e /opt/claude-ops/doc-rag
# Verify installation
docrag --help
# Optional: Install Playwright browsers (for scraping)
pipx runpip docrag install playwright
pipx run --spec docrag playwright install chromium注： 这 -e 标志以“可编辑”模式安装，这意味着对源代码的更改会立即反映出来，而无需重新安装。
替代方案：从源代码安装（开发）
# Clone or navigate to the project directory
cd /opt/claude-ops/doc-rag
# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate
# Install in development mode
pip install -e ".[dev]"
# Install Playwright browsers (for scraping)
playwright install chromium更新DocRAG
选项1：使用更新脚本（推荐）
cd /opt/claude-ops/doc-rag
./update.sh此脚本将：
- 从git中提取最新更改
- 检测您的安装方法（pipx或pip）
- 仅在必要时重新安装（不可编辑的安装）
- 自动处理可编辑的安装
选项2：使用Make
cd /opt/claude-ops/doc-rag
make update选项3：手动更新
对于 可编辑安装 （已安装 -e):
cd /opt/claude-ops/doc-rag
git pull origin main
# No reinstall needed - changes are already active!对于 定期安装 （未安装 -e):
cd /opt/claude-ops/doc-rag
git pull origin main
pipx uninstall docrag && pipx install -e .
# or for pip: pip install -e . --force-reinstall验证更新
# Check git status
cd /opt/claude-ops/doc-rag
git log -1 --oneline
# Test the installation
docrag --version
docrag --help快速开始
1.初始化DocRAG
docrag init这将在以下位置创建配置目录 ~/.docrag/ 具有以下结构：
~/.docrag/
├── config.json # Global configuration
├── collections/ # Documentation collections
└── vectordb/ # LanceDB storage2.添加文档集合
# Add documentation from a local directory
docrag add brightsign --source /path/to/brightsign/docs --description "BrightSign player documentation"
# Or add without source initially
docrag add venafi --description "Venafi TPP API documentation"3.列出收藏
docrag list4.搜索文档（CLI测试）
# Search across all active collections
docrag search "how to initialize the player"
# Search a specific collection
docrag search "authentication methods" --collection venafi --limit 105.启动MCP服务器
docrag serve服务器将在stdio上监听来自Claude Code的连接。
CLI命令
docrag init
初始化DocRAG配置目录。
docrag add
添加新的文档集合。
选项：
-s, --source PATH-包含文档的源目录-d, --description TEXT-藏品描述
例子：
docrag add qumu --source ~/docs/qumu --description "Qumu video platform docs"docrag list
列出所有文档集合及其状态。
docrag update
用新文档更新现有集合。
例子：
docrag update brightsign ~/docs/brightsign/updateddocrag remove
删除文档集合（确认后）。
docrag search
从CLI中搜索文档以进行测试。
选项：
-c, --collection TEXT-要搜索的特定集合-l, --limit INTEGER-结果数（默认值：5）
例子：
docrag search "websocket connection" --collection brightsigndocrag serve
启动MCP服务器以进行Claude Code集成。
docrag scrape
从网站上删除文档。
选项：
-o, --output PATH-输出目录（必填）--smart, --use-crawl4ai-使用AI驱动的Crawl4AI铲运机（推荐）--no-llm-禁用LLM提取（比基本提取更快，更好）--llm-provider TEXT-LLM提供程序（默认：openai/gpt-4o-mini）--playwright-使用Playwright制作动态内容（基本刮刀）--max-pages INTEGER-要抓取的最大页面数（默认值：1000）
示例：
# Basic scraping
docrag scrape https://docs.example.com --output ./docs
# Smart scraping with AI (recommended)
docrag scrape https://docs.example.com --output ./docs --smart
# Smart scraping without LLM (faster, no API key needed)
docrag scrape https://docs.example.com --output ./docs --smart --no-llm
# Limit pages
docrag scrape https://docs.example.com --output ./docs --max-pages 100智能刮擦功能：
- ✨ 基于AI的内容提取
- 🎯 自动删除导航和样板
- 📊 更好地处理复杂的布局
- 🧠 文档结构的语义理解
- ⚡ 比基本刮擦更快、更准确
要启用智能抓取，请执行以下操作：
# Install Crawl4AI
pipx inject docrag crawl4ai
# Optional: Set OpenAI API key for LLM-powered extraction
export OPENAI_API_KEY='your-key-here'使用Claude代码
1.配置克劳德代码MCP设置
将DocRAG添加到您的Claude Code MCP配置中(~/.config/claude-code/mcp_settings.json 或类似）：
{
"mcpServers": {
"docrag": {
"command": "docrag",
"args": ["serve"],
"env": {}
}
}
}如果使用完整路径：
{
"mcpServers": {
"docrag": {
"command": "/home/claude-admin/.local/bin/docrag",
"args": ["serve"],
"env": {}
}
}
}2.重新启动克劳德代码
添加配置后，重新启动Claude Code以加载MCP服务器。
3.在克劳德代码中使用
一旦连接，Claude Code可以使用两个工具：
search_docs：搜索索引文档集
Query: "how to handle authentication in BrightSign"
Collection: (optional) "brightsign"
Limit: (optional) 5list_collections：列出所有可用的文档集合
Claude在处理需要文档访问权限的项目时会自动使用这些工具。
建筑
核心组件
- 配置管理器 (
config.py)-管理配置和收集元数据 - 嵌入式生成器 (
embeddings.py)-使用句子变换器生成嵌入 - 矢量数据库 (
vectordb.py)LanceDB包装器，用于矢量存储和搜索 - 文档索引器 (
indexer.py)-智能文档分块和索引 - DocRAG服务器 (
server.py)-MCP服务器实施 - 命令行界面 (
cli.py)-命令行界面
技术栈
- MCP框架：官方Anthropic MCP包
- 向量数据库：LanceDB（轻量级、基于文件、高性能）
- 嵌入：全MiniLM-L6-v2型号的句子转换器（384调光，快速，本地）
- 文本处理：用于智能分块的langchain文本拆分器
- 命令行界面：单击以获取用户友好的命令
- Web剪贴：剧作家+美女搜刮4
数据结构
~/.docrag/
├── config.json # Global configuration
│ └── {
│ "active_collections": ["brightsign", "venafi"],
│ "embedding_model": "sentence-transformers/all-MiniLM-L6-v2",
│ "chunk_size": 512,
│ "chunk_overlap": 50
│ }
├── collections/
│ ├── brightsign/
│ │ ├── metadata.json # Collection metadata
│ │ └── source_docs/ # Original documents
│ ├── venafi/
│ └── qumu/
└── vectordb/
└── lancedb/ # Vector storage (one table per collection)配置
全局配置存储在 ~/.docrag/config.json:
{
"active_collections": ["brightsign", "venafi"],
"embedding_model": "sentence-transformers/all-MiniLM-L6-v2",
"chunk_size": 512,
"chunk_overlap": 50
}集合元数据存储在 ~/.docrag/collections//metadata.json:
{
"name": "brightsign",
"source_type": "local",
"source_path": "/path/to/docs",
"created_at": "2025-10-28T10:00:00",
"updated_at": "2025-10-28T10:00:00",
"doc_count": 150,
"description": "BrightSign player documentation"
}发展
项目结构
docrag/
├── docrag/
│ ├── __init__.py
│ ├── cli.py # CLI commands
│ ├── server.py # MCP server
│ ├── indexer.py # Document indexing
│ ├── vectordb.py # Vector database
│ ├── embeddings.py # Embeddings
│ ├── config.py # Configuration
│ └── scrapers/ # Web scrapers
│ ├── __init__.py
│ ├── base.py
│ └── generic.py
├── tests/
├── pyproject.toml
├── README.md
└── DOCRAG_MVP_BUILD_GUIDE.md运行测试
# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest代码格式化
# Format with black
black docrag/
# Lint with ruff
ruff check docrag/故障排除
“DocRAG未初始化”
跑 docrag init 首先创建配置目录。
“未找到收藏”
添加一个收藏 docrag add --source .
“模型下载失败”
第一次运行DocRAG时，它将下载句子转换器模型（~100MB）。确保你有互联网连接。
“未安装剧作家”
如果使用刮刀，请运行 playwright install chromium.
未来的增强功能
- \[\]Web scraper CLI命令
- \[\]支持更多文件类型（PDF、HTML、RST）
- \[\]增量索引（仅索引更改的文件）
- \[\]收款激活/停用
- \[\]收集统计数据和健康检查
- \[\]进出口收款
- \[\]集合的云同步
- \[\]高级搜索筛选器
许可证
麻省理工学院
作者
Ryan-专为家庭实验室和Claude Code集成而构建