diff --git a/README.md b/README.md index bdce4e5..8b6699e 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,9 @@ + +> [!NOTE] +> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 +> [English](./README.en.md) · [原始项目](https://github.com/getzep/graphiti) · [上游 README](https://github.com/getzep/graphiti/blob/HEAD/README.md) +> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 +

Zep Logo @@ -7,7 +13,7 @@

Graphiti

-

Build Temporal Context Graphs for AI Agents

+

为 AI Agent 构建时序上下文图（Temporal Context Graph）

@@ -28,31 +34,25 @@ Graphiti
> [!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！*   > [!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 提供丰富的结构化上下文，而非扁平的文档块或原始聊天历史。 +- 通过混合检索（语义 + 关键词 + 图遍历）跨时间、语义和关系进行查询。   @@ -62,123 +62,103 @@ Use Graphiti to:   -## 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 开源，并相信其作为上下文图引擎的潜力远不止于记忆类应用。

Zep: A Temporal Knowledge Graph Architecture for Agent Memory

-## 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）：** 通过并行处理与可插拔图后端高效管理大型数据集，适用于企业级工作负载。

Graphiti structured + unstructured demo

-## 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** 频道！