内容
<div align="center">
<br/>
[](https://github.com/SARAMALI15792/AgentRAG/actions/workflows/ci.yml)
[](https://pypi.org/project/aicompatible-rag/)
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://mypy.readthedocs.io/)
[](https://github.com/psf/black)
</div>
---
## 什么是AgentRAG
AI模型是强大的推理工具，但它们对您的私有数据一无所知。每个会话都从零开始。
AgentRAG弥补了这一差距。它是一个本地运行的MCP服务器，为Claude提供持久的、语义索引的内存，适用于您带来的任何文档。Claude调用`search_documents`、`plan_query`和`evaluate_chunks`，就像调用其他工具一样，并从正确的文档中获取最相关的片段，根据含义而不是关键词匹配进行排名。
**关键特性：**
- **默认完全本地** — Qdrant矢量存储在进程中运行，嵌入通过`sentence-transformers`本地生成。核心检索不需要API密钥。
- **通用摄入** — 20+文件类型：PDF、DOCX、XLSX、EPUB、JSON、YAML、Markdown、Python、Jupyter笔记本、字幕、电子邮件和网页。
- **智能检索** — Claude将复杂查询分解为子查询，搜索多个角度，评估相关性，并在需要时重新搜索 — 所有这些都通过本地MCP工具调用。
- **工作空间隔离** — 通过命名的Qdrant集合为每个项目维护单独的知识库。
- **云同步（可选）** — 加密快照推送/拉取到S3兼容存储。永远不会在没有明确`agentrag sync push`的情况下同步。
- **设计中的隐私** — 没有遥测，没有分析，没有网络调用，除非您明确配置一个。
---
## 60秒快速入门
```bash
# 安装
pip install aicompatible-rag
# （可选）启用智能检索 — 从 https://aistudio.google.com/ 获取免费密钥
export AGENTRAG_GOOGLE_API_KEY=your_key_here
# 启动MCP服务器
agentrag serve
```
然后将以下配置块添加到Claude Desktop并开始在您的文档上聊天。
---
## 集成
AgentRAG与任何MCP兼容的客户端一起工作。选择与您的工作流匹配的集成。
---
### Claude Desktop
将以下内容添加到您的Claude Desktop配置文件中：
| 平台 | 路径 |
|----------|------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |
**选项A — pip安装（推荐）**
```json
{
"mcpServers": {
"agentrag": {
"command": "agentrag",
"args": ["serve", "--data-dir", "~/.agentrag"]
}
}
}
```
**选项B — 通过uvx进行零安装（无需pip）**
```json
{
"mcpServers": {
"agentrag": {
"command": "uvx",
"args": ["--from", "aicompatible-rag", "agentrag", "serve", "--data-dir", "~/.agentrag"]
}
}
}
```
---
### Claude Code（CLI）
[Claude Code](https://claude.ai/code) 通过项目级或全局配置支持MCP服务器。
**添加到项目** （`.claude/mcp_servers.json` 在您的仓库中）：
```json
{
"agentrag": {
"command": "agentrag",
"args": ["serve", "--data-dir", "~/.agentrag"],
"env": {
"AGENTRAG_GOOGLE_API_KEY": "your_key_here"
}
}
}
```
或通过Claude Code CLI全局注册：
```bash
claude mcp add agentrag agentrag serve --data-dir ~/.agentrag
```
注册后，Claude Code可以直接从任何编码会话中调用所有AgentRAG工具（`ingest_file`、`search_documents`等），为您的私有文档、代码库和笔记提供语义内存。
---
### VS Code（GitHub Copilot / MCP扩展）
任何支持MCP服务器的VS Code扩展（例如带有MCP的GitHub Copilot或官方MCP扩展）都可以通过HTTP传输连接到AgentRAG。
> **为什么是`localhost`？** VS Code不支持`stdio`传输 — 它需要一个HTTP URL。`localhost:8000`是在您自己的机器上运行的AgentRAG的地址。不会有数据离开您的计算机； URL纯粹是本地的。
**步骤1 — 以HTTP模式启动AgentRAG：**
```bash
AGENTRAG_TRANSPORT=http AGENTRAG_PORT=8000 agentrag serve
```
**步骤2 — 添加到VS Code `settings.json`：**
```json
{
"mcp.servers": {
"agentrag": {
"url": "http://localhost:8000/mcp"
}
}
}
```
---
### JetBrains IDEs（IntelliJ，PyCharm，WebStorm等）
JetBrains AI助手通过HTTP传输支持MCP服务器。
> **为什么是`localhost`？** JetBrains AI助手需要一个HTTP URL来连接MCP服务器。`localhost:8000`指向在您自己的机器上运行的AgentRAG — 相同的隐私保证适用；不会将任何内容发送到网络上。
**步骤1 — 以HTTP模式启动AgentRAG：**
```bash
AGENTRAG_TRANSPORT=http AGENTRAG_PORT=8000 agentrag serve
```
**步骤2 — 在`Settings → Tools → AI Assistant → MCP Servers`中添加：**
```
名称： agentrag
网址： http://localhost:8000/mcp
```
---
### 任意MCP兼容客户端
AgentRAG通过`stdio`和HTTP在[模型上下文协议](https://modelcontextprotocol.io/)上进行通信。任何支持MCP的客户端都可以连接：
| 传输 | 用例 | 如何启动 |
|-----------|----------|--------------|
| `stdio` | Claude Desktop, Claude Code, 本地工具 | `agentrag serve` （默认） |
| `http` | VS Code, JetBrains, 远程代理, 自定义客户端 | `AGENTRAG_TRANSPORT=http agentrag serve` |
---
## CLI参考
```
agentrag serve 启动MCP服务器
agentrag ingest 将文件或目录摄入矢量存储
agentrag list 列出所有摄入的来源
agentrag sync 云同步子命令（push / pull / status）
```
### `agentrag serve`
| 标志 | 默认值 | 描述 |
|------|---------|-------------|
| `--data-dir` | `~/.agentrag` | Qdrant数据根目录 |
| `--transport` | `stdio` | `stdio`（Claude Desktop）或`http` |
| `--port` | `8000` | HTTP端口（忽略stdio） |
| `--embed-model` | `sentence-transformers/all-MiniLM-L6-v2` | 嵌入模型 |
| `--collection` | `documents` | 活动Qdrant集合名称 |
### `agentrag ingest`
```bash
agentrag ingest /path/to/file.pdf
agentrag ingest /path/to/directory --recursive
```
### `agentrag sync`
```bash
agentrag sync push # 快照 + 加密 + 上传
agentrag sync pull # 下载 + 解密 + 恢复
agentrag sync status # 显示最后的推送/拉取时间戳
```
需要`AGENTRAG_SYNC_BACKEND`、`AGENTRAG_SYNC_ENDPOINT`和`AGENTRAG_SYNC_KEY`。
参见[云同步](#云同步)以了解设置。
---
## 环境变量
所有变量都通过`pydantic-settings`从环境或`.env`文件加载。
### 核心
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `AGENTRAG_DATA_DIR` | `~/.agentrag` | Qdrant数据和配置的根目录 |
| `AGENTRAG_EMBED_MODEL` | `sentence-transformers/all-MiniLM-L6-v2` | 嵌入模型名称（完整的`{org}/{model}` HuggingFace路径） |
| `AGENTRAG_VECTOR_DIM` | `384` | 嵌入模型的输出维度 — 必须与Qdrant集合匹配 |
| `AGENTRAG_CHUNK_SIZE` | `512` | 滑动窗口分割的令牌块大小 |
| `AGENTRAG_CHUNK_OVERLAP` | `64` | 相邻块之间的令牌重叠 |
| `AGENTRAG_PORT` | `8000` | HTTP端口，用于HTTP传输模式 |
| `AGENTRAG_TRANSPORT` | `stdio` | `stdio`或`http` |
| `AGENTRAG_COLLECTION` | `documents` | 活动Qdrant集合名称 |
| `AGENTRAG_INGEST_TIMEOUT` | `300` | 每个文件摄入的最大秒数，超时前 |
| `AGENTRAG_MAX_FILE_SIZE_MB` | `100` | 最大文件大小（MB）— 超过此大小的文件将被拒绝，并显示可操作的错误 |
### 智能检索（Gemini）
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `AGENTRAG_GOOGLE_API_KEY` | _(无)_ | Google Gemini API密钥。在 [aistudio.google.com](https://aistudio.google.com/) 上获取免费密钥。如果缺少，降级检索永远不会被阻止。 |
| `AGENTRAG_GEMINI_MODEL` | `gemini-2.0-flash` | 用于查询分解和块评估的Gemini模型 |
| `AGENTRAG_QUERY_EXPAND` | `false` | 在`plan_query`中启用Gemini支持的查询扩展 |
| `AGENTRAG_RERANK` | `false` | 激活交叉编码器重新排序 (`ms-marco-MiniLM-L-6-v2`) |
### 云同步
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `AGENTRAG_SYNC_BACKEND` | `local` | `local`或`s3` |
| `AGENTRAG_SYNC_ENDPOINT` | _(无)_ | S3：存储桶名称。S3兼容：完整终端URL |
| `AGENTRAG_SYNC_KEY` | _(无)_ | Fernet加密密钥（base64）。生成：`python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'` |
| `AGENTRAG_SYNC_LOCAL_DIR` | `~/.agentrag/backups` | 本地后端快照存档目录 |
| `AGENTRAG_SYNC_PREFIX` | `agentrag/` | 所有上传快照的S3密钥前缀 |
---
## MCP工具
所有工具都可在Claude中原生使用 — 无需特殊提示。
### 摄入
| 工具 | 输入 | 描述 |
|------|-------|-------------|
| `ingest_file` | `path, metadata?` | 将单个本地文件摄入矢量存储 |
| `ingest_directory` | `path, recursive?, file_types?, metadata?` | 批量摄入目录中的所有支持文件 |
| `ingest_url` | `url, metadata?` | 获取网页并摄入其文本内容 |
### 检索
| 工具 | 输入 | 描述 |
|------|-------|-------------|
| `search_documents` | `query, top_k?, filters?` | 语义搜索 — 返回按相关性排序的块 |
| `search_by_metadata` | `filters` | 按元数据筛选来源，无语义查询 |
| `search_multi` | `queries, top_k?` | 多查询搜索；按`chunk_id`去重 |
| `search_stream` | `query, top_k?` | 流式搜索 — 结果到达时评分 |
### 智能循环
| 工具 | 输入 | 描述 |
|------|-------|-------------|
| `plan_query` | `query` | 将复杂查询分解为专注的子查询（Gemini支持） |
| `evaluate_chunks` | `query, results` | 评估每个块的相关性；返回`EvaluationReport`并提供重新搜索建议 |
### 文档管理
| 工具 | 输入 | 描述 |
|------|-------|-------------|
| `list_sources` | _(无)_ | 列出所有摄入的来源，元数据摘要 |
| `get_document` | `source_id` | 检索源的完整重建文本 |
| `delete_source` | `source_id` | 删除源及其所有矢量块 |
### 工作空间（集合）
| 工具 | 输入 | 描述 |
|------|-------|-------------|
| `list_collections` | _(无)_ | 列出所有命名的Qdrant集合 |
| `create_collection` | `name` | 创建新的命名集合，用于工作空间隔离 |
| `switch_collection` | `name` | 为后续操作设置活动集合 |
---
## 智能检索循环
当设置`AGENTRAG_GOOGLE_API_KEY`时，Claude可以运行完整的智能检索循环：```
plan_query("比较治疗A和治疗B以治疗X")
→ QueryPlan(sub_queries=["什么是治疗A？", "什么是治疗B？", "比较研究"])
search_multi(sub_queries, top_k=5)
→ deduplicated SearchResult list
evaluate_chunks(original_query, results)
→ EvaluationReport(sufficient=False, suggested_queries=["副作用比较", ...])
search_multi(suggested_queries) ← 如果不够充分则重新搜索
```
所有三个工具在API不可用时都会顺利降级 — 检索永远不会被阻止。
---
## 支持的文件类型
| 扩展名 | 类别 | 安装 |
|-----------|----------|---------|
| `.txt`, `.md` | 纯文本 | _(包含) |
| `.pdf` | 文档 | _(包含) |
| `.docx` | 文档 | _(包含) |
| `.html` | 网页 | _(包含) |
| `.py` | 代码 | _(包含) |
| `.ipynb` | 笔记本 | _(包含) |
| `.json`, `.yaml`, `.xml`, `.toml` | 结构化数据 | _(包含) |
| `.csv` | 表格数据 | _(包含) |
| `.eml`, `.mbox` | 电子邮件 | _(包含) |
| `.xlsx` | 电子表格 | `pip install aicompatible-rag[office]` |
| `.pptx` | 演示文稿 | `pip install aicompatible-rag[office]` |
| `.epub` | 电子书 | `pip install aicompatible-rag[ebooks]` |
| `.mobi` | 电子书 | `pip install aicompatible-rag[ebooks]` |
| `.srt`, `.vtt` | 字幕 | `pip install aicompatible-rag[web]` |
| URL | 网页 | `pip install aicompatible-rag[web]` |
安装所有可选类型：
```bash
pip install aicompatible-rag[all]
```
---
## 云同步
AgentRAG 可以将 Qdrant 矢量存储备份和恢复到任何 S3 兼容存储。所有快照在上传前都会在客户端加密 — 您的加密密钥永远不会离开您的机器。
### 本地备份（无需云支持）
```bash
# .env
AGENTRAG_SYNC_BACKEND=local
AGENTRAG_SYNC_LOCAL_DIR=~/agentrag-backups
AGENTRAG_SYNC_KEY=<your-fernet-key>
```
### S3 同步
```bash
# .env
AGENTRAG_SYNC_BACKEND=s3
AGENTRAG_SYNC_ENDPOINT=my-bucket-name
AGENTRAG_SYNC_KEY=<your-fernet-key>
```
生成密钥：
```bash
python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'
```
然后推送和拉取：
```bash
agentrag sync push # 快照 + 加密 + 上传
agentrag sync pull # 下载 + 解密 + 恢复
agentrag sync status # 最后的推送/拉取时间戳
```
> **隐私保证：** 快照使用 Fernet（AES-128-CBC + HMAC-SHA256）加密后上传。服务器永远不会看到纯文本数据。
---
## 工作空间隔离
使用命名的Qdrant集合为每个项目维护单独的知识库。
```bash
# 通过环境变量
AGENTRAG_COLLECTION=project-alpha agentrag serve
# 通过MCP工具（来自Claude）
create_collection("project-alpha")
switch_collection("project-alpha")
ingest_file("/path/to/docs")
search_documents("query") # 仅限于project-alpha
```
一个集合中的数据永远不会在另一个集合中可见。
---
## 架构
```
摄入路径：
文件 / URL
→ reader_registry（调度到格式读取器）
→ reader.py 原始文档
→ chunker.py 块列表 [Chunk]（512令牌 / 64重叠）
→ embedder.py 嵌入块列表 [EmbeddedChunk]（本地sentence-transformers）
→ store/qdrant.py upsert（嵌入式Qdrant，持久化到~/.agentrag）
检索路径：
Claude → search_documents
→ searcher.py 嵌入查询 + qdrant.query + 重新排序
→ List[SearchResult]
智能路径：
Claude → plan_query → search_multi → evaluate_chunks → （如有必要则重新搜索）
```
**依赖方向严格** — `store/` 永远不会导入 `ingestion/` 或 `retrieval/`。`ingestion/` 永远不会导入 `retrieval/`。`ingestion/readers/` 中的读取器模块是纯粹的叶函数：`(Path) -> str`。
---
## 开发设置
```bash
git clone https://github.com/SARAMALI15792/AgentRAG
cd AgentRAG
uv pip install -e ".[dev,office,ebooks,web]"
uv run pytest --tb=short
```
### 工具链
| 工具 | 命令 |
|------|---------|
| 格式 | `uv run black .` |
| 校验 | `uv run ruff check .` |
| 类型检查 | `uv run mypy --strict src/` |
| 测试 | `uv run pytest --tb=short` |
| 所有检查 | `uv run black . && uv run ruff check . && uv run mypy --strict src/` |
提交前钩子会自动运行所有三个检查。
### 项目布局
```
src/agentrag/
cli.py CLI入口点（typer）
config.py 所有运行时配置（pydantic-settings）
types.py 领域数据类 — 统一数据源
ingestion/ 读取器 → 分块器 → 嵌入器 → 管道
retrieval/ 搜索器，重新排序器，查询规划器，评估器，流式处理
store/ qdrant.py — qdrant_client的唯一导入者
sync/ 云同步后端（本地 + S3）
server/ MCP服务器，工具处理程序
tests/
unit/ 隔离，所有外部依赖被模拟
integration/ 真实的Qdrant嵌入，真实文件
scripts/
verify_phase*.sh 确定的阶段退出门
```
---
## 路线图
| 阶段 | 状态 | 可交付成果 |
|-------|--------|-------------|
| 1 — 核心管道 | ✅ 完成 | 读取 → 分块 → 嵌入 → 存储 |
| 2 — MCP服务器 | ✅ 完成 | 7个MCP工具，stdio + HTTP传输 |
| 3A — 扩展文件 | ✅ 完成 | DOCX，HTML，Python，Jupyter |
| 3B — 智能检索 | ✅ 完成 | 20+文件类型，`plan_query`，`search_multi`，`evaluate_chunks` |
| 4 — 搜索质量 | ✅ 完成 | 交叉编码器重新排序，元数据过滤强化 |
| 5 — 分发 | ✅ 完成 | PyPI包（`aicompatible-rag`），`uvx`入口点 |
| 6 — 多集合 | ✅ 完成 | 命名集合，流式检索 |
| 7 — 云同步 | ✅ 完成 | 加密推送/拉取到S3兼容后端 |
---
## 许可
MIT — 参见 [LICENSE](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器