核心定位

Graphiti 与传统 GraphRAG 方法的关键区别：

资料来源：README.md

什么是上下文图（Context Graph）

上下文图是一种时序实体、关系和事实的知识图谱——例如 *"Kendra 喜欢阿迪达斯鞋（截至 2026 年 3 月）"*。与传统的知识图谱不同，上下文图中的每个事实都有一个有效性时间窗口：它何时变为真，何时（如果有的话）被取代。实体随时间演变并更新摘要。一切都可以追溯到 Episodes——生成这些知识的原始数据。

Graphiti 的独特之处在于其能够从非结构化和结构化数据自主构建上下文图，在保留完整时序历史的同时处理变化的关系。

上下文图包含以下组件：

资料来源：README.md

核心能力

时序事实管理

事实具有有效性时间窗口。当信息发生变化时，旧事实会被失效——而非删除。用户可以查询现在什么是真的，或者在任何时间点什么是真的。

Episodes 与溯源

每个实体和关系都可以追溯到生成它的 Episodes（原始数据）。从派生事实到源数据的完整 lineage。

混合检索

结合多种搜索策略：

• 语义搜索：使用嵌入向量查找语义相似的内容
• BM25：基于关键词的文本检索
• 图遍历：利用实体之间的关系

增量数据更新

支持增量数据更新、高效检索和精确的历史查询，无需完全重新计算图谱。

资料来源：README.md

架构概览

Graphiti 的系统架构如下：

