Darwin RAG

Darwin RAG

在自己的设备上私密地搜索自己的文档，适用于任何 AI Agent。

Darwin 是一款本地优先的 RAG 引擎，可摄取文档，使用 BM25 和稠密嵌入为文档建立索引，并通过 MCP 服务提供搜索功能。将 Claude、Cursor 或任何 MCP 客户端连接到它，Agent 就能搜索你的 PDF、笔记、电子表格和网页，而无需将它们发送到云端索引。

初次设置时需要联网下载模型。之后，搜索和索引都可完全离线运行。

• 摄取：PDF、Markdown、HTML、图片（OCR）、CSV、Excel、ODS、URL
• 索引：结合 BM25 关键词和稠密嵌入的混合索引，支持可配置的分块策略
• 搜索：支持混合、语义或关键词检索，并提供重排、多样性重排和结构惩罚
• 生成：通过 LiteLLM（OpenAI、Anthropic、Gemini 等）合成由 LLM 支持的答案
• 可观测性：结构化日志，包含可通过 MCP 查询的会话历史
• 隔离：支持多个独立存储，实现租户／项目隔离
• 部署：支持 stdio（AI Agent 子进程）、SSE 或 Streamable HTTP；可用于 Docker
• 本地优先：所有操作均在本地运行，设置完成后可完全离线使用

由 BrightDotDev 构建。

---

为什么选择 Darwin？

• 默认保护隐私。 你的文档会留在自己的设备上。
• 适配你的 Agent。 标准 MCP 服务：适用于 Claude Desktop、Cursor 和其他 MCP 客户端。
• 按问题选择合适的搜索方式。 精确匹配用关键词搜索，理解含义用语义搜索，不确定时用混合搜索。
• 轻松起步。 required 预设只会下载一个嵌入模型。

---

快速开始

1. 安装

pip install darwin-rag

2. 设置模型

# Interactive: detects hardware, pick your models
darwin-admin setup interactive

# Or one-shot (embedding-only, no prompts)
darwin-admin setup --preset required

3. 启动 MCP 服务并连接

# stdio mode: for AI agent subprocess (Claude Desktop, Cursor, etc.)
darwin mcp

# Or HTTP mode: for remote clients
darwin mcp --http --port 8765

配置 MCP 客户端：

{
  "mcpServers": {
    "darwin": {
      "command": "darwin",
      "args": ["mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-..."  // At least one LLM provider key
      }
    }
  }
}

或自动生成配置：

darwin config claude          # Claude Desktop config
darwin config cursor          # Cursor config
darwin config all --copy      # All clients + copy to clipboard

4. 试用

向 Agent 提问：“使用 Darwin 摄取 ./my-notes，然后查找我写过的所有关于 的内容。”

---

将其用作 Agent 技能

Darwin 自带一项技能（skills/darwin-rag/SKILL.md），用于告诉 Agent 何时以及如何使用 MCP 工具：检查索引内容、摄取文档、选择搜索模式，并根据来源作答。将 darwin-rag 文件夹复制到 Agent 的技能目录中（对于 Claude Code：~/.claude/skills/）。

---

MCP 工具

工具	描述
search_darwin	使用混合／语义／关键词搜索查询知识库
search_lists	按字段值搜索结构化数据（CSV、JSON 数组）
get_search_results	列出已保存的搜索结果
get_search_result_by_id	按文件名加载已保存的搜索结果
get_schema	检查结构化文件的架构（键、类型、记录数）
run_pipeline	从路径或 URL 摄取文档并建立索引
purge_artifacts	删除指定文件的流水线产物
create_store	创建新的隔离数据存储
list_files	列出所有已跟踪文件及其流水线状态
file_status	查看单个文件在所有阶段的详细状态
get_logs	查询会话日志（按时间从旧到新，不包含 INFO）

完整文档：docs/mcp.md

---

远程／HTTP 模式

在可通过网络访问的端点上启动服务：

