dans lazy file dump

RAG在盒子里

将文档放入文件夹，运行索引器，并使用 MCP服务器 --任何与MCP兼容的AI助手（Claude Code、OpenClaw、Claude Desktop、Cursor等）都可以通过一个配置条目搜索您的文档。

没有要管理的基础设施。无需GPU。适用于 云API 开箱即用或 完全自托管.

用例

• 个人知识库 --为您的笔记、PDF、文档、图像、音频和视频建立索引。向你的人工智能助手提问，并从你自己的文件中获得答案。
• 公司文档搜索 --将法律合同、报告、SOP放入文件夹中。员工通过任何兼容MCP的助手使用元数据过滤器（按部门、文档类型、日期、标签）进行搜索。
• 研究助理 --索引论文、数据集和笔记。按含义搜索，而不仅仅是关键字。LLM富集自动提取实体、主题和关键事实。
• 黑曜石/Markdown拱顶 --适用于任何降价源（黑曜石、HackMD、Notion导出、GitBook）。提取YAML frontmatter以进行丰富的过滤。
• PDF繁重的工作流程 --扫描的PDF会自动进行OCR。页面感知分块保持上下文完整。从PDF属性中提取的元数据（作者、日期、页数）。
• 多代理工具 --将您的文档集合作为16 MCP工具公开。多个代理可以同时搜索、浏览、过滤和管理分类。

为什么这比其他RAG工具更重要？

堆栈

Qwen3-Reranker-8B通过DeepInfra。 |矢量+FTS|LanceDB+坦特维（BM25）| |编排|精确到3.x|

入门

1.安装

git clone https://github.com/DevNexsler/RAG-In-A-Box.git
cd RAG-In-A-Box
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2.配置

复制示例配置并编辑两个路径：

cp config.yaml.example config.yaml   # cloud providers (default)

打开 config.yaml 并设置：

• documents_root --文档集合的路径
• index_root --索引将存储在何处

自托管？ 使用 cp config.local.yaml.example config.yaml 相反。此配置使用Ollama、DeepSeek OCR2和llama服务器——请参阅 本地模式 在......下面

3.添加API密钥

创建一个 .env 项目根目录中的文件：

GEMINI_API_KEY=...               # OCR — get one at https://aistudio.google.com/apikey
OPENROUTER_API_KEY=sk-or-...     # embeddings + enrichment — https://openrouter.ai/keys
DEEPINFRA_API_KEY=...            # reranker — https://deepinfra.com/dash/api_keys

4.构建索引

python run_index.py

这将扫描您的文档，提取文本（Markdown、PDF、图像、音频、视频），生成嵌入，并将所有内容写入LanceDB索引。Prefect自动启动一个用于流/任务日志记录的临时服务器——仪表板位于 http://127.0.0.1:4200.

5.连接您的AI助手

MCP服务器允许任何兼容的AI助手通过以下工具访问您的文档 file_search, file_status，以及 file_recent。助手会自动启动服务器——您只需添加一个配置条目。

克劳德代码

添加到您的项目 .mcp.json （或 ~/.claude.json 全球访问）：

{
  "mcpServers": {
    "doc-organizer": {
      "command": "/path/to/Document-Organizer/.venv/bin/python",
      "args": ["/path/to/Document-Organizer/mcp_server.py"],
      "cwd": "/path/to/Document-Organizer"
    }
  }
}

开爪

添加到您的OpenClaw MCP配置中：

{
  "mcpServers": {
    "doc-organizer": {
      "command": "/path/to/Document-Organizer/.venv/bin/python",
      "args": ["mcp_server.py"],
      "cwd": "/path/to/Document-Organizer"
    }
  }
}

克劳德桌面版

添加 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）：

{
  "mcpServers": {
    "doc-organizer": {
      "command": "/path/to/Document-Organizer/.venv/bin/python",
      "args": ["/path/to/Document-Organizer/mcp_server.py"],
      "cwd": "/path/to/Document-Organizer"
    }
  }
}

