1. 为什么你的 AI 应用需要一个可查询的知识图谱服务如果你正在做 AI 助手、智能客服或者代码 Agent大概率遇到过这个尴尬模型聊到第三轮就忘了前面说过的实体关系用户问「上次那个订单关联的供应商是谁」它只能编。传统做法是把历史对话塞进向量库做 RAG但向量检索擅长「相似」不擅长「关系」——它没法告诉你 A 实体通过哪条边连到 B 实体也没法做多跳推理。Graphiti 就是冲着这个痛点来的。它是一个面向动态环境的时序知识图谱框架底层用 Neo4j 存图上层通过 MCPModel Context Protocol协议把「写事件、查实体、搜关系」这些能力暴露给 AI 客户端。简单说你给它一段对话或一篇文档它自动抽实体、抽关系、打时间戳存成图之后 AI 助手通过 MCP 工具调用就能查这张图。适合谁适合需要给 AI 应用加「长期记忆 关系推理」的开发者尤其是已经在用 Cursor、Claude Desktop、Cline 这类支持 MCP 的工具的人。我实测下来整套链路跑通的关键不在 Graphiti 本身而在三件事Neo4j 能不能连上、MCP 客户端的配置格式对不对、以及模型 API 的 Base URL 有没有配对。这篇就按「从零到可用」的顺序把服务端配置、MCP 客户端接入、图谱写入与检索验证、以及几个真实报错的排查过程完整走一遍。你跟着做最后应该能在一个支持 MCP 的客户端里用自然语言让 AI 往图谱里写数据、再查出来。先明确整体架构避免后面配置时迷路AI 客户端 (Cursor / Claude Desktop / Cline) │ MCP 协议 (SSE 或 stdio) ▼ Graphiti MCP Server (端口 8000) │ ├──► Neo4j (bolt://localhost:7687) 存图 └──► 模型 API (Base URL Key Model ID) 做实体抽取三个组件缺一不可。很多人卡在最后一步模型 API 用的是默认 OpenAI 地址但手里只有别的平台的 Key于是实体抽取一直失败。这里我用的模型接入层是 TaoToken它的 API 地址是https://taotoken.net/api兼容 OpenAI 的 chat completions 格式所以 Graphiti 里只要把OPENAI_BASE_URL指过去、OPENAI_API_KEY换成对应 Key 就行。下面第二节先把这块前置讲清楚。2. TaoToken 前置准备拿到 Base URL、Key 和 Model ID 三件套Graphiti 做实体抽取和关系推断时会调用一个兼容 OpenAI 协议的模型接口。默认它读OPENAI_API_KEY和OPENAI_BASE_URL两个环境变量。如果你直接用官方地址需要能访问对应服务如果你用 TaoToken 这类聚合接入层就把 Base URL 换成https://taotoken.net/apiKey 换成在控制台生成的令牌。具体操作路径是这样的先打开官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册登录然后进控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite创建 API Key。创建完记得复制保存页面关掉就看不到了。模型 ID 可以在模型对话页https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite里挑一个比如gpt-4o-mini这类性价比高的做实体抽取足够复杂关系推断可以换更强的模型。这里有个容易踩的坑Graphiti 内部有些版本会硬编码调用gpt-4o或gpt-4o-mini如果你选的模型 ID 和它默认的不一致要么在配置里显式指定MODEL_NAME要么确保你的 Key 有对应模型权限。我建议一开始就用gpt-4o-mini便宜且够用等图谱规模上来了再换。三件套整理成表格后面配置直接抄配置项值说明Base URLhttps://taotoken.net/api兼容 OpenAI 协议注意结尾不带/v1API Key控制台生成的sk-开头令牌只显示一次务必保存Model IDgpt-4o-mini实体抽取够用可换注意Base URL 填https://taotoken.net/api即可Graphiti 和 OpenAI SDK 会自动拼接/v1/chat/completions。如果你手动填了/v1有些版本会拼成/v1/v1/...导致 404。拿到这三样之后先别急着配 Graphiti用一条 curl 验证 Key 和 Base URL 是通的能省掉后面一半的排查时间curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: ping}] }返回里有choices[0].message.content就说明模型侧通了。这一步过了再往下配 Graphiti出问题就只可能是 Neo4j 或 MCP 配置排查范围直接砍一半。如果这一步就报 401回去检查 Key 有没有复制全、有没有多余空格报 model not found就去模型对话页确认这个模型 ID 在你的账号下可用。3. 可复制配置Graphiti 服务端 MCP 客户端完整片段这一节是全文的核心所有配置我都给完整片段路径和字段名保持和实际一致你复制后改 Key 和密码就能用。3.1 Neo4j 与 Graphiti 的 docker-compose 配置先起 Neo4j再起 Graphiti。新建一个目录放docker-compose.ymlversion: 3.8 services: neo4j: image: neo4j:5.26.0 ports: - 7474:7474 # HTTP 浏览器 - 7687:7687 # Bolt 协议 environment: - NEO4J_AUTHneo4j/your_password_here volumes: - neo4j_data:/data graphiti: image: zepai/graphiti:latest ports: - 8000:8000 environment: - NEO4J_URIbolt://neo4j:7687 - NEO4J_USERneo4j - NEO4J_PASSWORDyour_password_here - OPENAI_API_KEYsk-你的TaoTokenKey - OPENAI_BASE_URLhttps://taotoken.net/api - MODEL_NAMEgpt-4o-mini depends_on: - neo4j volumes: neo4j_data:几个字段说明NEO4J_AUTH的格式是用户名/密码密码自己定别用默认的neo4j/neo4jNeo4j 5.x 首次启动会强制改密码。OPENAI_BASE_URL就是上一节拿到的 TaoToken 地址注意这里不带/v1。MODEL_NAME对应你选的模型 ID。启动命令docker compose up -d起来之后先看 Neo4j 是否就绪浏览器打开http://localhost:7474用neo4j/your_password_here登录能进就说明图库没问题。再看 Graphiti 健康检查curl http://localhost:8000/health返回{status:ok}之类的就说明服务端起来了。3.2 MCP 客户端配置Cursor / Claude Desktop / ClineGraphiti 的 MCP Server 默认走 SSE地址是http://localhost:8000/sse。不同客户端的配置格式不一样我逐个给。Cursor 的配置在~/.cursor/mcp.jsonWindows 是%USERPROFILE%\.cursor\mcp.json{ mcpServers: { graphiti-memory: { url: http://localhost:8000/sse } } }Claude Desktop 的配置在~/Library/Application Support/Claude/claude_desktop_config.jsonWindows 是%APPDATA%\Claude\claude_desktop_config.json它不支持直接填 url需要用mcp-remote桥接{ mcpServers: { graphiti-memory: { command: npx, args: [ mcp-remote, http://localhost:8000/sse ] } } }ClineVS Code 插件的配置在插件设置里的 MCP Servers格式和 Cursor 类似也是填 url。如果你用的是 Codex 这类走auth.json的工具配置思路一样把 Base URL、Key、Model ID 三件套填进对应字段即可只是文件路径不同。注意Claude Desktop 用mcp-remote需要本机有 Node.js 和 npx。如果启动后 MCP 工具列表是空的先在终端手动跑一遍npx mcp-remote http://localhost:8000/sse看有没有报错比在客户端里盲猜快得多。配置改完重启客户端。Cursor 里在设置 → MCP 能看到graphiti-memory是绿色就通了Claude Desktop 重启后对话输入框旁边会出现工具图标。这一步过了服务端和客户端就算接上了。4. 验证请求往图谱写数据再查出来配置通了不代表能用得实际写一条数据、再查出来才算闭环。Graphiti 的 MCP 工具主要有几个add_episode写事件、search_nodes搜实体、search_facts搜关系、get_episodes查事件。我在 Cursor 里实测的流程如下。4.1 写入一条事件在 Cursor 的对话里直接说请调用 graphiti-memory 的 add_episode 工具添加一条事件 name: 项目启动会 episode_body: 张三负责后端李四负责前端项目代号 Phoenix计划两周后上线。 source: text模型会调用 MCP 工具Graphiti 收到后做实体抽取识别出「张三」「李四」「Phoenix」三个实体以及「负责」「代号」这些关系打上时间戳写进 Neo4j。返回结果里会有uuid和抽取到的实体列表。如果这一步报错最常见的是模型侧 401 或超时回去看第二节的 curl 是否还通。另一个常见报错是reading choices意思是模型返回体里没有choices字段通常是 Base URL 拼错或模型 ID 不存在见第五节。4.2 检索实体和关系写入成功后换个对话问请调用 search_nodes查询 Phoenix 相关的实体。正常返回会包含「Phoenix」节点以及和它相连的「张三」「李四」。再试关系检索请调用 search_facts查询 谁负责前端。应该返回「李四 - 负责 - 前端」这条边。到这一步说明写入、抽取、存储、检索整条链路都通了。4.3 直接查 Neo4j 确认落库如果 MCP 返回正常但你不放心直接去 Neo4j 浏览器验证MATCH (n) RETURN n LIMIT 25能看到节点和关系就说明数据真的落库了。Graphiti 会给节点打上Entity标签关系上带时间戳属性。这一步是排查「MCP 说成功但查不到」的终极手段——如果 Neo4j 里没有问题在写入侧如果有但 MCP 查不到问题在检索侧。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节按真实报错对照每个都给现象、原因、解决。401 Unauthorized。现象add_episode 时返回 401。原因九成是OPENAI_API_KEY没配对或者 Key 复制时带了空格。解决进容器确认环境变量docker exec -it graphiti容器名 env | grep OPENAI看 Key 和 Base URL 是否正确。注意 Base URL 结尾不要带/v1。local proxy failed / connection refused。现象MCP 客户端连不上http://localhost:8000/sse。原因Graphiti 容器没起来或者端口没映射。解决docker compose ps看 graphiti 是否 runningcurl http://localhost:8000/health看是否响应。如果容器在跑但 curl 不通检查ports映射有没有写错。reading choices of undefined。现象写入时报这个错。原因模型返回体结构不对通常是 Base URL 拼成了https://taotoken.net/api/v1SDK 又拼了一次/v1变成/v1/v1/chat/completions返回 404 页面而不是 JSON。解决Base URL 只填https://taotoken.net/api。OAuth / authentication error。现象Claude Desktop 里 MCP 工具加载失败提示 OAuth 相关。原因mcp-remote版本问题或 SSE 端点需要鉴权。解决先手动跑npx mcp-remote http://localhost:8000/sse看具体报错如果是版本问题npx mcp-remotelatest强制用最新版。Graphiti 本地部署默认不需要 OAuth如果提示这个多半是客户端把远程 MCP 的鉴权流程套上来了确认 url 是本地地址。Neo4j 连接超时。现象Graphiti 日志里报Unable to connect to bolt://neo4j:7687。原因docker-compose 里 graphiti 的depends_on只保证启动顺序不保证 Neo4j 就绪。解决等 Neo4j 完全起来再重启 graphiti或者加 healthcheck。实测 Neo4j 首次启动要 20 到 30 秒急着起 graphiti 必报这个。排查顺序建议固定成先 curl 模型接口 → 再 curl Graphiti health → 再查 Neo4j → 最后看 MCP 客户端。按这个顺序问题基本一次定位。6. 长期跑图谱服务把 Coding Plan 和接入文档用起来图谱服务搭起来只是开始真正要长期用有两个现实问题一是模型调用成本实体抽取是高频操作每条事件都要调一次模型二是配置维护MCP 客户端和 Graphiti 版本都在迭代配置格式偶尔会变。成本这块如果你打算把 Graphiti 接到日常编码或 Agent 工作流里长期跑可以看下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite它针对高频编码和 Agent 场景做了额度优化比按量单独调模型划算。我自己的用法是实体抽取用便宜模型走量复杂关系推断偶尔切强模型这样整体成本可控。配置维护这块建议把三件套Base URL、Key、Model ID统一放在一个.env文件里docker-compose 用env_file引入MCP 客户端配置里不要硬编码 Key。这样换 Key 或换模型时只改一处。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有各客户端的配置示例和模型列表遇到格式问题先翻文档比搜博客快。最后给一个我踩过的坑Graphiti 的 MCP 工具名在不同版本里可能有细微差异比如add_episode和add_memory都出现过。如果你在客户端里看到的工具名和我写的不一样以客户端实际列出的为准功能是对应的。验证模型是否可用可以去模型对话页https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite直接试确认模型 ID 拼写无误再填进配置。API Key 管理在控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteKey 泄露了及时删掉重建。整套跑通后你的 AI 助手就有了一个能查关系、能追时序的图记忆比纯向量 RAG 在「谁和谁有关系」这类问题上靠谱得多。