# SSE transport (legacy)
darwin mcp --sse --host 0.0.0.0 --port 8765

# Streamable HTTP transport (recommended for production)
darwin mcp --http --host 0.0.0.0 --port 8765

使用以下 URL 配置 MCP 客户端：

{
  "mcpServers": {
    "darwin": {
      "url": "http://your-host:8765/mcp"  // or /sse for SSE mode
    }
  }
}

---

环境变量

变量	必需	描述
OPENAI_API_KEY	否*	OpenAI 提供商密钥
ANTHROPIC_API_KEY	否*	Anthropic 提供商密钥
GEMINI_API_KEY	否*	Google Gemini 提供商密钥
MISTRAL_API_KEY	否*	Mistral AI 提供商密钥
GROQ_API_KEY	否*	Groq 提供商密钥
COHERE_API_KEY	否*	Cohere 提供商密钥
TOGETHER_API_KEY	否*	Together AI 提供商密钥
OPENROUTER_API_KEY	否*	OpenRouter 提供商密钥
DEEPSEEK_API_KEY	否*	DeepSeek 提供商密钥
DARWIN_BASE_DIR	否	覆盖基础数据目录
NO_COLOR	否	设置为任意值即可禁用 ANSI 颜色输出

* 生成答案至少需要一个大模型提供商密钥。搜索／索引无需密钥即可运行。

---

设置详情

命令	功能
darwin-admin setup interactive	引导式设置：检测硬件、选择模型
darwin-admin setup --preset required	仅下载嵌入模型（最快）
darwin-admin setup --preset recommended	下载嵌入、重排序和 OCR 模型
darwin-admin setup logging	仅重新配置日志记录
darwin-admin setup validate	验证当前设置

完整操作指南（包括 Docker、从源码安装和 API 密钥配置）请参阅 docs/setup.md。

---

CLI 参考

darwin：用户 CLI

命令	描述
darwin mcp	启动 MCP 服务（stdio；使用 --sse 或 --http 进行网络连接）
darwin config [client]	生成 MCP 客户端配置

darwin-admin：高级用户 CLI

命令	描述
darwin-admin setup	设置模型、日志记录和配置
darwin-admin status	系统状态概览
darwin-admin models	模型注册表：列出、安装、切换模型和管理密钥
darwin-admin store	数据存储：状态、文件、审计、健康检查和修复
darwin-admin pipeline	数据摄取管道：运行、摄取、索引、清除
darwin-admin search	交互式搜索
darwin-admin logs	结构化日志查看与管理
darwin-admin system	系统信息
darwin-admin uninstall	移除 Darwin 数据和配置

完整命令参考请参阅 docs/admin.md。

---

Python API

如需在自己的应用中将 darwin-rag 嵌入为库：

from core import Darwin

d = Darwin()
d.ingest("./papers", recursive=True)
results = d.search("what is this paper about")
records = d.search_records(filters={"status": "active"})

完整参考：docs/api.md

---

文档

文档	内容
setup.md	完整设置指南
mcp.md	MCP 服务、工具、资源和传输方式
admin.md	管理 CLI 参考
architecture.md	面向开发者和贡献者
pipeline.md	数据摄取与索引
retrieval.md	搜索引擎
storage.md	DarwinStore
models.md	模型注册表与推理
logger.md	结构化日志记录
orchestrators.md	高级业务逻辑
api.md	Python API（Darwin 类）

---

贡献

发现了 Bug？想添加新内容？欢迎参与。

• 问题：在 github.com/BrightDotDev/DARWIN/issues 中提交
• 代码：Fork 仓库、创建分支并提交 PR。尽量保持精简。
• AI 生成的代码也可以，但你要对提交的代码负责。提交前请先测试。

完整指南请参阅 CONTRIBUTING.md。

---

许可证

MIT。请参阅 LICENSE。

核心架构和实现由 BrightDotDev 提供。