graph TB
    subgraph "数据输入层"
        Episodes[Episodes<br/>文本/消息/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 支持多种图数据库作为存储后端：

[!NOTE]

当前版本不支持 RDF 知识图谱集成（社区议题 #933）。用户请求也包括对 Postgres（带 pgvector）和 MemGraph 的支持。

资料来源：README.md

支持的 LLM 和 Embedding 提供商

LLM 提供商

Embedding 提供商

资料来源：mcp_server/README.md

MCP 服务器

Graphiti 提供了一个实验性的 Model Context Protocol (MCP) 服务器实现，允许 AI 助手通过 MCP 协议与 Graphiti 的知识图谱功能交互。

MCP 工具列表

资料来源：mcp_server/README.md

自定义实体类型

Graphiti 支持通过 Pydantic 模型定义开发者自定义的实体类型。内置实体类型包括：

[!IMPORTANT]

Preference 类型具有最高优先级，在实体分类时应优先考虑。

资料来源：mcp_server/src/models/entity_types.py

安装要求

pip install graphiti-core

资料来源：README.md

快速开始流程

graph LR
    A[安装 Graphiti] --> B[配置数据库连接]
    B --> C[配置 LLM/Embedding]
    C --> D[初始化图谱]
    D --> E[添加 Episodes]
    E --> F[搜索查询]
    F --> G[获取结果]

基本使用示例

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

遥测数据收集

Graphiti 在初始化时会收集匿名遥测数据，用于了解配置选择和采用模式。

收集的数据

• 匿名标识符（随机 UUID）
• 系统信息（操作系统、Python 版本、架构）
• Graphiti 版本
• 配置选择（LLM 提供商、数据库后端、Embedding 提供商）

不收集的数据

• 个人身份信息
• API 密钥或凭证
• 实际数据、查询或图谱内容
• IP 地址或主机名
• 文件路径

遥测是可选退出的，可以在任何时候禁用：

# 在初始化前设置
import os
os.environ["GRAPHITI_TELEMETRY_ENABLED"] = "false"

资料来源：README.md

版本历史与已知问题

最新版本：v0.29.1

主要优化和效率改进：

• 属性幻觉防护：防止 LLM 将元推理内容写入实体属性字段
• 更低的提取成本：新的组合节点+边提取路径

已知问题

安全版本

• v0.28.2：修复 Cypher 注入漏洞，建议所有用户升级
• mcp-v1.0.2：要求 graphiti-core >= 0.28.2

资料来源：community_context

与 Zep 的关系

选择 Zep：如果需要企业级即用型平台，内置安全性、性能和支持。

选择 Graphiti：如果需要灵活的开源核心，并愿意自行构建和运维周边系统。

资料来源：README.md

Docker 部署

Graphiti 服务容器已自动构建并发布到 Docker Hub：

# 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

核心概念

Graphiti 是一个用于构建时序上下文图谱（Temporal Context Graph）的开源引擎。本页详细介绍 Graphiti 的核心数据模型、实体类型、关系管理以及检索机制，帮助开发者理解系统的工作原理和设计理念。

系统架构

Graphiti 是一个用于构建时序上下文图谱的开源引擎，专为 AI Agent 内存管理设计。本页详细说明 Graphiti 的核心系统架构，包括各组件职责、数据流转、以及扩展机制。

概述

Graphiti 的数据流与摄取管道是构建时序上下文图的核心组件，负责将原始数据（文本、JSON、对话等）转换为结构化的实体和关系。从 v0.29.0 版本开始，该管道进行了重大架构优化，引入了合并节点和边提取路径，允许单次 LLM 调用覆盖之前需要多次调用才能完成的工作，从而显著降低了提取成本。

管道的设计目标是支持：

• 增量图构建：新数据立即整合，无需批量重新计算
• 多源数据支持：文本、JSON、对话消息等多种输入格式
• 时序事实管理：自动处理事实的有效期和失效
• 可定制本体：通过 Pydantic 模型定义实体和边类型

资料来源：README.md:18-24

核心数据模型

Episode（事件）

Episode 是摄取管道的输入单位，代表原始数据的一次摄入。每个 Episode 包含：

支持的来源类型（EpisodeType）：

• text：纯文本内容
• json：结构化 JSON 数据
• message：对话式内容

资料来源：mcp_server/src/graphiti_mcp_server.py:89-101

Entity（实体）

实体是图中的节点，代表从数据中提取的有意义概念。Graphiti 支持以下内置实体类型：

⚠️ 注意：Preference 类型具有最高优先级，当内容表达用户偏好时应优先使用此分类。

资料来源：mcp_server/src/models/entity_types.py:1-80

Fact/Edge（事实/边）

事实表示两个实体之间的关系，包含：

• 源实体
• 目标实体
• 关系名称
• 有效性时间窗口（valid_from, valid_to）
• 溯源信息（指向产生该事实的 Episode）

资料来源：README.md:32-35

摄取管道架构

整体数据流

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 的分块策略来处理长内容：

分块决策基于实体密度评估：

• 高密度内容（JSON 数组、列表等）：适合分块，每个元素可能包含独立实体
• 低密度内容（散文、叙述）：不建议分块，会丢失上下文

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 调用同时提取节点和边：

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

#### 第四阶段：图写入与时序管理

写入图数据库时，管道处理以下逻辑：

资料来源：graphiti_core/utils/maintenance/node_operations.py、graphiti_core/utils/maintenance/edge_operations.py

MCP 服务摄取接口

MCP 服务器提供 add_memory 工具用于数据摄取：

add_memory(
    name="事件名称",
    episode_body="原始内容",
    source="text | json | message",  # 来源类型
    source_description="来源描述",
    group_id="分组标识"
)

JSON 数据摄取示例

MCP 服务支持通过 source="json" 自动从结构化数据提取实体和关系：

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

配置与调优

环境变量

自定义实体类型

在 config.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)：FalkorDriver.build_fulltext_query 在 group_id 包含连字符时产生 RediSearch 语法错误。驱动程序注释声称通过引号处理连字符，但实现仅使用 "..." 包裹而未进行转义。

变通方案：避免在 group_id 中使用连字符，或使用下划线替代。

数据库参数问题