任何兼容MCP的客户端

Cursor、Windsurf或任何支持MCP stdio服务器的工具的模式都是相同的。点 command 在venv Python和 args 在 mcp_server.py.API密钥从 .env 文件自动生成——无需在MCP配置中传递它们。

HTTP模式（远程/非MCP客户端）

python mcp_server.py --http
# Listens on 0.0.0.0:7788

VPS/Docker部署

在任何VPS或容器平台上作为独立的HTTP服务器运行。所有机器学习推理都使用云API——不需要GPU。

# Docker
docker build -t doc-organizer .
docker run -v /path/to/data:/data -p 7788:7788 \
  -e OPENROUTER_API_KEY=... \
  -e DEEPINFRA_API_KEY=... \
  -e API_KEY=your-secret-token \
  doc-organizer

# Or run directly
API_KEY=your-secret-token python server.py

环境变量覆盖 （用于容器/VPS）：

什么时候 API_KEY 已设置，所有HTTP请求必须包括 Authorization: Bearer 。参见 config.vps.yaml.example 对于VPS特定的配置。

渲染网站： 一键部署 render.yaml --持久磁盘位于 /data，自动生成的API密钥。

REST API（文件管理）

在HTTP模式下运行时(--http 或 server.py)，REST API与MCP服务器一起提供，用于上传、下载和列出文档。Auth使用相同的 API_KEY 不记名代币。

上传文件：

curl -X POST http://localhost:7788/api/upload \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@report.pdf" \
  -F "directory=2-Area/Legal"
# -> {"uploaded": true, "doc_id": "2-Area/Legal/report.pdf", "size": 84521}

下载文件：

curl http://localhost:7788/api/documents/2-Area/Legal/report.pdf \
  -H "Authorization: Bearer $API_KEY" -o report.pdf

列出目录中的文件：

curl "http://localhost:7788/api/documents/?directory=2-Area&limit=50" \
  -H "Authorization: Bearer $API_KEY"
# -> {"directory": "2-Area", "files": [...], "total": 12, "offset": 0, "limit": 50}

限制： 最多上传100 MB。允许的类型： .md, .pdf, .png, .jpg, .jpeg。路径遍历被阻止。上传后，运行 file_index_update （通过MCP）对新文档进行索引。

本地模式（可选）

要在自己的硬件而不是云API上运行所有内容：

1. 复制 config.local.yaml.example 到 config.yaml
2. 安装并启动 奥拉玛: brew install ollama && ollama serve

- ollama pull qwen3-embedding:0.6b （语义组块） - ollama pull qwen3-embedding:4b-q8_0 （嵌入）

1. 开始 DeepSeek OCR2 在端口8790上（用于PDF/图像OCR）

本地模式下不需要云API密钥（除了reranker-DeepInfra总是云）。

特性

Document Collection                    AI Assistants
 +------------------+                   +-------------------+
 | Markdown (.md)   |                   | Claude Code       |
 | PDFs             |    +---------+    | OpenClaw          |
 | Images (.png/jpg)|───>| Indexer |    | Claude Desktop    |
 +------------------+    +----+----+    | Cursor / Windsurf |
                              |         +--------+----------+
                              v                  |
                   +----------+----------+       | MCP (stdio)
                   |     LanceDB Index   |       |
                   |  vectors + metadata |<------+
                   |  + full-text (BM25) |  file_search
                   +---------------------+  file_status
                                            file_recent ...

混合搜索 --每个查询并行运行向量（语义）和关键字（BM25）搜索，将结果与互易秩融合融合，应用长度归一化、重要性加权、可选的带时间衰减下限的近因提升、交叉编码器重新排序（60/40混合余弦回退）、MMR分集滤波和最小分数阈值。预过滤器（标签、文件夹、文档类型、主题和复杂的JSON过滤器）在检索之前在数据库级别应用，以便每个结果都匹配。

