《RAGtime》（或译为《疯狂年代》）

RAGtime是一个本地检索增强生成（RAG）工具包，用于管理和提供私有语料库以服务于自主工作流程。它从混合文档集中提取结构化文本，使用Sentence Transformers对内容进行分块和嵌入，将向量持久化存储在Chroma中，并提供命令行界面（CLI）和模型上下文协议（MCP）接口以供查询。

特点/功能

文档摄入流水线 涵盖Docling提取、混合代码/文本分块以及BAAI BGE嵌入。
Granite Docling 降级方案 自动使用IBM的Granite Docling VLM重新运行稀疏提取（在Apple Silicon上可用时，使用MLX变体）。
本地向量存储 由持久的Chroma数据库支持着 data/databases/。
命令行编排 通过（某种方式或途径） ragtime 添加文档、提问、检查状态和重置数据库的命令。
MCP服务器 由FastMCP提供支持，内置STDIO和HTTP传输功能，实现与MCP兼容客户端的集成。
可扩展的辅助工具 在 src/ragtime/core/utilities.py 用于可重用的摄入、存储和查询逻辑。

快速入门

安装 Python 3.12+ 及以上版本紫外线。
克隆仓库并安装依赖项：

   uv sync

探索命令行界面（CLI）：

   uv run ragtime --help
   uv run ragtime add ./data/test_docs/F102AS.docx
   uv run ragtime ask "What is the clearance memo about?"
   uv run ragtime status

启动MCP服务器（选择一种传输方式）：

   uv run ragtime-mcp-stdio
   uv run ragtime-mcp-http -- --host 0.0.0.0 --port 9000

HTTP传输默认为 127.0.0.1:9000/mcp; 覆盖主机、端口、，或者在将其暴露给其他机器时，使用上述CLI标志指定路径。

在自定义端口上预览文档（使用 MkDocs 材料）以避免

与MCP HTTP服务器的冲突：

uv run -- mkdocs serve --config-file docs/mkdocs.yml --dev-addr 127.0.0.1:8001

不使用MCP（Cursor CLI）从另一个仓库中使用

当MCP不可用时，通过命令行界面（CLI）在任何其他环境中纯手动运行RAGtime 仓库。这使得游标代理能够调用 ragtime 直接命令同时保持该存储库下的工件（或制品） ./data/ 目录。

A) 指向这个仓库，使用 `uv` （不使用供应商本地化）

在你其他仓库的根目录下：

uv sync --directory /absolute/path/to/ragtime
uv run --directory /absolute/path/to/ragtime ragtime status
uv run --directory /absolute/path/to/ragtime ragtime add ./docs/sample.pdf
uv run --directory /absolute/path/to/ragtime ragtime ask "What changed?"

注释：

路径如 ./data/ 解析到您当前仓库的工作目录。
这对于本地使用和持续集成（CI）非常理想，因为您不想将代码托管到供应商那里。

B) 将供应商作为子模块并添加一个辅助脚本

将RAGtime添加为子模块，置于（项目/目录）下 tools/ragtime：

git submodule add https://git.corp.tanium.com/daniel-ballance/ragtime.git tools/ragtime
uv sync --directory ./tools/ragtime

重要提示：在供应商模式（选项B）下的数据位置

当通过……调用时 uv --directory ./tools/ragtimeRAGtime 解决其数据问题

相对于嵌入式项目目录的根路径。这意味着所有工件和数据库运行于（或位于） tools/ragtime/data/ （不是你的主机仓库根目录）： - 数据库： tools/ragtime/data/databases// - 人工制品；文物；遗迹 tools/ragtime/data/{extractions,chunks,embeddings}

如果你的仓库根目录下已经有数据库 ./data/databases/，或者

把它们移入 ./tools/ragtime/data/databases/ 或者调整您的包装器以 chdir 在启动 RAGtime 之前，请转到仓库根目录。

在你的仓库中创建一个包装脚本，例如：。 tools/ragtime.sh：