🔴 BUG (#1481)：Neo4jDriver.execute_query() 错误地将 database_ 放入 parameters_ 字典，导致查询时数据库参数未被正确传递。

日期时间序列化问题

🔴 BUG (#1438)：MCP search_memory_facts 在处理包含 neo4j.time.DateTime 类型的图时返回序列化错误。

Pydantic v2 兼容性

⚠️ DEPRECATION (#1477)：SearchInterface 使用了 Pydantic v1 风格的 class Config:，在 v3 版本中将导致硬失败。

性能优化建议

1. 批量实体摘要

v0.28.0 引入了批量实体摘要功能，可减少 LLM 调用次数：

# 在配置中启用批量摘要
config = GraphitiConfig(
    batch_entity_summarization=True,
    batch_size=10
)

2. 内容分块优化

对于高密度 JSON 数据，系统会自动评估是否需要分块。避免将大量无关内容放入单个 JSON 对象中。

3. group_id 命名规范

为避免 RediSearch 语法错误和数据库参数问题，建议：

• 使用下划线而非连字符：user_123 而非 user-123
• 避免特殊字符
• 保持命名简洁一致

相关文档

• 快速开始指南 - 基础摄取示例
• Azure OpenAI 集成 - 云端 LLM 配置
• 搜索配置 - 检索优化
• v0.29.0 发布说明 - 架构变更详情

概述

Neo4j 驱动是 Graphiti 框架中用于连接和操作 Neo4j 图数据库的核心组件。作为 Graphiti 支持的主要图存储后端之一，Neo4j 驱动提供了完整的图数据库操作能力，包括实体节点管理、关系边操作、搜索查询、Episode 管理以及图索引维护等功能。

Graphiti 的 Neo4j 驱动采用模块化架构设计，将不同类型的数据库操作分离到独立的操作模块中，通过统一的驱动接口对外提供服务。这种设计使得代码结构清晰，便于维护和扩展。

架构设计

驱动组件结构

graph TD
    A[Neo4jDriver] --> B[Graphiti 核心接口]
    A --> C[操作模块层]
    
    C --> D[graph_ops.py<br/>图操作]
    C --> E[search_ops.py<br/>搜索操作]
    C --> F[entity_node_ops.py<br/>实体节点操作]
    C --> G[entity_edge_ops.py<br/>实体边操作]
    C --> H[episode_ops.py<br/>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

数据库操作分层

核心配置

连接参数

Neo4jDriver(
    uri: str,           # bolt://localhost:7687
    user: str,          # neo4j
    password: str,      # 数据库密码
    database: str = "neo4j"  # 数据库名称，默认为 "neo4j"
)

环境变量配置

配置优先级：环境变量 > 配置文件 > 代码默认值 资料来源：mcp_server/src/services/factories.py:1-50

配置示例

# 基础连接配置
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

#### 节点数据模型

节点查询操作

Graphiti 提供了多种节点查询方式，包括按 UUID 查询、按分组查询、按名称搜索等。查询结果支持分页和排序功能。 资料来源：graphiti_core/driver/neo4j/operations/entity_node_ops.py:80-150

边操作

实体关系管理

实体边表示图中实体之间的关系，是构建知识图谱的关键组成部分。每条边包含源实体、目标实体、关系名称、边类型以及时态信息。 资料来源：graphiti_core/driver/neo4j/operations/entity_edge_ops.py:1-100

#### 边数据模型

时态事实处理

Graphiti 的核心特性之一是支持时态事实管理。当新的事实与现有事实矛盾时，系统不会删除旧数据，而是通过设置 invalid_at 时间戳来标记失效，同时创建新的有效事实。这种设计保证了数据的可追溯性和历史查询能力。 资料来源：graphiti_core/driver/neo4j/operations/entity_edge_ops.py:150-250

graph LR
    A[Episode 1<br/>2024-01-01] --> B[Alice 喜欢 苹果]
    B --> C[valid_at: 2024-01-01<br/>invalid_at: NULL]
    
    D[Episode 2<br/>2024-03-15] --> E[Alice 喜欢 香蕉]
    E --> F[valid_at: 2024-03-15<br/>invalid_at: NULL]
    
    B -.-> G[invalid_at: 2024-03-15]

搜索操作

混合搜索机制

Neo4j 驱动实现了混合搜索功能，结合语义相似度和关键词匹配（BM25）来提供高质量的搜索结果。搜索操作支持按分组过滤，可以限制搜索范围到特定的数据分组。 资料来源：graphiti_core/driver/neo4j/operations/search_ops.py:1-150

#### 搜索类型

全文索引

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

Episode 批量操作

为提高摄入效率，Graphiti 支持 Episode 批量操作。批量操作使用 Neo4j 的 UNWIND 子句来高效处理大量数据。 资料来源：graphiti_core/models/nodes/node_db_queries.py:50-150

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

#### 自动创建的约束

#### 自动创建的索引

图清理操作

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. 索引维护：在批量数据摄入后，建议运行索引统计更新以优化查询性能

与其他驱动的比较

最佳实践

连接配置

# 生产环境配置建议
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()

错误处理

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 驱动是 Graphiti 项目中用于连接和操作 FalkorDB 图数据库的核心组件。FalkorDB 是一个基于 Redis 的图数据库，支持 RediSearch 全文搜索功能，能够高效存储和检索知识图谱中的实体、关系和事实。

Graphiti 的核心设计理念是支持多种图数据库后端，通过统一的驱动接口实现跨数据库兼容性。FalkorDB 驱动实现了与 Neo4j 驱动相同的抽象接口，使得用户可以在不修改业务代码的情况下切换底层存储引擎。

主要职责：

• 管理与 FalkorDB 的连接生命周期
• 执行图查询语言（基于 Redis/GQL）操作
• 利用 RediSearch 实现全文搜索和混合检索
• 维护图索引和约束条件
• 处理事实的有效性时间窗口

架构设计

驱动层次结构

FalkorDB 驱动采用分层架构设计，将核心图操作与搜索功能解耦：

┌─────────────────────────────────────────────────────────┐
│                    Graphiti Core                        │
│                  (业务逻辑层)                             │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│              FalkorDBDriver                             │
│            (驱动抽象层)                                  │
├─────────────────────────────────────────────────────────┤
│  ┌──────────────────┐      ┌──────────────────────────┐ │
│  │  SearchOps       │      │    GraphOps              │ │
│  │  (搜索操作层)     │      │   (图操作层)              │ │
│  └────────┬─────────┘      └──────────┬───────────────┘ │
│           │                             │                │
│  ┌────────▼─────────────────────────────▼───────────────┐│
│  │           FalkorDB / RediSearch Client              ││
│  │                  (通信层)                             ││
│  └─────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────┘

核心组件

搜索操作（SearchOps）

全文本查询构建

SearchOps 组件负责构建 RediSearch 查询语句，实现 Graphiti 的混合搜索功能。搜索功能支持按 group_id 过滤结果，这是多租户数据隔离的关键机制。

查询构建流程：

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 兼容的查询字符串。该方法需要处理用户输入的特殊字符，包括空格、引号和连字符等。

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 使用索引来实现高效的实体查询和关系遍历。

索引类型：

约束条件

Graphiti 需要在数据库层面维护数据完整性约束：

• 唯一性约束：确保同一 group_id 下的实体 UUID 全局唯一
• 存在性约束：确保实体和边的必要属性存在
• 类型约束：验证实体和边的类型字段

配置与连接

环境变量配置

使用 FalkorDB 时，需要配置以下环境变量：

驱动初始化

from graphiti_core.driver.falkordb_driver import FalkorDBDriver

driver = FalkorDBDriver(
    uri="falkor://localhost:6379",
    database=0
)

# 初始化索引和约束
await driver.create_indices()

与 Neo4j 驱动的对比

已知问题与限制

Issue #1483：group_id 中连字符导致的语法错误

问题描述： FalkorDriver.build_fulltext_query 方法在处理包含连字符（-）的 group_id 时，会生成 RediSearch 解析失败的查询语句。

问题根源： 驱动代码注释声称已处理连字符转义，但实际实现仅使用双引号包裹，未进行正确的转义处理。

影响版本： graphiti-core 0.29

临时解决方案：

# 避免在 group_id 中使用连字符
group_id = "my_group_id"  # 使用下划线代替

预期修复： 在 build_fulltext_query 方法中添加对连字符的转义处理，确保 group_id 满足 RediSearch 的标识符语法要求。

使用示例

基础搜索操作

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 关键词匹配：

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 官方文档
• RediSearch 文档
• Graphiti GitHub 仓库
• Issue #1483：连字符处理问题

概述

Graphiti 支持多种图数据库作为后端存储引擎，主要包括 Kuzu 和 Amazon Neptune 两种驱动。这两个驱动实现了统一的 GraphDriver 接口，为 Graphiti 提供图存储、查询和索引管理能力。资料来源：README.md:1-30

Graphiti 采用可插拔的驱动架构，允许开发者根据部署环境选择合适的图数据库：

驱动架构

GraphDriver 接口抽象

所有图驱动均实现统一的 GraphDriver 接口，确保核心功能的一致性：

classDiagram
    class GraphDriver {
        <<interface>>
        +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

核心功能

Kuzu 图操作实现

Kuzu 驱动通过 graph_ops.py 中的操作类实现具体功能：

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):
        """搜索边"""

配置要求

# 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

架构特点

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 图操作实现

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 配置示例
graphiti:
  driver: neptune
  neptune:
    database: "default_db"
    search_domain: "graphiti-search"
  aws:
    region: "us-east-1"
    # 建议使用 IAM 角色或环境变量配置凭证

驱动初始化流程

统一初始化模式

所有驱动遵循一致的初始化流程：

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: 执行混合搜索

初始化参数

全文搜索集成

Kuzu 全文搜索

Kuzu 驱动内置向量搜索支持，无需外部服务：

class KuzuDriver:
    def build_fulltext_index(self):
        """创建 Kuzu 向量索引用于语义搜索"""
        
    def search_fulltext(self, query: str, limit: int = 10):
        """执行向量相似度搜索"""

Neptune 全文搜索

Neptune 驱动依赖 Amazon OpenSearch Serverless：

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 和 Neo4j 驱动，Kuzu 和 Neptune 驱动用户不受影响。

使用建议

1. Kuzu 驱动：适合本地开发和测试，无需配置外部服务
2. Neptune 驱动：适合 AWS 生产环境，自动获得高可用和扩展能力
3. 选择考虑因素：

• 部署规模（小型用 Kuzu，大型用 Neptune）
• 运维能力（Kuzu 自管理，Neptune 托管）
• 云服务商偏好（Neptune 仅限 AWS）

快速开始

Kuzu 快速启动

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 快速启动

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 核心库
• MCP 服务器文档
• 快速开始示例
• v0.29.0 发布说明 - 驱动架构优化

架构概述

Graphiti 采用模块化的 LLM 客户端架构，通过统一的接口抽象不同提供商的具体实现。这种设计允许开发者在不修改核心业务逻辑的情况下切换不同的 LLM 服务。

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

核心组件

支持的 LLM 提供商

OpenAI

OpenAI 是 Graphiti 的默认 LLM 提供商，适用于标准 GPT 系列模型的调用场景。

配置示例：

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

配置示例：

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)

环境变量配置：

使用前提：

1. 拥有 Azure 订阅并开通 OpenAI 服务
2. 部署 GPT 系列模型（建议 GPT-4o 或更新版本）
3. 配置嵌入模型部署用于语义搜索

Anthropic Claude

Anthropic 的 Claude 系列模型以安全性和长上下文能力著称。

配置示例：

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 提供多模态能力和长上下文窗口。

配置示例：

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 格式的服务提供商，包括本地部署模型和第三方服务。

典型应用场景：

graph LR
    A[OpenAIGenericClient] --> B[Ollama]
    A[OpenAIGenericClient] --> C[LM Studio]
    A[OpenAIGenericClient] --> D[vLLM]
    A[OpenAIGenericClient] --> E[LocalAI]
    A[OpenAIGenericClient] --> F[其他兼容服务]

Ollama 本地部署示例：

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"
        )
    )
)

