wehub/getzep--graphiti
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity

docs: make Chinese README the default
Lint with Ruff / ruff (push) Has been cancelled
Details
CodeQL Advanced / Analyze (actions) (push) Has been cancelled
Details
CodeQL Advanced / Analyze (python) (push) Has been cancelled
Details
Tests / unit-tests (push) Has been cancelled
Details
Tests / database-integration-tests (push) Has been cancelled
Details
Pyright Type Check / pyright (push) Has been cancelled
Details

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 10:31:46 +00:00
parent 2651277f7a
commit 1dea06d045
1 changed files with 201 additions and 240 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+201 -240
View File
@@ -1,3 +1,9 @@
<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/getzep/graphiti) · [上游 README](https://github.com/getzep/graphiti/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
<p align="center">
<a href="https://www.getzep.com/">
<img src="https://github.com/user-attachments/assets/119c5682-9654-4257-8922-56b7cb8ffd73" width="150" alt="Zep Logo">
@@ -7,7 +13,7 @@
<h1 align="center">
Graphiti
</h1>
<h2 align="center">Build Temporal Context Graphs for AI Agents</h2>
<h2 align="center">为 AI Agent 构建时序上下文图（Temporal Context Graph）</h2>
<div align="center">
@@ -28,31 +34,25 @@ Graphiti
</div>
> [!NOTE]
> **We're Hiring!** Build context graphs that power reliable, personalized, fast production AI agents.
> Come build with us — we're hiring Engineers and Developer Relations folks. [View open roles](https://www.getzep.com/careers/).
> **我们正在招聘！** 构建为可靠、个性化、高速的生产级 AI Agent 提供动力的上下文图。
> 加入我们，一起构建 — 我们正在招聘工程师和开发者关系（Developer Relations）岗位。[查看开放职位](https://www.getzep.com/careers/).
⭐ *Help us reach more developers and grow the Graphiti community. Star this repo!*
⭐ *帮助我们触达更多开发者，壮大 Graphiti 社区。请为本仓库点 Star！*
&nbsp;
> [!TIP]
> Check out the new [MCP server for Graphiti](mcp_server/README.md)! Give Claude, Cursor, and other MCP clients powerful
> context graph-based memory with temporal awareness.
> 来看看全新的 [Graphiti MCP 服务器](mcp_server/README.md)！为 Claude、Cursor 及其他 MCP 客户端提供强大的、具备时序感知能力的基于上下文图的记忆能力。
Graphiti is a framework for building and querying temporal context graphs for AI agents. Unlike static knowledge graphs,
Graphiti's context graphs track how facts change over time, maintain provenance to source data, and support both
prescribed and learned ontology — making them purpose-built for agents operating on evolving, real-world data.
Graphiti 是一个用于为 AI Agent 构建和查询时序上下文图的框架。与静态知识图谱不同，Graphiti 的上下文图会追踪事实如何随时间变化，保留到源数据的溯源（provenance），并同时支持规定式与学习式本体（ontology）——因此专为在持续演化的真实世界数据上运行的 Agent 而设计。
Unlike traditional retrieval-augmented generation (RAG) methods, Graphiti continuously integrates user interactions,
structured and unstructured enterprise data, and external information into a coherent, queryable graph. The framework
supports incremental data updates, efficient retrieval, and precise historical queries without requiring complete graph
recomputation, making it suitable for developing interactive, context-aware AI applications.
与传统检索增强生成（Retrieval-Augmented Generation，RAG）方法不同，Graphiti 持续将用户交互、结构化和非结构化企业数据以及外部信息整合为一个连贯、可查询的图。该框架支持增量数据更新、高效检索和精确的历史查询，且无需对整个图进行完全重算，因此适合开发交互式、具备上下文感知能力的 AI 应用。
Use Graphiti to:
使用 Graphiti 可以：
- Build context graphs that evolve with every interaction — tracking what's true now and what was true before.
- Give agents rich, structured context instead of flat document chunks or raw chat history.
- Query across time, meaning, and relationships with hybrid retrieval (semantic + keyword + graph traversal).
- 构建随每次交互而演化的上下文图 — 追踪当前何为真、此前何为真。
- 为 Agent 提供丰富的结构化上下文，而非扁平的文档块或原始聊天历史。
- 通过混合检索（语义 + 关键词 + 图遍历）跨时间、语义和关系进行查询。
&nbsp;
@@ -62,123 +62,103 @@ Use Graphiti to:
&nbsp;
## What is a Context Graph?
## 什么是上下文图（Context Graph）？
A **context graph** is a temporal graph of entities, relationships, and facts — like *"Kendra loves Adidas shoes (as of
March 2026)."* Unlike traditional knowledge graphs, each fact in a context graph has a validity window: when it became
true, and when (if ever) it was superseded. Entities evolve over time with updated summaries. Everything traces back to
**episodes** — the raw data that produced it.
**上下文图**是实体、关系与事实的时序图 — 例如 *"Kendra 喜欢 Adidas 鞋（截至 2026 年 3 月）。"* 与传统知识图谱不同，上下文图中的每条事实都有一个有效期窗口：它何时变为真，以及（若有）何时被取代。实体会随时间演化，摘要也会更新。一切均可追溯到 **episodes** — 产生这些内容的原始数据。
What makes Graphiti unique is its ability to autonomously build context graphs from unstructured and structured data,
handling changing relationships while preserving full temporal history.
Graphiti 的独特之处在于，它能够从非结构化与结构化数据中自主构建上下文图，在处理变化中的关系的同时保留完整的时序历史。
A context graph contains:
上下文图包含：
| Component | What it stores |
| 组件 | 存储内容 |
|-----------|---------------|
| **Entities** (nodes) | People, products, policies, concepts — with summaries that evolve over time |
| **Facts / Relationships** (edges) | Triplets (Entity → Relationship → Entity) with temporal validity windows |
| **Episodes** (provenance) | Raw data as ingested — the ground truth stream. Every derived fact traces back here |
| **Custom Types** (ontology) | Developer-defined entity and edge types via Pydantic models |
| **Entities（实体）**（节点） | 人物、产品、政策、概念 — 附带随时间演化的摘要 |
| **Facts / Relationships（事实 / 关系）**（边） | 三元组（Entity → Relationship → Entity），附带时序有效期窗口 |
| **Episodes（溯源片段）**（provenance） | 按摄入方式保存的原始数据 — 即真实数据流。每条衍生事实均可追溯至此 |
| **Custom Types（自定义类型）**（ontology） | 开发者通过 Pydantic 模型定义的实体与边类型 |
## Graphiti and Zep
## Graphiti 与 Zep
Graphiti is the open-source temporal context graph engine at the core of
[Zep's](https://www.getzep.com) context infrastructure for AI agents. Zep manages context graphs at scale, providing
governed, low-latency context retrieval and assembly for production agent deployments.
Graphiti 是 [Zep](https://www.getzep.com) AI Agent 上下文基础设施核心的开源时序上下文图引擎。Zep 大规模管理上下文图，为生产级 Agent 部署提供受治理、低延迟的上下文检索与组装能力。
Using Graphiti, we've demonstrated Zep is
the [State of the Art in Agent Memory](https://blog.getzep.com/state-of-the-art-agent-memory/).
借助 Graphiti，我们已证明 Zep 是 [Agent 记忆领域的最先进方案（State of the Art in Agent Memory）](https://blog.getzep.com/state-of-the-art-agent-memory/).
Read our paper: [Zep: A Temporal Knowledge Graph Architecture for Agent Memory](https://arxiv.org/abs/2501.13956).
阅读我们的论文：[Zep: A Temporal Knowledge Graph Architecture for Agent Memory](https://arxiv.org/abs/2501.13956).
We're excited to open-source Graphiti, believing its potential as a context graph engine reaches far beyond memory
applications.
我们很高兴将 Graphiti 开源，并相信其作为上下文图引擎的潜力远不止于记忆类应用。
<p align="center">
<a href="https://arxiv.org/abs/2501.13956"><img src="images/arxiv-screenshot.png" alt="Zep: A Temporal Knowledge Graph Architecture for Agent Memory" width="700px"></a>
</p>
## Zep vs Graphiti
## Zep 与 Graphiti 对比
| Aspect | Zep | Graphiti |
| 方面 | Zep | Graphiti |
|--------|-----|---------|
| **What they are** | Managed context graph infrastructure for AI agents | Open-source temporal context graph engine |
| **Context graphs** | Manages vast numbers of per-user/entity context graphs with governance | Build and query individual context graphs |
| **User & conversation management** | Built-in users, threads, and message storage | Build your own |
| **Retrieval & performance** | Pre-configured, production-ready retrieval with sub-200ms performance at scale | Custom implementation required; performance depends on your setup |
| **Developer tools** | Dashboard with graph visualization, debug logs, API logs; SDKs for Python, TypeScript, and Go | Build your own tools |
| **Enterprise features** | SLAs, support, security guarantees | Self-managed |
| **Deployment** | Fully managed or in your cloud | Self-hosted only |
| **定位** | 面向 AI Agent 的托管式上下文图基础设施 | 开源时序上下文图引擎 |
| **上下文图** | 以治理方式管理海量按用户/实体划分的上下文图 | 构建并查询单个上下文图 |
| **用户与会话管理** | 内置用户、线程与消息存储 | 需自行构建 |
| **检索与性能** | 预配置、可用于生产的检索，大规模下可实现亚 200ms 性能 | 需自行实现；性能取决于你的部署配置 |
| **开发者工具** | 带图可视化、调试日志、API 日志的仪表盘；提供 Python、TypeScript 与 Go SDK | 需自行构建工具 |
| **企业级能力** | SLA、支持、安全承诺 | 自行运维 |
| **部署方式** | 全托管或部署在你的云中 | 仅支持自托管 |
### When to choose which
### 如何选择
**Choose Zep** if you want a turnkey, enterprise-grade platform with security, performance, and support baked in.
**选择 Zep**：如果你需要开箱即用、企业级平台，且安全、性能与支持均已内置。
**Choose Graphiti** if you want a flexible OSS core and you're comfortable building/operating the surrounding system.
**选择 Graphiti**：如果你需要灵活的开源核心，并愿意自行构建/运维周边系统。
## Why Graphiti?
## 为什么选择 Graphiti？
Traditional RAG approaches often rely on batch processing and static data summarization, making them inefficient for
frequently changing data. Graphiti addresses these challenges by providing:
传统 RAG 方法往往依赖批处理与静态数据摘要，因此在频繁变化的数据场景下效率较低。Graphiti 通过以下能力应对这些挑战：
- **Temporal Fact Management:** Facts have validity windows. When information changes, old facts are
invalidated — not deleted. Query what's true now, or what was true at any point in time.
- **Episodes & Provenance:** Every entity and relationship traces back to the episodes (raw data) that produced it.
Full lineage from derived fact to source.
- **Prescribed & Learned Ontology:** Define entity and edge types upfront via Pydantic models (prescribed), or let
structure emerge from your data (learned). Start simple, evolve as patterns appear.
- **Incremental Graph Construction:** New data integrates immediately without batch recomputation. The graph evolves
in real-time as episodes are ingested.
- **Hybrid Retrieval:** Combines semantic embeddings, keyword (BM25), and graph traversal for low-latency,
high-precision queries without reliance on LLM summarization.
- **Scalability:** Efficiently manages large datasets with parallel processing, pluggable graph backends, suitable
for enterprise workloads.
- **时序事实管理（Temporal Fact Management）：** 事实具有有效期窗口。当信息发生变化时，旧事实会被作废 — 而非删除。可查询当前何为真，或任意时间点何为真。
- **Episodes 与溯源（Provenance）：** 每个实体与关系均可追溯到产生它的 episodes（原始数据）。从衍生事实到源数据的完整血缘。
- **规定式与学习式本体（Prescribed & Learned Ontology）：** 可通过 Pydantic 模型预先定义实体与边类型（规定式），或让结构从数据中涌现（学习式）。从简单起步，随模式出现而演进。
- **增量图构建（Incremental Graph Construction）：** 新数据可立即整合，无需批处理重算。图会在 episodes 摄入时实时演化。
- **混合检索（Hybrid Retrieval）：** 结合语义嵌入、关键词（BM25）与图遍历，实现低延迟、高精度的查询，且不依赖 LLM 摘要。
- **可扩展性（Scalability）：** 通过并行处理与可插拔图后端高效管理大型数据集，适用于企业级工作负载。
<p align="center">
<img src="/images/graphiti-intro-slides-stock-2.gif" alt="Graphiti structured + unstructured demo" width="700px">
</p>
## Graphiti vs. GraphRAG
## Graphiti 与 GraphRAG 对比
| Aspect | GraphRAG | Graphiti |
| 方面 | GraphRAG | Graphiti |
|--------|----------|---------|
| **Primary Use** | Static document summarization | Dynamic, evolving context for agents |
| **Data Handling** | Batch-oriented processing | Continuous, incremental updates |
| **Knowledge Structure** | Entity clusters & community summaries | Temporal context graph — entities, facts with validity windows, episodes, communities |
| **Retrieval Method** | Sequential LLM summarization | Hybrid semantic, keyword, and graph-based search |
| **Adaptability** | Low | High |
| **Temporal Handling** | Basic timestamp tracking | Explicit bi-temporal tracking with automatic fact invalidation |
| **Contradiction Handling** | LLM-driven summarization judgments | Automatic fact invalidation with temporal history preserved |
| **Query Latency** | Seconds to tens of seconds | Typically sub-second latency |
| **Custom Entity Types** | No | Yes, customizable via Pydantic models |
| **Scalability** | Moderate | High, optimized for large datasets |
| **主要用途** | 静态文档摘要 | 面向 Agent 的动态、持续演化的上下文 |
| **数据处理方式** | 面向批处理 | 持续、增量更新 |
| **知识结构** | 实体聚类与社区摘要 | 时序上下文图 — 实体、带有效期窗口的事实、episodes、社区 |
| **检索方法** | 顺序式 LLM 摘要 | 混合语义、关键词与基于图的搜索 |
| **适应性** | 低 | 高 |
| **时序处理** | 基础时间戳追踪 | 显式双时态（bi-temporal）追踪，并自动作废事实 |
| **矛盾处理** | 由 LLM 驱动的摘要判断 | 自动作废事实，同时保留时序历史 |
| **查询延迟** | 数秒到数十秒 | 通常亚秒级延迟 |
| **自定义实体类型** | 否 | 是，可通过 Pydantic 模型自定义 |
| **可扩展性** | 中等 | 高，针对大型数据集优化 |
Graphiti is specifically designed to address the challenges of dynamic and frequently updated datasets, making it
particularly suitable for applications requiring real-time interaction and precise historical queries.
Graphiti 专为应对动态且频繁更新的数据集所带来的挑战而设计，因此特别适合需要实时交互和精确历史查询的应用。
## Installation
## 安装
Requirements:
要求：
- Python 3.10 or higher
- Neo4j 5.26 / FalkorDB 1.1.2 / Amazon Neptune Database Cluster or Neptune Analytics Graph + Amazon OpenSearch
Serverless collection (serves as the full text search backend) / Kuzu 0.11.2 (**deprecated**, see below)
- OpenAI API key (Graphiti defaults to OpenAI for LLM inference and embedding)
- Python 3.10 或更高版本
- Neo4j 5.26 / FalkorDB 1.1.2 / Amazon Neptune Database Cluster 或 Neptune Analytics Graph + Amazon OpenSearch Serverless collection（作为全文检索后端）/ Kuzu 0.11.2（**已弃用**，见下文）
- OpenAI API 密钥（Graphiti 默认使用 OpenAI 进行 LLM 推理与嵌入）
> [!IMPORTANT]
> Graphiti works best with LLM services that support Structured Output (such as OpenAI, Anthropic, and Gemini).
> Using other services may result in incorrect output schemas and ingestion failures. This is particularly
> problematic when using smaller models.
> Graphiti 最适合搭配支持 Structured Output（结构化输出）的 LLM 服务（如 OpenAI、Anthropic 和 Gemini）。使用其他服务可能导致输出 schema 不正确以及摄取失败，在使用较小模型时尤其如此。
Optional:
可选：
- Google Gemini, Anthropic, or Groq API key (for alternative LLM providers)
- Google Gemini、Anthropic 或 Groq API 密钥（用于替代 LLM 提供商）
> [!TIP]
> The simplest way to install Neo4j is via [Neo4j Desktop](https://neo4j.com/download/). It provides a user-friendly
> interface to manage Neo4j instances and databases.
> Alternatively, you can use FalkorDB on-premises via Docker and instantly start with the quickstart example:
> 安装 Neo4j 最简单的方式是通过 [Neo4j Desktop](https://neo4j.com/download/).。它提供了友好的界面来管理 Neo4j 实例和数据库。
> 或者，你可以通过 Docker 在本地部署 FalkorDB，并立即使用 quickstart 示例启动：
> ```
> docker run -p 6379:6379 -p 3000:3000 -it --rm falkordb/falkordb:latest
> ```
@@ -187,15 +167,15 @@ Optional:
pip install graphiti-core
```
or
或
```bash
uv add graphiti-core
```
### Installing with FalkorDB Support
### 安装 FalkorDB 支持
If you plan to use FalkorDB as your graph database backend, install with the FalkorDB extra:
如果你计划将 FalkorDB 用作图数据库后端，请安装 FalkorDB extra：
```bash
pip install graphiti-core[falkordb]
@@ -209,14 +189,12 @@ pip install graphiti-core[falkordblite]
uv add graphiti-core[falkordblite]
```
### Installing with Kuzu Support
### 安装 Kuzu 支持
> [!WARNING]
> **Kuzu is deprecated** and will be removed in a future release — the upstream Kuzu project is no longer
> maintained. New projects should use Neo4j or FalkorDB. The driver still ships for now but emits a
> `DeprecationWarning`.
> **Kuzu 已弃用**，并将在未来版本中移除——上游 Kuzu 项目已不再维护。新项目应使用 Neo4j 或 FalkorDB。该驱动目前仍会随附发布，但会发出 `DeprecationWarning`。
If you plan to use Kuzu as your graph database backend, install with the Kuzu extra:
如果你计划将 Kuzu 用作图数据库后端，请安装 Kuzu extra：
```bash
pip install graphiti-core[kuzu]
@@ -225,9 +203,9 @@ pip install graphiti-core[kuzu]
uv add graphiti-core[kuzu]
```
### Installing with Amazon Neptune Support
### 安装 Amazon Neptune 支持
If you plan to use Amazon Neptune as your graph database backend, install with the Amazon Neptune extra:
如果你计划将 Amazon Neptune 用作图数据库后端，请安装 Amazon Neptune extra：
```bash
pip install graphiti-core[neptune]
@@ -236,7 +214,7 @@ pip install graphiti-core[neptune]
uv add graphiti-core[neptune]
```
### You can also install optional LLM providers as extras:
### 你也可以将可选的 LLM 提供商作为 extra 安装：
```bash
# Install with Anthropic support
@@ -258,102 +236,89 @@ pip install graphiti-core[falkordb,anthropic,google-genai]
pip install graphiti-core[neptune]
```
## Default to Low Concurrency; LLM Provider 429 Rate Limit Errors
## 默认低并发；LLM 提供商 429 速率限制错误
Graphiti's ingestion pipelines are designed for high concurrency. By default, concurrency is set low to avoid LLM
Provider 429 Rate Limit Errors. If you find Graphiti slow, please increase concurrency as described below.
Graphiti 的摄取流水线面向高并发设计。为避免 LLM 提供商 429 速率限制错误，默认将并发设得较低。如果你觉得 Graphiti 较慢，请按下文说明提高并发。
Concurrency controlled by the `SEMAPHORE_LIMIT` environment variable. By default, `SEMAPHORE_LIMIT` is set to `10`
concurrent operations to help prevent `429` rate limit errors from your LLM provider. If you encounter such errors, try
lowering this value.
并发由 `SEMAPHORE_LIMIT` 环境变量控制。默认情况下，`SEMAPHORE_LIMIT` 设为 `10` 个并发操作，以帮助防止来自 LLM 提供商的 `429` 速率限制错误。若遇到此类错误，请尝试降低该值。
If your LLM provider allows higher throughput, you can increase `SEMAPHORE_LIMIT` to boost episode ingestion
performance.
如果你的 LLM 提供商允许更高吞吐，可提高 `SEMAPHORE_LIMIT` 以提升 episode 摄取性能。
## Quick Start
## 快速开始
> [!IMPORTANT]
> Graphiti defaults to using OpenAI for LLM inference and embedding. Ensure that an `OPENAI_API_KEY` is set in your
> environment.
> Support for Anthropic, Gemini, and Groq is available, too. Other LLM providers — both hosted OpenAI-compatible APIs
> (DeepSeek, Together, OpenRouter, …) and local servers (Ollama, vLLM, llama.cpp, LM Studio) — may be used via their
> OpenAI-compatible endpoints; see
> [Using Graphiti with OpenAI-compatible providers and local LLMs](#using-graphiti-with-openai-compatible-providers-and-local-llms).
> Graphiti 默认使用 OpenAI 进行 LLM 推理与嵌入。请确保在环境中设置了 `OPENAI_API_KEY`。
> 也支持 Anthropic、Gemini 和 Groq。其他 LLM 提供商——包括托管的 OpenAI 兼容 API（DeepSeek、Together、OpenRouter 等）以及本地服务（Ollama、vLLM、llama.cpp、LM Studio）——可通过其 OpenAI 兼容端点使用；参见
> [将 Graphiti 与 OpenAI 兼容提供商及本地 LLM 配合使用](#using-graphiti-with-openai-compatible-providers-and-local-llms)。
For a complete working example, see the [Quickstart Example](examples/quickstart/README.md) in the examples directory.
The quickstart demonstrates:
完整可运行示例见 examples 目录中的 [Quickstart Example](examples/quickstart/README.md)。
quickstart 演示了：
1. Connecting to a Neo4j, Amazon Neptune, FalkorDB, or Kuzu database
2. Initializing Graphiti indices and constraints
3. Adding episodes to the graph (both text and structured JSON)
4. Searching for relationships (edges) using hybrid search
5. Reranking search results using graph distance
6. Searching for nodes using predefined search recipes
1. 连接 Neo4j、Amazon Neptune、FalkorDB 或 Kuzu 数据库
2. 初始化 Graphiti 索引与约束
3. 向图中添加 episode（文本与结构化 JSON）
4. 使用混合搜索查找关系（边）
5. 使用图距离对搜索结果重排序
6. 使用预定义搜索配方查找节点
The example is fully documented with clear explanations of each functionality and includes a comprehensive README with
setup instructions and next steps.
该示例附有完整文档，清晰说明各项功能，并包含带设置说明与后续步骤的详尽 README。
### Running with Docker Compose
### 使用 Docker Compose 运行
You can use Docker Compose to quickly start the required services:
你可以使用 Docker Compose 快速启动所需服务：
- **Neo4j Docker:**
- **Neo4j Docker：**
```bash
docker compose up
```
This will start the Neo4j Docker service and related components.
这将启动 Neo4j Docker 服务及相关组件。
- **FalkorDB Docker:**
- **FalkorDB Docker：**
```bash
docker compose --profile falkordb up
```
This will start the FalkorDB Docker service and related components.
这将启动 FalkorDB Docker 服务及相关组件。
## MCP Server
## MCP 服务器
The `mcp_server` directory contains a Model Context Protocol (MCP) server implementation for Graphiti. This server
allows AI assistants to interact with Graphiti's context graph capabilities through the MCP protocol.
`mcp_server` 目录包含 Graphiti 的 Model Context Protocol（MCP）服务器实现。该服务器使 AI 助手能够通过 MCP 协议与 Graphiti 的上下文图能力交互。
Key features of the MCP server include:
MCP 服务器的主要功能包括：
- Episode management (add, retrieve, delete)
- Entity management and relationship handling
- Semantic and hybrid search capabilities
- Group management for organizing related data
- Graph maintenance operations
- Episode 管理（添加、检索、删除）
- 实体管理与关系处理
- 语义搜索与混合搜索能力
- 分组管理以组织相关数据
- 图维护操作
The MCP server can be deployed using Docker with Neo4j, making it easy to integrate Graphiti into your AI assistant
workflows.
MCP 服务器可与 Neo4j 一同通过 Docker 部署，便于将 Graphiti 集成到 AI 助手工作流中。
For detailed setup instructions and usage examples, see the [MCP server README](mcp_server/README.md).
详细设置说明与使用示例见 [MCP 服务器 README](mcp_server/README.md)。
## REST Service
## REST 服务
The `server` directory contains an API service for interacting with the Graphiti API. It is built using FastAPI.
`server` 目录包含用于与 Graphiti API 交互的 API 服务，基于 FastAPI 构建。
Please see the [server README](server/README.md) for more information.
更多信息见 [server README](server/README.md)。
## Optional Environment Variables
## 可选环境变量
In addition to the Neo4j and OpenAi-compatible credentials, Graphiti also has a few optional environment variables.
If you are using one of our supported models, such as Anthropic or Voyage models, the necessary environment variables
must be set.
除 Neo4j 与 OpenAI 兼容凭据外，Graphiti 还有一些可选环境变量。若使用我们支持的模型（如 Anthropic 或 Voyage 模型），必须设置相应环境变量。
### Database Configuration
### 数据库配置
Database names are configured directly in the driver constructors:
数据库名称在驱动构造函数中直接配置：
- **Neo4j**: Database name defaults to `neo4j` (hardcoded in Neo4jDriver)
- **FalkorDB**: Database name defaults to `default_db` (hardcoded in FalkorDriver)
- **Neo4j**：数据库名称默认为 `neo4j`（在 Neo4jDriver 中硬编码）
- **FalkorDB**：数据库名称默认为 `default_db`（在 FalkorDriver 中硬编码）
As of v0.17.0, if you need to customize your database configuration, you can instantiate a database driver and pass it
to the Graphiti constructor using the `graph_driver` parameter.
自 v0.17.0 起，若需自定义数据库配置，可实例化数据库驱动，并通过 `graph_driver` 参数传入 Graphiti 构造函数。
#### Neo4j with Custom Database Name
#### 使用自定义数据库名称的 Neo4j
```python
from graphiti_core import Graphiti
@@ -371,7 +336,7 @@ driver = Neo4jDriver(
graphiti = Graphiti(graph_driver=driver)
```
#### FalkorDB with Custom Database Name
#### 使用自定义数据库名称的 FalkorDB
```python
from graphiti_core import Graphiti
@@ -398,8 +363,8 @@ graphiti = Graphiti(graph_driver=driver)
#### Kuzu
> [!WARNING]
> Kuzu is **deprecated** (upstream project unmaintained) and will be removed in a future release. Prefer Neo4j or
> FalkorDB.
> Kuzu 已**弃用**（上游项目不再维护），并将在未来版本中移除。请优先使用 Neo4j 或
> FalkorDB。
```python
from graphiti_core import Graphiti
@@ -430,13 +395,13 @@ driver = NeptuneDriver(
graphiti = Graphiti(graph_driver=driver)
```
Contributing a new graph backend? See [Adding a graph driver](CONTRIBUTING.md#adding-a-graph-driver).
要贡献新的图数据库后端？请参阅 [Adding a graph driver](CONTRIBUTING.md#adding-a-graph-driver)。
## Using Graphiti with Azure OpenAI
## 在 Graphiti 中使用 Azure OpenAI
Graphiti supports Azure OpenAI for both LLM inference and embeddings using Azure's OpenAI v1 API compatibility layer.
Graphiti 通过 Azure 的 OpenAI v1 API 兼容层，支持将 Azure OpenAI 用于 LLM 推理和嵌入（embeddings）。
### Quick Start
### 快速入门
```python
from openai import AsyncOpenAI
@@ -474,21 +439,21 @@ graphiti = Graphiti(
# Now you can use Graphiti with Azure OpenAI
```
**Key Points:**
**要点：**
- Use the standard `AsyncOpenAI` client with Azure's v1 API endpoint format:
- 使用标准 `AsyncOpenAI` 客户端，配合 Azure 的 v1 API 端点格式：
`https://your-resource-name.openai.azure.com/openai/v1/`
- The deployment names (e.g., `gpt-5-mini`, `text-embedding-3-small`) should match your Azure OpenAI deployment names
- See `examples/azure-openai/` for a complete working example
- 部署名称（例如 `gpt-5-mini`、`text-embedding-3-small`）应与你的 Azure OpenAI 部署名称一致
- 完整可运行示例请参阅 `examples/azure-openai/`
Make sure to replace the placeholder values with your actual Azure OpenAI credentials and deployment names.
请务必将占位符值替换为你的实际 Azure OpenAI 凭据和部署名称。
## Using Graphiti with Google Gemini
## 在 Graphiti 中使用 Google Gemini
Graphiti supports Google's Gemini models for LLM inference, embeddings, and cross-encoding/reranking. To use Gemini,
you'll need to configure the LLM client, embedder, and the cross-encoder with your Google API key.
Graphiti 支持将 Google 的 Gemini 模型用于 LLM 推理、嵌入以及交叉编码/重排序（cross-encoding/reranking）。要使用 Gemini，
你需要使用 Google API 密钥配置 LLM 客户端、嵌入器（embedder）和交叉编码器（cross-encoder）。
Install Graphiti:
安装 Graphiti：
```bash
uv add "graphiti-core[google-genai]"
@@ -535,21 +500,21 @@ graphiti = Graphiti(
# Now you can use Graphiti with Google Gemini for all components
```
The Gemini reranker uses the `gemini-2.5-flash-lite` model by default, which is optimized for
cost-effective and low-latency classification tasks. It uses the same boolean classification approach as the OpenAI
reranker, leveraging Gemini's log probabilities feature to rank passage relevance.
Gemini 重排序器默认使用 `gemini-2.5-flash-lite` 模型，该模型针对
高性价比、低延迟的分类任务进行了优化。它采用与 OpenAI
重排序器相同的布尔分类方法，利用 Gemini 的对数概率（log probabilities）功能对段落相关性进行排序。
## Using Graphiti with OpenAI-compatible providers and local LLMs
## 在 Graphiti 中使用 OpenAI 兼容提供商与本地 LLM
Graphiti can use any OpenAI-compatible `/v1` endpoint for LLM inference via `OpenAIGenericClient` — both **hosted
providers** (DeepSeek, Together, OpenRouter, Fireworks, etc.) and **local servers** (Ollama, vLLM, llama.cpp, LM
Studio). Local servers are ideal for privacy-focused applications or avoiding API costs. The example below uses Ollama;
for any other provider, point `base_url` at its endpoint and set the appropriate `api_key` and `model`.
Graphiti 可通过 `OpenAIGenericClient` 使用任何 OpenAI 兼容的 `/v1` 端点进行 LLM 推理——包括**托管
提供商**（DeepSeek、Together、OpenRouter、Fireworks 等）和**本地服务器**（Ollama、vLLM、llama.cpp、LM
Studio）。本地服务器非常适合注重隐私的应用，或用于避免 API 费用。以下示例使用 Ollama；
对于其他提供商，将 `base_url` 指向其端点，并设置相应的 `api_key` 和 `model`。
**Note:** Use `OpenAIGenericClient` (not `OpenAIClient`) for these endpoints. It is optimized for local models with a
higher default max token limit (16K vs 8K) and handles structured outputs across compatible providers.
**注意：** 对于这些端点，请使用 `OpenAIGenericClient`（而非 `OpenAIClient`）。它针对本地模型进行了优化，
默认最大 token 上限更高（16K 对比 8K），并能在兼容的提供商之间处理结构化输出。
Install the models:
安装模型：
```bash
ollama pull deepseek-r1:7b # LLM
@@ -593,29 +558,29 @@ graphiti = Graphiti(
# Now you can use Graphiti with local Ollama models
```
Ensure Ollama is running (`ollama serve`) and that you have pulled the models you want to use.
请确保 Ollama 正在运行（`ollama serve`），且已拉取你要使用的模型。
### Structured output and small models
### 结构化输出与小模型
Graphiti depends on structured (JSON) output for entity/edge extraction and deduplication, and works best with models
and providers that reliably honor it (OpenAI, Anthropic, Gemini). Reliability varies across OpenAI-compatible providers and
especially on smaller or local models, so `OpenAIGenericClient` exposes a `structured_output_mode`:
Graphiti 依赖结构化（JSON）输出进行实体/边提取与去重，在能够可靠遵循该要求的模型
和提供商（OpenAI、Anthropic、Gemini）上效果最佳。不同 OpenAI 兼容提供商之间的可靠性差异较大，
尤其是在较小或本地模型上，因此 `OpenAIGenericClient` 提供了 `structured_output_mode`：
- `"json_schema"` (default): requests native structured output via `response_format`. Best on capable models and
providers that enforce the schema via constrained decoding.
- `"json_object"`: requests plain-JSON mode and injects the schema into the prompt instead. Use this for
providers/models that don't reliably honor `json_schema` — including some local servers that accept the `json_schema`
request but don't actually constrain output to it, where `json_object` can be *more* reliable.
- `"json_schema"`（默认）：通过 `response_format` 请求原生结构化输出。在能力较强的模型和
通过约束解码（constrained decoding）强制执行 schema 的提供商上效果最佳。
- `"json_object"`：请求纯 JSON 模式，并将 schema 注入提示词中。适用于
不能可靠遵循 `json_schema` 的提供商/模型——包括某些本地服务器，它们会接受 `json_schema`
请求但实际上并不将输出约束到该 schema，此时 `json_object` 可能*更*可靠。
When using smaller or local models:
使用较小或本地模型时：
- Prefer the most capable model you can run. Very small models frequently emit JSON that doesn't match the requested
schema, which surfaces as extraction failures.
- Responses wrapped in Markdown ` ```json ` code fences are stripped automatically.
- Keep `SEMAPHORE_LIMIT` low (see [above](#default-to-low-concurrency-llm-provider-429-rate-limit-errors)) — local
servers and some providers have limited concurrency.
- 优先使用你能运行的最强模型。非常小的模型经常输出与请求
schema 不匹配的 JSON，这会表现为提取失败。
- 包裹在 Markdown ` ```json ` 代码围栏中的响应会自动剥离。
- 保持 `SEMAPHORE_LIMIT` 较低（参见[上文](#default-to-low-concurrency-llm-provider-429-rate-limit-errors)）——本地
服务器和部分提供商的并发能力有限。
## Documentation
## 文档
- [Guides and API documentation](https://help.getzep.com/graphiti).
- [Quick Start](https://help.getzep.com/graphiti/graphiti/quick-start)
@@ -623,50 +588,49 @@ When using smaller or local models:
## Telemetry
Graphiti collects anonymous usage statistics to help us understand how the framework is being used and improve it for
everyone. We believe transparency is important, so here's exactly what we collect and why.
Graphiti 会收集匿名使用统计，帮助我们了解框架的使用情况并改进产品，惠及所有用户。我们重视透明度，因此下面会说明我们具体收集哪些数据以及原因。
### What We Collect
When you initialize a Graphiti instance, we collect:
初始化 Graphiti 实例时，我们会收集：
- **Anonymous identifier**: A randomly generated UUID stored locally in `~/.cache/graphiti/telemetry_anon_id`
- **System information**: Operating system, Python version, and system architecture
- **Graphiti version**: The version you're using
- **Configuration choices**:
- LLM provider type (OpenAI, Azure, Anthropic, etc.)
- Database backend (Neo4j, FalkorDB, Kuzu, Amazon Neptune Database or Neptune Analytics)
- Embedder provider (OpenAI, Azure, Voyage, etc.)
- **Anonymous identifier（匿名标识符）**：随机生成的 UUID，本地存储在 `~/.cache/graphiti/telemetry_anon_id`
- **System information（系统信息）**：操作系统、Python 版本和系统架构
- **Graphiti version（Graphiti 版本）**：你正在使用的版本
- **Configuration choices（配置选择）**：
- LLM provider type（LLM 提供商类型）（OpenAI、Azure、Anthropic 等）
- Database backend（数据库后端）（Neo4j、FalkorDB、Kuzu、Amazon Neptune Database 或 Neptune Analytics）
- Embedder provider（嵌入模型提供商）（OpenAI、Azure、Voyage 等）
### What We Don't Collect
We are committed to protecting your privacy. We **never** collect:
我们致力于保护你的隐私。我们**从不**收集：
- Personal information or identifiers
- API keys or credentials
- Your actual data, queries, or graph content
- IP addresses or hostnames
- File paths or system-specific information
- Any content from your episodes, nodes, or edges
- 个人信息或标识符
- API keys 或凭据
- 你的实际数据、查询或图内容
- IP 地址或主机名
- 文件路径或系统特定信息
- 来自 episodes、nodes 或 edges 的任何内容
### Why We Collect This Data
This information helps us:
这些信息帮助我们：
- Understand which configurations are most popular to prioritize support and testing
- Identify which LLM and database providers to focus development efforts on
- Track adoption patterns to guide our roadmap
- Ensure compatibility across different Python versions and operating systems
- 了解哪些配置最受欢迎，从而优先提供支持和测试
- 确定应重点投入开发的 LLM 和数据库提供商
- 跟踪采用模式以指导路线图
- 确保在不同 Python 版本和操作系统上的兼容性
By sharing this anonymous information, you help us make Graphiti better for everyone in the community.
通过分享这些匿名信息，你帮助我们让 Graphiti 对整个社区变得更好。
### View the Telemetry Code
The Telemetry code [may be found here](graphiti_core/telemetry/telemetry.py).
Telemetry 代码[可在此处查看](graphiti_core/telemetry/telemetry.py)。
### How to Disable Telemetry
Telemetry is **opt-out** and can be disabled at any time. To disable telemetry collection:
Telemetry 采用**选择退出（opt-out）**机制，可随时禁用。要禁用 telemetry 收集：
**Option 1: Environment Variable**
@@ -697,21 +661,18 @@ from graphiti_core import Graphiti
graphiti = Graphiti(...)
```
Telemetry is automatically disabled during test runs (when `pytest` is detected).
在测试运行期间（检测到 `pytest` 时），Telemetry 会自动禁用。
### Technical Details
- Telemetry uses PostHog for anonymous analytics collection
- All telemetry operations are designed to fail silently - they will never interrupt your application or affect Graphiti
functionality
- The anonymous ID is stored locally and is not tied to any personal information
- Telemetry 使用 PostHog 进行匿名分析收集
- 所有 telemetry 操作均设计为静默失败——它们不会中断你的应用，也不会影响 Graphiti 功能
- 匿名 ID 存储在本地，不与任何个人信息关联
## Contributing
We encourage and appreciate all forms of contributions, whether it's code, documentation, addressing GitHub Issues, or
answering questions in the Graphiti Discord channel. For detailed guidelines on code contributions, please refer
to [CONTRIBUTING](CONTRIBUTING.md).
我们鼓励并感谢各种形式的贡献，无论是代码、文档、处理 GitHub Issues，还是在 Graphiti Discord 频道中回答问题。有关代码贡献的详细指南，请参阅 [CONTRIBUTING](CONTRIBUTING.md)。
## Support
Join the [Zep Discord server](https://discord.com/invite/W8Kw6bsgXQ) and make your way to the **#Graphiti** channel!
加入 [Zep Discord server](https://discord.com/invite/W8Kw6bsgXQ))，前往 **#Graphiti** 频道！