内容
# 智能检索增强生成系统 MCP
[](https://github.com/enached134-ctrl/agentic-rag-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.python.org/)
[](https://modelcontextprotocol.io)
<p align="center">
<img src="docs/img/01-architecture.png" alt="智能检索增强生成系统 — 多智能体图" width="880">
</p>
一个 **多智能体检索增强生成系统，作为 MCP 服务器暴露**。提出一个问题，[LangGraph](https://langchain-ai.github.io/langgraph/) 管道计划检索，从 **pgvector** 知识库中提取证据，可选地用实时网络研究增强，起草一个 **引用的答案**，然后 **自我批评** 以确保答案有来源支持 —— 直到答案得到来源支持。
它作为三个工具插入到任何 MCP 客户端（Claude Code/Desktop、Cursor、Windsurf、…）：`ingest`、`ask` 和 `search`。
> **为什么采用这种设计？** 一个裸 RAG 端点很容易复制；一个 **验证自己的答案并作为 MCP 服务器交付的多智能体系统** 却不容易。架构是护城河 —— “容易购买，难以复制。”
---
## 架构
```mermaid
flowchart LR
Q([问题]) --> P[🧭 计划器<br/>计划 + 搜索查询]
P --> R[📚 检索器<br/>pgvector top-k]
R --> W[🌐 网络研究员<br/>Firecrawl • 可选]
W --> S[✍️ 合成器<br/>引用答案]
S --> C{🔎 批评者<br/>有来源支持？}
C -- 需要修订 --> S
C -- 有来源支持 --> A([答案 + 引用])
subgraph 存储
DB[(Supabase<br/>pgvector)]
end
R <-->|余弦搜索| DB
classDef agent fill:#1e293b,stroke:#7C3AED,color:#e2e8f0;
class P,R,W,S,C agent;
```
| 智能体 | 模型 / 工具 | 责任 |
|---|---|---|
| **计划器** | Claude (`claude-opus-4-8`，自适应思考) | 将问题分解为聚焦的搜索查询 |
| **检索器** | Voyage 嵌入 + pgvector | 知识库上的余弦 top-k |
| **网络研究员** | Firecrawl *(可选)* | 在设置密钥时用实时网络结果增强 |
| **合成器** | Claude | 起草一个有来源支持的答案，并引用 `[n]` |
| **批评者** | Claude | 验证来源支持；如果不支持则循环修订 |
---
## MCP 工具
| 工具 | 参数 | 返回值 |
|---|---|---|
| `ingest` | `url: str` | 抓取 URL，分割并嵌入，存储。`{ url, chunks_added }` |
| `ask` | `question: str` | 运行完整管道。`{ answer, citations, plan, grounded }` |
| `search` | `query: str, k: int = 5` | 仅检索 — top-k 分割与相似度得分 |
---
## 快速入门
```bash
# 1. 安装（Python 3.10+）
uv venv && uv pip install -e ".[dev]" # 或：pip install -e ".[dev]"
# 2. 配置
cp .env.example .env # 填写 ANTHROPIC_API_KEY、VOYAGE_API_KEY、DATABASE_URL
# 3. 创建向量表（Supabase SQL 编辑器或 psql）
psql "$DATABASE_URL" -f sql/schema.sql
# 4. 运行 MCP 服务器（默认为标准输出）
agentic-rag-mcp
```
### 连接到 Claude Code
```bash
claude mcp add agentic-rag -s user \
--env ANTHROPIC_API_KEY=sk-ant-... \
--env VOYAGE_API_KEY=pa-... \
--env DATABASE_URL=postgresql://... \
-- agentic-rag-mcp
```
然后，从客户端： *"ingest https://example.com/docs"* → *"ask: 如何配置 X?"*。
---
## 工作原理
1. **计划** — Claude 将问题转化为一个短计划 + 1-5 个搜索查询。
2. **检索** — 每个查询都被嵌入（Voyage `voyage-3.5`）并通过余弦距离与 pgvector 匹配；结果被去重并排名。
3. **研究** — 如果设置了 `FIRECRAWL_API_KEY`，则将实时网络结果添加到上下文中。
4. **合成** — Claude 编写一个仅基于编号上下文的答案，并引用每个声明为 `[n]`。
5. **批评** — 一个严格的事实检查通行证决定答案是否完全支持。如果不支持（并且修订仍然存在），则循环返回到合成器并提供反馈。
通过环境变量可配置：`RAG_MODEL`、`RAG_TOP_K`、`RAG_MAX_REVISIONS`、`RAG_EMBED_MODEL`。
<p align="center">
<img src="docs/img/05-live-retrieval.png" alt="pgvector 上的实时检索" width="820">
</p>
<p align="center"><sub>pgvector 上的实时检索 — Voyage 嵌入，真实余弦相似度（演示性演示语料库）。</sub></p>
---
## 评估 — CI 门控
答案质量通过 [promptfoo](https://promptfoo.dev) 在 **黄金数据集**（[`evals/golden.yaml`](evals/golden.yaml) — 20 个种子案例：可回答 / 拒绝 / 对抗性，针对已提交的语料库编写）进行衡量，并在 **每次推送时在 CI 中强制执行**：`evals` 作业启动一个 pgvector 服务容器，用 `evals/corpus/` 播种它，并通过真实管道运行每个案例 — 计划器、检索器、合成器、自我批评。没有任何模拟。回归 **在到达用户之前会破坏构建**。
评分维度：**引用存在**（确定性）· **基础性**（LLM 作为裁判）· **拒绝正确性**（LLM 作为裁判）· **延迟**（阈值）。
```bash
python evals/seed.py --schema --reset # 将语料库播种到向量存储中
make eval # 在本地运行套件
```
查看 [`evals/`](evals/) 以获取语料库、黄金数据集和回归捕获规则：每个现实世界的失败都成为一个新的黄金案例，因此没有 bug 被修复两次。
> 当配置 `ANTHROPIC_API_KEY` 和 `VOYAGE_API_KEY` 仓库秘密时，CI 门控激活；如果没有它们（例如在分支中），作业将跳过并显示可见通知。
---
## 可观察性
选择加入 OpenTelemetry 跟踪到 [Arize Phoenix](https://phoenix.arize.com/)：
```bash
pip install -e ".[trace]"
phoenix serve # 本地 Phoenix UI on :6006
PHOENIX_ENABLED=1 agentic-rag-mcp
```
每次 `ask` 运行都显示为一个完整的跟踪 — LangGraph 节点跨度（计划 → 检索 → 研究 → 合成 → 批评）加上每个 Claude 调用及其 token 使用和每个跨度的延迟。 将 `PHOENIX_COLLECTOR_ENDPOINT` 指向托管的收集器以将跟踪发送到外部。
---
## 部署
容器化并准备好用于 [Railway](https://railway.app)（HTTP 传输）：
```bash
railway up # 使用 Dockerfile + railway.json；设置 RAG_TRANSPORT=http
```
公开 `RAG_HTTP_PORT` 并通过 `--transport http` 连接。 `cloudflared` 隧道适用于本地演示。
### Kubernetes
生产环境的配置文件 — 就绪/活跃度探测、资源限制、机密驱动的环境变量 — 存放在 [`deploy/k8s/`](deploy/k8s/) 中，包括一个基于 [kind](https://kind.sigs.k8s.io/) 的本地烟雾测试演练。
---
## 项目布局
```
src/agentic_rag_mcp/
config.py # 环境变量驱动的设置
llm.py # Anthropic (Claude) 助手 — 自适应思考、JSON 解析
embeddings.py # Voyage 嵌入
store.py # pgvector 存储（psycopg）
web.py # Firecrawl 网络研究（可选）
ingest.py # 分割 + ingestion
state.py # LangGraph 状态
nodes.py # 计划器 / 检索器 / 研究人员 / 合成器 / 批评者
graph.py # 图表组装
tracing.py # 可选 OpenTelemetry → Arize Phoenix
server.py # FastMCP 服务器（ingest / ask / search）
sql/schema.sql # pgvector 架构
evals/ # 黄金数据集 + 语料库 + promptfoo 套件（在 CI 中运行）
deploy/k8s/ # Kubernetes 配置文件 + kind 烟雾测试
```
## License
MIT — 请参阅 [LICENSE](LICENSE)。