客户端特性：

LLMConfig 配置详解

LLMConfig 是所有 LLM 客户端的统一配置模型：

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  # 请求超时时间

配置参数说明

嵌入模型集成

Graphiti 的搜索功能依赖嵌入模型生成语义向量。嵌入层与 LLM 层相互独立，支持灵活配置。

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

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 配合使用本地嵌入模型：

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"
    )
)

提供商选择指南

选择考量因素

模型配对建议

Graphiti 使用双模型策略：一个主模型处理复杂任务，一个小型模型处理简单任务以控制成本。

常见问题

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 版本和模型本身能力。

环境变量汇总

相关资源

• Graphiti 官方文档
• Ollama 官方文档
• Azure OpenAI 文档
• Anthropic Claude 文档
• Google Gemini 文档

概述

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）支持"维度缩减"功能，可以在不损失太多精度的情况下减少向量维度，从而降低存储成本和计算开销。

嵌入器实现详解

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 方法接收查询和候选文档列表，返回按相关性排序的结果。

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 类定义搜索行为的关键参数，包括使用的嵌入模型、重排序配置、结果数量限制等。配置支持运行时调整，允许不同场景使用不同策略。

@dataclass
class SearchConfig:
    embedder_config: EmbedderConfig
    reranker_config: RerankerConfig | None
    hybrid_config: HybridSearchConfig
    temporal_config: TemporalSearchConfig