macOS / Linux

#!/usr/bin/env bash
exec uv run --directory "$(git rev-parse --show-toplevel)/tools/ragtime" \
  ragtime "$@"

制作 ragtime.sh 可执行文件

chmod +x ./tools/ragtime.sh

用法（从您的仓库根目录开始）：

./tools/ragtime.sh status
./tools/ragtime.sh add ./docs
./tools/ragtime.sh ask "Summarize the design"

Windows 在你的仓库中创建一个包装脚本，例如：。 tools/ragtime.ps1：

# tools/ragtime.ps1
param([Parameter(ValueFromRemainingArguments = $true)][string[]]$Forwarded)

$repoRoot = (git rev-parse --show-toplevel).Trim()
$ragtimeDir = Join-Path $repoRoot 'tools/ragtime'

uv --directory $ragtimeDir run ragtime @Forwarded

用法（从您的仓库根目录）：

.\tools\ragtime.ps1 status
.\tools\ragtime.ps1 add .\docs
.\tools\ragtime.ps1 ask "Summarize the design"

C) 容器化封装（隔离依赖，共享数据）

macOS / Linux 一次构建：

docker build -f /path/to/ragtime/docker/Dockerfile -t ragtime:latest /path/to/ragtime

创造 tools/ragtime-docker.sh 在你的仓库中：

#!/usr/bin/env bash
exec docker run --rm -i --network host \
  -v "$(pwd)/data:/data" \
  -v "$(pwd):/workspace" \
  -w /workspace \
  ragtime:latest ragtime "$@"

用法：

./tools/ragtime-docker.sh status
./tools/ragtime-docker.sh add ./docs
./tools/ragtime-docker.sh ask "Show related ADRs"

Windows 创造 tools/ragtime-docker.ps1 在你的代码库中：

# tools/ragtime-docker.ps1
param([Parameter(ValueFromRemainingArguments = $true)][string[]]$Forwarded)

docker run --rm -it `
  --network host `
  -v "${PWD}/data:/data" `
  -v "${PWD}:/workspace" `
  ragtime:latest ragtime @Forwarded

用法：

.\tools\ragtime-docker.ps1 status
.\tools\ragtime-docker.ps1 add .\docs
.\tools\ragtime-docker.ps1 ask "Show related ADRs"

光标提示：请代理在内部运行上述辅助脚本/命令您的目标存储库。使用CLI时无需MCP配置。

Docker 部署

该存储库包含一个多阶段（流程/系统） Dockerfile 那个烘烤的 SentenceTransformer和Docling模型缓存到镜像中，以便容器可以完全离线运行。构建过程耗时更长，但会生成一个约1.5GB的镜像，不过可以避免（某些问题或限制）运行时下载。仅适用于Apple的依赖项（mlx-vlm) 被跳过，因为 Linux镜像不提供兼容的wheel（预编译包）；Docling的默认OCR保持不变可用。

图像变体

最小化（runtime 目标，缺省值）：包含代码库和预热模型

缓存。使用隐式或显式选择的最终阶段进行构建：

  docker build -f docker/Dockerfile -t ragtime:minimal .
  # or
  docker build -f docker/Dockerfile -t ragtime:minimal --target runtime .

满（runtime-full 目标：此外，还捆绑了从（某处）获取的预构建数据库

兄弟姐妹 ragtime-content 仓库。将该仓库作为构建资源提供在调用 Docker 时提供上下文，以便镜像可以复制数据层：

  docker build -f docker/Dockerfile -t ragtime:full \
    --target runtime-full \
    --build-context ragtime-content=../ragtime-content \
    .

艺名是 runtime-full; 确保 --target 标志与之完全匹配。

这些构建命令假定使用的是 Docker BuildKit（在最新版本中默认启用） Docker Desktop 和 Engine 发布版)。

该图像包既不包含样本配件，也不包含（其他特定内容，根据上下文可能需要补充） data/test_docs/; 挂载或复制任何在运行时想要处理的文档。

