Graphiti（GitHub 约 3.2 万 Star）是 Zep 团队开源的时序上下文图谱框架，官方定位「a framework for building and querying temporal context graphs for AI agents」。与静态知识图谱不同，Graphiti 会跟踪事实随时间的变化、保留数据来源、支持混合检索。本文基于官方 README 的 Installation 与 Quick Start 章节。
一、项目介绍与适用场景
Graphiti 是一个Python 库，不是独立服务：你给它文本/结构化数据，它自动抽实体关系写入 Neo4j / FalkorDB / Amazon Neptune，查询时做混合检索 + 图谱距离重排。Zep Cloud 就是基于它构建的商业产品。
典型场景：
- 给 Agent 加长期记忆：跨会话记住用户偏好。
- 企业动态知识库：组织架构、项目关系随时间演进。
- 替代纯向量 RAG：图谱关系比向量更精准。
二、核心功能逐条拆解
- 时序图谱：事实带时间戳，能回答「当时」vs「现在」。
- 自动实体抽取：文本自动变成节点和边。
- 混合检索：语义 + 图谱距离重排。
- 多图后端：Neo4j、FalkorDB、Amazon Neptune。
- MCP / REST 参考服务器：
mcp_server和server目录提供参考实现。 - 多 LLM 支持：OpenAI 默认，Anthropic/Gemini/Groq 可装 extra。
- 并发控制：
SEMAPHORE_LIMIT环境变量控制并发。
三、全套官方链接
| 类型 | 链接 |
|---|---|
| GitHub 仓库 | https://github.com/getzep/graphiti |
| 官方文档 | https://help.getzep.com |
| 官方 Demo | https://www.getzep.com |
| License | Apache-2.0 |
四、硬件与环境前置要求
官方 README 明确：
- Python 3.10+
- 图数据库：Neo4j 5.26 / FalkorDB 1.1.2 / Amazon Neptune
- OpenAI API Key（默认 LLM 与 embedding）
- 可选：Anthropic / Gemini / Groq Key
五、多平台部署步骤
5.1 pip 安装
官方 README 原文：
pip install graphiti-core
或：
uv add graphiti-core
FalkorDB 支持：
pip install graphiti-core[falkordb]
LLM provider extras：
pip install graphiti-core[anthropic,groq,google-genai]
5.2 启动图数据库（FalkorDB 官方一行命令）
官方 README 原文：
docker run -p 6379:6379 -p 3000:3000 -it --rm falkordb/falkordb:latest
逐段解释：FalkorDB 是兼容 Redis 的图数据库，一行 Docker 起，自带 3000 端口的 Web 界面。
Neo4j 用户官方推荐 Neo4j Desktop，或用仓库自带 docker compose：
docker compose up
FalkorDB profile：
docker compose --profile falkordb up
5.3 配置 LLM
官方 README 说明：默认用 OpenAI，设置 OPENAI_API_KEY 即可；其他 provider 通过 extra 安装。
六、配置文件全部参数解释
| 参数 | 作用 | 默认值 |
|---|---|---|
OPENAI_API_KEY |
OpenAI 密钥 | 无 |
SEMAPHORE_LIMIT |
并发数 | 10 |
| 图数据库连接串 | Neo4j/FalkorDB 地址 | 代码里配置 |
官方说明：遇到 429 限流就调小 SEMAPHORE_LIMIT；想提速就调大。
七、启动、后台常驻与开机自启
Graphiti 是库，不是服务，由你的 Python 应用托管。官方提供的 MCP/REST 参考服务器明确标注「无鉴权、不要暴露公网」。
八、功能实操教程
第 1 步：pip install graphiti-core。
第 2 步：docker run -p 6379:6379 -p 3000:3000 -it --rm falkordb/falkordb:latest 起图数据库。
第 3 步：设 export OPENAI_API_KEY=sk-xxx。
第 4 步：按官方 examples/quickstart 写 Python 脚本：初始化 Graphiti、add_episode 写入文本、search 查询。
第 5 步：访问 FalkorDB 的 http://localhost:3000 看图谱。
九、全套报错故障排查
-
报错原文：429 Rate Limit from OpenAI/Anthropic 原因分析：Graphiti 抽取时并发调用 LLM 太猛，触发厂商限流。 解决方案：官方 README 给出
SEMAPHORE_LIMIT环境变量，默认 10；遇到 429 就export SEMAPHORE_LIMIT=3或 5，等 LLM 配额恢复再调大。 -
报错原文：图数据库连不上 ConnectionRefusedError 原因分析：FalkorDB 或 Neo4j 没启动，或端口不对。 解决方案：
docker ps确认容器在跑；FalkorDB 默认 6379 端口，Neo4j 默认 7687；代码里连接串端口要对应。 -
报错原文：抽取 schema 错误 / 输出不是预期 JSON 原因分析：官方 README 明确警告——Graphiti 依赖 LLM 的 Structured Output 能力，小模型或不支持的 provider 会出错。 解决方案：换 OpenAI、Anthropic、Gemini 这些官方支持的 provider；本地小模型请通过 OpenAI 兼容端点并确认其支持 structured output。
-
报错原文：
add_episode很慢 原因分析：默认SEMAPHORE_LIMIT=10是为了避免 429 故意调低。 解决方案：如果你的 LLM 配额充足，把SEMAPHORE_LIMIT调到 20~50 提速。 -
报错原文：Kuzu deprecated 警告 原因分析：官方已废弃 Kuzu 后端（上游 Kuzu 项目不再维护）。 解决方案：新项目直接用 Neo4j 或 FalkorDB；存量项目按官方迁移指南换后端。
-
报错原文：MCP 参考服务器暴露公网被攻击 原因分析：官方 README 明确警告
mcp_server和server目录是参考实现，无鉴权、无注入过滤、默认密码。 解决方案：生产环境不要直接暴露参考服务器；要么用graphiti-core库嵌入自己的服务（自己加鉴权和输入过滤），要么用 Zep 商业版。
十、升级、回滚与卸载
升级：pip install -U graphiti-core。
卸载：pip uninstall graphiti-core。
十一、商用许可与合规风险提示
Graphiti 采用 Apache-2.0，商用友好。注意：官方 README 明确说明 MCP/REST 参考服务器无鉴权，生产环境必须自己在前面加认证，或直接用 graphiti-core 库嵌入自己的服务。
参考链接：
- Graphiti GitHub README：https://github.com/getzep/graphiti
- Zep 文档：https://help.getzep.com
- Quickstart 示例：https://github.com/getzep/graphiti/tree/main/examples/quickstart