REST 服务 API（中文译文）
原始 DeepWiki 页面：https://deepwiki.com/getzep/graphiti/8.3-rest-service-api
翻译时间：2026-05-27T08:44:49.526Z
翻译模型：deepseek-chat
原文字符数：8959
项目：Graphiti (graphiti)
---
REST 服务 API
相关源文件
以下文件被用作生成此维基页面的上下文：
Dockerfiledocker-compose.ymlserver/Makefileserver/README.mdserver/graph_service/config.pyserver/graph_service/dto/__init__.pyserver/graph_service/dto/common.pyserver/graph_service/dto/ingest.pyserver/graph_service/dto/retrieve.pyserver/graph_service/main.pyserver/graph_service/routers/ingest.pyserver/graph_service/routers/retrieve.pyserver/graph_service/zep_graphiti.py
Graphiti REST 服务是一个基于 FastAPI 的 Web 应用程序，它提供了一个高级 HTTP 接口，用于将时序知识图谱能力集成到外部系统中。该服务封装了 graphiti-core 库，并公开了用于事件入库、语义搜索和图管理的端点。
该服务位于 server/ 目录中，设计为作为独立容器或微服务架构的一部分进行部署。
来源：server/pyproject.toml:1-16, server/graph_service/main.py:1-30, server/README.md:1-4
架构与数据流
REST 服务充当 HTTP 客户端与底层 Graphiti 核心之间的编排层。它使用一个专门的包装类 ZepGraphiti，通过服务特定的逻辑（如组删除和 DTO 映射）来扩展核心功能。
系统组件图
graph TD
subgraph "客户端空间"
API_CLIENT["HTTP 客户端<br/>（AI 智能体 / 应用）"]
end
subgraph "REST 服务（FastAPI）"
ROUTERS["路由器<br/>（ingest.py, retrieve.py）"]
DTO["数据传输对象<br/>（Pydantic 模型）"]
ZEP_G["ZepGraphiti<br/>（包装类）"]
WORKER["异步工作器<br/>（后台队列）"]
end
subgraph "Graphiti 核心"
G_CORE["Graphiti 核心客户端"]
DRIVER["GraphDriver<br/>（Neo4j/FalkorDB）"]
end
API_CLIENT -- "POST /messages" --> ROUTERS
ROUTERS -- "放入任务" --> WORKER
WORKER -- "调用 add_episode" --> ZEP_G
ZEP_G -- "继承/调用" --> G_CORE
G_CORE -- "Cypher/Bolt" --> DRIVER
API_CLIENT -- "POST /search" --> ROUTERS
ROUTERS -- "调用 search" --> ZEP_G
ZEP_G -- "返回边" --> ROUTERS
ROUTERS -- "映射为 FactResult" --> API_CLIENT
图：REST 服务架构与请求流程
来源：server/graph_service/zep_graphiti.py:17-19, server/graph_service/routers/ingest.py:13-38, server/graph_service/routers/retrieve.py:17-27
核心实现：ZepGraphiti
ZepGraphiti 类扩展了标准的 Graphiti 客户端，为 REST API 提供了额外的辅助方法。它处理来自环境设置的初始化，并为节点和边管理提供了更高层次的抽象。
关键方法
| 方法 | 描述 | 实现细节 |
|---|---|---|
save_entity_node | 手动创建一个 EntityNode。 | 在保存之前，通过 new_node.generate_name_embedding 生成名称嵌入向量。server/graph_service/zep_graphiti.py:21-30 |
get_entity_edge | 通过 UUID 检索特定的边。 | 使用 EdgeNotFoundError 抛出 HTTPException(404)。server/graph_service/zep_graphiti.py:32-38 |
delete_group | 对 group_id 进行级联删除。 | 删除该组所有关联的 EntityEdge、EntityNode 和 EpisodicNode 对象。server/graph_service/zep_graphiti.py:39-58 |
delete_episodic_node | 移除特定的事件。 | 通过 EpisodicNode.get_by_uuid 获取节点，然后调用 .delete()。server/graph_service/zep_graphiti.py:66-72 |
来源：server/graph_service/zep_graphiti.py:17-72
API 路由器和端点
该服务分为两个主要路由器：ingest 用于写入数据，retrieve 用于查询。
入库路由器（/ingest）
该路由器管理图中数据的生命周期。它实现了一个 AsyncWorker 来在后台处理事件，防止在复杂的大语言模型（LLM）提取任务期间发生 HTTP 超时。
- POST
/messages：接受一个AddMessagesRequest。它将每条消息推入AsyncWorker队列，以异步调用graphiti.add_episode，其中source=EpisodeType.message。server/graph_service/routers/ingest.py:51-70 - POST
/entity-node：使用save_entity_node辅助方法直接创建一个实体节点。server/graph_service/routers/ingest.py:73-85 - DELETE
/group/{group_id}：通过graphiti.delete_group清除与特定组关联的所有数据。server/graph_service/routers/ingest.py:93-97 - POST
/clear：维护端点，调用驱动上的clear_data，并通过build_indices_and_constraints重建索引。server/graph_service/routers/ingest.py:105-112
检索路由器（/retrieve）
该路由器提供用于搜索和获取图数据的端点。
- POST
/search：在指定的group_ids上执行语义搜索。它将EntityEdge结果映射为FactResult数据传输对象（DTO）。server/graph_service/routers/retrieve.py:17-28 - POST
/get-memory：一个专门的搜索端点，接受一个Message对象列表，通过compose_query_from_messages将它们组合成一个查询字符串，然后执行搜索。server/graph_service/routers/retrieve.py:44-57 - GET
/episodes/{group_id}：检索一个组的最后last_n个事件，使用graphiti.retrieve_episodes。server/graph_service/routers/retrieve.py:36-42
来源：server/graph_service/routers/ingest.py:48-112, server/graph_service/routers/retrieve.py:14-57
数据传输对象（DTO）
该服务使用 Pydantic 模型来定义 API 模式并确保严格的数据校验。
自然语言到代码实体的映射
classDiagram
class Message {
+str content
+str role_type
+str role
+datetime timestamp
}
class SearchQuery {
+list[str] group_ids
+str query
+int max_facts
}
class FactResult {
+str uuid
+str name
+str fact
+datetime valid_at
+datetime created_at
}
Message --|> "EpisodicNode" : "在 add_messages_task 中转换为 episode_body"
SearchQuery --|> "ZepGraphiti" : "传递给 .search()"
"EntityEdge" --|> FactResult : "通过 get_fact_result_from_edge 映射"
图：DTO 到核心实体的映射
来源：server/graph_service/dto/common.py:13-29, server/graph_service/dto/retrieve.py:8-23, server/graph_service/zep_graphiti.py:102-111, server/graph_service/routers/ingest.py:56-65
部署与配置
REST 服务通过环境变量进行配置，并在 FastAPI 生命周期期间进行初始化。它通过 Docker Compose 配置文件支持 Neo4j 和 FalkorDB 两种后端。
环境变量
| 变量 | 描述 |
|---|---|
OPENAI_API_KEY | 大语言模型（LLM）和嵌入向量服务的 API 密钥。server/graph_service/config.py:10 |
OPENAI_BASE_URL | 可选的基础 URL，用于兼容 OpenAI 的代理。server/graph_service/config.py:11 |
NEO4J_URI | Neo4j 数据库的 Bolt URI。server/graph_service/config.py:14 |
NEO4J_USER | 数据库用户名。server/graph_service/config.py:15 |
NEO4J_PASSWORD | 数据库密码。server/graph_service/config.py:16 |
MODEL_NAME | 用于提取的大语言模型（LLM）模型名称。server/graph_service/config.py:12 |
GRAPHITI_BACKEND | 指定数据库后端（例如 falkordb）。docker-compose.yml:86 |
来源：server/graph_service/config.py:9-18, server/graph_service/zep_graphiti.py:74-86, docker-compose.yml:81-88
服务生命周期
应用程序使用 lifespan 上下文管理器来执行启动和关闭任务：
- 启动：调用
initialize_graphiti，该函数在图驱动上触发build_indices_and_constraints。server/graph_service/main.py:12-14,server/graph_service/zep_graphiti.py:93-99 - 请求处理：
get_graphiti依赖注入为每个请求注入一个ZepGraphiti实例，确保干净的会话管理。server/graph_service/zep_graphiti.py:74-90 - 关闭：关闭
ZepGraphiti客户端并停止AsyncWorker。server/graph_service/zep_graphiti.py:90,server/graph_service/routers/ingest.py:41-46
来源：server/graph_service/main.py:11-20, server/graph_service/zep_graphiti.py:74-100, server/graph_service/routers/ingest.py:41-48