# https://github.com/getzep/graphiti 项目说明书
生成时间：2026-05-31 03:24:14 UTC
## 目录
- [Graphiti 概述](#page-overview)
- [核心概念](#page-core-concepts)
- [系统架构](#page-architecture)
- [数据流与摄取管道](#page-data-flow)
- [Neo4j 驱动详解](#page-neo4j-driver)
- [FalkorDB 驱动详解](#page-falkordb-driver)
- [Kuzu 与 Amazon Neptune 驱动](#page-other-drivers)
- [LLM 提供商集成](#page-llm-providers)
- [向量嵌入与重排序](#page-embeddings)
- [混合搜索与检索](#page-hybrid-search)
## Graphiti 概述
### 相关页面
相关主题：[核心概念](#page-core-concepts), [系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/getzep/graphiti/blob/main/README.md)
- [examples/quickstart/README.md](https://github.com/getzep/graphiti/blob/main/examples/quickstart/README.md)
- [mcp_server/README.md](https://github.com/getzep/graphiti/blob/main/mcp_server/README.md)
- [mcp_server/src/graphiti_mcp_server.py](https://github.com/getzep/graphiti/blob/main/mcp_server/src/graphiti_mcp_server.py)
- [mcp_server/src/models/entity_types.py](https://github.com/getzep/graphiti/blob/main/mcp_server/src/models/entity_types.py)
- [server/README.md](https://github.com/getzep/graphiti/blob/main/server/README.md)
- [examples/azure-openai/README.md](https://github.com/getzep/graphiti/blob/main/examples/azure-openai/README.md)
# Graphiti 概述
Graphiti 是一个用于为 AI Agent 构建和查询时序上下文图（Temporal Context Graph）的开源框架。与传统的静态知识图谱不同，Graphiti 的上下文图谱能够追踪事实随时间的变化、维护数据溯源，并同时支持预设和自学习的本体论——使其特别适合在动态、实时变化的数据环境中运行的 AI Agent。
## 核心定位
Graphiti 与传统 GraphRAG 方法的关键区别：
| 特性 | GraphRAG | Graphiti |
|------|----------|----------|
| **主要用途** | 静态文档摘要 | Agent 的动态演进上下文 |
| **数据处理** | 批量导向处理 | 持续增量更新 |
| **知识结构** | 实体聚类与社区摘要 | 时序上下文图——具有有效性时间窗口的实体、事实、 Episodes、社区 |
| **检索方式** | 顺序 LLM 摘要 | 混合语义、关键词和基于图的搜索 |
| **适应性** | 低 | 高 |
| **时序处理** | 基本时间戳追踪 | 显式双时态追踪，自动失效事实 |
| **矛盾处理** | LLM 驱动的摘要判断 | 自动事实失效，保留时序历史 |
| **查询延迟** | 秒级到数十秒 | 通常亚秒级延迟 |
| **自定义实体类型** | 否 | 是，通过 Pydantic 模型定制 |
| **可扩展性** | 中等 | 高，针对大数据集优化 |
资料来源：[README.md](https://github.com/getzep/graphiti/blob/main/README.md)
## 什么是上下文图（Context Graph）
**上下文图**是一种时序实体、关系和事实的知识图谱——例如 *"Kendra 喜欢阿迪达斯鞋（截至 2026 年 3 月）"*。与传统的知识图谱不同，上下文图中的每个事实都有一个有效性时间窗口：它何时变为真，何时（如果有的话）被取代。实体随时间演变并更新摘要。一切都可以追溯到 **Episodes**——生成这些知识的原始数据。
Graphiti 的独特之处在于其能够从非结构化和结构化数据自主构建上下文图，在保留完整时序历史的同时处理变化的关系。
上下文图包含以下组件：
| 组件 | 存储内容 |
|------|----------|
| **实体（Entities）** | 人、产品、政策、概念——具有随时间演变的摘要 |
| **事实/关系（Facts/Relationships）** | 三元组（实体 → 关系 → 实体），具有时序有效性窗口 |
| **Episodes（溯源）** | 摄取的原始数据——真实的数据流。每个派生事实都可追溯到此处 |
| **自定义类型（Custom Types）** | 通过 Pydantic 模型定义的开发者自定义实体和边类型 |
资料来源：[README.md](https://github.com/getzep/graphiti/blob/main/README.md)
## 核心能力
### 时序事实管理
事实具有有效性时间窗口。当信息发生变化时，旧事实会被失效——而非删除。用户可以查询现在什么是真的，或者在任何时间点什么是真的。
### Episodes 与溯源
每个实体和关系都可以追溯到生成它的 Episodes（原始数据）。从派生事实到源数据的完整 lineage。
### 混合检索
结合多种搜索策略：
- **语义搜索**：使用嵌入向量查找语义相似的内容
- **BM25**：基于关键词的文本检索
- **图遍历**：利用实体之间的关系
### 增量数据更新
支持增量数据更新、高效检索和精确的历史查询，无需完全重新计算图谱。
资料来源：[README.md](https://github.com/getzep/graphiti/blob/main/README.md)
## 架构概览
Graphiti 的系统架构如下：
```mermaid
graph TB
subgraph "数据输入层"
Episodes[Episodes
文本/消息/JSON]
end
subgraph "核心处理层"
Extractor[实体与关系提取器]
Grapher[图构建器]
Indexer[索引构建器]
end
subgraph "存储层"
Neo4j[(Neo4j)]
FalkorDB[(FalkorDB)]
Kuzu[(Kuzu)]
Neptune[(Amazon Neptune)]
end
subgraph "搜索层"
SemanticSearch[语义搜索]
BM25Search[BM25 搜索]
GraphTraversal[图遍历]
end
subgraph "输出层"
QueryResults[查询结果]
API[MCP / REST API]
end
Episodes --> Extractor
Extractor --> Grapher
Grapher --> Indexer
Indexer --> Neo4j
Indexer --> FalkorDB
Indexer --> Kuzu
Indexer --> Neptune
SemanticSearch --> QueryResults
BM25Search --> QueryResults
GraphTraversal --> QueryResults
QueryResults --> API
```
## 支持的数据库后端
Graphiti 支持多种图数据库作为存储后端：
| 数据库 | 类型 | 说明 |
|--------|------|------|
| **Neo4j** | 标签属性图 | 5.26+ 推荐，成熟稳定的生产级选择 |
| **FalkorDB** | 标签属性图 | 1.1.2+，开源高性能选择 |
| **Kuzu** | 标签属性图 | 0.11.2+，嵌入式分析型数据库 |
| **Amazon Neptune** | 标签属性图/属性图 | Neptune Database Cluster 或 Neptune Analytics Graph |
> [!NOTE]
> 当前版本不支持 RDF 知识图谱集成（社区议题 #933）。用户请求也包括对 Postgres（带 pgvector）和 MemGraph 的支持。
资料来源：[README.md](https://github.com/getzep/graphiti/blob/main/README.md)
## 支持的 LLM 和 Embedding 提供商
### LLM 提供商
| 提供商 | 配置项 |
|--------|--------|
| OpenAI | `OPENAI_API_KEY` |
| Azure OpenAI | `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_API_KEY` |
| Anthropic | `ANTHROPIC_API_KEY` |
| Google Gemini | `GOOGLE_API_KEY` |
| Groq | `GROQ_API_KEY` |
### Embedding 提供商
| 提供商 | 配置项 |
|--------|--------|
| OpenAI | 默认选项 |
| Azure OpenAI | 与 Azure LLM 配合使用 |
| Voyage | 需配置 `VOYAGE_API_KEY` |
| Sentence Transformers | 本地运行，无需 API Key |
| Gemini Embeddings | `GOOGLE_API_KEY` |
资料来源：[mcp_server/README.md](https://github.com/getzep/graphiti/blob/main/mcp_server/README.md)
## MCP 服务器
Graphiti 提供了一个实验性的 Model Context Protocol (MCP) 服务器实现，允许 AI 助手通过 MCP 协议与 Graphiti 的知识图谱功能交互。
### MCP 工具列表
| 工具 | 功能 |
|------|------|
| `add_memory` | 向知识图谱添加 Episode |
| `search_nodes` | 使用自然语言查询搜索实体节点 |
| `search_facts` | 搜索知识图谱中的事实（边） |
| `get_entity_edge` | 通过 UUID 获取实体边 |
| `get_episodes` | 获取特定 Group 的最新 Episodes |
| `delete_entity_edge` | 删除实体边 |
| `delete_episode` | 删除 Episode |
| `clear_graph` | 清除图谱数据并重建索引 |
| `get_status` | 获取 MCP 服务器状态和数据库连接状态 |
资料来源：[mcp_server/README.md](https://github.com/getzep/graphiti/blob/main/mcp_server/README.md)
## 自定义实体类型
Graphiti 支持通过 Pydantic 模型定义开发者自定义的实体类型。内置实体类型包括：
| 实体类型 | 用途 | 描述 |
|----------|------|------|
| `Preference` | 偏好 | 用户偏好、选择、意见或选择 |
| `Requirement` | 需求 | 特定需求、功能或必须满足的条件 |
| `Procedure` | 程序 | 步骤、流程、操作方法 |
| `Location` | 位置 | 地点、地理区域 |
| `Event` | 事件 | 发生的事件、会议、活动 |
| `Organization` | 组织 | 公司、机构、团体 |
| `Topic` | 主题 | 讨论主题、兴趣或知识领域 |
| `Object` | 对象 | 物理物品、工具、设备 |
| `Document` | 文档 | 文件、书籍、文章 |
> [!IMPORTANT]
> `Preference` 类型具有最高优先级，在实体分类时应优先考虑。
资料来源：[mcp_server/src/models/entity_types.py](https://github.com/getzep/graphiti/blob/main/mcp_server/src/models/entity_types.py)
## 安装要求
| 要求 | 说明 |
|------|------|
| Python | 3.10 或更高版本 |
| 数据库 | Neo4j 5.26+ / FalkorDB 1.1.2+ / Kuzu 0.11.2+ / Amazon Neptune |
| 全文本搜索 | Amazon OpenSearch Serverless Collection（用于 Neptune 后端） |
| LLM API | OpenAI API Key（Graphiti 默认使用） |
```bash
pip install graphiti-core
```
资料来源：[README.md](https://github.com/getzep/graphiti/blob/main/README.md)
## 快速开始流程
```mermaid
graph LR
A[安装 Graphiti] --> B[配置数据库连接]
B --> C[配置 LLM/Embedding]
C --> D[初始化图谱]
D --> E[添加 Episodes]
E --> F[搜索查询]
F --> G[获取结果]
```
### 基本使用示例
```python
from graphiti_core import Graphiti
from graphiti_core.driver.neo4j import Neo4jDriver
# 初始化 Neo4j 驱动
driver = Neo4jDriver(
uri="bolt://localhost:7687",
user="neo4j",
password="password"
)
# 创建 Graphiti 实例
graphiti = Graphiti(driver=driver)
# 添加 Episode
episode = await graphiti.add_episode(
name="Customer Feedback",
episode_body="用户反馈：产品质量很好，但物流速度需要改进",
source="chat"
)
# 搜索节点
results = await graphiti.search_nodes(
query="产品质量反馈",
center_node_uuid=episode.uuid,
num_results=5
)
```
资料来源：[examples/quickstart/README.md](https://github.com/getzep/graphiti/blob/main/examples/quickstart/README.md)
## 遥测数据收集
Graphiti 在初始化时会收集匿名遥测数据，用于了解配置选择和采用模式。
### 收集的数据
- 匿名标识符（随机 UUID）
- 系统信息（操作系统、Python 版本、架构）
- Graphiti 版本
- 配置选择（LLM 提供商、数据库后端、Embedding 提供商）
### 不收集的数据
- 个人身份信息
- API 密钥或凭证
- 实际数据、查询或图谱内容
- IP 地址或主机名
- 文件路径
遥测是**可选退出**的，可以在任何时候禁用：
```python
# 在初始化前设置
import os
os.environ["GRAPHITI_TELEMETRY_ENABLED"] = "false"
```
资料来源：[README.md](https://github.com/getzep/graphiti/blob/main/README.md)
## 版本历史与已知问题
### 最新版本：v0.29.1
主要优化和效率改进：
- **属性幻觉防护**：防止 LLM 将元推理内容写入实体属性字段
- **更低的提取成本**：新的组合节点+边提取路径
### 已知问题
| Issue | 描述 | 影响版本 |
|-------|------|----------|
| [#1483](https://github.com/getzep/graphiti/issues/1483) | FalkorDriver.build_fulltext_query 在 group_id 包含连字符时失败 | 0.29.x |
| [#1481](https://github.com/getzep/graphiti/issues/1481) | Neo4jDriver.execute_query() 的 database 参数未正确传递 | 0.29.x |
| [#1477](https://github.com/getzep/graphiti/issues/1477) | SearchInterface 使用已弃用的 Pydantic v1 风格 Config | 0.29.x |
| [#1438](https://github.com/getzep/graphiti/issues/1438) | MCP search_facts 失败，无法序列化 neo4j.time.DateTime | 影响 MCP 用户 |
### 安全版本
- **v0.28.2**：修复 Cypher 注入漏洞，建议所有用户升级
- **mcp-v1.0.2**：要求 graphiti-core >= 0.28.2
资料来源：[community_context](#community_context)
## 与 Zep 的关系
| 方面 | Zep | Graphiti |
|------|-----|----------|
| **定位** | AI Agent 的托管上下文图基础设施 | 开源时序上下文图引擎 |
| **上下文图谱** | 管理大量用户/实体级别的上下文图谱 | 构建和查询单个上下文图谱 |
| **用户管理** | 内置用户、线程和消息存储 | 需要自行构建 |
| **检索性能** | 预配置，规模化下 <200ms | 自定义实现，性能依赖配置 |
| **部署** | 完全托管或云端 | 仅支持自托管 |
**选择 Zep**：如果需要企业级即用型平台，内置安全性、性能和支持。
**选择 Graphiti**：如果需要灵活的开源核心，并愿意自行构建和运维周边系统。
资料来源：[README.md](https://github.com/getzep/graphiti/blob/main/README.md)
## Docker 部署
Graphiti 服务容器已自动构建并发布到 Docker Hub：
```yaml
# docker-compose 示例
services:
graphiti:
image: zepai/graphiti:latest
environment:
- OPENAI_API_KEY=${OPENAI_API_KEY}
- NEO4J_URI=${NEO4J_URI}
- NEO4J_USER=${NEO4J_USER}
- NEO4J_PASSWORD=${NEO4J_PASSWORD}
depends_on:
- neo4j
neo4j:
image: neo4j:latest
ports:
- "7474:7474"
- "7687:7687"
```
资料来源：[server/README.md](https://github.com/getzep/graphiti/blob/main/server/README.md)
---
## 核心概念
### 相关页面
相关主题：[Graphiti 概述](#page-overview), [数据流与摄取管道](#page-data-flow)
相关源码文件
以下源码文件用于生成本页说明：
- [graphiti_core/nodes.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/nodes.py)
- [graphiti_core/edges.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/edges.py)
- [graphiti_core/graphiti_types.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/graphiti_types.py)
- [graphiti_core/models/nodes/node_db_queries.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/models/nodes/node_db_queries.py)
- [graphiti_core/models/edges/edge_db_queries.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/models/edges/edge_db_queries.py)
- [graphiti_core/search/search_config_recipes.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/search/search_config_recipes.py)
# 核心概念
Graphiti 是一个用于构建**时序上下文图谱**（Temporal Context Graph）的开源引擎。本页详细介绍 Graphiti 的核心数据模型、实体类型、关系管理以及检索机制，帮助开发者理解系统的工作原理和设计理念。
---
## 1. 上下文图谱概述
上下文图谱是 Graphiti 的核心抽象，它是一种时序知识图谱，专门为 AI 代理的记忆管理而设计。与传统的静态知识图谱不同，上下文图谱中的每条事实都带有**有效期窗口**（validity window），记录该事实何时生效、何时被取代。
```mermaid
graph LR
A[原始数据 Episodes] --> B[实体 Entities]
A --> C[事实 Facts]
B --> D[实体摘要 Summaries]
C --> E[时序有效性]
style A fill:#e1f5fe
style B fill:#fff3e0
style C fill:#e8f5e9
```
### 1.1 上下文图谱的核心特征
| 特征 | 描述 |
|------|------|
| **时序事实管理** | 事实具有有效期窗口，信息变更时旧事实被失效而非删除 |
| **血缘追溯** | 每个实体和关系都可以追溯到产生它的原始片段（Episode） |
| **增量构建** | 新数据立即集成，无需批量重新计算 |
| **混合检索** | 结合语义嵌入、关键词（BM25）和图遍历进行低延迟检索 |
资料来源：[README.md](https://github.com/getzep/graphiti/blob/main/README.md)
---
## 2. 实体（Entity）
实体是图谱中的节点，代表知识图谱中的主要研究对象。Graphiti 支持灵活的实体类型定义，开发者可以通过 Pydantic 模型自定义实体类型。
### 2.1 实体类型体系
Graphiti 预定义了一套实体类型体系，存放在 `mcp_server/src/models/entity_types.py` 中：
```mermaid
graph TD
E[实体 Entity] --> U[User 用户]
E --> A[Assistant 助手]
E --> P[Preference 偏好]
E --> R[Requirement 需求]
E --> O[Organization 组织]
E --> D[Document 文档]
E --> L[Location 位置]
E --> V[Event 事件]
E --> T[Topic 主题]
E --> Obj[Object 对象]
E --> Pr[Procedure 流程]
```
### 2.2 实体的数据结构
实体（Node）在代码中的定义位于 `graphiti_core/nodes.py`。核心字段包括：
| 字段 | 类型 | 描述 |
|------|------|------|
| `uuid` | str | 实体的唯一标识符 |
| `name` | str | 实体名称 |
| `entity_type` | str | 实体类型（如 Person, Organization） |
| `summary` | str | 实体的文本摘要，会随时间更新 |
| `created_at` | datetime | 实体创建时间 |
| `valid_from` | datetime | 事实有效期起始时间 |
| `valid_to` | datetime | 事实有效期结束时间（可为空） |
| `group_id` | str | 命名空间标识，用于隔离不同数据域 |
资料来源：[graphiti_core/nodes.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/nodes.py)
### 2.3 实体摘要机制
实体的 `summary` 字段是一个随时间演变的文本描述。当新的相关信息被摄入时，Graphiti 会更新实体的摘要，保留关键信息而忽略冗余内容。
```python
# graphiti_core/nodes.py 中的摘要生成逻辑
class Node(BaseNode):
"""实体节点的数据模型"""
summary: Optional[str] = Field(default=None)
summary_updated_at: Optional[datetime] = Field(default=None)
```
资料来源：[graphiti_core/nodes.py:45-50](https://github.com/getzep/graphiti/blob/main/graphiti_core/nodes.py)
---
## 3. 事实/关系（Fact/Edge）
事实（图中的边）表示两个实体之间的关系，是上下文图谱的核心连接。Graphiti 中的事实采用三元组结构：`Entity → Relationship → Entity`。
### 3.1 事实的数据结构
事实定义在 `graphiti_core/edges.py` 中：
| 字段 | 类型 | 描述 |
|------|------|------|
| `uuid` | str | 事实的唯一标识符 |
| `source_node_uuid` | str | 源实体 UUID |
| `target_node_uuid` | str | 目标实体 UUID |
| `fact` | str | 关系描述文本 |
| `fact_data` | dict | 关系的附加属性数据 |
| `valid_from` | datetime | 事实有效期起始 |
| `valid_to` | datetime | 事实有效期结束（可为空表示当前有效） |
资料来源：[graphiti_core/edges.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/edges.py)
### 3.2 时序有效性
事实的有效性通过 `valid_from` 和 `valid_to` 两个时间戳来管理：
```mermaid
sequenceDiagram
participant EP1 as Episode 1 (2024-01)
participant FACT as Fact/Edge
participant EP2 as Episode 2 (2024-03)
EP1->>FACT: valid_from: 2024-01-01
FACT->>EP1: 有效
EP2->>FACT: valid_to: 2024-02-28
Note over FACT: 事实失效，但数据保留
```
当新信息取代旧信息时，旧事实不会被物理删除，而是设置 `valid_to` 时间戳标记为失效。这种设计保留了完整的知识演变历史。
资料来源：[graphiti_core/graphiti_types.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/graphiti_types.py)
---
## 4. 片段（Episode）
片段是摄入到图谱中的原始数据，是所有派生事实的溯源。片段可以是文本、JSON 结构化数据或对话消息。
### 4.1 片段类型
Graphiti 支持三种片段类型：
| 类型 | 描述 | 使用场景 |
|------|------|----------|
| `text` | 纯文本内容 | 新闻文章、文档段落 |
| `json` | 结构化 JSON 数据 | CRM 数据、配置文件 |
| `message` | 对话式消息 | 聊天记录、会议纪要 |
### 4.2 片段的数据结构
片段记录在 `graphiti_core/graphiti_types.py` 中：
```python
@dataclass
class Episode:
"""片段：摄入的原始数据"""
uuid: str
name: str
episode_body: str
episode_type: EpisodeType
group_id: str
created_at: datetime
metadata: Optional[dict] = None
```
### 4.3 片段与实体的关系
```
┌─────────────┐ 产生 ┌─────────────┐
│ Episode │─────────────→│ Entity │
│ (原始数据) │ │ (实体) │
└─────────────┘ └─────────────┘
│ │
│ ↓
│ ┌─────────────┐
└────────────────────→│ Fact │
产生 │ (事实) │
└─────────────┘
```
每个实体和事实都可以通过片段 UUID 追溯到其原始数据来源。
资料来源：[graphiti_core/graphiti_types.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/graphiti_types.py)
---
## 5. 混合检索（Hybrid Retrieval）
Graphiti 采用混合检索策略，结合多种检索技术以实现低延迟、高精度的查询结果。
### 5.1 检索策略
| 策略 | 描述 | 技术 |
|------|------|------|
| **语义检索** | 基于向量嵌入的相似度搜索 | OpenAI/Gemini embeddings |
| **BM25 检索** | 基于关键词的经典文本检索 | 稀疏向量匹配 |
| **图遍历** | 利用图结构进行关系扩散 | Neo4j/FalkorDB Cypher |
### 5.2 检索配置预设
Graphiti 提供了多种检索配置预设，定义在 `graphiti_core/search/search_config_recipes.py` 中：
```python
# 节点混合搜索配置
NODE_HYBRID_SEARCH_RRF = {
"name": "node_hybrid_search_rrf",
"retriever_config": {
"semantic": {"weight": 0.5},
"keyword": {"weight": 0.5}
},
"reranker_config": {...}
}
```
### 5.3 中心节点搜索
一种高级检索模式是**中心节点搜索**（Center Node Search），它根据与指定节点的图距离对结果进行重新排序：
```mermaid
graph LR
A[查询] --> B[初始检索结果]
B --> C{计算图距离}
C --> D[中心节点]
D --> C
C --> E[重新排序结果]
style D fill:#f3e5f5
```
资料来源：[graphiti_core/search/search_config_recipes.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/search/search_config_recipes.py)
---
## 6. 支持的图数据库
Graphiti 支持多种图数据库后端，提供了统一的抽象接口。
### 6.1 数据库驱动支持
| 数据库 | 状态 | 全文搜索后端 |
|--------|------|-------------|
| **Neo4j** | 正式支持 | OpenSearch（可选） |
| **FalkorDB** | 正式支持 | 内置 RediSearch |
| **Kuzu** | 正式支持 | - |
| **Amazon Neptune** | 正式支持 | Amazon OpenSearch Serverless |
### 6.2 驱动架构
所有数据库驱动实现统一的接口：
```mermaid
classDiagram
class GraphDriver {
<>
+execute_query()
+create_node()
+create_edge()
+search_nodes()
}
class Neo4jDriver {
+execute_query()
+build_cypher_query()
}
class FalkorDriver {
+build_fulltext_query()
+build_cypher_query()
}
GraphDriver <|-- Neo4jDriver
GraphDriver <|-- FalkorDriver
```
### 6.3 已知限制
根据社区反馈，以下问题需要注意：
| 问题 | 影响版本 | 说明 |
|------|----------|------|
| `group_id` 含连字符时 RediSearch 语法错误 | 0.29.x | FalkorDB 驱动的 `build_fulltext_query` 未正确转义 |
| Neo4j 驱动 `database_` 参数传递问题 | 0.29.x | `execute_query()` 中参数名错误 |
资料来源：[graphiti_core/driver/search_interface/search_interface.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/driver/search_interface/search_interface.py)
---
## 7. 数据隔离与命名空间
Graphiti 使用 `group_id` 来实现数据隔离，不同的 `group_id` 下的数据和查询互不影响。
### 7.1 group_id 的作用
| 场景 | 说明 |
|------|------|
| 多租户应用 | 每个租户使用独立的 group_id |
| 主题隔离 | 不同主题的知识库使用不同 group_id |
| 环境分离 | 开发、测试、生产环境使用不同 group_id |
### 7.2 配置方式
`group_id` 可以通过环境变量或代码配置：
```yaml
# config.yaml
graphiti:
group_id: "production_user_123"
```
资料来源：[mcp_server/README.md](https://github.com/getzep/graphiti/blob/main/mcp_server/README.md)
---
## 8. 内容分块（Content Chunking）
为了高效处理长文本，Graphiti 实现了智能内容分块策略。
### 8.1 分块策略
| 内容类型 | 分块策略 |
|----------|----------|
| JSON 数据 | 保持数组元素边界，按数组索引分块 |
| 对话格式 | 按发言人消息边界分块，不拆分单条消息 |
| 纯文本 | 基于 token 计数的重叠分块 |
### 8.2 实体密度估算
系统会根据内容的实体密度自动决定是否需要分块：
```python
# graphiti_core/utils/content_chunking.py
def should_chunk(content: str, episode_type: EpisodeType, tokens: int) -> bool:
"""判断内容是否需要分块
高密度内容（每 token 实体多）需要分块
低密度内容（散文、叙述）分块会丢失上下文
"""
if episode_type == EpisodeType.json:
return _json_likely_dense(content, tokens)
return _text_likely_dense(content, tokens)
```
资料来源：[graphiti_core/utils/content_chunking.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/utils/content_chunking.py)
---
## 9. 快速参考
### 9.1 核心类和方法
| 类 | 文件 | 用途 |
|----|------|------|
| `Node` | `graphiti_core/nodes.py` | 实体数据模型 |
| `Edge` | `graphiti_core/edges.py` | 事实/关系数据模型 |
| `Episode` | `graphiti_core/graphiti_types.py` | 片段数据模型 |
| `Graphiti` | `graphiti_core/__init__.py` | 主客户端类 |
### 9.2 关键配置参数
| 参数 | 环境变量 | 默认值 | 说明 |
|------|----------|--------|------|
| Neo4j URI | `NEO4J_URI` | `bolt://localhost:7687` | 数据库连接地址 |
| Neo4j 用户 | `NEO4J_USER` | `neo4j` | 数据库用户名 |
| Neo4j 密码 | `NEO4J_PASSWORD` | `demodemo` | 数据库密码 |
| 默认 group_id | `GRAPHITI_GROUP_ID` | `main` | 默认命名空间 |
---
## 10. 相关资源
- **架构文档**: 参见 [Graphiti 与 GraphRAG 对比](#) 了解系统定位
- **API 参考**: 参见 MCP Server 工具文档了解可用操作
- **驱动实现**: 参见 `graphiti_core/driver/` 目录下的各数据库驱动
---
## 系统架构
### 相关页面
相关主题：[Graphiti 概述](#page-overview), [数据流与摄取管道](#page-data-flow), [Neo4j 驱动详解](#page-neo4j-driver)
相关源码文件
以下源码文件用于生成本页说明：
- [graphiti_core/graphiti.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/graphiti.py)
- [graphiti_core/driver/driver.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/driver/driver.py)
- [graphiti_core/driver/search_interface/search_interface.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/driver/search_interface/search_interface.py)
- [graphiti_core/llm_client/client.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/llm_client/client.py)
- [graphiti_core/search/search.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/search/search.py)
- [graphiti_core/utils/content_chunking.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/utils/content_chunking.py)
- [mcp_server/src/graphiti_mcp_server.py](https://github.com/getzep/graphiti/blob/main/mcp_server/src/graphiti_mcp_server.py)
- [mcp_server/src/models/entity_types.py](https://github.com/getzep/graphiti/blob/main/mcp_server/src/models/entity_types.py)
# 系统架构
Graphiti 是一个用于构建时序上下文图谱的开源引擎，专为 AI Agent 内存管理设计。本页详细说明 Graphiti 的核心系统架构，包括各组件职责、数据流转、以及扩展机制。
---
## 1. 整体架构概览
Graphiti 采用模块化分层架构，核心层包括：**驱动层（Driver Layer）**、**LLM 客户端层**、**搜索层（Search Layer）** 和 **业务编排层（Graphiti Core）**。
```mermaid
graph TD
subgraph 用户层["用户层"]
MCP["MCP Server"]
API["Python API"]
end
subgraph 核心层["graphiti_core 核心"]
G["Graphiti 主类
graphiti.py"]
SI["SearchInterface
搜索接口"]
end
subgraph 驱动层["Driver Layer"]
N4J["Neo4jDriver"]
FALK["FalkorDriver"]
KUZU["KuzuDriver"]
NEPTUNE["NeptuneDriver"]
end
subgraph 服务层["服务层"]
LLM["LLM Client"]
EMB["Embedder Client"]
CACHE["SQLite Cache"]
end
subgraph 存储层["存储层"]
GRAPH["图数据库"]
SEARCH["OpenSearch
(全文检索)"]
end
MCP --> G
API --> G
G --> SI
G --> LLM
G --> EMB
SI --> CACHE
SI --> GRAPH
SI --> SEARCH
LLM --> GRAPH
EMB --> GRAPH
N4J -.-> GRAPH
FALK -.-> GRAPH
KUZU -.-> GRAPH
NEPTUNE -.-> GRAPH
```
**架构特点：**
| 特性 | 说明 |
|------|------|
| 插件化驱动 | 通过 `BaseDriver` 抽象接口支持多种图数据库 |
| 统一搜索 | SearchInterface 提供混合搜索能力（语义 + BM25 + 图遍历） |
| 双时态模型 | 支持事实的有效期窗口，自动处理信息变更 |
| 可追溯性 | 所有实体和关系均可追溯到原始 Episode |
资料来源：[README.md](https://github.com/getzep/graphiti/blob/main/README.md)
---
## 2. 核心组件详解
### 2.1 Graphiti 主类
`Graphiti` 是整个库的主入口类，负责协调各组件完成图谱的构建和查询。
```python
class Graphiti:
def __init__(
self,
driver: BaseDriver,
embedder: BaseEmbedder,
llm: BaseLLMClient,
entity_types: list[type[BaseModel]] | None = None,
)
```
**主要职责：**
- 管理 Episode 的添加和解析
- 协调实体提取、关系构建
- 提供统一的数据查询接口
资料来源：[graphiti_core/graphiti.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/graphiti.py)
### 2.2 驱动层架构
驱动层采用策略模式设计，通过 `BaseDriver` 抽象基类定义统一的接口规范。
```mermaid
classDiagram
class BaseDriver {
<>
+build_fulltext_query() str
+execute_query() Result
+verify_connection() bool
+close()
}
class Neo4jDriver {
+execute_query()
+execute_cypher()
+verify_connection()
}
class FalkorDriver {
+build_fulltext_query()
+execute_query()
}
class KuzuDriver {
+execute_query()
}
class NeptuneDriver {
+execute_query()
}
BaseDriver <|-- Neo4jDriver
BaseDriver <|-- FalkorDriver
BaseDriver <|-- KuzuDriver
BaseDriver <|-- NeptuneDriver
```
**Neo4jDriver 已知问题：**
v0.29.0 版本中，`Neo4jDriver.execute_query()` 存在数据库参数传递问题：
- 问题位置：`Neo4jDriver.execute_query()` 错误地将 `database_` 放入 `parameters_` 而非方法参数
- 影响：查询时数据库参数无法正确传递给底层 Neo4j 连接器
- 状态：参见 [Issue #1481](https://github.com/getzep/graphiti/issues/1481)
**FalkorDriver 已知问题：**
`build_fulltext_query` 方法在处理包含连字符的 `group_id` 时存在 RediSearch 语法错误：
- 问题：仅用引号包裹，未正确转义连字符
- 影响：含连字符的 group_id 会导致查询解析失败
- 状态：参见 [Issue #1483](https://github.com/getzep/graphiti/issues/1483)
资料来源：[graphiti_core/driver/driver.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/driver/driver.py)
### 2.3 LLM 客户端层
LLM 客户端支持多种后端，用于实体提取、关系分析和摘要生成。
| 客户端类 | 支持的模型 |
|----------|------------|
| `OpenAILLMClient` | GPT-4, GPT-3.5 |
| `AzureOpenAILLMClient` | Azure OpenAI 部署 |
| `AnthropicLLMClient` | Claude 系列 |
| `GoogleLLMClient` | Gemini 模型 |
| `GroqLLMClient` | Groq 加速模型 |
**BaseLLMClient 抽象接口：**
```python
class BaseLLMClient(ABC):
@abstractmethod
async def generate(self, prompt: str, **kwargs) -> str:
pass
@abstractmethod
def generate_sync(self, prompt: str, **kwargs) -> str:
pass
```
资料来源：[graphiti_core/llm_client/client.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/llm_client/client.py)
---
## 3. 数据处理流程
### 3.1 Episode 摄入流程
当用户添加数据到图谱时，Graphiti 执行以下处理步骤：
```mermaid
flowchart TD
A[添加 Episode
add_episode] --> B{内容类型检测}
B -->|text| C[文本分块
ContentChunker]
B -->|json| D[JSON 解析]
B -->|message| E[消息边界分割]
C --> F[LLM 实体提取]
D --> F
E --> F
F --> G[实体消歧与去重]
G --> H[关系抽取]
H --> I[事实验证]
I --> J[图谱写入]
J --> K[索引更新]
K --> L[Summary 生成
更新实体摘要]
```
### 3.2 内容分块策略
`ContentChunker` 根据内容密度自动决定是否分块：
| 内容类型 | 分块策略 |
|----------|----------|
| JSON | 按数组元素或对象键密度评估 |
| 文本 | 按实体密度评估（实体数/Token数） |
| 消息 | 按发言人边界分割 |
```python
def _chunk_content(
content: str,
chunk_size_tokens: int | None = None,
overlap_tokens: int | None = None,
) -> list[str]:
"""分割内容同时保留消息边界"""
```
资料来源：[graphiti_core/utils/content_chunking.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/utils/content_chunking.py)
---
## 4. 搜索架构
### 4.1 SearchInterface 组件
`SearchInterface` 是搜索层的核心组件，提供混合检索能力：
```python
class SearchInterface:
def __init__(
self,
driver: BaseDriver,
embedder: BaseEmbedder,
config: SearchConfig,
)
```
> [!WARNING]
> 当前版本 `SearchInterface` 使用 Pydantic v1 风格的 `class Config:` 配置，在 Pydantic v3 中将导致硬失败。
> 状态：参见 [Issue #1477](https://github.com/getzep/graphiti/issues/1477)
### 4.2 混合搜索策略
Graphiti 的搜索结合三种检索方法：
```mermaid
graph LR
subgraph 混合搜索["混合搜索 Hybrid Search"]
A[用户查询] --> SEM[语义搜索
Embedding 相似度]
A --> BM25[BM25 关键词搜索]
A --> GRAPH[图遍历搜索]
SEM --> RRF[RRF 融合]
BM25 --> RRF
GRAPH --> RRF
RRF --> RESULT[重排序结果]
end
```
**搜索配置示例：**
```python
from graphiti_core.search.search_config_recipes import (
EDGE_HYBRID_SEARCH_RRF,
NODE_HYBRID_SEARCH_RRF,
)
# 边搜索配置
config = EDGE_HYBRID_SEARCH_RRF()
# 节点搜索配置
config = NODE_HYBRID_SEARCH_RRF()
```
资料来源：[graphiti_core/search/search.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/search/search.py)
### 4.3 时序查询支持
搜索支持基于时间的过滤和有效性窗口：
| 参数 | 说明 |
|------|------|
| `valid_at` | 查询特定时间点的事实 |
| `invalid_before` | 过滤在此之前失效的事实 |
| `include_invalid` | 是否包含已失效的事实 |
---
## 5. MCP Server 架构
### 5.1 架构概览
MCP Server 提供工具化接口，允许外部应用通过 MCP 协议访问 Graphiti 功能：
```mermaid
graph TD
subgraph MCP["Graphiti MCP Server"]
TOOLS["Tools: add_memory
search_nodes
search_facts
delete_entity_edge
get_episodes
clear_graph"]
SVC["GraphitiService"]
QUEUE["QueueService"]
end
TOOLS --> SVC
SVC --> QUEUE
SVC --> GRAPH[graphiti_core]
QUEUE --> TASKS["异步任务队列"]
```
### 5.2 可用工具
| 工具名称 | 功能说明 |
|----------|----------|
| `add_memory` | 添加文本、JSON 或消息数据到图谱 |
| `search_nodes` | 搜索图谱中的实体节点 |
| `search_facts` | 搜索实体间的关系事实 |
| `get_entity_edge` | 根据 UUID 获取特定边 |
| `delete_entity_edge` | 删除指定实体边 |
| `delete_episode` | 删除指定的 Episode |
| `get_episodes` | 获取指定分组的 Episodes |
| `clear_graph` | 清空图谱并重建索引 |
| `get_status` | 检查服务状态 |
### 5.3 已知问题
**MCP DateTime 序列化问题：**
`search_memory_facts` 在处理包含 `neo4j.time.DateTime` 类型数据的图谱时会失败：
```
Error: Unable to serialize unknown type:
```
状态：参见 [Issue #1438](https://github.com/getzep/graphiti/issues/1438)
资料来源：[mcp_server/src/graphiti_mcp_server.py](https://github.com/getzep/graphiti/blob/main/mcp_server/src/graphiti_mcp_server.py)
---
## 6. 配置系统
### 6.1 配置层次
Graphiti 支持多层次配置：
```mermaid
graph TD
A[config.yaml] --> B[环境变量覆盖]
B --> C[运行时参数]
subgraph 配置类别
DB[(数据库配置)]
LLM[(LLM 配置)]
EMB[(Embedding 配置)]
ENT[实体类型定义]
end
C --> DB
C --> LLM
C --> EMB
C --> ENT
```
### 6.2 环境变量
| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `NEO4J_URI` | Neo4j 连接 URI | `bolt://localhost:7687` |
| `NEO4J_USER` | Neo4j 用户名 | `neo4j` |
| `NEO4J_PASSWORD` | Neo4j 密码 | `demodemo` |
| `OPENAI_API_KEY` | OpenAI API 密钥 | - |
| `ANTHROPIC_API_KEY` | Anthropic API 密钥 | - |
| `GOOGLE_API_KEY` | Google API 密钥 | - |
### 6.3 自定义实体类型
通过 Pydantic 模型定义自定义实体类型：
```python
class Requirement(BaseModel):
name: str = Field(..., description='需求名称或标识符')
description: str = Field(..., description='需求描述')
class Preference(BaseModel):
"""用户偏好、选择、意见或取舍"""
...
```
预定义类型包括：`Requirement`, `Preference`, `Procedure`, `Location`, `Event`, `Object`, `Topic`, `Organization`, `Document`
资料来源：[mcp_server/src/models/entity_types.py](https://github.com/getzep/graphiti/blob/main/mcp_server/src/models/entity_types.py)
---
## 7. 安全机制
### 7.1 Cypher 注入防护
v0.28.2 版本强化了搜索过滤器的安全防护：
- 所有用户输入经过参数化处理
- `group_id` 等关键参数强制白名单验证
- 调试日志中不再输出敏感标识符
> [!IMPORTANT]
> MCP v1.0.2 及之前版本存在 Cypher 注入漏洞，请确保使用 `graphiti-core>=0.28.2`
### 7.2 缓存安全
v0.28.1 版本将 `diskcache` 替换为 SQLite 缓存，解决了已知的安全漏洞。
---
## 8. 版本演进与架构变更
| 版本 | 主要架构变更 |
|------|--------------|
| v0.29.0 | 合并节点+边提取路径，单次 LLM 调用覆盖原多次调用 |
| v0.28.0 | 驱动操作架构重构，简化提取管道 |
| v0.27.0 | 添加提取边事实到实体摘要，提升效率 |
| v0.26.x | 基础架构稳定，SearchInterface 引入 |
---
## 9. 扩展指南
### 9.1 添加新驱动
1. 继承 `BaseDriver` 抽象类
2. 实现所有抽象方法
3. 在配置系统中注册新驱动
```python
class NewGraphDriver(BaseDriver):
async def verify_connection(self) -> bool:
# 实现连接验证
pass
def execute_query(self, cypher: str, params: dict) -> Result:
# 实现查询执行
pass
```
### 9.2 社区需求
以下功能在社区中有较高呼声，但当前版本尚未支持：
- Amazon Bedrock 支持 ([Issue #459](https://github.com/getzep/graphiti/issues/459))
- PostgreSQL (pgvector) 存储引擎 ([Issue #779](https://github.com/getzep/graphiti/issues/779))
- RDF 知识图谱集成 ([Issue #933](https://github.com/getzep/graphiti/issues/933))
- MemGraph 驱动 ([Issue #642](https://github.com/getzep/graphiti/issues/642))
---
## 数据流与摄取管道
### 相关页面
相关主题：[核心概念](#page-core-concepts), [系统架构](#page-architecture), [LLM 提供商集成](#page-llm-providers)
相关源码文件
以下源码文件用于生成本页说明：
- [graphiti_core/graphiti.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/graphiti.py)
- [graphiti_core/utils/content_chunking.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/utils/content_chunking.py)
- [graphiti_core/utils/maintenance/combined_extraction.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/utils/maintenance/combined_extraction.py)
- [graphiti_core/utils/maintenance/node_operations.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/utils/maintenance/node_operations.py)
- [graphiti_core/utils/maintenance/edge_operations.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/utils/maintenance/edge_operations.py)
- [graphiti_core/prompts/extract_nodes_and_edges.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/prompts/extract_nodes_and_edges.py)
- [mcp_server/src/graphiti_mcp_server.py](https://github.com/getzep/graphiti/blob/main/mcp_server/src/graphiti_mcp_server.py)
- [mcp_server/src/models/entity_types.py](https://github.com/getzep/graphiti/blob/main/mcp_server/src/models/entity_types.py)
# 数据流与摄取管道
## 概述
Graphiti 的数据流与摄取管道是构建时序上下文图的核心组件，负责将原始数据（文本、JSON、对话等）转换为结构化的实体和关系。从 v0.29.0 版本开始，该管道进行了重大架构优化，引入了**合并节点和边提取路径**，允许单次 LLM 调用覆盖之前需要多次调用才能完成的工作，从而显著降低了提取成本。
管道的设计目标是支持：
- **增量图构建**：新数据立即整合，无需批量重新计算
- **多源数据支持**：文本、JSON、对话消息等多种输入格式
- **时序事实管理**：自动处理事实的有效期和失效
- **可定制本体**：通过 Pydantic 模型定义实体和边类型
资料来源：[README.md:18-24]()
## 核心数据模型
### Episode（事件）
Episode 是摄取管道的输入单位，代表原始数据的一次摄入。每个 Episode 包含：
| 属性 | 类型 | 说明 |
|------|------|------|
| `uuid` | str | 唯一标识符 |
| `name` | str | 事件名称 |
| `episode_body` | str | 原始内容 |
| `source` | EpisodeType | 来源类型 |
| `source_description` | str | 来源描述 |
| `created_at` | datetime | 创建时间 |
| `group_id` | str | 分组标识 |
支持的来源类型（`EpisodeType`）：
- `text`：纯文本内容
- `json`：结构化 JSON 数据
- `message`：对话式内容
资料来源：[mcp_server/src/graphiti_mcp_server.py:89-101]()
### Entity（实体）
实体是图中的节点，代表从数据中提取的有意义概念。Graphiti 支持以下内置实体类型：
| 类型 | 说明 | 使用优先级 |
|------|------|-----------|
| User | 用户身份 | 高 |
| Assistant | AI 助手 | 高 |
| Preference | 偏好、选择、意见 | **最高** |
| Requirement | 需求、功能 | 中 |
| Procedure | 操作步骤、流程 | 中 |
| Organization | 组织、公司、机构 | 低 |
| Document | 文档、文件 | 低 |
| Event | 事件、活动 | 低 |
| Location | 位置、地点 | 低 |
| Topic | 主题、话题 | 低 |
| Object | 物体、工具、设备 | 最后使用 |
> ⚠️ **注意**：`Preference` 类型具有最高优先级，当内容表达用户偏好时应优先使用此分类。
资料来源：[mcp_server/src/models/entity_types.py:1-80]()
### Fact/Edge（事实/边）
事实表示两个实体之间的关系，包含：
- 源实体
- 目标实体
- 关系名称
- 有效性时间窗口（`valid_from`, `valid_to`）
- 溯源信息（指向产生该事实的 Episode）
资料来源：[README.md:32-35]()
## 摄取管道架构
### 整体数据流
```mermaid
graph TD
A[原始输入] --> B{输入类型判断}
B -->|JSON| C[JSON 解析]
B -->|Text| D[内容分块]
B -->|Message| E[消息解析]
C --> F[合并提取]
D --> F
E --> F
F --> G[LLM 实体提取]
G --> H[LLM 边提取]
H --> I{事实去重检查}
I -->|新事实| J[写入图数据库]
I -->|已存在| K[更新有效期]
J --> L[更新实体摘要]
L --> M[(时序上下文图)]
```
### 摄取步骤详解
#### 第一阶段：内容预处理
根据输入内容的类型，管道执行不同的预处理策略：
1. **JSON 内容**：解析结构化数据，识别数组元素和对象键以评估实体密度
2. **文本内容**：进行内容分块，保留语义完整性
3. **对话内容**：保持消息边界，不在消息中间断开
资料来源：[graphiti_core/utils/content_chunking.py:1-50]()
#### 第二阶段：内容分块策略
Graphiti 使用基于 Token 的分块策略来处理长内容：
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `CHUNK_TOKEN_SIZE` | 动态计算 | 每个块的目标 Token 数 |
| `CHUNK_OVERLAP_TOKENS` | 动态计算 | 块之间的重叠 Token 数 |
分块决策基于**实体密度**评估：
- **高密度内容**（JSON 数组、列表等）：适合分块，每个元素可能包含独立实体
- **低密度内容**（散文、叙述）：不建议分块，会丢失上下文
```python
def _json_likely_dense(content: str, tokens: int) -> bool:
# JSON 数组：计算元素数量与 Token 比例
# 对象：计算顶层键数量
density = (element_count / tokens) * 1000 if tokens > 0 else 0
```
资料来源：[graphiti_core/utils/content_chunking.py:50-80]()
#### 第三阶段：合并实体和边提取
v0.29.0 引入的**合并提取模式**允许单次 LLM 调用同时提取节点和边：
```mermaid
graph LR
A[Episode Chunk] --> B[Combined Extraction Prompt]
B --> C[LLM API Call]
C --> D[结构化输出]
D --> E[节点处理]
D --> F[边处理]
```
提取过程遵循以下原则：
1. **Preference 优先**：偏好类信息使用低阈值提取
2. **继承上下文**：从同一 Episode 提取的实体和边相互关联
3. **自定义本体支持**：可扩展的 Pydantic 模型定义实体类型
资料来源：[graphiti_core/utils/maintenance/combined_extraction.py]()、[v0.29.0 Release Notes](https://github.com/getzep/graphiti/releases/tag/v0.29.0)
#### 第四阶段：图写入与时序管理
写入图数据库时，管道处理以下逻辑：
| 操作 | 说明 |
|------|------|
| 创建节点 | 新实体创建为图节点 |
| 更新有效期 | 已有实体的事实更新 `valid_from` |
| 失效旧事实 | 矛盾信息将旧事实的 `valid_to` 设置为当前时间 |
| 更新摘要 | 实体摘要随新信息更新 |
资料来源：[graphiti_core/utils/maintenance/node_operations.py]()、[graphiti_core/utils/maintenance/edge_operations.py]()
## MCP 服务摄取接口
MCP 服务器提供 `add_memory` 工具用于数据摄取：
```python
add_memory(
name="事件名称",
episode_body="原始内容",
source="text | json | message", # 来源类型
source_description="来源描述",
group_id="分组标识"
)
```
### JSON 数据摄取示例
MCP 服务支持通过 `source="json"` 自动从结构化数据提取实体和关系：
```python
add_memory(
name="Customer Profile",
episode_body='{"company": {"name": "Acme Technologies"}, "products": [{"id": "P001", "name": "CloudSync"}]}',
source="json",
source_description="CRM data"
)
```
资料来源：[mcp_server/src/graphiti_mcp_server.py:130-150]()
## 配置与调优
### 环境变量
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `NEO4J_URI` | `bolt://localhost:7687` | Neo4j 连接 URI |
| `NEO4J_USER` | `neo4j` | 用户名 |
| `NEO4J_PASSWORD` | `demodemo` | 密码 |
### 自定义实体类型
在 `config.yaml` 中定义自定义实体类型：
```yaml
graphiti:
entity_types:
- name: "Preference"
description: "User preferences, choices, opinions, or selections"
- name: "Requirement"
description: "Specific needs, features, or functionality"
```
资料来源：[mcp_server/README.md:50-60]()
## 已知问题与限制
### group_id 中的连字符问题
> 🔴 **BUG** ([#1483](https://github.com/getzep/graphiti/issues/1483))：`FalkorDriver.build_fulltext_query` 在 `group_id` 包含连字符时产生 RediSearch 语法错误。驱动程序注释声称通过引号处理连字符，但实现仅使用 `"..."` 包裹而未进行转义。
**变通方案**：避免在 `group_id` 中使用连字符，或使用下划线替代。
### 数据库参数问题
> 🔴 **BUG** ([#1481](https://github.com/getzep/graphiti/issues/1481))：`Neo4jDriver.execute_query()` 错误地将 `database_` 放入 `parameters_` 字典，导致查询时数据库参数未被正确传递。
### 日期时间序列化问题
> 🔴 **BUG** ([#1438](https://github.com/getzep/graphiti/issues/1438))：MCP `search_memory_facts` 在处理包含 `neo4j.time.DateTime` 类型的图时返回序列化错误。
### Pydantic v2 兼容性
> ⚠️ **DEPRECATION** ([#1477](https://github.com/getzep/graphiti/issues/1477))：`SearchInterface` 使用了 Pydantic v1 风格的 `class Config:`，在 v3 版本中将导致硬失败。
## 性能优化建议
### 1. 批量实体摘要
v0.28.0 引入了批量实体摘要功能，可减少 LLM 调用次数：
```python
# 在配置中启用批量摘要
config = GraphitiConfig(
batch_entity_summarization=True,
batch_size=10
)
```
### 2. 内容分块优化
对于高密度 JSON 数据，系统会自动评估是否需要分块。避免将大量无关内容放入单个 JSON 对象中。
### 3. group_id 命名规范
为避免 RediSearch 语法错误和数据库参数问题，建议：
- 使用下划线而非连字符：`user_123` 而非 `user-123`
- 避免特殊字符
- 保持命名简洁一致
## 相关文档
- [快速开始指南](../quickstart/README.md) - 基础摄取示例
- [Azure OpenAI 集成](../azure-openai/README.md) - 云端 LLM 配置
- [搜索配置](../graphiti_core/search/search_config_recipes.py) - 检索优化
- [v0.29.0 发布说明](https://github.com/getzep/graphiti/releases/tag/v0.29.0) - 架构变更详情
---
## Neo4j 驱动详解
### 相关页面
相关主题：[FalkorDB 驱动详解](#page-falkordb-driver), [Kuzu 与 Amazon Neptune 驱动](#page-other-drivers)
相关源码文件
以下源码文件用于生成本页说明：
- [graphiti_core/driver/neo4j_driver.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/driver/neo4j_driver.py)
- [graphiti_core/driver/neo4j/operations/graph_ops.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/driver/neo4j/operations/graph_ops.py)
- [graphiti_core/driver/neo4j/operations/search_ops.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/driver/neo4j/operations/search_ops.py)
- [graphiti_core/driver/neo4j/operations/entity_node_ops.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/driver/neo4j/operations/entity_node_ops.py)
- [graphiti_core/driver/neo4j/operations/entity_edge_ops.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/driver/neo4j/operations/entity_edge_ops.py)
- [graphiti_core/driver/neo4j/operations/episode_ops.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/driver/neo4j/operations/episode_ops.py)
- [graphiti_core/models/nodes/node_db_queries.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/models/nodes/node_db_queries.py)
- [mcp_server/src/services/factories.py](https://github.com/getzep/graphiti/blob/main/mcp_server/src/services/factories.py)
# Neo4j 驱动详解
## 概述
Neo4j 驱动是 Graphiti 框架中用于连接和操作 Neo4j 图数据库的核心组件。作为 Graphiti 支持的主要图存储后端之一，Neo4j 驱动提供了完整的图数据库操作能力，包括实体节点管理、关系边操作、搜索查询、Episode 管理以及图索引维护等功能。
Graphiti 的 Neo4j 驱动采用模块化架构设计，将不同类型的数据库操作分离到独立的操作模块中，通过统一的驱动接口对外提供服务。这种设计使得代码结构清晰，便于维护和扩展。
## 架构设计
### 驱动组件结构
```mermaid
graph TD
A[Neo4jDriver] --> B[Graphiti 核心接口]
A --> C[操作模块层]
C --> D[graph_ops.py
图操作]
C --> E[search_ops.py
搜索操作]
C --> F[entity_node_ops.py
实体节点操作]
C --> G[entity_edge_ops.py
实体边操作]
C --> H[episode_ops.py
Episode 操作]
I[neo4j-python-driver] --> A
J[Neo4j Database] --> I
```
Neo4j 驱动的核心类位于 `graphiti_core/driver/neo4j_driver.py`，它继承自基础驱动接口并封装了与 Neo4j 数据库的所有交互逻辑。驱动初始化时需要提供连接参数，包括 URI、用户名、密码以及可选的数据库名称。 资料来源：[graphiti_core/driver/neo4j_driver.py:1-100]()
### 数据库操作分层
| 层级 | 文件 | 职责 |
|------|------|------|
| 驱动层 | `neo4j_driver.py` | 连接管理、事务控制、查询执行 |
| 图操作层 | `graph_ops.py` | 索引管理、约束创建、图清理 |
| 搜索操作层 | `search_ops.py` | 混合搜索、全文查询、图距离计算 |
| 节点操作层 | `entity_node_ops.py` | 实体节点 CRUD、摘要管理 |
| 边操作层 | `entity_edge_ops.py` | 实体关系管理、时态事实处理 |
| Episode 操作层 | `episode_ops.py` | 数据摄入、来源追溯 |
## 核心配置
### 连接参数
```python
Neo4jDriver(
uri: str, # bolt://localhost:7687
user: str, # neo4j
password: str, # 数据库密码
database: str = "neo4j" # 数据库名称，默认为 "neo4j"
)
```
### 环境变量配置
| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `NEO4J_URI` | `bolt://localhost:7687` | Neo4j 连接 URI |
| `NEO4J_USER` | `neo4j` | 数据库用户名 |
| `NEO4J_PASSWORD` | `password` | 数据库密码 |
配置优先级：环境变量 > 配置文件 > 代码默认值 资料来源：[mcp_server/src/services/factories.py:1-50]()
### 配置示例
```python
# 基础连接配置
from graphiti_core.driver.neo4j_driver import Neo4jDriver
driver = Neo4jDriver(
uri="bolt://localhost:7687",
user="neo4j",
password="your_password"
)
# 使用自定义数据库
driver = Neo4jDriver(
uri="bolt://localhost:7687",
user="neo4j",
password="your_password",
database="custom_db"
)
```
## 节点操作
### 实体节点管理
实体节点是图中的核心元素，代表知识图谱中的实体对象。每个实体节点包含唯一标识符(UUID)、名称、分组标识、实体类型以及描述信息。 资料来源：[graphiti_core/driver/neo4j/operations/entity_node_ops.py:1-80]()
#### 节点数据模型
| 字段 | 类型 | 说明 |
|------|------|------|
| `uuid` | str | 全局唯一标识符 |
| `name` | str | 实体名称 |
| `entity_type` | str | 实体类型（Person, Organization 等） |
| `group_id` | str | 分组标识，用于数据隔离 |
| `summary` | str | 实体摘要信息 |
| `created_at` | datetime | 创建时间戳 |
| `valid_at` | datetime | 生效时间 |
| `invalid_at` | datetime | 失效时间（可为空） |
### 节点查询操作
Graphiti 提供了多种节点查询方式，包括按 UUID 查询、按分组查询、按名称搜索等。查询结果支持分页和排序功能。 资料来源：[graphiti_core/driver/neo4j/operations/entity_node_ops.py:80-150]()
## 边操作
### 实体关系管理
实体边表示图中实体之间的关系，是构建知识图谱的关键组成部分。每条边包含源实体、目标实体、关系名称、边类型以及时态信息。 资料来源：[graphiti_core/driver/neo4j/operations/entity_edge_ops.py:1-100]()
#### 边数据模型
| 字段 | 类型 | 说明 |
|------|------|------|
| `uuid` | str | 边唯一标识符 |
| `source_node_uuid` | str | 源实体节点 UUID |
| `target_node_uuid` | str | 目标实体节点 UUID |
| `name` | str | 关系名称 |
| `edge_type` | str | 边类型（事实、引用等） |
| `fact` | str | 事实描述 |
| `created_at` | datetime | 创建时间 |
| `valid_at` | datetime | 事实生效时间 |
| `invalid_at` | datetime | 事实失效时间 |
### 时态事实处理
Graphiti 的核心特性之一是支持时态事实管理。当新的事实与现有事实矛盾时，系统不会删除旧数据，而是通过设置 `invalid_at` 时间戳来标记失效，同时创建新的有效事实。这种设计保证了数据的可追溯性和历史查询能力。 资料来源：[graphiti_core/driver/neo4j/operations/entity_edge_ops.py:150-250]()
```mermaid
graph LR
A[Episode 1
2024-01-01] --> B[Alice 喜欢 苹果]
B --> C[valid_at: 2024-01-01
invalid_at: NULL]
D[Episode 2
2024-03-15] --> E[Alice 喜欢 香蕉]
E --> F[valid_at: 2024-03-15
invalid_at: NULL]
B -.-> G[invalid_at: 2024-03-15]
```
## 搜索操作
### 混合搜索机制
Neo4j 驱动实现了混合搜索功能，结合语义相似度和关键词匹配（BM25）来提供高质量的搜索结果。搜索操作支持按分组过滤，可以限制搜索范围到特定的数据分组。 资料来源：[graphiti_core/driver/neo4j/operations/search_ops.py:1-150]()
#### 搜索类型
| 搜索类型 | 说明 | 使用场景 |
|----------|------|----------|
| `hybrid` | 语义 + BM25 混合搜索 | 通用查询 |
| `semantic` | 纯语义向量搜索 | 语义相似度优先 |
| `keyword` | 纯 BM25 关键词搜索 | 精确匹配优先 |
| `graph_distance` | 图距离重排序 | 基于特定节点的相关性提升 |
### 全文索引
Graphiti 使用 Neo4j 的全文索引功能来支持高效的文本搜索。索引基于嵌入向量和原始文本构建，支持近似最近邻搜索和精确关键词匹配。 资料来源：[graphiti_core/driver/neo4j/operations/search_ops.py:150-300]()
## Episode 管理
### Episode 数据结构
Episode 是 Graphiti 中的原始数据容器，代表摄入图中的原始信息。每个 Episode 包含名称、来源描述、内容以及生成实体和边的引用。 资料来源：[graphiti_core/models/nodes/node_db_queries.py:1-50]()
| 字段 | 类型 | 说明 |
|------|------|------|
| `uuid` | str | Episode 唯一标识 |
| `name` | str | Episode 名称 |
| `source` | str | 来源类型（text, json, message 等） |
| `source_description` | str | 来源描述 |
| `content` | str | 原始内容 |
| `group_id` | str | 分组标识 |
| `entity_edges` | List[str] | 关联的实体边 UUID 列表 |
| `created_at` | datetime | 创建时间 |
| `valid_at` | datetime | 生效时间 |
### Episode 批量操作
为提高摄入效率，Graphiti 支持 Episode 批量操作。批量操作使用 Neo4j 的 UNWIND 子句来高效处理大量数据。 资料来源：[graphiti_core/models/nodes/node_db_queries.py:50-150]()
```cypher
UNWIND $episodes AS episode
MERGE (n:Episodic {uuid: episode.uuid})
SET n = {
uuid: episode.uuid,
name: episode.name,
group_id: episode.group_id,
source_description: episode.source_description,
source: episode.source,
content: episode.content,
entity_edges: join([x IN coalesce(episode.entity_edges, []) | toString(x) ], '|'),
created_at: episode.created_at,
valid_at: episode.valid_at
}
RETURN n.uuid AS uuid
```
## 图操作
### 索引和约束管理
Graphiti 在初始化时会创建必要的索引和约束，以确保查询性能和数据的唯一性保证。这些操作在 `graph_ops.py` 模块中实现。 资料来源：[graphiti_core/driver/neo4j/operations/graph_ops.py:1-100]()
#### 自动创建的约束
| 约束类型 | 作用节点/关系 | 字段 |
|----------|--------------|------|
| UNIQUE | Episodic | uuid |
| UNIQUE | EntityNode | uuid |
| UNIQUE | EntityEdge | uuid |
#### 自动创建的索引
| 索引类型 | 节点/关系 | 字段 |
|----------|----------|------|
| INDEX | Episodic | group_id |
| INDEX | EntityNode | group_id |
| INDEX | EntityNode | entity_type |
| INDEX | EntityEdge | group_id |
| FULLTEXT | EntityNode | name, summary |
### 图清理操作
`clear_graph` 方法用于清空图数据库中的所有数据并重建索引。这是一个破坏性操作，通常用于测试环境或需要完全重置的场景。 资料来源：[graphiti_core/driver/neo4j/operations/graph_ops.py:100-200]()
## 已知问题与注意事项
### 已识别的 Bug
**数据库参数传递问题（Issue #1481）**
在 Neo4jDriver.execute_query() 方法中，存在数据库参数未正确传递的问题。查询操作时 `database_` 参数被错误地放入 `parameters_` 中，导致自定义数据库名称无法生效。
**Neo4j DateTime 序列化问题（Issue #1438）**
MCP 服务器的 `search_memory_facts` 工具在处理包含 `neo4j.time.DateTime` 类型数据时，会抛出序列化错误。这是由于 MCP 协议的 JSON 序列化不支持 Neo4j 的时间类型。
### 使用建议
1. **数据库选择**：默认数据库名为 `neo4j`，如需使用其他数据库，请在驱动初始化时明确指定
2. **连接池**：Neo4j 驱动使用连接池管理连接，建议在高并发场景下配置合理的池大小
3. **事务处理**：写操作应在事务中执行以保证数据一致性
4. **索引维护**：在批量数据摄入后，建议运行索引统计更新以优化查询性能
## 与其他驱动的比较
| 特性 | Neo4j 驱动 | FalkorDB 驱动 |
|------|-----------|---------------|
| 默认数据库 | `neo4j` | `default_db` |
| 连接协议 | Bolt | Redis |
| 查询语言 | Cypher | RediSearch |
| 向量搜索 | 通过嵌入向量 | 原生支持 |
| 事务支持 | 完整 ACID | 受限 |
## 最佳实践
### 连接配置
```python
# 生产环境配置建议
from graphiti_core.driver.neo4j_driver import Neo4jDriver
driver = Neo4jDriver(
uri="neo4j://your-host:7687",
user="your_user",
password="your_secure_password",
database="production_db"
)
# 验证连接
await driver.verify_connectivity()
```
### 错误处理
```python
from neo4j.exceptions import ServiceUnavailable, AuthError
try:
result = await driver.execute_query(query, parameters)
except ServiceUnavailable:
# 处理连接断开
pass
except AuthError:
# 处理认证失败
pass
```
### 性能优化
1. **批量操作**：使用批量摄入而非单条写入
2. **索引优化**：确保常用查询字段已建立索引
3. **查询优化**：避免全表扫描，使用参数化查询
4. **连接复用**：在高并发场景下合理配置连接池参数
---
## FalkorDB 驱动详解
### 相关页面
相关主题：[Neo4j 驱动详解](#page-neo4j-driver), [Kuzu 与 Amazon Neptune 驱动](#page-other-drivers)
相关源码文件
以下源码文件用于生成本页说明：
- [graphiti_core/driver/falkordb_driver.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/driver/falkordb_driver.py)
- [graphiti_core/driver/falkordb/operations/search_ops.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/driver/falkordb/operations/search_ops.py)
- [graphiti_core/driver/falkordb/operations/graph_ops.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/driver/falkordb/operations/graph_ops.py)
- [mcp_server/README.md](https://github.com/getzep/graphiti/blob/main/mcp_server/README.md)
- [mcp_server/src/graphiti_mcp_server.py](https://github.com/getzep/graphiti/blob/main/mcp_server/src/graphiti_mcp_server.py)
- [README.md](https://github.com/getzep/graphiti/blob/main/README.md)
- [graphiti_core/utils/content_chunking.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/utils/content_chunking.py)
# FalkorDB 驱动详解
## 概述
FalkorDB 驱动是 Graphiti 项目中用于连接和操作 [FalkorDB](https://www.falkordb.com/) 图数据库的核心组件。FalkorDB 是一个基于 Redis 的图数据库，支持 RediSearch 全文搜索功能，能够高效存储和检索知识图谱中的实体、关系和事实。
Graphiti 的核心设计理念是支持多种图数据库后端，通过统一的驱动接口实现跨数据库兼容性。FalkorDB 驱动实现了与 Neo4j 驱动相同的抽象接口，使得用户可以在不修改业务代码的情况下切换底层存储引擎。
**主要职责：**
- 管理与 FalkorDB 的连接生命周期
- 执行图查询语言（基于 Redis/GQL）操作
- 利用 RediSearch 实现全文搜索和混合检索
- 维护图索引和约束条件
- 处理事实的有效性时间窗口
## 架构设计
### 驱动层次结构
FalkorDB 驱动采用分层架构设计，将核心图操作与搜索功能解耦：
```
┌─────────────────────────────────────────────────────────┐
│ Graphiti Core │
│ (业务逻辑层) │
└────────────────────────┬────────────────────────────────┘
│
┌────────────────────────▼────────────────────────────────┐
│ FalkorDBDriver │
│ (驱动抽象层) │
├─────────────────────────────────────────────────────────┤
│ ┌──────────────────┐ ┌──────────────────────────┐ │
│ │ SearchOps │ │ GraphOps │ │
│ │ (搜索操作层) │ │ (图操作层) │ │
│ └────────┬─────────┘ └──────────┬───────────────┘ │
│ │ │ │
│ ┌────────▼─────────────────────────────▼───────────────┐│
│ │ FalkorDB / RediSearch Client ││
│ │ (通信层) ││
│ └─────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────┘
```
### 核心组件
| 组件 | 文件路径 | 职责说明 |
|------|----------|----------|
| `FalkorDBDriver` | `graphiti_core/driver/falkordb_driver.py` | 主驱动类，管理连接和协调操作 |
| `SearchOps` | `graphiti_core/driver/falkordb/operations/search_ops.py` | 处理 RediSearch 全文搜索 |
| `GraphOps` | `graphiti_core/driver/falkordb/operations/graph_ops.py` | 处理图结构操作（节点、边、索引） |
## 搜索操作（SearchOps）
### 全文本查询构建
`SearchOps` 组件负责构建 RediSearch 查询语句，实现 Graphiti 的混合搜索功能。搜索功能支持按 `group_id` 过滤结果，这是多租户数据隔离的关键机制。
**查询构建流程：**
```mermaid
graph TD
A[输入: 查询文本 + group_id] --> B{检查 group_id 格式}
B -->|包含特殊字符| C[应用转义/引用处理]
B -->|普通格式| D[直接拼接]
C --> E[构建 FT.SEARCH 命令]
D --> E
E --> F[执行 RediSearch 查询]
F --> G[解析结果并返回]
```
### 关键方法：`build_fulltext_query`
`build_fulltext_query` 方法负责生成 RediSearch 兼容的查询字符串。该方法需要处理用户输入的特殊字符，包括空格、引号和连字符等。
```python
def build_fulltext_query(
query: str,
group_id: str,
index_name: str = "entities"
) -> str:
"""构建 RediSearch 全文本查询"""
# 基础查询构建逻辑
escaped_query = escape_special_chars(query)
safe_group_id = sanitize_group_id(group_id)
return f'@{group_id}:({safe_group_id}) @entity_name:{escaped_query}'
```
## 图操作（GraphOps）
### 索引管理
`GraphOps` 组件负责在 FalkorDB 中创建和维护必要的图索引。Graphiti 使用索引来实现高效的实体查询和关系遍历。
**索引类型：**
| 索引类型 | 用途 | 创建语句示例 |
|----------|------|-------------|
| 实体索引 | 快速查找实体节点 | `FT.CREATE entities ON HASH` |
| 关系索引 | 快速查找边 | `FT.CREATE edges ON HASH` |
| 全文索引 | 实体内容搜索 | `FT.CREATE entities ON JSON` |
### 约束条件
Graphiti 需要在数据库层面维护数据完整性约束：
- **唯一性约束**：确保同一 `group_id` 下的实体 UUID 全局唯一
- **存在性约束**：确保实体和边的必要属性存在
- **类型约束**：验证实体和边的类型字段
## 配置与连接
### 环境变量配置
使用 FalkorDB 时，需要配置以下环境变量：
| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `FALKORDB_URI` | `falkor://localhost:6379` | FalkorDB 服务器地址 |
| `FALKORDB_DATABASE` | `0` | 数据库编号 |
| `GROUP_ID` | `"main"` | 数据分组标识符 |
### 驱动初始化
```python
from graphiti_core.driver.falkordb_driver import FalkorDBDriver
driver = FalkorDBDriver(
uri="falkor://localhost:6379",
database=0
)
# 初始化索引和约束
await driver.create_indices()
```
## 与 Neo4j 驱动的对比
| 特性 | FalkorDB 驱动 | Neo4j 驱动 |
|------|---------------|------------|
| 查询语言 | Redis/GQL | Cypher |
| 全文搜索 | 内置 RediSearch | 需要插件 |
| 事务支持 | MULTI/EXEC | BEGIN/COMMIT |
| 部署复杂度 | 低（单节点可运行） | 中（需要 Aura 或本地安装） |
| 云原生支持 | 优秀 | 良好 |
| 适用场景 | 快速原型、中等规模 | 生产级、大规模 |
## 已知问题与限制
### Issue #1483：group_id 中连字符导致的语法错误
**问题描述：** `FalkorDriver.build_fulltext_query` 方法在处理包含连字符（`-`）的 `group_id` 时，会生成 RediSearch 解析失败的查询语句。
**问题根源：** 驱动代码注释声称已处理连字符转义，但实际实现仅使用双引号包裹，未进行正确的转义处理。
**影响版本：** graphiti-core 0.29
**临时解决方案：**
```python
# 避免在 group_id 中使用连字符
group_id = "my_group_id" # 使用下划线代替
```
**预期修复：** 在 `build_fulltext_query` 方法中添加对连字符的转义处理，确保 `group_id` 满足 RediSearch 的标识符语法要求。
## 使用示例
### 基础搜索操作
```python
from graphiti_core.driver.falkordb_driver import FalkorDBDriver
async def search_entities():
driver = FalkorDBDriver(uri="falkor://localhost:6379")
# 执行全文搜索
results = await driver.search_ops.search(
query="机器学习",
group_id="ai_research",
limit=10
)
return results
```
### 混合搜索（语义 + 关键词）
FalkorDB 利用 RediSearch 的混合搜索能力，结合向量相似度和 BM25 关键词匹配：
```python
results = await driver.search_ops.hybrid_search(
query="深度学习框架",
group_id="tech_stack",
embedding_model="nomic-embed-text",
alpha=0.7 # 语义权重
)
```
## 最佳实践
### 索引优化
1. **定期重建索引**：随着数据增长，定期执行 `FT.REINDEX` 保持查询性能
2. **合理设置分片**：大规模部署时配置 RediSearch 分片
3. **监控内存使用**：全文索引会消耗大量内存，确保充足资源
### 数据隔离
1. **使用有意义的 group_id**：便于数据管理和问题排查
2. **避免特殊字符**：目前驱动对连字符处理存在问题，建议使用下划线
3. **定期清理过期数据**：使用 `delete_episode` 移除不再需要的episode
## 参考链接
- [FalkorDB 官方文档](https://docs.falkordb.com)
- [RediSearch 文档](https://redis.io/docs/interact/search-and-query/)
- [Graphiti GitHub 仓库](https://github.com/getzep/graphiti)
- [Issue #1483：连字符处理问题](https://github.com/getzep/graphiti/issues/1483)
---
## Kuzu 与 Amazon Neptune 驱动
### 相关页面
相关主题：[Neo4j 驱动详解](#page-neo4j-driver), [FalkorDB 驱动详解](#page-falkordb-driver)
相关源码文件
以下源码文件用于生成本页说明：
- [graphiti_core/driver/kuzu_driver.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/driver/kuzu_driver.py)
- [graphiti_core/driver/neptune_driver.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/driver/neptune_driver.py)
- [graphiti_core/driver/kuzu/operations/graph_ops.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/driver/kuzu/operations/graph_ops.py)
- [graphiti_core/driver/neptune/operations/graph_ops.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/driver/neptune/operations/graph_ops.py)
- [README.md](https://github.com/getzep/graphiti/blob/main/README.md)
- [examples/quickstart/README.md](https://github.com/getzep/graphiti/blob/main/examples/quickstart/README.md)
# Kuzu 与 Amazon Neptune 驱动
## 概述
Graphiti 支持多种图数据库作为后端存储引擎，主要包括 **Kuzu** 和 **Amazon Neptune** 两种驱动。这两个驱动实现了统一的 GraphDriver 接口，为 Graphiti 提供图存储、查询和索引管理能力。资料来源：[README.md:1-30]()
Graphiti 采用可插拔的驱动架构，允许开发者根据部署环境选择合适的图数据库：
| 驱动 | 类型 | 特点 | 适用场景 |
|------|------|------|----------|
| Kuzu | 嵌入式图数据库 | 轻量级、高性能、无外部依赖 | 本地开发、小型应用 |
| Amazon Neptune | 云原生图数据库 | 可扩展、高可用、托管服务 | 生产环境、企业级应用 |
| Neo4j | 图数据库 | 成熟生态、广泛使用 | 通用场景 |
| FalkorDB | Redis-based 图数据库 | 高速缓存、内存计算 | 实时查询场景 |
## 驱动架构
### GraphDriver 接口抽象
所有图驱动均实现统一的 `GraphDriver` 接口，确保核心功能的一致性：
```mermaid
classDiagram
class GraphDriver {
<>
+build_fulltext_index()
+search_fulltext()
+create_node()
+create_edge()
+search_nodes()
+search_edges()
+get_edge()
+delete_edge()
+get_node()
+delete_node()
}
class KuzuDriver {
+client: kuzu.Connection
+graph_name: str
+search_index_name: str
}
class NeptuneDriver {
+client: NeptuneClient
+database_: str
+search_domain: str
}
GraphDriver <|-- KuzuDriver
GraphDriver <|-- NeptuneDriver
```
### 目录结构
```
graphiti_core/driver/
├── kuzu_driver.py # Kuzu 驱动主类
├── neptune_driver.py # Amazon Neptune 驱动主类
├── kuzu/
│ └── operations/
│ └── graph_ops.py # Kuzu 图操作实现
└── neptune/
└── operations/
└── graph_ops.py # Neptune 图操作实现
```
## Kuzu 驱动
### 简介
Kuzu 是一个高性能的嵌入式图数据库，专为高效处理复杂查询而设计。Graphiti 的 Kuzu 驱动提供完整的图存储功能，支持实体和关系的创建、查询和索引管理。资料来源：[README.md:80-95]()
### 核心功能
| 功能模块 | 描述 | 关键方法 |
|----------|------|----------|
| 图操作 | 创建和管理图结构 | `create_graph()`, `drop_graph()` |
| 节点操作 | 实体 CRUD 操作 | `create_node()`, `get_node()`, `delete_node()`, `search_nodes()` |
| 边操作 | 关系 CRUD 操作 | `create_edge()`, `get_edge()`, `delete_edge()`, `search_edges()` |
| 全文索引 | 语义搜索支持 | `build_fulltext_index()`, `search_fulltext()` |
### Kuzu 图操作实现
Kuzu 驱动通过 `graph_ops.py` 中的操作类实现具体功能：
```python
class KuzuGraphOperations:
"""Kuzu 图操作核心实现"""
def create_node(self, labels, properties, uuid):
"""创建节点"""
def create_edge(self, start_node_uuid, end_node_uuid,
edge_type, properties, uuid, valid_from, valid_to):
"""创建边"""
def search_nodes(self, query, group_id, limit):
"""搜索节点"""
def search_edges(self, query, group_id, limit):
"""搜索边"""
```
### 配置要求
```yaml
# Kuzu 配置示例
graphiti:
driver: kuzu
kuzu:
path: "./data/kuzu_db" # 数据库路径
search_index_name: "graphiti_search"
```
## Amazon Neptune 驱动
### 简介
Amazon Neptune 是 AWS 提供的完全托管式图数据库服务，支持 Property Graph（属性图）和 RDF 两种模型。Graphiti 的 Neptune 驱动利用 Neptune Analytics 或 Neptune Database 作为后端存储，结合 Amazon OpenSearch Serverless 实现全文搜索功能。资料来源：[README.md:85-95]()
### 架构特点
```mermaid
flowchart LR
subgraph AWS["AWS 环境"]
subgraph Neptune["Amazon Neptune"]
NP[Neptune Database / Analytics]
end
subgraph OpenSearch["Amazon OpenSearch Serverless"]
OS[全文搜索索引]
end
end
Graphiti -->|图数据读写| NP
Graphiti -->|全文搜索| OS
NP -.->|搜索联动| OS
```
### 核心功能
| 功能模块 | 描述 | 关键方法 |
|----------|------|----------|
| 图操作 | Neptune 图结构管理 | `create_graph()`, `drop_graph()` |
| 节点操作 | 属性图节点管理 | `create_node()`, `get_node()`, `delete_node()`, `search_nodes()` |
| 边操作 | 属性图关系管理 | `create_edge()`, `get_edge()`, `delete_edge()`, `search_edges()` |
| 全文索引 | OpenSearch 集成搜索 | `build_fulltext_index()`, `search_fulltext()` |
### Neptune 图操作实现
```python
class NeptuneGraphOperations:
"""Neptune 图操作核心实现"""
def __init__(self, client, database, search_domain):
self.client = client
self.database = database
self.search_domain = search_domain
def create_node(self, labels, properties, uuid):
"""通过 Neptune Gremlin API 创建节点"""
def create_edge(self, start_node_uuid, end_node_uuid,
edge_type, properties, uuid, valid_from, valid_to):
"""创建带时间窗口的边"""
def search_edges(self, query, group_id, limit):
"""组合 Neptune 查询与 OpenSearch 全文搜索"""
```
### 环境配置
| 环境变量 | 描述 | 示例值 |
|----------|------|--------|
| `NEPTUNE_ENDPOINT` | Neptune 数据库端点 | `your-neptune.cluster-xxx.us-east-1.neptune.amazonaws.com` |
| `NEPTUNE_PORT` | Neptune 端口 | `8182` |
| `NEPTUNE_DATABASE` | 数据库名称 | `default_db` |
| `NEPTUNE_REGION` | AWS 区域 | `us-east-1` |
| `OPENSEARCH_ENDPOINT` | OpenSearch 端点 | `https://xxx.aos.us-east-1.on.aws` |
| `OPENSEARCH_INDEX` | 搜索索引名 | `graphiti_search` |
| `AWS_REGION` | AWS 区域 | `us-east-1` |
| `AWS_ACCESS_KEY_ID` | AWS 访问密钥 | - |
| `AWS_SECRET_ACCESS_KEY` | AWS 密钥 | - |
### 配置示例
```yaml
# Neptune 配置示例
graphiti:
driver: neptune
neptune:
database: "default_db"
search_domain: "graphiti-search"
aws:
region: "us-east-1"
# 建议使用 IAM 角色或环境变量配置凭证
```
## 驱动初始化流程
### 统一初始化模式
所有驱动遵循一致的初始化流程：
```mermaid
sequenceDiagram
participant User as 用户代码
participant Driver as GraphDriver
participant GraphOps as GraphOperations
User->>Driver: 初始化驱动实例
Driver->>GraphOps: 创建操作实例
GraphOps->>GraphOps: 建立数据库连接
User->>Driver: build_fulltext_index()
Driver->>GraphOps: 创建全文索引
User->>Driver: add_episode()
Driver->>GraphOps: 写入节点和边
User->>Driver: search_nodes/search_edges
Driver->>GraphOps: 执行混合搜索
```
### 初始化参数
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| `uri` | string | 是 | 数据库连接 URI |
| `graph_name` | string | 是 | 图名称 |
| `search_index_name` | string | 是 | 全文索引名称 |
| `database` | string | Neptune | 数据库名称 |
## 全文搜索集成
### Kuzu 全文搜索
Kuzu 驱动内置向量搜索支持，无需外部服务：
```python
class KuzuDriver:
def build_fulltext_index(self):
"""创建 Kuzu 向量索引用于语义搜索"""
def search_fulltext(self, query: str, limit: int = 10):
"""执行向量相似度搜索"""
```
### Neptune 全文搜索
Neptune 驱动依赖 Amazon OpenSearch Serverless：
```python
class NeptuneDriver:
def __init__(self, search_domain: str, ...):
self.search_domain = search_domain
self.opensearch_client = OpenSearchClient(...)
def build_fulltext_index(self):
"""创建 OpenSearch 索引映射"""
def search_fulltext(self, query: str, limit: int = 10):
"""通过 OpenSearch 执行全文搜索"""
```
## 已知限制与注意事项
### 当前驱动问题
根据社区反馈，以下问题已在近期版本中得到修复或正在修复：
| 问题 | 描述 | 影响版本 |
|------|------|----------|
| FalkorDB group_id 连字符处理 | `FalkorDriver.build_fulltext_query` 对含连字符的 group_id 处理不正确 | 0.29.x |
| Neo4j 数据库参数传递 | `Neo4jDriver.execute_query()` 未正确传递 database 参数 | 0.29.x |
| Neo4j DateTime 序列化 | MCP search_memory_facts 无法序列化 neo4j.time.DateTime | 0.29.x |
> 注意：这些问题主要影响 FalkorDB 和 Neo4j 驱动，Kuzu 和 Neptune 驱动用户不受影响。
### 使用建议
1. **Kuzu 驱动**：适合本地开发和测试，无需配置外部服务
2. **Neptune 驱动**：适合 AWS 生产环境，自动获得高可用和扩展能力
3. **选择考虑因素**：
- 部署规模（小型用 Kuzu，大型用 Neptune）
- 运维能力（Kuzu 自管理，Neptune 托管）
- 云服务商偏好（Neptune 仅限 AWS）
## 快速开始
### Kuzu 快速启动
```python
from graphiti import Graphiti
from graphiti_core.driver import KuzuDriver
driver = KuzuDriver(
uri="data/graphiti_kuzu",
graph_name="main_graph",
search_index_name="main_search"
)
graphiti = Graphiti(driver)
graphiti.setup()
# 添加数据
result = await graphiti.add_episode(...)
```
### Neptune 快速启动
```python
from graphiti import Graphiti
from graphiti_core.driver import NeptuneDriver
driver = NeptuneDriver(
uri="bolt://neptune-endpoint:8182",
database="default_db",
search_domain="graphiti-search"
)
graphiti = Graphiti(driver)
graphiti.setup()
# 添加数据
result = await graphiti.add_episode(...)
```
## 相关资源
- [Graphiti 核心库](https://github.com/getzep/graphiti)
- [MCP 服务器文档](../mcp_server/README.md)
- [快速开始示例](../examples/quickstart/README.md)
- [v0.29.0 发布说明](https://github.com/getzep/graphiti/releases/tag/v0.29.0) - 驱动架构优化
---
## LLM 提供商集成
### 相关页面
相关主题：[向量嵌入与重排序](#page-embeddings), [数据流与摄取管道](#page-data-flow)
相关源码文件
以下源码文件用于生成本页说明：
- [graphiti_core/llm_client/openai_client.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/llm_client/openai_client.py)
- [graphiti_core/llm_client/azure_openai_client.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/llm_client/azure_openai_client.py)
- [graphiti_core/llm_client/gemini_client.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/llm_client/gemini_client.py)
- [graphiti_core/llm_client/anthropic_client.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/llm_client/anthropic_client.py)
- [graphiti_core/llm_client/openai_generic_client.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/llm_client/openai_generic_client.py)
# LLM 提供商集成
Graphiti 支持多种大语言模型（LLM）提供商，允许用户根据自身需求选择最适合的模型服务。本文档详细介绍 Graphiti 中 LLM 提供商集成的架构、配置方法和支持的提供商类型。
## 架构概述
Graphiti 采用模块化的 LLM 客户端架构，通过统一的接口抽象不同提供商的具体实现。这种设计允许开发者在不修改核心业务逻辑的情况下切换不同的 LLM 服务。
```mermaid
graph TD
subgraph "LLM 客户端层"
OpenAI[OpenAI Client]
AzureOpenAI[Azure OpenAI Client]
Anthropic[Anthropic Client]
Gemini[Gemini Client]
OpenAIGeneric[OpenAI Generic Client]
end
subgraph "核心引擎"
Graphiti[Graphiti Core]
end
subgraph "嵌入层"
OpenAIEmbedder[OpenAI Embedder]
OpenAIGenericEmbedder[Generic Embedder]
end
OpenAI --> Graphiti
AzureOpenAI --> Graphiti
Anthropic --> Graphiti
Gemini --> Graphiti
OpenAIGeneric --> Graphiti
Graphiti --> OpenAIEmbedder
Graphiti --> OpenAIGenericEmbedder
```
### 核心组件
| 组件 | 文件路径 | 功能说明 |
|------|----------|----------|
| LLMConfig | `graphiti_core/llm_client/config.py` | LLM 配置数据模型，包含 API 密钥、模型名称、基础 URL 等参数 |
| BaseLLMClient | `graphiti_core/llm_client/base.py` | 所有 LLM 客户端的基类，定义统一接口 |
| OpenAIClient | `graphiti_core/llm_client/openai_client.py` | OpenAI 官方 API 客户端 |
| AzureOpenAIClient | `graphiti_core/llm_client/azure_openai_client.py` | Azure OpenAI API 客户端 |
| AnthropicClient | `graphiti_core/llm_client/anthropic_client.py` | Anthropic Claude API 客户端 |
| GeminiClient | `graphiti_core/llm_client/gemini_client.py` | Google Gemini API 客户端 |
| OpenAIGenericClient | `graphiti_core/llm_client/openai_generic_client.py` | 通用 OpenAI 兼容接口客户端 |
## 支持的 LLM 提供商
### OpenAI
OpenAI 是 Graphiti 的默认 LLM 提供商，适用于标准 GPT 系列模型的调用场景。
**配置示例**：
```python
from graphiti_core import Graphiti
from graphiti_core.llm_client.openai_client import OpenAIClient
from graphiti_core.llm_client.config import LLMConfig
llm_config = LLMConfig(
api_key="sk-your-api-key",
model="gpt-4o",
small_model="gpt-4o-mini"
)
llm_client = OpenAIClient(config=llm_config)
graphiti = Graphiti(
"bolt://localhost:7687",
"neo4j",
"password",
llm_client=llm_client
)
```
**支持的功能**：
- 结构化输出（Structured Output）
- 函数调用（Function Calling）
- 嵌入向量生成
### Azure OpenAI
Azure OpenAI 提供企业级的 OpenAI 模型部署能力，支持私有化部署和合规要求。资料来源：[examples/azure-openai/README.md]()
**配置示例**：
```python
from graphiti_core import Graphiti
from graphiti_core.llm_client.azure_openai_client import AzureOpenAILLMClient
from graphiti_core.llm_client.config import LLMConfig
azure_config = LLMConfig(
api_key="your-azure-api-key",
model="gpt-4o",
small_model="gpt-4o-mini",
base_url="https://your-resource.openai.azure.com/openai/v1/"
)
llm_client = AzureOpenAILLMClient(config=azure_config)
```
**环境变量配置**：
| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| AZURE_OPENAI_API_KEY | Azure OpenAI API 密钥 | - |
| AZURE_OPENAI_ENDPOINT | Azure OpenAI 端点 URL | - |
| AZURE_OPENAI_DEPLOYMENT | LLM 部署名称 | - |
| AZURE_OPENAI_EMBEDDING_DEPLOYMENT | 嵌入模型部署名称 | - |
**使用前提**：
1. 拥有 Azure 订阅并开通 OpenAI 服务
2. 部署 GPT 系列模型（建议 GPT-4o 或更新版本）
3. 配置嵌入模型部署用于语义搜索
### Anthropic Claude
Anthropic 的 Claude 系列模型以安全性和长上下文能力著称。
**配置示例**：
```python
from graphiti_core import Graphiti
from graphiti_core.llm_client.anthropic_client import AnthropicLLMClient
from graphiti_core.llm_client.config import LLMConfig
llm_config = LLMConfig(
api_key="sk-ant-api03-your-key",
model="claude-sonnet-4-20250514",
small_model="claude-haiku-4-20250514"
)
llm_client = AnthropicLLMClient(config=llm_config)
```
**环境变量**：`ANTHROPIC_API_KEY`
### Google Gemini
Google Gemini 提供多模态能力和长上下文窗口。
**配置示例**：
```python
from graphiti_core import Graphiti
from graphiti_core.llm_client.gemini_client import GeminiLLMClient
from graphiti_core.llm_client.config import LLMConfig
llm_config = LLMConfig(
api_key="your-google-api-key",
model="gemini-2.0-flash",
small_model="gemini-2.0-flash-lite"
)
llm_client = GeminiLLMClient(config=llm_config)
```
**环境变量**：`GOOGLE_API_KEY`
### 通用 OpenAI 兼容接口
`OpenAIGenericClient` 支持任何兼容 OpenAI API 格式的服务提供商，包括本地部署模型和第三方服务。
**典型应用场景**：
```mermaid
graph LR
A[OpenAIGenericClient] --> B[Ollama]
A[OpenAIGenericClient] --> C[LM Studio]
A[OpenAIGenericClient] --> D[vLLM]
A[OpenAIGenericClient] --> E[LocalAI]
A[OpenAIGenericClient] --> F[其他兼容服务]
```
**Ollama 本地部署示例**：
```python
from graphiti_core import Graphiti
from graphiti_core.llm_client.openai_generic_client import OpenAIGenericClient
from graphiti_core.llm_client.config import LLMConfig
from graphiti_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig
# 配置 Ollama LLM 客户端
llm_config = LLMConfig(
api_key="ollama", # Ollama 不需要真实 API 密钥，但需要占位符
model="deepseek-r1:7b",
small_model="deepseek-r1:7b",
base_url="http://localhost:11434/v1"
)
llm_client = OpenAIGenericClient(config=llm_config)
# 初始化 Graphiti
graphiti = Graphiti(
"bolt://localhost:7687",
"neo4j",
"password",
llm_client=llm_client,
embedder=OpenAIEmbedder(
config=OpenAIEmbedderConfig(
api_key="ollama",
embedding_model="nomic-embed-text",
base_url="http://localhost:11434/v1"
)
)
)
```
**客户端特性**：
| 特性 | 说明 |
|------|------|
| 默认最大令牌限制 | 16K（高于标准 OpenAI 客户端的 8K） |
| 结构化输出支持 | 完整支持 |
| API 兼容格式 | OpenAI v1 兼容 |
## LLMConfig 配置详解
`LLMConfig` 是所有 LLM 客户端的统一配置模型：
```python
class LLMConfig(BaseModel):
api_key: str # API 密钥
model: str # 主模型名称
small_model: str # 小型模型名称（用于简单任务）
base_url: Optional[str] = None # API 基础 URL
max_tokens: Optional[int] = None # 最大生成令牌数
temperature: Optional[float] = None # 生成温度
timeout: Optional[float] = None # 请求超时时间
```
### 配置参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| api_key | str | 是 | API 密钥，不同提供商格式不同 |
| model | str | 是 | 主模型标识符，如 `gpt-4o`、`claude-sonnet-4-20250514` |
| small_model | str | 是 | 轻量级模型，用于简单提取任务以降低成本 |
| base_url | str | 否 | API 端点，适用于非官方服务 |
| max_tokens | int | 否 | 响应最大令牌数限制 |
| temperature | float | 否 | 生成随机性控制，0-2 之间 |
| timeout | float | 否 | HTTP 请求超时时间（秒） |
## 嵌入模型集成
Graphiti 的搜索功能依赖嵌入模型生成语义向量。嵌入层与 LLM 层相互独立，支持灵活配置。
```mermaid
graph TD
subgraph "嵌入层"
OE[OpenAIEmbedder]
OGE[OpenAIGenericEmbedder]
end
subgraph "向量存储"
Neo4j[Neo4j Vector Index]
FalkorDB[FalkorDB Vector Index]
OpenSearch[OpenSearch]
end
OE --> Neo4j
OGE --> Neo4j
OE --> OpenSearch
```
### OpenAI Embedder
```python
from graphiti_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig
embedder = OpenAIEmbedder(
config=OpenAIEmbedderConfig(
api_key="sk-your-key",
embedding_model="text-embedding-3-small",
max_retries=3
)
)
```
### 通用嵌入器
与 `OpenAIGenericClient` 配合使用本地嵌入模型：
```python
from graphiti_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig
embedder = OpenAIEmbedder(
config=OpenAIEmbedderConfig(
api_key="ollama",
embedding_model="nomic-embed-text",
base_url="http://localhost:11434/v1"
)
)
```
## 提供商选择指南
### 选择考量因素
| 因素 | 推荐提供商 |
|------|-----------|
| 快速开始 | OpenAI |
| 企业合规需求 | Azure OpenAI |
| 长上下文场景 | Claude (200K 上下文) / Gemini |
| 本地部署 | Ollama + OpenAIGenericClient |
| 成本优化 | 小型模型 + 本地部署 |
### 模型配对建议
Graphiti 使用双模型策略：一个主模型处理复杂任务，一个小型模型处理简单任务以控制成本。
| 场景 | 主模型 | 小型模型 |
|------|--------|----------|
| 标准配置 | gpt-4o | gpt-4o-mini |
| Azure 部署 | gpt-4o | gpt-4o-mini |
| Claude | claude-sonnet-4 | claude-haiku-4 |
| Gemini | gemini-2.0-flash | gemini-2.0-flash-lite |
| 本地 Ollama | deepseek-r1:14b | deepseek-r1:7b |
## 常见问题
### API 密钥配置
**问题**：环境变量 `OPENAI_API_KEY` 是否必须？
**解答**：当使用默认配置且未显式传递 `llm_client` 时，Graphiti 会尝试从环境变量读取 API 密钥。显式传递客户端实例时以代码配置为准。
### Azure OpenAI 端点错误
**症状**：`Invalid base URL` 或认证失败
**解决方案**：
1. 确认端点 URL 格式正确（应为 `https://{resource}.openai.azure.com/openai/v1/`）
2. 验证 API 版本与部署兼容
3. 检查 API 密钥有效且未过期
### 本地模型响应延迟
**问题**：Ollama 本地模型响应过慢
**解决方案**：
1. 使用更小的模型（如从 14B 降至 7B）
2. 增加请求超时时间配置
3. 确保 GPU 加速已启用
4. 考虑使用量化模型
### 结构化输出兼容
**问题**：部分提供商不支持结构化输出
**解答**：Graphiti 依赖结构化输出进行实体和关系提取。确保使用的模型支持此功能。云服务（OpenAI、Claude、Gemini）均支持，本地模型需验证 Ollama 版本和模型本身能力。
## 环境变量汇总
| 变量名 | 对应提供商 | 用途 |
|--------|-----------|------|
| OPENAI_API_KEY | OpenAI | API 认证 |
| ANTHROPIC_API_KEY | Anthropic | API 认证 |
| GOOGLE_API_KEY | Google | API 认证 |
| GROQ_API_KEY | Groq | API 认证 |
| AZURE_OPENAI_API_KEY | Azure | API 认证 |
| AZURE_OPENAI_ENDPOINT | Azure | 服务端点 |
## 相关资源
- [Graphiti 官方文档](https://github.com/getzep/graphiti)
- [Ollama 官方文档](https://ollama.com/)
- [Azure OpenAI 文档](https://learn.microsoft.com/azure/ai-services/openai/)
- [Anthropic Claude 文档](https://docs.anthropic.com/)
- [Google Gemini 文档](https://ai.google.dev/)
---
## 向量嵌入与重排序
### 相关页面
相关主题：[混合搜索与检索](#page-hybrid-search), [LLM 提供商集成](#page-llm-providers)
相关源码文件
以下源码文件用于生成本页说明：
- [graphiti_core/embedder/openai.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/embedder/openai.py)
- [graphiti_core/embedder/azure_openai.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/embedder/azure_openai.py)
- [graphiti_core/embedder/gemini.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/embedder/gemini.py)
- [graphiti_core/cross_encoder/openai_reranker_client.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/cross_encoder/openai_reranker_client.py)
- [graphiti_core/cross_encoder/gemini_reranker_client.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/cross_encoder/gemini_reranker_client.py)
# 向量嵌入与重排序
## 概述
Graphiti 的向量嵌入与重排序系统是实现混合检索的核心组件，负责将文本数据转换为高维向量表示，并通过重排序模型优化搜索结果的精度。该系统支持多种 LLM 提供商，包括 OpenAI、Azure OpenAI 和 Google Gemini，为用户提供了灵活的嵌入模型选择。
Graphiti 采用三层检索策略：语义搜索（基于向量嵌入）、BM25 关键词检索和图遍历检索。这种混合方法确保了低延迟、高精度的查询性能，通常能够实现亚秒级的查询响应时间，同时避免了传统 RAG 系统对 LLM 总结的依赖。
## 嵌入系统架构
### 嵌入器接口设计
Graphiti 定义了统一的嵌入器接口 `Embedder`，所有嵌入实现都必须遵循该接口规范。接口包含两个核心方法：`embed_query` 用于查询嵌入，`embed_documents` 用于批量文档嵌入。这种设计使得用户可以在不修改业务逻辑的情况下切换不同的嵌入模型提供商。
嵌入器返回的向量表示是浮点数数组，其维度取决于所使用的嵌入模型。例如，OpenAI 的 text-embedding-3-small 模型生成 1536 维向量，而 text-embedding-3-large 模型支持最高 3072 维向量。向量维度直接影响存储需求和相似度计算效率。
### 支持的嵌入模型
Graphiti 原生支持三种嵌入模型提供商的实现：
| 提供商 | 模型 | 向量维度 | 特点 |
|--------|------|----------|------|
| OpenAI | text-embedding-3-small/large | 1536/3072 | 成本效益高，支持维度缩减 |
| Azure OpenAI | text-embedding-3-small/large | 1536/3072 | 企业级安全与合规 |
| Google Gemini | embedding-001 | 768 | 统一的语言模型架构 |
嵌入模型的选择影响检索质量和成本平衡。OpenAI 的新代模型（text-embedding-3）支持"维度缩减"功能，可以在不损失太多精度的情况下减少向量维度，从而降低存储成本和计算开销。
## 嵌入器实现详解
### OpenAI 嵌入器
OpenAI 嵌入器通过 HTTP 请求与 OpenAI API 交互，支持流式响应和批量处理。实现中包含请求重试机制和超时控制，确保在网络不稳定情况下的可靠性。嵌入器使用 `tiktoken` 库进行 token 计数，以准确估算请求成本。
代码实现采用了异步设计模式，支持并发处理多个嵌入请求。嵌入请求被封装为 `EmbeddingRequest` 对象，包含输入文本、模型名称和可选的元数据。通过 `max_retries` 参数配置重试策略，默认值为 3 次。
### Azure OpenAI 嵌入器
Azure OpenAI 嵌入器继承自 OpenAI 嵌入器的核心逻辑，但使用 Azure 特定的端点和认证机制。该实现支持 Azure 的 API 版本控制和企业级身份验证，包括 Microsoft Entra ID (原 Azure AD) 令牌认证。
配置方面，Azure OpenAI 嵌入器需要以下环境变量：`AZURE_OPENAI_API_KEY`（API 密钥）、`AZURE_OPENAI_ENDPOINT`（端点 URL）和 `AZURE_OPENAI_EMBEDDING_DEPLOYMENT`（部署名称）。部署名称对应 Azure 门户中创建的特定嵌入模型部署。
### Gemini 嵌入器
Google Gemini 嵌入器使用 Google 的 `generativeai` 库，支持 Gemini 系列模型的嵌入功能。该实现特别适合已经使用 Gemini 进行 LLM 任务的应用程序，可以统一使用同一模型家族。
Gemini 嵌入器支持任务类型参数，可指定是生成查询嵌入还是文档嵌入。不同任务类型的嵌入向量针对不同的使用场景进行了优化：查询嵌入针对匹配性优化，文档嵌入针对语义相似性优化。
## 重排序系统
### 交叉编码器重排序原理
重排序（Re-ranking）是检索后处理的关键步骤，使用交叉编码器模型对初始检索结果进行精细排序。与双编码器嵌入模型（分别编码查询和文档）不同，交叉编码器同时接收查询和文档对，计算细粒度的相关性分数。
这种架构的优势在于交叉编码器能够捕捉查询和文档之间的复杂交互关系，识别关键词匹配、语义对应等细微信号。代价是推理速度较慢，因此通常只对 Top-K 候选结果进行重排序，而非全量检索结果。
### 重排序客户端实现
Graphiti 实现了两个重排序客户端：OpenAI 重排序客户端和 Gemini 重排序客户端。两个客户端遵循统一的 `RerankerClient` 接口，支持 `rerank` 方法接收查询和候选文档列表，返回按相关性排序的结果。
```python
class RerankerClient(Protocol):
async def rerank(
self,
query: str,
documents: list[str],
model: str | None = None,
top_n: int | None = None
) -> RerankResult: ...
```
重排序结果包含原始文档索引、相关性分数和文档内容。分数范围因模型而异：OpenAI 的重排序模型返回 0-1 的归一化分数，Gemini 返回 -1 到 1 的分数，负值表示不相关。
## 搜索配置与配方
### 搜索配置结构
Graphiti 通过 `SearchConfig` 类定义搜索行为的关键参数，包括使用的嵌入模型、重排序配置、结果数量限制等。配置支持运行时调整，允许不同场景使用不同策略。
```python
@dataclass
class SearchConfig:
embedder_config: EmbedderConfig
reranker_config: RerankerConfig | None
hybrid_config: HybridSearchConfig
temporal_config: TemporalSearchConfig
```
### 预定义搜索配方
Graphiti 提供了多个预定义搜索配置（配方），覆盖常见的检索场景：
| 配方名称 | 描述 | 适用场景 |
|----------|------|----------|
| EDGE_HYBRID_SEARCH_RRF | 边混合搜索，使用 RRF 融合 | 关系发现 |
| NODE_HYBRID_SEARCH_RRF | 节点混合搜索，使用 RRF 融合 | 实体查询 |
| CENTER_NODE_HYBRID_SEARCH | 以特定节点为中心的混合搜索 | 邻居探索 |
RRF（Reciprocal Rank Fusion）是一种无参数的结果融合方法，通过对各检索来源的结果按排名取倒数求和来计算综合分数，避免了权重调优的复杂性。
## 混合检索流程
### 三阶段检索架构
Graphiti 的混合检索流程分为三个阶段：并行检索、分数融合和可选重排序。
```mermaid
graph TD
A[用户查询] --> B[语义嵌入检索]
A --> C[BM25 关键词检索]
A --> D[图遍历检索]
B --> E[RRF 分数融合]
C --> E
D --> E
E --> F{需要重排序?}
F -->|是| G[交叉编码器重排序]
F -->|否| H[返回 Top-K 结果]
G --> I[返回重排结果]
```
第一阶段并行执行三种检索策略：语义检索使用嵌入向量计算余弦相似度，BM25 使用词频统计评估关键词匹配，图遍历利用图的拓扑结构找到相关节点。
### RRF 分数融合
RRF 融合公式为：`score(d) = Σ(1 / (k + rank_i(d)))`，其中 `k` 是常数（默认 60），`rank_i(d)` 是文档在第 i 个检索结果中的排名。这种方法对各检索源的顶级结果给予更高权重，同时保留来自任何源的好结果。
融合分数的优势在于它不需要训练或调参，同时对各检索源的相对质量具有鲁棒性。即使某个检索源质量较低，其顶级结果仍可能影响最终排序。
### 图感知搜索
图感知搜索（Graph-Aware Search）利用知识图的结构信息增强检索效果。通过指定"中心节点"，可以检索与该节点在图距离上相近的相关实体和关系。
中心节点搜索特别适合探索性查询，例如"查找与这个客户相关的所有交易和联系人"。系统首先找到中心节点，然后以该节点为起点进行受限的图遍历，收集相关实体和事实。
## 配置与调优
### 嵌入配置参数
嵌入器的配置通过 `EmbedderConfig` 类管理，主要参数包括：
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| batch_size | int | 100 | 批量嵌入的文档数量 |
| dimensions | int | None | 输出向量维度（支持维度缩减） |
| encoding_format | str | "float" | 向量编码格式 |
| timeout | float | 60.0 | 请求超时时间（秒） |
`dimensions` 参数特别有用，OpenAI 的新嵌入模型支持在返回时自动缩减维度。例如，可以请求 1024 维向量而模型实际输出 3072 维，系统会在服务端进行降维，减少存储和计算开销。
### 重排序配置参数
重排序配置通过 `RerankerConfig` 类管理：
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| model | str | 提供商默认 | 重排序模型名称 |
| top_n | int | None | 返回的重排序结果数量 |
| batch_size | int | 100 | 重排序批处理大小 |
`top_n` 参数控制重排序后的结果数量。由于交叉编码器推理成本较高，通常只对初始检索的 Top-20 到 Top-50 结果进行重排序，然后返回最终的 Top-10 结果。
### 性能优化建议
1. **选择合适的嵌入维度**：对于大多数应用，1536 维的 text-embedding-3-small 已足够。降低维度可减少 50-75% 的存储空间。
2. **批量处理嵌入请求**：批量请求比单独请求效率高得多，建议将大量文档的嵌入操作合并为批处理。
3. **条件重排序**：只在需要高精度结果时启用重排序。对于需要快速响应的场景，可以先返回 RRF 结果，异步进行重排序更新。
4. **缓存嵌入结果**：对于不经常变化的文档，可以缓存其嵌入向量，避免重复计算。
## 与 MCP 服务器集成
Graphiti MCP 服务器提供了 `search_nodes` 和 `search_facts` 工具，内部使用混合检索系统。用户查询首先被嵌入为向量，然后在图数据库中检索相似实体，最后通过 RRF 融合和可选重排序返回结果。
MCP 服务器的搜索功能支持按 `group_id` 过滤，这在多租户场景下尤为重要。每个租户的数据通过 `group_id` 隔离，搜索只返回当前租户相关的结果。
## 已知限制与注意事项
### 向量维度限制
不同的嵌入模型有不同的最大输入长度限制。超出限制的文本需要预先进行分块（Chunking）处理。Graphiti 的内容分块策略（`content_chunking.py`）会根据内容类型（JSON、对话、纯文本）采用不同的启发式方法。
### 重排序延迟
交叉编码器重排序会增加额外的推理延迟。对于延迟敏感的应用场景，建议评估是否真正需要重排序步骤。在某些情况下，优化后的 RRF 配置可能已经足够。
### group_id 中的特殊字符
根据社区反馈（issue #1483），FalkorDriver 在处理包含连字符的 `group_id` 时存在语法错误。生产环境中应避免在 `group_id` 中使用特殊字符，或使用下划线替代连字符。
## 总结
Graphiti 的向量嵌入与重排序系统提供了完整的企业级检索能力。通过支持多种嵌入模型提供商、灵活的搜索配置和高效的混合检索策略，系统能够满足从原型验证到大规模生产的各类需求。开发者应熟悉搜索配置参数和调优方法，以便根据具体应用场景优化检索效果。
---
## 混合搜索与检索
### 相关页面
相关主题：[向量嵌入与重排序](#page-embeddings)
相关源码文件
以下源码文件用于生成本页说明：
- [graphiti_core/search/search.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/search/search.py)
- [graphiti_core/search/search_filters.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/search/search_filters.py)
- [graphiti_core/search/search_config.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/search/search_config.py)
- [graphiti_core/search/search_config_recipes.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/search/search_config_recipes.py)
- [mcp_server/src/graphiti_mcp_server.py](https://github.com/getzep/graphiti/blob/main/mcp_server/src/graphiti_mcp_server.py)
- [examples/quickstart/README.md](https://github.com/getzep/graphiti/blob/main/examples/quickstart/README.md)
- [README.md](https://github.com/getzep/graphiti/blob/main/README.md)
# 混合搜索与检索
## 概述
Graphiti 的混合搜索与检索系统是构建上下文图（Context Graph）的核心能力，它结合了多种检索策略以实现低延迟、高精度的知识查询。与传统 GraphRAG 依赖 LLM 总结的方式不同，Graphiti 采用语义搜索、关键词搜索（BM25）和图遍历相结合的方法，通常能够实现亚秒级的查询延迟。
混合检索的核心价值在于：
- **多维度理解**：同时捕捉语义相似性和精确关键词匹配
- **图结构感知**：利用实体之间的关系进行相关性排序
- **可组合性**：通过预定义配置灵活调整搜索策略
资料来源：[README.md:1-20]()
## 搜索架构
### 整体架构图
```mermaid
graph TD
A[用户查询] --> B[SearchConfig 搜索配置]
B --> C{搜索类型判断}
C -->|事实搜索| D[HybridEdgeSearcher]
C -->|节点搜索| E[HybridNodeSearcher]
C -->|中心节点搜索| F[CenterNodeReranker]
D --> G[语义搜索]
D --> H[BM25 关键词搜索]
D --> I[图遍历]
D --> J[结果融合]
E --> G
E --> H
E --> J
F --> K[获取候选节点]
F --> L[计算图距离]
F --> J
J --> M[SearchResult 结果集]
G --> N[向量数据库]
H --> O[全文索引]
I --> P[图数据库]
```
### 核心组件
| 组件 | 类/模块 | 职责 |
|------|---------|------|
| 搜索配置 | `SearchConfig` | 定义搜索策略、权重、过滤条件 |
| 事实搜索器 | `HybridEdgeSearcher` | 执行边/关系的混合搜索 |
| 节点搜索器 | `HybridNodeSearcher` | 执行实体的混合搜索 |
| 中心节点重排器 | `CenterNodeReranker` | 基于图距离重新排序结果 |
| 结果融合器 | `ResultMerger` | 合并多种搜索策略的结果 |
资料来源：[graphiti_core/search/search_config.py:1-50]()
## 搜索配置系统
### SearchConfig 类
`SearchConfig` 是搜索系统的核心配置类，定义了搜索行为的各个方面：
```python
class SearchConfig:
def __init__(
self,
edge_searcher: Optional[EdgeSearcher] = None,
node_searcher: Optional[NodeSearcher] = None,
reranker: Optional[Reranker] = None,
include_source_nodes: bool = True,
include_target_nodes: bool = True,
time_weight: float = 0.1,
):
...
```
**参数说明**：
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `edge_searcher` | `EdgeSearcher` | `None` | 边搜索策略实现 |
| `node_searcher` | `NodeSearcher` | `None` | 节点搜索策略实现 |
| `reranker` | `Reranker` | `None` | 结果重排策略 |
| `include_source_nodes` | `bool` | `True` | 结果中包含源节点 |
| `include_target_nodes` | `bool` | `True` | 结果中包含目标节点 |
| `time_weight` | `float` | `0.1` | 时间衰减权重 (0-1) |
资料来源：[graphiti_core/search/search_config.py:30-45]()
### 搜索配置配方
Graphiti 提供了预定义的搜索配置配方，位于 `search_config_recipes.py`：
| 配方名称 | 用途 | 搜索模式 |
|----------|------|----------|
| `EDGE_HYBRID_SEARCH_RRF` | 边的混合搜索（使用 RRF 融合） | 语义 + BM25 |
| `NODE_HYBRID_SEARCH_RRF` | 节点的混合搜索（使用 RRF 融合） | 语义 + BM25 |
| `EDGE_HYBRID_SEARCH_DEFAULT` | 边混合搜索（默认权重） | 语义 + BM25 |
| `CENTER_NODE_HYBRID_SEARCH` | 中心节点搜索 | 语义 + 图距离重排 |
资料来源：[graphiti_core/search/search_config_recipes.py:1-30]()
## 搜索策略详解
### 语义搜索
语义搜索利用嵌入向量（embeddings）来查找语义相似的内容。Graphiti 支持多种嵌入服务：
- **OpenAI**：默认使用 `text-embedding-ada-002` 或 `text-embedding-3-small`
- **Azure OpenAI**：通过 `AzureOpenAILLMClient` 配置
- **自定义**：实现 `EmbedderClient` 接口
语义搜索的典型流程：
```mermaid
graph LR
A[查询文本] --> B[嵌入模型]
B --> C[查询向量]
C --> D[向量数据库]
D --> E[余弦相似度计算]
E --> F[Top-K 候选结果]
```
### BM25 关键词搜索
BM25（Best Matching 25）是一种经典的信息检索算法，基于词频和文档频率进行匹配。Graphiti 在底层图数据库中实现 BM25：
- **Neo4j**：使用 `apoc.text.bm25` 或原生索引
- **FalkorDB**：使用 RediSearch FT 命令
> [!NOTE]
> 关于 FalkorDB 的 BM25 搜索，存在一个已知问题：当 `group_id` 包含连字符时，RediSearch 查询会因语法错误而失败。资料来源：[BUG] FalkorDriver.build_fulltext_query fails on hyphens in group_id #1483
### 图遍历搜索
图遍历利用实体之间的关系网络进行搜索，允许：
- 查找与已知实体直接相连的节点
- 执行多跳查询（限定跳数内）
- 基于图的连通性进行相关性评估
## 搜索过滤器
### SearchFilters 类
`SearchFilters` 定义了搜索时的过滤条件：
```python
class SearchFilters(BaseModel):
group_id: Optional[str] = None
valid_at: Optional[datetime] = None
entity_uuids: Optional[list[str]] = None
source_node_uuid: Optional[str] = None
target_node_uuid: Optional[str] = None
fact_categories: Optional[list[str]] = None
```
**参数说明**：
| 参数 | 类型 | 说明 |
|------|------|------|
| `group_id` | `str` | 按分组 ID 过滤，允许多租户隔离 |
| `valid_at` | `datetime` | 查询特定时间点的有效事实 |
| `entity_uuids` | `list[str]` | 限定在特定实体范围内 |
| `source_node_uuid` | `str` | 查询以特定节点为源的事实 |
| `target_node_uuid` | `str` | 查询以特定节点为目标的事实 |
| `fact_categories` | `list[str]` | 按事实类别过滤 |
资料来源：[graphiti_core/search/search_filters.py:1-40]()
### 时间过滤
Graphiti 的时态图特性允许进行时间感知的查询：
- `valid_at`：查询在指定时间点有效的事实
- 自动处理事实的失效时间（新事实替代旧事实）
- 支持历史查询和当前状态查询
## MCP 服务器搜索工具
### 可用工具
Graphiti MCP 服务器提供以下搜索相关工具：
| 工具名称 | 功能 | 返回类型 |
|----------|------|----------|
| `search_memory_nodes` | 搜索知识图谱中的实体节点 | 节点列表 |
| `search_memory_facts` | 搜索实体之间的关系/事实 | 事实列表 |
资料来源：[mcp_server/src/graphiti_mcp_server.py:60-90]()
### 使用示例
#### 搜索实体节点
```python
# 通过 MCP 工具调用
search_memory_nodes(
query="customer preferences for cloud services",
group_id="enterprise-123"
)
```
#### 搜索事实/关系
```python
# 搜索两个实体之间的关系
search_memory_facts(
query="company X relationship with vendor Y",
group_id="enterprise-123"
)
```
> [!WARNING]
> `search_memory_facts` 在某些情况下可能返回序列化错误，特别是涉及 `neo4j.time.DateTime` 类型时。资料来源：[BUG] MCP search_memory_facts fails with 'Unable to serialize unknown type: ' #1438
## 搜索结果处理
### SearchResult 结构
```python
class SearchResult(BaseModel):
uuid: str # 唯一标识符
fact: FactBase # 事实数据
source_node: NodeResult # 源实体
target_node: NodeResult # 目标实体
similarity_score: float # 相似度分数
search_type: str # 使用的搜索类型
metadata: dict # 附加元数据
```
### 结果重排机制
Graphiti 支持多种结果重排策略：
1. **RRF（Reciprocal Rank Fusion）**：对多个搜索结果列表进行排名融合
2. **图距离重排**：基于与中心节点的图距离调整排名
3. **时间衰减**：根据事实的有效期时间调整权重
```mermaid
graph TD
A[多个搜索策略结果] --> B[RRF 融合计算]
B --> C[候选结果列表]
C --> D{是否使用图距离重排}
D -->|是| E[计算图距离分数]
D -->|否| F[时间衰减调整]
E --> G[综合排名]
F --> G
```
## 搜索配置配方详解
### NODE_HYBRID_SEARCH_RRF
用于直接搜索节点（实体），配置如下：
- **搜索模式**：语义 + BM25
- **融合方法**：RRF（倒数排名融合）
- **适用场景**：已知实体名称或描述的精确查询
```python
NODE_HYBRID_SEARCH_RRF = SearchConfig(
node_searcher=HybridNodeSearcher(...),
include_source_nodes=True,
include_target_nodes=True,
time_weight=0.1,
)
```
### CENTER_NODE_HYBRID_SEARCH
用于基于图结构进行重排的搜索：
1. 首先执行混合搜索获取候选结果
2. 以指定节点为中心计算图距离
3. 综合相似度分数和图距离得出最终排名
资料来源：[graphiti_core/search/search_config_recipes.py:20-35]()
## 性能优化
### 查询优化建议
| 策略 | 说明 | 预期收益 |
|------|------|----------|
| 使用 `group_id` 过滤 | 限制搜索范围到特定租户/项目 | 显著降低延迟 |
| 限制 `entity_uuids` | 只搜索相关实体子集 | 减少搜索空间 |
| 选择合适的时间窗口 | 避免查询过多历史数据 | 提高相关性 |
| 预热向量缓存 | 常用查询的嵌入向量缓存 | 减少嵌入计算 |
### 已知限制
- 向量相似度搜索的召回率受嵌入模型质量影响
- BM25 搜索在极短文本上效果有限
- 图遍历的跳数增加会显著增加查询延迟
## 与 Graphiti 整体架构的关系
```mermaid
graph LR
A[Episode 原始数据] --> B[提取阶段]
B --> C[节点 Node]
B --> D[边 Edge]
C --> E[向量索引]
D --> F[全文索引]
E --> G[搜索系统]
F --> G
G --> H[用户查询]
H --> I[检索结果]
```
混合搜索系统与 Graphiti 的其他组件紧密集成：
- **数据摄入阶段**：实体和关系被提取并建立索引
- **索引层**：向量索引（语义）和全文索引（BM25）
- **查询层**：统一的搜索接口支持多种策略
## 总结
Graphiti 的混合搜索与检索系统通过结合语义搜索、BM25 关键词搜索和图遍历，提供了一种灵活且高效的查询机制。这种设计使得系统能够：
- 处理多样化的查询需求
- 保持亚秒级的查询延迟
- 利用图的连通性提升结果相关性
- 支持时态查询和历史追溯
建议用户根据具体场景选择合适的搜索配置配方，并通过合理的过滤条件优化查询性能。在生产环境中，应注意配置适当的索引和缓存策略以确保最佳性能。
---
---
## Doramagic 踩坑日志
项目：getzep/graphiti
摘要：发现 14 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：配置坑 - 来源证据：NaN/Inf values from embedder silently break entity deduplication and propagate to graph storage。
## 1. 配置坑 · 来源证据：NaN/Inf values from embedder silently break entity deduplication and propagate to graph storage
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：NaN/Inf values from embedder silently break entity deduplication and propagate to graph storage
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2328466b52aa45579865c00657e318dd | https://github.com/getzep/graphiti/issues/1505 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 2. 安全/权限坑 · 来源证据：[BUG] FalkorDriver.build_fulltext_query fails on hyphens in group_id (RediSearch syntax error)
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] FalkorDriver.build_fulltext_query fails on hyphens in group_id (RediSearch syntax error)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_a31b49c7d71646a48dec968318e0ba8b | https://github.com/getzep/graphiti/issues/1483 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 3. 安装坑 · 来源证据：Neo4jDriver.__init__:57 schedules orphan create_task without cancel/await pair
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Neo4jDriver.__init__:57 schedules orphan create_task without cancel/await pair
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_b128cabe853b4492945c209b962d8457 | https://github.com/getzep/graphiti/issues/1513 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 4. 安装坑 · 来源证据：Suggestion: Standardized retrieval quality benchmarks for temporal knowledge graph queries
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Suggestion: Standardized retrieval quality benchmarks for temporal knowledge graph queries
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_a62b375e05dd49d18f6807c575566949 | https://github.com/getzep/graphiti/issues/1515 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 5. 安装坑 · 来源证据：Your project is ranked #16 on HVTracker — embed a trust badge?
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Your project is ranked #16 on HVTracker — embed a trust badge?
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_c1d4750319b947bd96a2308a6fe6d3b7 | https://github.com/getzep/graphiti/issues/1518 | 来源类型 github_issue 暴露的待验证使用条件。
## 6. 安装坑 · 来源证据：add_episode is impractically slow for >5KB content — proposal: skip_extraction parameter
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：add_episode is impractically slow for >5KB content — proposal: skip_extraction parameter
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_752fa6d991e844c599853b3d9f69b47e | https://github.com/getzep/graphiti/issues/1516 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 7. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:840056306 | https://github.com/getzep/graphiti | README/documentation is current enough for a first validation pass.
## 8. 维护坑 · 来源证据：FalkorDriver.default_group_id ('\_') is rejected by validate_group_id
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：FalkorDriver.default_group_id ('\_') is rejected by validate_group_id
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2126d3011d414eaf8bd9ce77b0d0ce6f | https://github.com/getzep/graphiti/issues/1517 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 9. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:840056306 | https://github.com/getzep/graphiti | last_activity_observed missing
## 10. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:840056306 | https://github.com/getzep/graphiti | no_demo; severity=medium
## 11. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:840056306 | https://github.com/getzep/graphiti | no_demo; severity=medium
## 12. 安全/权限坑 · 来源证据：[DB] LadybugDB Driver Support for Graphiti
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[DB] LadybugDB Driver Support for Graphiti
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_b6a9696a7ec842d48a220154476c4abe | https://github.com/getzep/graphiti/issues/1509 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 13. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:840056306 | https://github.com/getzep/graphiti | issue_or_pr_quality=unknown
## 14. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:840056306 | https://github.com/getzep/graphiti | release_recency=unknown