项目级别的 .dockerignore 保持缓存（.venv/， .uv_cache/， data/等脱离构建上下文，因此镜像保持可重复构建，不受本地状态影响。

macOS 可能会附加（或连接） com.apple.provenance 为下载的文件添加扩展属性，这可以触发 failed to xattr data: permission denied 在……期间 docker build tar 步骤。如果遇到错误，请在构建前清除这些属性：

find . ../ragtime-content -xattrname com.apple.provenance \
  -exec xattr -d com.apple.provenance {} +

Docker Compose 对这些目标进行了镜像处理： ragtime 并且 docs 构建最小化（版本/系统/模型等，具体根据上下文确定）可变版本，而可选的 ragtime-full 服务捆绑了数据库（以及省略了数据量，因此烘焙后的工件保持原位。

构建

docker build -f docker/Dockerfile -t ragtime:latest .

MCP HTTP服务器（端口9000）

容器默认在9000端口上启动MCP HTTP传输。使用主机（注：此处“host”可能指的是在主机上配置或绑定服务，具体含义需根据上下文确定，若“host”后有更多内容，则需结合具体内容翻译）网络设置以便IDE客户端可以连接到 http://127.0.0.1:9000 无需额外端口转发，以及挂载 ./data 在运行之间持久化数据库：

docker run --rm --network host -v "$(pwd)/data:/data" ragtime:latest

MkDocs 预览（端口 9001）

在9001端口上以相同的主机网络暴露文档服务器，并且数据挂载：

docker run --rm --network host -v "$(pwd)/data:/data" \
  ragtime:latest -- mkdocs serve --config-file /app/docs/mkdocs.yml --dev-addr 0.0.0.0:9001

CLI（命令行界面）工作流

挂载任何您想要纳入处理的主机文件夹（例如，存储库本身）伴随着持续增长的数据量。入口点已经调用了 uv run，因此，CLI 命令直接映射到容器参数。以下示例假设你从仓库根目录运行：

docker run --rm -it \
  --network host \
  -v "$(pwd)/data:/data" \
  -v "$(pwd):/workspace" \
  ragtime:latest ragtime add /workspace/data/test_docs/F102AS.docx

将命令尾部替换为其他子命令（例如 ragtime status 或者 ragtime ask "..."）。

STDIO MCP 传输

Cursor、Claude 或 Codex CLI 可以通过以下方式引用容器化的 STDIO 服务器：包装 Docker 调用。一种常见的模式是创建一个小的 shell 脚本在主机上找到与预期二进制路径匹配的脚本：

#!/usr/bin/env bash
exec docker run --rm -i \
  --network host \
  -v "/path/to/ragtime/data:/data" \
  ragtime:latest ragtime-mcp-stdio "$@"

将你的MCP客户端指向该脚本；它将通过容器流式传输STDIO（标准输入/输出）同时重用相同的持久化数据库卷。

Docker Compose

docker/docker-compose.yml 定义了两个具有可重写端口的服务（默认 9000端口用于MCP HTTP，9001端口用于MkDocs。Compose环境变量允许您无需编辑文件即可调整已发布的端口：

docker compose -f docker/docker-compose.yml up ragtime               # MCP HTTP on 9000
docker compose -f docker/docker-compose.yml up docs                  # MkDocs on 9001
MCP_HTTP_PORT=9100 docker compose -f docker/docker-compose.yml up ragtime  # MCP HTTP on 9100
MKDOCS_PORT=9102 docker compose -f docker/docker-compose.yml up docs       # MkDocs on 9102

使用 docker compose -f docker/docker-compose.yml run --rm ragtime ragtime status 用于临时工作流程。

MCP客户端集成

RAGtime的FastMCP服务器可以被不同的具备MCP功能的客户端所使用以下示例假设仓库位于 /path/to/ragtime; 更新路径以匹配您的环境。运行 uv sync 事先确定好入口点可用的。