预定义搜索配方

Graphiti 提供了多个预定义搜索配置（配方），覆盖常见的检索场景：

RRF（Reciprocal Rank Fusion）是一种无参数的结果融合方法，通过对各检索来源的结果按排名取倒数求和来计算综合分数，避免了权重调优的复杂性。

混合检索流程

三阶段检索架构

Graphiti 的混合检索流程分为三个阶段：并行检索、分数融合和可选重排序。

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 类管理，主要参数包括：

dimensions 参数特别有用，OpenAI 的新嵌入模型支持在返回时自动缩减维度。例如，可以请求 1024 维向量而模型实际输出 3072 维，系统会在服务端进行降维，减少存储和计算开销。

重排序配置参数

重排序配置通过 RerankerConfig 类管理：

top_n 参数控制重排序后的结果数量。由于交叉编码器推理成本较高，通常只对初始检索的 Top-20 到 Top-50 结果进行重排序，然后返回最终的 Top-10 结果。

性能优化建议

1. 选择合适的嵌入维度：对于大多数应用，1536 维的 text-embedding-3-small 已足够。降低维度可减少 50-75% 的存储空间。

1. 批量处理嵌入请求：批量请求比单独请求效率高得多，建议将大量文档的嵌入操作合并为批处理。

1. 条件重排序：只在需要高精度结果时启用重排序。对于需要快速响应的场景，可以先返回 RRF 结果，异步进行重排序更新。

