agentic_huge_data_base / wiki
页面 Graphiti · 8.3 REST 服务 API·DeepWiki 中文全文译文
DeepWiki 中文译文 / Graphiti / 8.3

8.3 · REST 服务 API（REST Service API）

时序知识图谱与动态事实记忆 · 聚焦本章的模块关系、源码依据与实现要点。

项目Graphiti 章节8.3 状态全文译文 模块检索、召回与索引、接口与服务契约、配置治理、图谱与关系
项目要点页2.5 参考项目 项目章节目录Graphiti DeepWiki 原始章节REST Service API 上一章8.2 下一章9
源码线索
  • Dockerfile
  • docker-compose.yml
  • server/Makefile
  • server/README.md
  • server/graph_service/config.py
  • server/graph_service/dto/__init__.py
  • server/graph_service/dto/common.py
  • server/graph_service/dto/ingest.py
  • server/graph_service/dto/retrieve.py
  • server/graph_service/main.py
模块标签
  • 检索、召回与索引
  • 接口与服务契约
  • 配置治理
  • 图谱与关系
  • 系统架构

章节正文

REST 服务 API

原始 DeepWiki 页面https://deepwiki.com/getzep/graphiti/8.3-rest-service-api

REST 服务 API

相关源文件

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

  • Dockerfile
  • docker-compose.yml
  • server/Makefile
  • server/README.md
  • server/graph_service/config.py
  • server/graph_service/dto/__init__.py
  • server/graph_service/dto/common.py
  • server/graph_service/dto/ingest.py
  • server/graph_service/dto/retrieve.py
  • server/graph_service/main.py
  • server/graph_service/routers/ingest.py
  • server/graph_service/routers/retrieve.py
  • server/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 映射）来扩展核心功能。

系统组件图
Graphiti · 系统组件图 · 图 1
Graphiti · 系统组件图 · 图 1

图：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 模式并确保严格的数据校验。

自然语言到代码实体的映射
Graphiti · 自然语言到代码实体的映射 · 图 2
Graphiti · 自然语言到代码实体的映射 · 图 2

图：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_URINeo4j 数据库的 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 上下文管理器来执行启动和关闭任务：

  1. 启动：调用 initialize_graphiti，该函数在图驱动上触发 build_indices_and_constraints。server/graph_service/main.py:12-14, server/graph_service/zep_graphiti.py:93-99
  2. 请求处理：get_graphiti 依赖注入为每个请求注入一个 ZepGraphiti 实例，确保干净的会话管理。server/graph_service/zep_graphiti.py:74-90
  3. 关闭：关闭 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