克劳德代码（克劳德桌面版）

STDIO（推荐）： 编辑 ~/Library/Application Support/Claude/claude_desktop_config.json

(人类中心论文档）。添加一个服务器条目以启动stdio传输：

  {
    "mcpServers": {
      "ragtime": {
        "command": "uv",
        "args": ["--directory", "/path/to/ragtime", "run", "ragtime-mcp-stdio"]
      }
    }
  }

重启 Claude 桌面应用以加载配置。

HTTP：（超文本传输协议） 跑 uv run ragtime-mcp-http -- --host 127.0.0.1 --port 9000 在一个

独立终端。Claude Desktop 正在推出基于 URL 的 MCP（可能是指某种配置或策略）定义；在支持它的构建中，添加如下条目：

  {
    "mcpServers": {
      "ragtime-http": {
        "url": "http://127.0.0.1:9000"
      }
    }
  }

如果你的构建缺少 url 支持，使用标准I/O（stdio）或通过运行HTTP服务器路由器风格的 mcp-router。

Cursor 集成开发环境（IDE）

STDIO:（注：STDIO通常指标准输入输出库，但在此处作为单独的词汇出现，可能是一个特定上下文或项目中的术语，直接翻译为“标准输入输出”可能不够准确，但基于常见理解，可暂译为）标准输入输出（库/接口）创建或编辑 ~/Library/Application Support/Cursor/mcp.json

（或项目级别的 .cursor/mcp.json) 包括：

  {
    "mcpServers": {
      "ragtime": {
        "command": "uv",
        "args": ["--directory", "/path/to/ragtime", "run", "ragtime-mcp-stdio"]
      }
    }
  }

HTTP:（超文本传输协议） 启动HTTP服务器（uv run ragtime-mcp-http --host 0.0.0.0 --port 9000）。

Cursor 通过（某种方式）支持 HTTP/SSE 端点 url 密钥（Cursor 文档)：

  {
    "mcpServers": {
      "ragtime-http": {
        "url": "http://127.0.0.1:9000/mcp"
      }
    }
  }

Codex CLI（可译为“Codex 命令行界面”或“Codex 命令行工具”）

STDIO（注：STDIO通常指的是标准输入输出库，如C语言中的\，但在此上下文中未给出具体含义，故直接翻译为“标准输入输出”）： 更新 ~/.codex/config.toml （或特定配置文件的配置）到

使用Codex文档中描述的TOML格式注册服务器 (配置引用)：

  [mcp_servers.ragtime]
  command = "uv"
  args = ["--directory", "/path/to/ragtime", "run", "ragtime-mcp-stdio"]

HTTP： 启动HTTP服务器（uv run ragtime-mcp-http -- --port 9000）。

Codex CLI 目前仅通过（某种方式）生成 stdio 传输 mcp_servers. 要使用 HTTP端点，运行一个桥接器，例如 mcp-router 或者 @modelcontextprotocol/inspector 与……相连接的 http://127.0.0.1:9000 并将一个stdio端点暴露给Codex。

CLI 概述

命令	描述
`ragtime add PATH` 将文件或目录导入到Chroma数据库中；支持 `--database`， `--split-by-subdir`以及嵌入选项。
`ragtime ask QUERY`	在一个或多个数据库中运行可调参数的语义搜索 `--top-k`， `--collection`设备/型号覆盖，以及可选的交叉编码器重排序（`--rerank-top-k`）。
`ragtime status` 报告检测到的数据库以及提取、分块和嵌入工件的数量。
`ragtime reset`	删除一个或多个数据库（`--database`， `--all`， `--yes`)。

摄入的工件被存储在 data/extractions/， data/chunks/，和 data/embeddings/生成的内容被视为临时性的，除非需要用于调试，否则不应被追踪。

VLM备用配置