多格式提取 --索引Markdown、PDF、图像、音频和视频。PDF首先使用文本提取，然后再使用OCR扫描页面。图像获得OCR文本和视觉描述。音频/视频文件被base64发送到OpenRouter兼容的媒体模型，用于转录/搜索笔记。EXIF元数据（相机、GPS、日期）会自动提取。

LLM富集 --LLM分析每个文档以提取结构化元数据：摘要、文档类型、实体（人、地点、组织、日期）、主题、关键字、关键事实、建议标签和建议文件夹。所有字段都是可搜索和可过滤的。

分类系统 --存储在单独的LanceDB表中的标签和文件夹路径的受控词汇表，其中嵌入了描述。LLM在丰富过程中使用分类法来建议一致的标签和归档位置。从现有的标签/目录数据库中播种。通过7个MCP CRUD工具进行管理(file_taxonomy_*).

智能分块 --Markdown按标题拆分，PDF按页面拆分。大片段得到语义组块（通过句子嵌入进行主题边界检测）。每个块都有一个上下文标头，前缀有标题、路径和主题，因此每个块都是自描述的，以便更好地检索。

丰富的元数据和过滤 --YAML frontmatter（标签、状态、作者、日期、自定义字段）被自动提取并提升为可过滤的列。自定义frontmatter键是自动升级的，不需要更改模式。 file_search 支持精确过滤器和复杂的JSON过滤器 eq, ne, contains, prefix, in, and, or，以及 not.

MCP服务器 --通过模型上下文协议公开16个工具。任何兼容MCP的助手都可以搜索、浏览、过滤文档和管理分类条目。通过stdio（由助手自动启动）或HTTP工作。

增量更新 --重新索引时只处理新的和修改过的文件。删除的文件会自动清理。失败的文档会被跟踪并重试。

云端或本地 --每个组件（OCR、嵌入、丰富、重新登录）都有云和本地提供商选项。默认配置使用云API，不运行服务器。通过单个配置文件交换切换到完全自托管。

默认情况下具有弹性 --每个文档的错误处理，包括重试、结构化的MCP错误响应、对每个查询的搜索诊断(vector_search_active, reranker_applied, degraded)，过滤器密钥上的SQL注入保护，以及自动LanceDB损坏恢复（版本回滚+重建）。

MCP工具

运行测试

python -m pytest tests/ -m "not live" -x    # ~370 offline tests (no API keys)
python -m pytest tests/ -x                   # ~454 full suite (requires API keys)

项目布局

core/                        Config, storage interface, taxonomy helpers
providers/embed/             Embedding providers (OpenRouter, Ollama, LlamaIndex)
providers/llm/               LLM providers (OpenRouter, Ollama)
providers/ocr/               OCR providers (Gemini Vision, DeepSeek OCR2)
taxonomy_store.py            Taxonomy LanceDB store (CRUD, vector search, FTS)
doc_enrichment.py            LLM metadata extraction (with taxonomy integration)
extractors.py                Text extraction (MD, PDF, images, audio/video)
flow_index_vault.py          Prefect indexing flow
lancedb_store.py             LanceDB storage + search
search_hybrid.py             10-step hybrid search pipeline
mcp_server.py                MCP server (stdio + HTTP, 16 tools)
server.py                    VPS entrypoint — starts HTTP server on $PORT
run_index.py                 CLI entrypoint
scripts/seed_taxonomy.py     Import taxonomy from existing SQLite DBs
config.yaml.example          Cloud config template
config.local.yaml.example    Local/self-hosted config template
config.vps.yaml.example      VPS/container config template
Dockerfile                   Docker image (Python 3.13-slim, no GPU)
.dockerignore                Docker build exclusions
render.yaml                  Render.com deployment descriptor
tests/                       ~454 tests
docs/architecture.md         Search pipeline, schema, component details
docs/vps-architecture.md     VPS/cloud deployment architecture

许可证

PolyForm非商业版1.0.0 --免费用于个人、研究、教育和非营利用途。商业用途需要单独的许可证。