1. 缓存嵌入结果：对于不经常变化的文档，可以缓存其嵌入向量，避免重复计算。

与 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 的向量嵌入与重排序系统提供了完整的企业级检索能力。通过支持多种嵌入模型提供商、灵活的搜索配置和高效的混合检索策略，系统能够满足从原型验证到大规模生产的各类需求。开发者应熟悉搜索配置参数和调优方法，以便根据具体应用场景优化检索效果。

概述

Graphiti 的混合搜索与检索系统是构建上下文图（Context Graph）的核心能力，它结合了多种检索策略以实现低延迟、高精度的知识查询。与传统 GraphRAG 依赖 LLM 总结的方式不同，Graphiti 采用语义搜索、关键词搜索（BM25）和图遍历相结合的方法，通常能够实现亚秒级的查询延迟。

混合检索的核心价值在于：

• 多维度理解：同时捕捉语义相似性和精确关键词匹配
• 图结构感知：利用实体之间的关系进行相关性排序
• 可组合性：通过预定义配置灵活调整搜索策略

资料来源：README.md:1-20

搜索架构

整体架构图

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[图数据库]

核心组件

资料来源：graphiti_core/search/search_config.py:1-50

搜索配置系统

SearchConfig 类

SearchConfig 是搜索系统的核心配置类，定义了搜索行为的各个方面：

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,
    ):
        ...