当初始的Docling处理返回的单词数少于150个时，系统会自动使用IBM Granite Docling重新运行提取过程，并在Apple Silicon上切换到MLX版本。
要强制使用特定的Docling VLM规范（例如，用于故障排除），请进行导出 RAGTIME_VLM_SPEC 带有所需的常数，如 GRANITEDOCLING_TRANSFORMERS 或者 SMOLDOCLING_TRANSFORMERS 在跑步之前 ragtime add。

数据库位置和联合查询

默认设置（在RAGtime仓库内运行或使用选项A）：数据库处于活动状态

下面；在……之下 ./data/databases/ 在当前的存储库中。

供应商模式（选项B，带 uv --directory ./tools/ragtime): 数据库存活

在...下面 ./tools/ragtime/data/databases/ 相对于您的主仓库根目录。放置这里的每个数据库对应的文件夹（例如。， deploy， platform）。

每个内部子目录 data/databases/ 被视为一个独立的数据库（例如。， data/databases/local/， data/databases/vendor_docs/)。
该 ragtime status 命令列出这些目录。如果未找到任何目录，它会打印出一个绝对路径，您可以在该路径下创建它们。
在摄入期间，使用 --database NAME 指定一个特定的子目录；省略则默认为 local （即。， data/databases/local/）。
联合查询涵盖所有子目录下的内容 data/databases/ 除非你加以限制 --database 开启/在 ragtime ask。

发展任务

格式化和代码检查： uv run ruff format src 并且 uv run ruff check src。
测试（请自行添加 pytest （套房）： uv run pytest。
更新贡献者指南 AGENTS.md 当工作流程发生变化时。

如需完整的操作指南，包括管道详情和MCP工具合约，请参阅以下MkDocs文档： docs/ 或者使用（某种工具/方法）在本地构建网站 mkdocs serve --config-file docs/mkdocs.yml 安装可选文档依赖项后。

使用交叉编码器对顶级匹配项进行重新排序，以提升以答案为中心的性能

订购：

  uv run ragtime ask "Summarize the design" \
    --rerank-top-k 10 \
    --rerank-model BAAI/bge-reranker-large

当你首次使用一个新模型时，重排序器会从Hugging Face下载该模型。将模型缓存到以下位置 ~/.cache/huggingface 以避免重复下载。

ragtime (Danielballance)

快速接入

详细介绍

《RAGtime》（或译为《疯狂年代》）

特点/功能

快速入门

不使用MCP（Cursor CLI）从另一个仓库中使用

A) 指向这个仓库，使用 `uv` （不使用供应商本地化）

B) 将供应商作为子模块并添加一个辅助脚本

C) 容器化封装（隔离依赖，共享数据）

Docker 部署

图像变体

构建

MCP HTTP服务器（端口9000）

MkDocs 预览（端口 9001）

CLI（命令行界面）工作流

STDIO MCP 传输

Docker Compose

MCP客户端集成

克劳德代码（克劳德桌面版）

Cursor 集成开发环境（IDE）

Codex CLI（可译为“Codex 命令行界面”或“Codex 命令行工具”）

CLI 概述

VLM备用配置

数据库位置和联合查询

发展任务

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

ragtime (Danielballance)

快速接入

详细介绍

《RAGtime》（或译为《疯狂年代》）

特点/功能

快速入门

不使用MCP（Cursor CLI）从另一个仓库中使用

A) 指向这个仓库，使用 uv （不使用供应商本地化）

B) 将供应商作为子模块并添加一个辅助脚本

C) 容器化封装（隔离依赖，共享数据）

Docker 部署

图像变体

构建

MCP HTTP服务器（端口9000）

MkDocs 预览（端口 9001）

CLI（命令行界面）工作流

STDIO MCP 传输

Docker Compose

MCP客户端集成

克劳德代码（克劳德桌面版）

Cursor 集成开发环境（IDE）

Codex CLI（可译为“Codex 命令行界面”或“Codex 命令行工具”）

CLI 概述

VLM备用配置

数据库位置和联合查询

发展任务

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

A) 指向这个仓库，使用 `uv` （不使用供应商本地化）