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 管道的開發者打造