Deeprepo

🚀 DeepRepo - 本地RAG引擎

DeepRepo 是一个生产级的 Python 库，支持在本地代码库上执行 RAG（检索增强生成），并支持多种 AI 供应商。

🚀 快速开始

安装

cd deeprepo_core
pip install -e .

详细的各供应商设置说明请参阅 INSTALLATION.md。

基本用法

from deeprepo import DeepRepoClient

# 使用 Ollama (免费，本地) 进行初始化 - 嵌入和大语言模型使用同一供应商
client = DeepRepoClient(provider_name="ollama")

# 或者为嵌入和大语言模型使用不同的供应商
# 示例：使用 OpenAI 进行嵌入，Anthropic 进行大语言模型
client = DeepRepoClient(
    embedding_provider_name="openai",
    llm_provider_name="anthropic"
)

# 摄入文档
result = client.ingest("/path/to/your/code")
print(f"已摄入 {result['chunks_processed']} 个块")

# 使用 RAG 进行查询
response = client.query("身份验证是如何工作的？")
print(response['answer'])
print(f"来源: {response['sources']}")

✨ 主要特性

• 纯 Python 实现：无需使用大型框架（如 LangChain/LlamaIndex），也无需外部向量数据库。
• 多 AI 供应商支持：支持 Ollama（本地）、HuggingFace、OpenAI、Anthropic 和 Gemini。
• MCP 服务器支持：可与 Cursor、Claude Desktop、Antigravity 等 MCP 客户端集成。
• 基于装饰器的插件系统：便于供应商注册和扩展。
• 向量存储：使用 NumPy 实现余弦相似度，并以 JSON 格式持久化。
• RESTful API：提供 FastAPI 服务，便于集成。
• 支持 Docker：可进行完整的容器化部署。

📦 安装指南

安装 MCP 依赖

pip install deeprepo[mcp]

启动 MCP 服务器

# 使用 CLI 命令
deeprepo-mcp

# 或者作为 Python 模块运行
python -m deeprepo.mcp.server

配置 Cursor

创建或编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "deeprepo": {
      "command": "python",
      "args": ["-m", "deeprepo.mcp.server"],
      "env": {
        "LLM_PROVIDER": "ollama"
      }
    }
  }
}

使用不同的供应商：