参数说明：

资料来源：graphiti_core/search/search_config.py:30-45

搜索配置配方

Graphiti 提供了预定义的搜索配置配方，位于 search_config_recipes.py：

资料来源：graphiti_core/search/search_config_recipes.py:1-30

搜索策略详解

语义搜索

语义搜索利用嵌入向量（embeddings）来查找语义相似的内容。Graphiti 支持多种嵌入服务：

• OpenAI：默认使用 text-embedding-ada-002 或 text-embedding-3-small
• Azure OpenAI：通过 AzureOpenAILLMClient 配置
• 自定义：实现 EmbedderClient 接口

语义搜索的典型流程：

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 定义了搜索时的过滤条件：

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

参数说明：

资料来源：graphiti_core/search/search_filters.py:1-40

时间过滤

Graphiti 的时态图特性允许进行时间感知的查询：

• valid_at：查询在指定时间点有效的事实
• 自动处理事实的失效时间（新事实替代旧事实）
• 支持历史查询和当前状态查询

MCP 服务器搜索工具

可用工具

Graphiti MCP 服务器提供以下搜索相关工具：

资料来源：mcp_server/src/graphiti_mcp_server.py:60-90

使用示例

#### 搜索实体节点

# 通过 MCP 工具调用
search_memory_nodes(
    query="customer preferences for cloud services",
    group_id="enterprise-123"
)

#### 搜索事实/关系

# 搜索两个实体之间的关系
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: <class neo4j.time.DateTime>' #1438

搜索结果处理

SearchResult 结构

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. 时间衰减：根据事实的有效期时间调整权重

graph TD
    A[多个搜索策略结果] --> B[RRF 融合计算]
    B --> C[候选结果列表]
    C --> D{是否使用图距离重排}
    D -->|是| E[计算图距离分数]
    D -->|否| F[时间衰减调整]
    E --> G[综合排名]
    F --> G

搜索配置配方详解

NODE_HYBRID_SEARCH_RRF

用于直接搜索节点（实体），配置如下：

• 搜索模式：语义 + BM25
• 融合方法：RRF（倒数排名融合）
• 适用场景：已知实体名称或描述的精确查询

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

性能优化

查询优化建议

已知限制

• 向量相似度搜索的召回率受嵌入模型质量影响
• BM25 搜索在极短文本上效果有限
• 图遍历的跳数增加会显著增加查询延迟

与 Graphiti 整体架构的关系

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 关键词搜索和图遍历，提供了一种灵活且高效的查询机制。这种设计使得系统能够：

• 处理多样化的查询需求
• 保持亚秒级的查询延迟
• 利用图的连通性提升结果相关性
• 支持时态查询和历史追溯

建议用户根据具体场景选择合适的搜索配置配方，并通过合理的过滤条件优化查询性能。在生产环境中，应注意配置适当的索引和缓存策略以确保最佳性能。

Pitfall Log / 踩坑日志

项目：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