wehub-resource-sync
1dea06d045
Lint with Ruff / ruff (push) Has been cancelled
CodeQL Advanced / Analyze (actions) (push) Has been cancelled
CodeQL Advanced / Analyze (python) (push) Has been cancelled
Tests / unit-tests (push) Has been cancelled
Tests / database-integration-tests (push) Has been cancelled
Pyright Type Check / pyright (push) Has been cancelled
679 lines
27 KiB
Markdown
679 lines
27 KiB
Markdown
<!-- 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">
|
||
</a>
|
||
</p>
|
||
|
||
<h1 align="center">
|
||
Graphiti
|
||
</h1>
|
||
<h2 align="center">为 AI Agent 构建时序上下文图（Temporal Context Graph）</h2>
|
||
|
||
<div align="center">
|
||
|
||
[](https://github.com/getzep/Graphiti/actions/workflows/lint.yml)
|
||
[](https://github.com/getzep/Graphiti/actions/workflows/unit_tests.yml)
|
||
[](https://github.com/getzep/Graphiti/actions/workflows/typecheck.yml)
|
||
|
||
[](https://github.com/getzep/graphiti/stargazers)
|
||
[](https://discord.com/invite/W8Kw6bsgXQ)
|
||
[](https://arxiv.org/abs/2501.13956)
|
||
[](https://github.com/getzep/graphiti/releases)
|
||
|
||
</div>
|
||
<div align="center">
|
||
|
||
<a href="https://trendshift.io/repositories/12986" target="_blank"><img src="https://trendshift.io/api/badge/repositories/12986" alt="getzep%2Fgraphiti | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
|
||
|
||
</div>
|
||
|
||
> [!NOTE]
|
||
> **我们正在招聘！** 构建为可靠、个性化、高速的生产级 AI Agent 提供动力的上下文图。
|
||
> 加入我们，一起构建 — 我们正在招聘工程师和开发者关系（Developer Relations）岗位。[查看开放职位](https://www.getzep.com/careers/).
|
||
|
||
⭐ *帮助我们触达更多开发者，壮大 Graphiti 社区。请为本仓库点 Star！*
|
||
|
||
|
||
|
||
> [!TIP]
|
||
> 来看看全新的 [Graphiti MCP 服务器](mcp_server/README.md)！为 Claude、Cursor 及其他 MCP 客户端提供强大的、具备时序感知能力的基于上下文图的记忆能力。
|
||
|
||
Graphiti 是一个用于为 AI Agent 构建和查询时序上下文图的框架。与静态知识图谱不同，Graphiti 的上下文图会追踪事实如何随时间变化，保留到源数据的溯源（provenance），并同时支持规定式与学习式本体（ontology）——因此专为在持续演化的真实世界数据上运行的 Agent 而设计。
|
||
|
||
与传统检索增强生成（Retrieval-Augmented Generation，RAG）方法不同，Graphiti 持续将用户交互、结构化和非结构化企业数据以及外部信息整合为一个连贯、可查询的图。该框架支持增量数据更新、高效检索和精确的历史查询，且无需对整个图进行完全重算，因此适合开发交互式、具备上下文感知能力的 AI 应用。
|
||
|
||
使用 Graphiti 可以：
|
||
|
||
- 构建随每次交互而演化的上下文图 — 追踪当前何为真、此前何为真。
|
||
- 为 Agent 提供丰富的结构化上下文，而非扁平的文档块或原始聊天历史。
|
||
- 通过混合检索（语义 + 关键词 + 图遍历）跨时间、语义和关系进行查询。
|
||
|
||
|
||
|
||
<p align="center">
|
||
<img src="images/graphiti-graph-intro.gif" alt="Graphiti temporal walkthrough" width="700px">
|
||
</p>
|
||
|
||
|
||
|
||
## 什么是上下文图（Context Graph）？
|
||
|
||
**上下文图**是实体、关系与事实的时序图 — 例如 *"Kendra 喜欢 Adidas 鞋（截至 2026 年 3 月）。"* 与传统知识图谱不同，上下文图中的每条事实都有一个有效期窗口：它何时变为真，以及（若有）何时被取代。实体会随时间演化，摘要也会更新。一切均可追溯到 **episodes** — 产生这些内容的原始数据。
|
||
|
||
Graphiti 的独特之处在于，它能够从非结构化与结构化数据中自主构建上下文图，在处理变化中的关系的同时保留完整的时序历史。
|
||
|
||
上下文图包含：
|
||
|
||
| 组件 | 存储内容 |
|
||
|-----------|---------------|
|
||
| **Entities（实体）**（节点） | 人物、产品、政策、概念 — 附带随时间演化的摘要 |
|
||
| **Facts / Relationships（事实 / 关系）**（边） | 三元组（Entity → Relationship → Entity），附带时序有效期窗口 |
|
||
| **Episodes（溯源片段）**（provenance） | 按摄入方式保存的原始数据 — 即真实数据流。每条衍生事实均可追溯至此 |
|
||
| **Custom Types（自定义类型）**（ontology） | 开发者通过 Pydantic 模型定义的实体与边类型 |
|
||
|
||
## Graphiti 与 Zep
|
||
|
||
Graphiti 是 [Zep](https://www.getzep.com) AI Agent 上下文基础设施核心的开源时序上下文图引擎。Zep 大规模管理上下文图，为生产级 Agent 部署提供受治理、低延迟的上下文检索与组装能力。
|
||
|
||
借助 Graphiti，我们已证明 Zep 是 [Agent 记忆领域的最先进方案（State of the Art in Agent Memory）](https://blog.getzep.com/state-of-the-art-agent-memory/).
|
||
|
||
阅读我们的论文：[Zep: A Temporal Knowledge Graph Architecture for Agent Memory](https://arxiv.org/abs/2501.13956).
|
||
|
||
我们很高兴将 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 与 Graphiti 对比
|
||
|
||
| 方面 | Zep | Graphiti |
|
||
|--------|-----|---------|
|
||
| **定位** | 面向 AI Agent 的托管式上下文图基础设施 | 开源时序上下文图引擎 |
|
||
| **上下文图** | 以治理方式管理海量按用户/实体划分的上下文图 | 构建并查询单个上下文图 |
|
||
| **用户与会话管理** | 内置用户、线程与消息存储 | 需自行构建 |
|
||
| **检索与性能** | 预配置、可用于生产的检索，大规模下可实现亚 200ms 性能 | 需自行实现；性能取决于你的部署配置 |
|
||
| **开发者工具** | 带图可视化、调试日志、API 日志的仪表盘；提供 Python、TypeScript 与 Go SDK | 需自行构建工具 |
|
||
| **企业级能力** | SLA、支持、安全承诺 | 自行运维 |
|
||
| **部署方式** | 全托管或部署在你的云中 | 仅支持自托管 |
|
||
|
||
### 如何选择
|
||
|
||
**选择 Zep**：如果你需要开箱即用、企业级平台，且安全、性能与支持均已内置。
|
||
|
||
**选择 Graphiti**：如果你需要灵活的开源核心，并愿意自行构建/运维周边系统。
|
||
|
||
## 为什么选择 Graphiti？
|
||
|
||
传统 RAG 方法往往依赖批处理与静态数据摘要，因此在频繁变化的数据场景下效率较低。Graphiti 通过以下能力应对这些挑战：
|
||
|
||
- **时序事实管理（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 与 GraphRAG 对比
|
||
|
||
| 方面 | GraphRAG | Graphiti |
|
||
|--------|----------|---------|
|
||
| **主要用途** | 静态文档摘要 | 面向 Agent 的动态、持续演化的上下文 |
|
||
| **数据处理方式** | 面向批处理 | 持续、增量更新 |
|
||
| **知识结构** | 实体聚类与社区摘要 | 时序上下文图 — 实体、带有效期窗口的事实、episodes、社区 |
|
||
| **检索方法** | 顺序式 LLM 摘要 | 混合语义、关键词与基于图的搜索 |
|
||
| **适应性** | 低 | 高 |
|
||
| **时序处理** | 基础时间戳追踪 | 显式双时态（bi-temporal）追踪，并自动作废事实 |
|
||
| **矛盾处理** | 由 LLM 驱动的摘要判断 | 自动作废事实，同时保留时序历史 |
|
||
| **查询延迟** | 数秒到数十秒 | 通常亚秒级延迟 |
|
||
| **自定义实体类型** | 否 | 是，可通过 Pydantic 模型自定义 |
|
||
| **可扩展性** | 中等 | 高，针对大型数据集优化 |
|
||
|
||
Graphiti 专为应对动态且频繁更新的数据集所带来的挑战而设计，因此特别适合需要实时交互和精确历史查询的应用。
|
||
|
||
## 安装
|
||
|
||
要求：
|
||
|
||
- 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 最适合搭配支持 Structured Output（结构化输出）的 LLM 服务（如 OpenAI、Anthropic 和 Gemini）。使用其他服务可能导致输出 schema 不正确以及摄取失败，在使用较小模型时尤其如此。
|
||
|
||
可选：
|
||
|
||
- Google Gemini、Anthropic 或 Groq API 密钥（用于替代 LLM 提供商）
|
||
|
||
> [!TIP]
|
||
> 安装 Neo4j 最简单的方式是通过 [Neo4j Desktop](https://neo4j.com/download/).。它提供了友好的界面来管理 Neo4j 实例和数据库。
|
||
> 或者，你可以通过 Docker 在本地部署 FalkorDB，并立即使用 quickstart 示例启动：
|
||
> ```
|
||
> docker run -p 6379:6379 -p 3000:3000 -it --rm falkordb/falkordb:latest
|
||
> ```
|
||
|
||
```bash
|
||
pip install graphiti-core
|
||
```
|
||
|
||
或
|
||
|
||
```bash
|
||
uv add graphiti-core
|
||
```
|
||
|
||
### 安装 FalkorDB 支持
|
||
|
||
如果你计划将 FalkorDB 用作图数据库后端，请安装 FalkorDB extra：
|
||
|
||
```bash
|
||
pip install graphiti-core[falkordb]
|
||
|
||
# or with uv
|
||
uv add graphiti-core[falkordb]
|
||
|
||
# or embedded version (requires Python 3.12+)
|
||
pip install graphiti-core[falkordblite]
|
||
# or with uv
|
||
uv add graphiti-core[falkordblite]
|
||
```
|
||
|
||
### 安装 Kuzu 支持
|
||
|
||
> [!WARNING]
|
||
> **Kuzu 已弃用**，并将在未来版本中移除——上游 Kuzu 项目已不再维护。新项目应使用 Neo4j 或 FalkorDB。该驱动目前仍会随附发布，但会发出 `DeprecationWarning`。
|
||
|
||
如果你计划将 Kuzu 用作图数据库后端，请安装 Kuzu extra：
|
||
|
||
```bash
|
||
pip install graphiti-core[kuzu]
|
||
|
||
# or with uv
|
||
uv add graphiti-core[kuzu]
|
||
```
|
||
|
||
### 安装 Amazon Neptune 支持
|
||
|
||
如果你计划将 Amazon Neptune 用作图数据库后端，请安装 Amazon Neptune extra：
|
||
|
||
```bash
|
||
pip install graphiti-core[neptune]
|
||
|
||
# or with uv
|
||
uv add graphiti-core[neptune]
|
||
```
|
||
|
||
### 你也可以将可选的 LLM 提供商作为 extra 安装：
|
||
|
||
```bash
|
||
# Install with Anthropic support
|
||
pip install graphiti-core[anthropic]
|
||
|
||
# Install with Groq support
|
||
pip install graphiti-core[groq]
|
||
|
||
# Install with Google Gemini support
|
||
pip install graphiti-core[google-genai]
|
||
|
||
# Install with multiple providers
|
||
pip install graphiti-core[anthropic,groq,google-genai]
|
||
|
||
# Install with FalkorDB and LLM providers
|
||
pip install graphiti-core[falkordb,anthropic,google-genai]
|
||
|
||
# Install with Amazon Neptune
|
||
pip install graphiti-core[neptune]
|
||
```
|
||
|
||
## 默认低并发；LLM 提供商 429 速率限制错误
|
||
|
||
Graphiti 的摄取流水线面向高并发设计。为避免 LLM 提供商 429 速率限制错误，默认将并发设得较低。如果你觉得 Graphiti 较慢，请按下文说明提高并发。
|
||
|
||
并发由 `SEMAPHORE_LIMIT` 环境变量控制。默认情况下，`SEMAPHORE_LIMIT` 设为 `10` 个并发操作，以帮助防止来自 LLM 提供商的 `429` 速率限制错误。若遇到此类错误，请尝试降低该值。
|
||
|
||
如果你的 LLM 提供商允许更高吞吐，可提高 `SEMAPHORE_LIMIT` 以提升 episode 摄取性能。
|
||
|
||
## 快速开始
|
||
|
||
> [!IMPORTANT]
|
||
> 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)。
|
||
|
||
完整可运行示例见 examples 目录中的 [Quickstart Example](examples/quickstart/README.md)。
|
||
quickstart 演示了：
|
||
|
||
1. 连接 Neo4j、Amazon Neptune、FalkorDB 或 Kuzu 数据库
|
||
2. 初始化 Graphiti 索引与约束
|
||
3. 向图中添加 episode（文本与结构化 JSON）
|
||
4. 使用混合搜索查找关系（边）
|
||
5. 使用图距离对搜索结果重排序
|
||
6. 使用预定义搜索配方查找节点
|
||
|
||
该示例附有完整文档，清晰说明各项功能，并包含带设置说明与后续步骤的详尽 README。
|
||
|
||
### 使用 Docker Compose 运行
|
||
|
||
你可以使用 Docker Compose 快速启动所需服务：
|
||
|
||
- **Neo4j Docker：**
|
||
|
||
```bash
|
||
docker compose up
|
||
```
|
||
|
||
这将启动 Neo4j Docker 服务及相关组件。
|
||
|
||
- **FalkorDB Docker：**
|
||
|
||
```bash
|
||
docker compose --profile falkordb up
|
||
```
|
||
|
||
这将启动 FalkorDB Docker 服务及相关组件。
|
||
|
||
## MCP 服务器
|
||
|
||
`mcp_server` 目录包含 Graphiti 的 Model Context Protocol（MCP）服务器实现。该服务器使 AI 助手能够通过 MCP 协议与 Graphiti 的上下文图能力交互。
|
||
|
||
MCP 服务器的主要功能包括：
|
||
|
||
- Episode 管理（添加、检索、删除）
|
||
- 实体管理与关系处理
|
||
- 语义搜索与混合搜索能力
|
||
- 分组管理以组织相关数据
|
||
- 图维护操作
|
||
|
||
MCP 服务器可与 Neo4j 一同通过 Docker 部署，便于将 Graphiti 集成到 AI 助手工作流中。
|
||
|
||
详细设置说明与使用示例见 [MCP 服务器 README](mcp_server/README.md)。
|
||
|
||
## REST 服务
|
||
|
||
`server` 目录包含用于与 Graphiti API 交互的 API 服务，基于 FastAPI 构建。
|
||
|
||
更多信息见 [server README](server/README.md)。
|
||
|
||
## 可选环境变量
|
||
|
||
除 Neo4j 与 OpenAI 兼容凭据外，Graphiti 还有一些可选环境变量。若使用我们支持的模型（如 Anthropic 或 Voyage 模型），必须设置相应环境变量。
|
||
|
||
### 数据库配置
|
||
|
||
数据库名称在驱动构造函数中直接配置：
|
||
|
||
- **Neo4j**：数据库名称默认为 `neo4j`（在 Neo4jDriver 中硬编码）
|
||
- **FalkorDB**：数据库名称默认为 `default_db`（在 FalkorDriver 中硬编码）
|
||
|
||
自 v0.17.0 起，若需自定义数据库配置，可实例化数据库驱动，并通过 `graph_driver` 参数传入 Graphiti 构造函数。
|
||
|
||
#### 使用自定义数据库名称的 Neo4j
|
||
|
||
```python
|
||
from graphiti_core import Graphiti
|
||
from graphiti_core.driver.neo4j_driver import Neo4jDriver
|
||
|
||
# Create a Neo4j driver with custom database name
|
||
driver = Neo4jDriver(
|
||
uri="bolt://localhost:7687",
|
||
user="neo4j",
|
||
password="password",
|
||
database="my_custom_database" # Custom database name
|
||
)
|
||
|
||
# Pass the driver to Graphiti
|
||
graphiti = Graphiti(graph_driver=driver)
|
||
```
|
||
|
||
#### 使用自定义数据库名称的 FalkorDB
|
||
|
||
```python
|
||
from graphiti_core import Graphiti
|
||
from graphiti_core.driver.falkordb_driver import FalkorDriver
|
||
|
||
# Create a FalkorDB driver with custom database name
|
||
driver = FalkorDriver(
|
||
host="localhost",
|
||
port=6379,
|
||
username="falkor_user", # Optional
|
||
password="falkor_password", # Optional
|
||
database="my_custom_graph" # Custom database name
|
||
)
|
||
|
||
# Or use embedded FalkorDB Lite (requires Python 3.12+)
|
||
# from redislite.async_falkordb_client import AsyncFalkorDB
|
||
# falkordb_client = AsyncFalkorDB(dbfilename='/path/to/database.db')
|
||
# driver = FalkorDriver(falkor_db=falkordb_client)
|
||
|
||
# Pass the driver to Graphiti
|
||
graphiti = Graphiti(graph_driver=driver)
|
||
```
|
||
|
||
#### Kuzu
|
||
|
||
> [!WARNING]
|
||
> Kuzu 已**弃用**（上游项目不再维护），并将在未来版本中移除。请优先使用 Neo4j 或
|
||
> FalkorDB。
|
||
|
||
```python
|
||
from graphiti_core import Graphiti
|
||
from graphiti_core.driver.kuzu_driver import KuzuDriver
|
||
|
||
# Create a Kuzu driver
|
||
driver = KuzuDriver(db="/tmp/graphiti.kuzu")
|
||
|
||
# Pass the driver to Graphiti
|
||
graphiti = Graphiti(graph_driver=driver)
|
||
```
|
||
|
||
#### Amazon Neptune
|
||
|
||
```python
|
||
from graphiti_core import Graphiti
|
||
from graphiti_core.driver.neptune_driver import NeptuneDriver
|
||
|
||
# Create a Neptune driver
|
||
driver = NeptuneDriver(
|
||
host='<NEPTUNE_ENDPOINT>',
|
||
aoss_host='<AMAZON_OPENSEARCH_SERVERLESS_HOST>',
|
||
port=8182, # Optional, defaults to 8182
|
||
aoss_port=443, # Optional, defaults to 443
|
||
)
|
||
|
||
# Pass the driver to Graphiti
|
||
graphiti = Graphiti(graph_driver=driver)
|
||
```
|
||
|
||
要贡献新的图数据库后端？请参阅 [Adding a graph driver](CONTRIBUTING.md#adding-a-graph-driver)。
|
||
|
||
## 在 Graphiti 中使用 Azure OpenAI
|
||
|
||
Graphiti 通过 Azure 的 OpenAI v1 API 兼容层，支持将 Azure OpenAI 用于 LLM 推理和嵌入（embeddings）。
|
||
|
||
### 快速入门
|
||
|
||
```python
|
||
from openai import AsyncOpenAI
|
||
from graphiti_core import Graphiti
|
||
from graphiti_core.llm_client.azure_openai_client import AzureOpenAILLMClient
|
||
from graphiti_core.llm_client.config import LLMConfig
|
||
from graphiti_core.embedder.azure_openai import AzureOpenAIEmbedderClient
|
||
|
||
# Initialize Azure OpenAI client using the standard OpenAI client
|
||
# with Azure's v1 API endpoint
|
||
azure_client = AsyncOpenAI(
|
||
base_url="https://your-resource-name.openai.azure.com/openai/v1/",
|
||
api_key="your-api-key",
|
||
)
|
||
|
||
# Create LLM and Embedder clients
|
||
llm_client = AzureOpenAILLMClient(
|
||
azure_client=azure_client,
|
||
config=LLMConfig(model="gpt-5-mini", small_model="gpt-5-mini") # Your Azure deployment name
|
||
)
|
||
embedder_client = AzureOpenAIEmbedderClient(
|
||
azure_client=azure_client,
|
||
model="text-embedding-3-small" # Your Azure embedding deployment name
|
||
)
|
||
|
||
# Initialize Graphiti with Azure OpenAI clients
|
||
graphiti = Graphiti(
|
||
"bolt://localhost:7687",
|
||
"neo4j",
|
||
"password",
|
||
llm_client=llm_client,
|
||
embedder=embedder_client,
|
||
)
|
||
|
||
# Now you can use Graphiti with Azure OpenAI
|
||
```
|
||
|
||
**要点：**
|
||
|
||
- 使用标准 `AsyncOpenAI` 客户端，配合 Azure 的 v1 API 端点格式：
|
||
`https://your-resource-name.openai.azure.com/openai/v1/`
|
||
- 部署名称（例如 `gpt-5-mini`、`text-embedding-3-small`）应与你的 Azure OpenAI 部署名称一致
|
||
- 完整可运行示例请参阅 `examples/azure-openai/`
|
||
|
||
请务必将占位符值替换为你的实际 Azure OpenAI 凭据和部署名称。
|
||
|
||
## 在 Graphiti 中使用 Google Gemini
|
||
|
||
Graphiti 支持将 Google 的 Gemini 模型用于 LLM 推理、嵌入以及交叉编码/重排序（cross-encoding/reranking）。要使用 Gemini，
|
||
你需要使用 Google API 密钥配置 LLM 客户端、嵌入器（embedder）和交叉编码器（cross-encoder）。
|
||
|
||
安装 Graphiti：
|
||
|
||
```bash
|
||
uv add "graphiti-core[google-genai]"
|
||
|
||
# or
|
||
|
||
pip install "graphiti-core[google-genai]"
|
||
```
|
||
|
||
```python
|
||
from graphiti_core import Graphiti
|
||
from graphiti_core.llm_client.gemini_client import GeminiClient, LLMConfig
|
||
from graphiti_core.embedder.gemini import GeminiEmbedder, GeminiEmbedderConfig
|
||
from graphiti_core.cross_encoder.gemini_reranker_client import GeminiRerankerClient
|
||
|
||
# Google API key configuration
|
||
api_key = "<your-google-api-key>"
|
||
|
||
# Initialize Graphiti with Gemini clients
|
||
graphiti = Graphiti(
|
||
"bolt://localhost:7687",
|
||
"neo4j",
|
||
"password",
|
||
llm_client=GeminiClient(
|
||
config=LLMConfig(
|
||
api_key=api_key,
|
||
model="gemini-2.0-flash"
|
||
)
|
||
),
|
||
embedder=GeminiEmbedder(
|
||
config=GeminiEmbedderConfig(
|
||
api_key=api_key,
|
||
embedding_model="embedding-001"
|
||
)
|
||
),
|
||
cross_encoder=GeminiRerankerClient(
|
||
config=LLMConfig(
|
||
api_key=api_key,
|
||
model="gemini-2.5-flash-lite"
|
||
)
|
||
)
|
||
)
|
||
|
||
# Now you can use Graphiti with Google Gemini for all components
|
||
```
|
||
|
||
Gemini 重排序器默认使用 `gemini-2.5-flash-lite` 模型，该模型针对
|
||
高性价比、低延迟的分类任务进行了优化。它采用与 OpenAI
|
||
重排序器相同的布尔分类方法，利用 Gemini 的对数概率（log probabilities）功能对段落相关性进行排序。
|
||
|
||
## 在 Graphiti 中使用 OpenAI 兼容提供商与本地 LLM
|
||
|
||
Graphiti 可通过 `OpenAIGenericClient` 使用任何 OpenAI 兼容的 `/v1` 端点进行 LLM 推理——包括**托管
|
||
提供商**（DeepSeek、Together、OpenRouter、Fireworks 等）和**本地服务器**（Ollama、vLLM、llama.cpp、LM
|
||
Studio）。本地服务器非常适合注重隐私的应用，或用于避免 API 费用。以下示例使用 Ollama；
|
||
对于其他提供商，将 `base_url` 指向其端点，并设置相应的 `api_key` 和 `model`。
|
||
|
||
**注意：** 对于这些端点，请使用 `OpenAIGenericClient`（而非 `OpenAIClient`）。它针对本地模型进行了优化，
|
||
默认最大 token 上限更高（16K 对比 8K），并能在兼容的提供商之间处理结构化输出。
|
||
|
||
安装模型：
|
||
|
||
```bash
|
||
ollama pull deepseek-r1:7b # LLM
|
||
ollama pull nomic-embed-text # embeddings
|
||
```
|
||
|
||
```python
|
||
from graphiti_core import Graphiti
|
||
from graphiti_core.llm_client.config import LLMConfig
|
||
from graphiti_core.llm_client.openai_generic_client import OpenAIGenericClient
|
||
from graphiti_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig
|
||
from graphiti_core.cross_encoder.openai_reranker_client import OpenAIRerankerClient
|
||
|
||
# Configure Ollama LLM client
|
||
llm_config = LLMConfig(
|
||
api_key="ollama", # Ollama doesn't require a real API key, but some placeholder is needed
|
||
model="deepseek-r1:7b",
|
||
small_model="deepseek-r1:7b",
|
||
base_url="http://localhost:11434/v1", # Ollama's OpenAI-compatible endpoint
|
||
)
|
||
|
||
llm_client = OpenAIGenericClient(config=llm_config)
|
||
|
||
# Initialize Graphiti with Ollama clients
|
||
graphiti = Graphiti(
|
||
"bolt://localhost:7687",
|
||
"neo4j",
|
||
"password",
|
||
llm_client=llm_client,
|
||
embedder=OpenAIEmbedder(
|
||
config=OpenAIEmbedderConfig(
|
||
api_key="ollama", # Placeholder API key
|
||
embedding_model="nomic-embed-text",
|
||
embedding_dim=768,
|
||
base_url="http://localhost:11434/v1",
|
||
)
|
||
),
|
||
cross_encoder=OpenAIRerankerClient(client=llm_client, config=llm_config),
|
||
)
|
||
|
||
# Now you can use Graphiti with local Ollama models
|
||
```
|
||
|
||
请确保 Ollama 正在运行（`ollama serve`），且已拉取你要使用的模型。
|
||
|
||
### 结构化输出与小模型
|
||
|
||
Graphiti 依赖结构化（JSON）输出进行实体/边提取与去重，在能够可靠遵循该要求的模型
|
||
和提供商（OpenAI、Anthropic、Gemini）上效果最佳。不同 OpenAI 兼容提供商之间的可靠性差异较大，
|
||
尤其是在较小或本地模型上，因此 `OpenAIGenericClient` 提供了 `structured_output_mode`：
|
||
|
||
- `"json_schema"`（默认）：通过 `response_format` 请求原生结构化输出。在能力较强的模型和
|
||
通过约束解码（constrained decoding）强制执行 schema 的提供商上效果最佳。
|
||
- `"json_object"`：请求纯 JSON 模式，并将 schema 注入提示词中。适用于
|
||
不能可靠遵循 `json_schema` 的提供商/模型——包括某些本地服务器，它们会接受 `json_schema`
|
||
请求但实际上并不将输出约束到该 schema，此时 `json_object` 可能*更*可靠。
|
||
|
||
使用较小或本地模型时：
|
||
|
||
- 优先使用你能运行的最强模型。非常小的模型经常输出与请求
|
||
schema 不匹配的 JSON，这会表现为提取失败。
|
||
- 包裹在 Markdown ` ```json ` 代码围栏中的响应会自动剥离。
|
||
- 保持 `SEMAPHORE_LIMIT` 较低（参见[上文](#default-to-low-concurrency-llm-provider-429-rate-limit-errors)）——本地
|
||
服务器和部分提供商的并发能力有限。
|
||
|
||
## 文档
|
||
|
||
- [Guides and API documentation](https://help.getzep.com/graphiti).
|
||
- [Quick Start](https://help.getzep.com/graphiti/graphiti/quick-start)
|
||
- [Building an agent with LangChain's LangGraph and Graphiti](https://help.getzep.com/graphiti/integrations/lang-graph-agent)
|
||
|
||
## Telemetry
|
||
|
||
Graphiti 会收集匿名使用统计，帮助我们了解框架的使用情况并改进产品，惠及所有用户。我们重视透明度，因此下面会说明我们具体收集哪些数据以及原因。
|
||
|
||
### What We Collect
|
||
|
||
初始化 Graphiti 实例时，我们会收集：
|
||
|
||
- **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
|
||
|
||
我们致力于保护你的隐私。我们**从不**收集：
|
||
|
||
- 个人信息或标识符
|
||
- API keys 或凭据
|
||
- 你的实际数据、查询或图内容
|
||
- IP 地址或主机名
|
||
- 文件路径或系统特定信息
|
||
- 来自 episodes、nodes 或 edges 的任何内容
|
||
|
||
### Why We Collect This Data
|
||
|
||
这些信息帮助我们：
|
||
|
||
- 了解哪些配置最受欢迎，从而优先提供支持和测试
|
||
- 确定应重点投入开发的 LLM 和数据库提供商
|
||
- 跟踪采用模式以指导路线图
|
||
- 确保在不同 Python 版本和操作系统上的兼容性
|
||
|
||
通过分享这些匿名信息，你帮助我们让 Graphiti 对整个社区变得更好。
|
||
|
||
### View the Telemetry Code
|
||
|
||
Telemetry 代码[可在此处查看](graphiti_core/telemetry/telemetry.py)。
|
||
|
||
### How to Disable Telemetry
|
||
|
||
Telemetry 采用**选择退出（opt-out）**机制，可随时禁用。要禁用 telemetry 收集：
|
||
|
||
**Option 1: Environment Variable**
|
||
|
||
```bash
|
||
export GRAPHITI_TELEMETRY_ENABLED=false
|
||
```
|
||
|
||
**Option 2: Set in your shell profile**
|
||
|
||
```bash
|
||
# For bash users (~/.bashrc or ~/.bash_profile)
|
||
echo 'export GRAPHITI_TELEMETRY_ENABLED=false' >> ~/.bashrc
|
||
|
||
# For zsh users (~/.zshrc)
|
||
echo 'export GRAPHITI_TELEMETRY_ENABLED=false' >> ~/.zshrc
|
||
```
|
||
|
||
**Option 3: Set for a specific Python session**
|
||
|
||
```python
|
||
import os
|
||
|
||
os.environ['GRAPHITI_TELEMETRY_ENABLED'] = 'false'
|
||
|
||
# Then initialize Graphiti as usual
|
||
from graphiti_core import Graphiti
|
||
|
||
graphiti = Graphiti(...)
|
||
```
|
||
|
||
在测试运行期间（检测到 `pytest` 时），Telemetry 会自动禁用。
|
||
|
||
### Technical Details
|
||
|
||
- Telemetry 使用 PostHog 进行匿名分析收集
|
||
- 所有 telemetry 操作均设计为静默失败——它们不会中断你的应用，也不会影响 Graphiti 功能
|
||
- 匿名 ID 存储在本地，不与任何个人信息关联
|
||
|
||
## Contributing
|
||
|
||
我们鼓励并感谢各种形式的贡献，无论是代码、文档、处理 GitHub Issues，还是在 Graphiti Discord 频道中回答问题。有关代码贡献的详细指南，请参阅 [CONTRIBUTING](CONTRIBUTING.md)。
|
||
|
||
## Support
|
||
|
||
加入 [Zep Discord server](https://discord.com/invite/W8Kw6bsgXQ))，前往 **#Graphiti** 频道！
|