{
  "mcpServers": {
    "deeprepo": {
      "command": "python",
      "args": ["-m", "deeprepo.mcp.server"],
      "env": {
        "EMBEDDING_PROVIDER": "openai",
        "LLM_PROVIDER": "anthropic",
        "OPENAI_API_KEY": "sk-...",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

启动 FastAPI 服务器

export OPENAI_API_KEY=your-key  # 或者使用 Ollama（无需密钥）
uvicorn web_app.main:app --reload

Docker 部署

docker-compose up --build

服务将在 http://localhost:8000 上可用。

💻 使用示例

基础用法

# 使用 Ollama 进行初始化
client = DeepRepoClient(provider_name="ollama")

# 摄入文档
result = client.ingest("/path/to/your/code")
print(f"已摄入 {result['chunks_processed']} 个块")

# 使用 RAG 进行查询
response = client.query("身份验证是如何工作的？")
print(response['answer'])
print(f"来源: {response['sources']}")

高级用法

# 使用不同的供应商进行嵌入和大语言模型
client = DeepRepoClient(
    embedding_provider_name="openai",
    llm_provider_name="anthropic"
)

# 摄入文档
result = client.ingest("/path/to/your/code")
print(f"已摄入 {result['chunks_processed']} 个块")

# 使用 RAG 进行查询
response = client.query("身份验证是如何工作的？")
print(response['answer'])
print(f"来源: {response['sources']}")

📚 详细文档

支持的 AI 供应商

*免费套餐有使用限制

供应商示例

# 嵌入和大语言模型使用同一供应商
# Ollama（推荐 - 免费且无限制）
client = DeepRepoClient(provider_name="ollama")

# HuggingFace（免费套餐）
client = DeepRepoClient(provider_name="huggingface")

# OpenAI（付费，质量最佳）
client = DeepRepoClient(provider_name="openai")

# Anthropic（付费，推理能力出色）
# 注意：Anthropic 没有嵌入 API，因此需要与其他供应商配合使用
client = DeepRepoClient(
    embedding_provider_name="openai",  # 使用 OpenAI 进行嵌入
    llm_provider_name="anthropic"     # 使用 Anthropic 进行大语言模型
)

# Gemini（免费套餐，有使用限制）
client = DeepRepoClient(provider_name="gemini")

# 混合使用供应商
# 示例：使用免费的 HuggingFace 进行嵌入，付费的 OpenAI 进行大语言模型
client = DeepRepoClient(
    embedding_provider_name="huggingface",
    llm_provider_name="openai"
)

API 端点

API 示例

# 摄入文档
curl -X POST http://localhost:8000/ingest \
  -H "Content-Type: application/json" \
  -d '{"path": "/path/to/code"}'

# 查询
curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"query": "这段代码是做什么的？"}'

可用的 MCP 工具

详细的 MCP 配置请参阅 deeprepo_core/src/deeprepo/mcp/README.md。

配置

环境变量

切换供应商

# 嵌入和大语言模型使用同一供应商（向后兼容）
client = DeepRepoClient(
    provider_name="ollama",  # 或 "huggingface", "openai", "anthropic", "gemini"
    storage_path="vectors.json"
)

# 嵌入和大语言模型使用不同的供应商
client = DeepRepoClient(
    embedding_provider_name="openai",    # 嵌入供应商
    llm_provider_name="anthropic",      # 大语言模型供应商
    storage_path="vectors.json"
)

或者使用环境变量：

# 单一供应商（向后兼容）
export LLM_PROVIDER=ollama
python your_script.py

# 不同的供应商
export EMBEDDING_PROVIDER=openai
export LLM_PROVIDER=anthropic
python your_script.py

常见用例：

• 使用 Anthropic 进行大语言模型：由于 Anthropic 没有嵌入 API，建议与 OpenAI 或 HuggingFace 配合使用。
• 成本优化：使用免费的 HuggingFace 进行嵌入，付费的 OpenAI 进行大语言模型。
• 性能优化：使用快速的 OpenAI 进行嵌入，强大的 Anthropic 进行大语言模型。

测试

快速开始

# 运行所有单元测试（快速，无需 API 密钥）
pytest tests/unit/ -v

# 运行测试并生成覆盖率报告
pytest tests/unit/ --cov=deeprepo --cov-report=html

# 运行所有测试，包括集成测试
pytest tests/ -v

测试结构

• 单元测试 (tests/unit/) - 快速、独立，无外部依赖

  • test_storage.py - 向量存储和余弦相似度
  • test_ingestion.py - 文件扫描和文本分块
  • test_client.py - 客户端接口和初始化

• 集成测试 (tests/integration/) - 端到端测试

  • test_document.py - 文档处理流程
  • test_all_providers.py - 手动验证供应商

手动测试供应商

# 测试特定供应商
python tests/integration/test_all_providers.py ollama
python tests/integration/test_all_providers.py huggingface openai

详细的测试文档请参阅 tests/README.md。

开发

添加新的供应商

1. 在 src/deeprepo/providers/ 中创建一个新文件。
2. 实现 EmbeddingProvider 和 LLMProvider 接口。
3. 使用 @register_embedding 和 @register_llm 装饰器。
4. 供应商将自动被发现！

示例：

from deeprepo.interfaces import EmbeddingProvider, LLMProvider
from deeprepo.registry import register_embedding, register_llm

@register_embedding("my_provider")
class MyEmbeddingProvider(EmbeddingProvider):
    def embed(self, text: str) -> list[float]:
        # 你的实现
        pass

@register_llm("my_provider")
class MyLLM(LLMProvider):
    def generate(self, prompt: str, context: str = None) -> str:
        # 你的实现
        pass

🔧 技术细节

架构

deeprepo_core/
├── src/deeprepo/
│   ├── client.py       # 主门面
│   ├── storage.py      # 向量存储 (JSON + NumPy)
│   ├── ingestion.py    # 文件扫描和分块
│   ├── interfaces.py   # 抽象基类
│   ├── registry.py     # 基于装饰器的注册表
│   ├── mcp/            # 用于 AI 助手的 MCP 服务器
│   │   ├── server.py       # FastMCP 服务器
│   │   └── README.md       # MCP 文档
│   └── providers/
│       ├── ollama_v.py      # Ollama (本地，免费)
│       ├── huggingface_v.py # HuggingFace (云，免费)
│       ├── openai_v.py      # OpenAI (付费)
│       ├── anthropic_v.py   # Anthropic (付费)
│       └── gemini_v.py      # Gemini (免费套餐)

设计模式

• 仓库模式：VectorStore 将存储与应用逻辑解耦。
• 策略模式：LLMProvider 和 EmbeddingProvider 抽象接口。
• 注册表模式：@register_llm 装饰器用于动态发现供应商。
• 单例模式：FastAPI 在启动时加载一次客户端。

📄 许可证

本项目采用 MIT 许可证，详细信息请参阅 LICENSE 文件。

贡献

欢迎贡献代码！请随时提交拉取请求。

支持

如有问题、疑问或功能请求，请在 GitHub 上提交问题。

为希望完全控制其 RAG 管道的开发者打造