Rag Starter

rag-starter — 与文档聊天（RAG），并附带引用

开箱即用、适用于生产环境的入门项目，可将一组文档转化为带引用的问答服务。放入 PDF、Markdown 或文本文件，提出问题，即可获得以源文档为依据的回答——每条陈述都能追溯到对应的原文段落。

同一代码库提供两种接入方式：

• MCP 服务——将其接入 Claude Desktop、Claude Code 或任意 MCP 主机，即可与文档聊天。
• HTTP API（FastAPI）——可从任意应用调用。

一次构建，为每个客户端换肤。替换 data/ 文件夹，调整 config.py，即可发布。

有何不同

• 默认无需密钥。 嵌入在本地运行（ONNX MiniLM）——无需 API 密钥、没有单次查询费用，还可离线运行。几秒钟内即可在任何地方进行演示。
• 提供引用，不搞幻觉。 检索会返回按相关性排序并标注 [source#chunk] / [file.pdf p3] 的段落。找不到答案时会返回 "Not found in the documents"，绝不捏造答案。
• 可选答案合成。 设置 ANTHROPIC_API_KEY 后，它会生成带引用的答案；未设置时，则会返回段落供主机大模型回答。无论哪种方式，RAG 都能正常工作。
• 幂等摄取。 重新摄取文件会原位更新，不会产生重复项。

快速开始

pip install -r requirements.txt          # or: pip install -e .
PYTHONUTF8=1 python tests/test_smoke.py   # proves retrieval works on the sample docs

作为 HTTP API 使用

rag-starter-api            # uvicorn on 127.0.0.1:8000
# then:
curl -X POST localhost:8000/ingest  -H "content-type: application/json" -d '{"path":"./data"}'
curl -X POST localhost:8000/search  -H "content-type: application/json" -d '{"query":"refund policy"}'
curl -X POST localhost:8000/answer  -H "content-type: application/json" -d '{"query":"how long is the refund window?"}'

作为 MCP 服务使用（Claude Desktop）

将以下内容添加到 claude_desktop_config.json → mcpServers：

{
  "rag-starter": {
    "command": "python",
    "args": ["-m", "rag_starter"],
    "cwd": "C:/path/to/rag-starter"
  }
}

重启 Claude Desktop，然后输入：“摄取文件夹 ./data”，再输入：“退款政策是什么？”

工具 / 端点

MCP 工具	HTTP	用途
rag_ingest(path)	POST /ingest	为单个文件或文件夹建立索引（txt/md/pdf）。
rag_search(query, k)	POST /search	返回排名前 k 的带引用段落（无需密钥）。
rag_answer(query, k)	POST /answer	返回带引用的答案（需密钥）或段落（无需密钥）。
—	GET /health	存活状态、已索引分块数量及嵌入后端。

配置

所有配置均位于 config.py 中（也可通过环境变量或 .env 设置——参见 .env.example）：分块大小和重叠量、top-k、嵌入后端（default 表示本地，openai 表示 OpenAI）以及答案模型。为客户端换肤通常只需：替换 data/、设置 RAG_COLLECTION，然后重新摄取。

架构

documents ──ingest.py──> chunks(+citations) ──store.py──> Chroma (local, persistent)
                                                              │
question ─────────────────retrieve.py──> top-k cited passages┤
                                                              ├─> rag_search  (host LLM answers)
                                                  answer.py ──┴─> rag_answer  (server synthesizes, optional)

复用 mcp-factory 契约（Result、formatting、cache），因此可以与目录中的其他项目组合使用。

许可证

MIT。