本文内容
EdgeQuake:用 PostgreSQL GraphRAG 构建 MCP 智能体记忆
EdgeQuake 是用 Rust 编写的 GraphRAG 服务端,将文档检索与知识图谱整合在 PostgreSQL 中。借助 MCP,智能体在不同对话中都能从中检索证据。它尤其值得用于答案分散在多份文档中的问题,例如:某个产品使用的组件,受哪份供应商协议约束?
v0.40.12 版本于 2026年11月9日发布,适合作为评估这套架构的版本基线。如果团队已经在运维 PostgreSQL,将图谱、向量和文档数据放在同一个数据存储中,可以让系统更容易维护。
核查日期:。本文核查了该版本标签下的文档与实现。下文给出的是建议采用的评估步骤;Wavect 尚未运行这套 EdgeQuake 部署,也未独立复现其基准测试。
EdgeQuake v0.40.12 更新了什么?
v0.40.12 保留 schema 231,并调整混合查询和图谱读取。 该版本的升级说明说明,补丁将类型化向量查询的 SQL 语句时间预算提升到 15 秒,实际设置为 14,750 毫秒。图谱表已存在但切换状态未完成时,读取会被拒绝,直至迁移完成。
v0.40.11 已使用 schema 231。从旧版 v0.34.0 升级需要制定迁移计划。旧库依赖 AGE 时,请在副本中演练备份、恢复与图谱切换。v0.35.5 切换说明解释了为什么不含 AGE 的新 PostgreSQL 镜像无法直接打开旧 AGE 数据卷。
当答案藏在关系中,再考虑 GraphRAG
EdgeQuake 仓库 介绍基于 LightRAG 思路的 Rust 实现,包括摄取文档、提取实体与关系,并结合向量与图谱检索上下文。 PostgreSQL 保存文档数据,pgvector 负责向量搜索。图谱切换完成后,图谱查询使用 PostgreSQL 的 eq_graph_nodes 与 eq_graph_edges 表。
可以先用下面这组完全虚构的文档做评估:
| 文档 | 记录的事实 | 回答需要提供的证据 |
|---|---|---|
| 产品规格书 | Atlas 产品使用组件 C-17。 | 产品与组件的对应关系。 |
| 供应商协议 | 协议 S-24 适用于组件 C-17。 | 组件与协议的对应关系。 |
| 职责登记表 | 采购团队负责协议 S-24。 | 协议与负责团队的对应关系。 |
提问:“哪份协议会影响 Atlas 产品,由谁负责?”有用的回答需要为每一步关联提供正确出处。仅找到一段提到 Atlas 的文字还不够。提取出来的图谱关系也可能出错,因此,接受答案前应核对原文。
向量检索本身也能解决一部分跨文档问题,尤其是在分块合理、允许多轮检索时。应通过实际问题衡量加入图谱是否有帮助。我们的智能体图工程指南讨论更广泛的架构选择;本文聚焦 EdgeQuake 的部署与运行。
“一个 PostgreSQL”实际包含哪些组件
数据集中在一处,运行时仍有多个进程。该版本的 Docker Compose 文件 定义 PostgreSQL、Rust API、Web 前端及先于 API 启动的迁移服务。 发布方为 PostgreSQL 16、17 和 18 提供了带 pgvector 的镜像。全新部署使用 PostgreSQL 原生图谱表,无需 Apache AGE。
Rust 服务端是一个二进制程序。前端、可选的身份提供方,以及本地模型服务器,各有自己的运行要求。“一个 PostgreSQL”说明的是检索数据存在哪里;模型托管、备份和升级仍然需要纳入运维预算。
为了便于重复评估,先下载本文核查过的 Compose 文件,并在启动前检查所选镜像:
mkdir edgequake-0.40.12
cd edgequake-0.40.12
curl -fsSL \
https://raw.githubusercontent.com/raphaelmansuy/edgequake/v0.40.12/docker-compose.quickstart.yml \
-o docker-compose.quickstart.yml
export EDGEQUAKE_VERSION=0.40.12
docker compose -f docker-compose.quickstart.yml config --images将这个版本号保存在部署配置中,否则文件默认使用 latest。演示配置将对外发布的端口绑定到回环地址,并关闭身份认证。用作共享知识服务前,应先配置登录。下文的认证部分说明了需要添加的 Compose 覆盖配置。
MCP 记忆的流程:摄取、等待索引、检索证据
MCP 集成指南给出的网关端点是 POST /mcp,别名为 /api/v1/mcp。完整流程如下:
- 通过界面或 REST API 创建工作区,为指定身份授予访问权限。
- 具有写入权限的调用方通过
eq_ingest提交文本,使用eq_upload_*工具上传文件。 - 保存返回的任务标识,并轮询
eq_task_get。任务状态变为indexed后,文档才可供检索。 - 先调用
eq_search,再通过eq_fetch的view=toc查看现有证据。随后获取所需文本块或引用。 - 由宿主智能体组织答案,并保留来源引用。开启新对话后,需要再次检索相关证据。
这些 MCP 工具返回证据,供宿主智能体使用。独立的答案生成 API 是另一条调用路径。“第二大脑”可以用来概括持久保存、随时可检索的知识,但它并不代表系统会自动记录每次对话,也不能保证每个答案都正确。
只需要检索的连接器,应在 API 进程的环境中设置 EDGEQUAKE_MCP_PROFILE=query。默认的 control 配置也会开放写入工具,memory 是它的别名。采用只读查询配置后,需要通过界面、REST API 或另行配置的服务导入知识。
让智能体的权限与目标工作区一致
API 密钥说明区分了 edgequake:read、edgequake:query 和 edgequake:write。密钥的默认权限范围是读取和查询。应为智能体使用专用身份签发密钥,并将该身份的成员权限限制在实际需要的范围内。
按照认证快速入门启用登录。对于本文核查的 Compose 部署,需要设置 EDGEQUAKE_AUTH_ENABLED=true、EDGEQUAKE_DEV_MODE=false,保存强度足够且持久不变的 JWT_SECRET,配置首次管理员凭据,并通过 Compose 覆盖配置向 API 传入 EDGEQUAKE_CORS_ORIGINS。也应在这份 API 覆盖配置中设置 MCP profile;仅在宿主机 shell 中导出变量,这份 Compose 文件不会将其传入容器。项目支持通过 Keycloak/OIDC 实现 SSO,但身份服务的部署与账号生命周期需要单独配置。
工作区请求头用于选择上下文,访问范围则必须由授权检查来约束。该版本的API 密钥创建类型接受名称、权限范围和可选的有效期,没有工作区标识字段。即使客户端设置了默认工作区,也不能据此认定高权限用户的密钥被限制在该工作区内。
选一个获准访问的工作区和另一个工作区,用同一凭据分别测试。省略工作区请求头、撤销访问权限后,再重复测试。除搜索外,也要检查文档读取和图谱工具。如果需要继承上游系统的文档级访问权限,可参考我们的RAG 权限控制指南;单独进行工作区隔离,并不能证明源系统的文档权限已经得到落实。
向已启用认证的服务器发送经源码核查的 HTTP 查询
配置好服务器,并为虚构语料完成索引后,通过本地环境变量提供密钥、租户 ID 和工作区 ID。以下诊断请求对照了该版本的HTTP 传输校验与工具参数 schema。不要将凭据写入会提交到版本库的客户端配置。
curl --fail-with-body -sS http://localhost:8080/mcp \
-H "Authorization: Bearer $EDGEQUAKE_API_KEY" \
-H "X-Tenant-ID: $EDGEQUAKE_TENANT_ID" \
-H "X-Workspace-Id: $EDGEQUAKE_WORKSPACE_ID" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2026-07-28' \
-H 'Mcp-Method: tools/call' \
-H 'Mcp-Name: eq_search' \
--data-binary @- <<'JSON'
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "eq_search",
"arguments": {
"query": "Which agreement affects Product Atlas, and who owns it?",
"mode": "hybrid",
"budget": "standard",
"limit": 8
}
}
}
JSON这条网关诊断请求经过源码核查,尚未在实际运行的服务器上执行。常规 MCP 客户端还会完成初始化握手。远程部署应使用 HTTPS。检查返回的证据句柄和错误,包括 JSON-RPC 的 error 与 MCP 的 isError;收到 HTTP 响应本身,并不能证明检索成功。
hybrid 结合局部与全局图检索。默认的 mix 模式加入融合检索与重排序;下文的基准测试使用 Mix。记录评估结果时,应同时记录查询模式。
选用桥接程序前,先检查客户端的传输兼容性。该版本的stdio 桥接实现没有发送上述 method/name 请求头,也没有转发配置中的默认租户。这些细节限制了它在本次源码核查中能证明的多租户连接能力。采用通用 npx 配置示例前,应核对实际安装的包及其发出的请求。
要让数据全程留在本地,逐一检查模型角色
EdgeQuake 支持云端模型服务和本地模型端点。相比查看服务商标识,工作区模型角色说明更有助于判断数据流向:
| 角色 | 处理的数据 | 需要核对的配置 |
|---|---|---|
| 提取(Extract) | 文档文本与关系。 | 环境变量可能优先于工作区设置。 |
| 关键词与查询(Keyword、Query) | 问题;由服务器生成答案时使用的检索上下文。 | 同时检查两个角色,以及请求级覆盖设置。 |
| 摘要(Summary) | 需要合并的实体描述。 | 在核查版本中,此角色不使用已保存的 Connection。 |
| 嵌入(Embedding) | 需要转换为向量的文本。 | 更换模型或维度后,需要重建已存储的嵌入向量。 |
| 视觉(Vision) | PDF 页面图像。 | 检查上传设置,以及工作区的视觉模型。 |
| 重排序(Reranker,启用时) | 检索到的候选内容与问题。 | 在服务器级别配置。 |
角色文档说明,当已保存的 Connection 无法使用时,系统可能回退到工作区或服务器默认配置。使用 Ollama、LM Studio、MLX 或 llama.cpp 本地部署时,应核对可达端点与实际选中的模型角色。随后模拟本地端点故障,检查请求是否被发送给了其他服务商。
智能体自身使用的模型,也是一个数据去向。本地知识存储可以将原文片段返回给使用云端模型的 MCP 客户端。判断整个流程是否满足本地处理要求时,必须将最后这次模型调用计算在内。
模型服务安全指南说明,已保存的服务商密钥使用 AES-256-GCM 加密,密钥只能写入,不能通过 API 读回。应妥善持久保存 EDGEQUAKE_SECRETS_KEY:修改或丢失它,会导致已存储的密钥无法解密。交互式快速入门脚本每次运行都会生成新密钥,除非事先已导出该变量。静态加密保护的是存储中的凭据;配置的模型服务商仍会处理发送给它的请求。
先评估 PDF 提取结果,再相信图谱关系
PDF 处理指南介绍了文本提取,以及面向扫描页面和复杂版式的视觉处理。用一张实际表格、一个扫描页面,以及一份包含修订后组件编号的文档做测试。评估答案前,先检查提取的内容与来源引用。表格中提错的一行数据,可能在图谱中变成看似可信、实则错误的关系。
EdgeQuake 与 LightRAG:先看清缓存条件
项目公开的基准测试记录. 下列较早的项目方测试用于说明准确率和缓存条件。发布标签的变更记录中的最新有效对比来自 10 月 24 日的 medical-mid 数据包。72 个配对样本中,EdgeQuake 得分 0.8084,LightRAG 得分 0.7681。差值的 95% 置信区间为 [-0.0241, +0.1036],包含零。v0.40.12 未单独重新评分。
| 指标 | EdgeQuake | LightRAG | 测试条件与解读 |
|---|---|---|---|
| 答案准确率 | 0.792 | 0.786 | 2026年8月15日,medical-mid,n=200。未得出明确优胜者。 |
| 证据召回率 | 0.932 | 0.949 | 在准确率评估对应的测试中,LightRAG 的证据召回率更高。 |
| 上下文相关性 | 0.471 | 0.510 | 在同一评估中,LightRAG 的上下文相关性更高。 |
| 热缓存查询 p50 | 82 ms | 993 ms | 2026年8月15日,n=200,启用 LLM 与嵌入缓存。 |
| 冷查询 p50 | 4,447 ms | 4,359 ms | 2026年7月23日,n=40,关闭 LLM 缓存。延迟中位数接近。 |
准确率对比使用相同语料、问题、Mix 模式、Mistral Small 和 mistral-embed。准确率差值的 95% 置信区间为 [-0.022, +0.034],包含零。这个结果并不能证明两者的检索质量等同。
热缓存测试中,关键词、嵌入和生成阶段的耗时中位数都记录为零毫秒。因此,82 ms 不能用来说明通过新模型调用回答新问题需要多久。重复查询可能受益于这条缓存路径;首次查询的耗时应单独测量。
先在一个工作区完成有针对性的评估
我们建议从一小组获准使用的文档开始,选择需要明确实体关系才能回答的问题。导入前,先约定正确答案必须包含哪些证据。也应加入一个文档无法回答的问题。
- 核验 Atlas 示例中的完整关系链,并检查每一处引用的原文。
- 用选定的图检索模式和较简单的检索基线,分别回答同一组问题。
- 单独记录首次查询延迟、重复查询延迟、摄取耗时和模型成本。
- 使用第二个身份,检查工作区隔离、失效凭据以及被撤销的成员权限。
- 修改一条源事实,重新处理文档,再检查是否仍有冲突或过时的证据。
- 在测试环境中恢复数据库及所需密钥,然后再次检索。
使用 edgequake doctor 检查配置与数据库就绪情况,并在启动升级后的 API 前完成明确的迁移步骤。源码核查与进程健康状态为评估提供依据;文档、权限和恢复测试,才能判断这套部署是否适合你的实际工作。
当问题需要跨文档梳理关系,而团队又适合采用 PostgreSQL 运维时,EdgeQuake 值得评估。如果主要需求是在不同 IDE 之间共享编程决策,我们的 mcp-memory-service 配置指南更聚焦这个场景。需要在自建知识服务与现成产品之间做选择时,可参考定制软件与现成软件选型指南。
EdgeQuake、PostgreSQL 与 MCP 常见问题
EdgeQuake 是什么?
EdgeQuake 是一个开源的 Rust GraphRAG 服务端,使用 PostgreSQL、pgvector 和原生图谱表。它将导入的文档处理成可检索文本,以及包含实体与关系的图谱。MCP 客户端可以从这份持久存储中检索证据。
EdgeQuake 需要单独部署图数据库吗?
本文核查的 PostgreSQL 部署通过 pgvector 和原生图谱表,将向量与图谱数据保存在 PostgreSQL 中。完整系统还包括 API、前端和独立执行的迁移服务。本地模型服务器与可选的身份提供方会增加运行组件。
EdgeQuake 比 LightRAG 更快、更准确吗?
8 月的准确率对比没有明确优胜者。82 毫秒的热查询中位数使用了缓存,冷查询延迟相近。10 月更新评估的置信区间也包含零。
EdgeQuake MCP 能用作只读的智能体记忆吗?
在 API 上设置 EDGEQUAKE_MCP_PROFILE=query,并使用权限范围适当的读取和查询凭据。限制该身份的成员权限,并测试它能否访问其他工作区。新增知识需要通过这个只读查询连接器之外的授权摄取路径导入。
本地运行 EdgeQuake,就能让所有数据留在本地吗?
需要检查提取、关键词、摘要、嵌入、视觉、重排序和模型回退配置,也要检查宿主智能体使用的模型。即使 PostgreSQL 与 EdgeQuake 在本地运行,使用云端模型的客户端仍可能收到检索出的原文片段。
EdgeQuake v0.40.12 有哪些新功能?
补丁修复了混合查询过早超时的问题。图谱切换未完成时会拒绝读取。从 v0.40.11 升级时 schema 保持 231。旧 AGE 部署应先演练恢复与迁移。
