2 · 快速开始（Getting Started）

快速开始

快速入门

相关源文件

本章引用的主要源码文件：

• .env.example
• README.md
• examples/quickstart/README.md
• examples/quickstart/quickstart_falkordb.py
• examples/quickstart/quickstart_neo4j.py
• graphiti_core/decorators.py
• pyproject.toml
• tests/llm_client/test_anthropic_client_int.py
• tests/llm_client/test_client.py
• uv.lock

本指南将引导您完成 Graphiti 的安装、环境配置，以及首次事件入库和搜索查询操作。有关底层架构的详细信息，请参阅系统架构。有关高级搜索能力和时间过滤功能，请参阅搜索过滤器与时间查询。

前提条件

在安装 Graphiti 之前，请确保满足以下条件：

系统要求

图数据库设置

选择以下数据库后端之一：

Neo4j：安装 Neo4j Desktop 用于本地开发。驱动程序默认使用 neo4j 数据库名称 examples/quickstart/README.md:95-106。

FalkorDB：通过 Docker 运行以快速启动：

docker run -p 6379:6379 -p 3000:3000 -it --rm falkordb/falkordb:latest

Kuzu：嵌入式数据库，无需单独安装。

Amazon Neptune：需要 AWS 环境，包括 Neptune Database（neptune-db://）或 Neptune Analytics（neptune-graph://），以及用于全文搜索的 Amazon OpenSearch Serverless（AOSS）主机 examples/quickstart/README.md:56-59。

来源：README.md:136-159、examples/quickstart/README.md:12-23、examples/quickstart/quickstart_falkordb.py:48-62、pyproject.toml:12-21

安装

核心安装

安装基础 graphiti-core 包：

pip install graphiti-core

数据库特定安装

根据您选择的后端，安装带有数据库特定扩展的包 pyproject.toml:27-38：

# FalkorDB 支持
pip install graphiti-core[falkordb]

# Kuzu 支持
pip install graphiti-core[kuzu]

# Amazon Neptune 支持
pip install graphiti-core[neptune]

大语言模型（LLM）提供商安装

根据需要安装可选的大语言模型（LLM）提供商依赖 pyproject.toml:28-30：

# Anthropic Claude 支持
pip install graphiti-core[anthropic]

# Google Gemini 支持
pip install graphiti-core[google-genai]

# Groq 支持
pip install graphiti-core[groq]

安装流程与包依赖关系

来源：pyproject.toml:13-21、pyproject.toml:27-38、examples/quickstart/README.md:27-31

环境配置

必需的环境变量

为 OpenAI（默认提供商）设置以下环境变量 .env.example:1：

export OPENAI_API_KEY=your_openai_api_key

可选配置变量

来源：examples/quickstart/README.md:33-54、.env.example:1-19

初始化 Graphiti

使用 Neo4j 进行基本初始化

Graphiti 类是主要的入口点。使用数据库凭证进行初始化 examples/quickstart/quickstart_neo4j.py:67：

from graphiti_core import Graphiti

graphiti = Graphiti(
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password"
)

Graphiti 初始化架构

来源：graphiti_core/llm_client/client.py:17-20、examples/quickstart/quickstart_neo4j.py:66-68

替代数据库驱动程序

FalkorDB 初始化

from graphiti_core.driver.falkordb_driver import FalkorDriver
# 快速入门中的 FalkorDriver 初始化
falkor_driver = FalkorDriver(host="localhost", port="6379")
graphiti = Graphiti(graph_driver=falkor_driver)

来源：examples/quickstart/quickstart_falkordb.py:75-78

自定义大语言模型（LLM）提供商配置

使用 Anthropic

from graphiti_core.llm_client.anthropic_client import AnthropicClient
from graphiti_core.llm_client.config import LLMConfig

# Anthropic 的配置
llm_client = AnthropicClient(config=LLMConfig(api_key="sk-...", model="claude-3-5-sonnet-20241022"))
graphiti = Graphiti(uri="...", user="...", password="...", llm_client=llm_client)

来源：tests/llm_client/test_anthropic_client_int.py:24-25, 48、tests/llm_client/test_client.py:17-18

首次事件入库

理解事件

事件是离散的信息单元。Graphiti 支持 EpisodeType.text 和 EpisodeType.json examples/quickstart/quickstart_falkordb.py:92-125。

事件入库流程

来源：examples/quickstart/quickstart_falkordb.py:128-137、examples/quickstart/README.md:75

添加文本事件

from datetime import datetime, timezone
from graphiti_core.nodes import EpisodeType

await graphiti.add_episode(
    name="会议记录",
    episode_body="Kamala Harris 是加利福尼亚州的总检察长。",
    source=EpisodeType.text,
    source_description="播客转录",
    reference_time=datetime.now(timezone.utc),
)

来源：examples/quickstart/quickstart_falkordb.py:128-137、graphiti_core/nodes.py:28

首次搜索查询

基本边搜索

默认情况下，search() 执行混合搜索，结合语义相似性和 BM25 检索来查找关系（边）examples/quickstart/README.md:76。

results = await graphiti.search('谁是加利福尼亚州的总检察长？')

for result in results:
    print(f'事实: {result.fact}')
    if hasattr(result, 'valid_at') and result.valid_at:
        print(f'有效时间从: {result.valid_at}')

来源：examples/quickstart/quickstart_falkordb.py:151-162、examples/quickstart/README.md:110-118

节点搜索

要搜索节点（实体）而不是边，请使用 NODE_HYBRID_SEARCH_RRF 配方 examples/quickstart/quickstart_falkordb.py:29：

from graphiti_core.search.search_config_recipes import NODE_HYBRID_SEARCH_RRF

node_results = await graphiti.search(
    'Gavin Newsom',
    config=NODE_HYBRID_SEARCH_RRF
)

来源：examples/quickstart/README.md:78、examples/quickstart/README.md:120-129

中心节点重排序

您可以根据与特定节点 UUID 的图距离对结果进行重排序 examples/quickstart/README.md:77：

# 使用先前结果中的源节点 UUID
center_uuid = results[0].source_node_uuid

reranked = await graphiti.search(
    '加利福尼亚政治',
    center_node_uuid=center_uuid
)

来源：examples/quickstart/quickstart_falkordb.py:175-184

后续步骤

1. 社区检测：使用 await graphiti.build_communities() 构建全局摘要。
2. 自定义本体：通过 Pydantic 模型定义实体和边类型 README.md:82。
3. MCP 服务器：通过 MCP 服务器将 Graphiti 连接到 Claude 或 Cursor README.md:39。

来源：examples/quickstart/README.md:81-90