企业官网建设流程全解析

如何用 zepai/graphiti 容器镜像和 Neo4j 部署 Graphiti REST API 服务并验证 /docs 与 /healthcheck？

【免费下载链接】graphitiBuild Real-Time Knowledge Graphs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/grap/graphiti

Graphiti 仓库的server/子目录实现了一个基于 FastAPI 的 REST API 服务，官方会把它构建成zepai/graphiti容器镜像发布到 Docker Hub（server/README.md）。这篇文章覆盖一个明确的任务：在本地用 Docker Compose 拉起zepai/graphiti镜像和配套的 Neo4j 实例，然后确认服务的 Swagger 文档页/docs和健康检查接口/healthcheck都能正常访问。开始前你的机器上需要安装 Docker 和 Docker Compose，并且能提供一个 OpenAI API Key 和一组 Neo4j 账号密码。

镜像与版本信息

根据 server/README.md，容器镜像的基本信息如下：

• 镜像：zepai/graphiti
• 可用 tag：latest（最新稳定版）和具体版本号（与graphiti-core的 PyPI 版本一致，文档中给出的示例是0.22.1）
• 平台：linux/amd64、linux/arm64
• 自动发布规则：每当graphiti-core发布新的稳定版到 PyPI 时触发，预发布版本不会自动构建

镜像内部以非 root 用户运行，固定监听 8000 端口，启动命令为uv run --no-sync uvicorn graph_service.main:app --host 0.0.0.0 --port 8000（见 Dockerfile）。所以宿主机的端口映射要映射到容器内的 8000 端口。

服务启动时需要哪些配置，可以从 配置文件类 看出来：openai_api_key是必填项（缺失时启动失败），neo4j_uri、neo4j_user、neo4j_password用于连接 Neo4j，db_backend缺省值就是neo4j，因此走 Neo4j 后端时无需额外指定。

编写 docker compose 文件

按 server/README.md 给出的示例，在任意一个工作目录下创建docker-compose.yml（下文${OPENAI_API_KEY}、${NEO4J_USER}、${NEO4J_PASSWORD}、${NEO4J_PORT}四个变量需要在启动前由你提供，例如通过 shell 导出或在 compose 所在目录的.env文件中定义，否则 compose 插值会失败）：

version: '3.8' services: graph: image: zepai/graphiti:latest ports: - "8000:8000" environment: - OPENAI_API_KEY=${OPENAI_API_KEY} - NEO4J_URI=bolt://neo4j:${NEO4J_PORT} - NEO4J_USER=${NEO4J_USER} - NEO4J_PASSWORD=${NEO4J_PASSWORD} neo4j: image: neo4j:5.22.0 ports: - "7474:7474" # HTTP - "${NEO4J_PORT}:${NEO4J_PORT}" # Bolt volumes: - neo4j_data:/data environment: - NEO4J_AUTH=${NEO4J_USER}/${NEO4J_PASSWORD} volumes: neo4j_data:

几个关键点的说明：

• graph服务通过NEO4J_URI=bolt://neo4j:${NEO4J_PORT}访问 Neo4j，neo4j是 compose 网络内的服务名，不是 localhost。
• Neo4j 服务暴露两个端口：7474是 HTTP 端口（Neo4j Browser 用），${NEO4J_PORT}是 Bolt 端口（Graphiti 服务实际通过它连接，README 示例中该变量对应 Neo4j 默认的 Bolt 端口，你需要把它与NEO4J_AUTH的用户密码保持一致）。
• neo4j_data卷用于持久化数据库数据。
• README 同时说明，你也可以不用 compose 里的 Neo4j 容器，改用 Neo4j Cloud 或桌面版，只要把NEO4J_URI、NEO4J_USER、NEO4J_PASSWORD指向你的实例即可——这是文档明确给出的替代路径，但本文主路径继续用容器化 Neo4j。

注意仓库根目录还有一个 docker-compose.yml，那是用于从源码构建镜像（build: context: .）的测试编排，并包含 FalkorDB 的可选 profile，与本文“拉取zepai/graphiti镜像”的目标不同，不要混用。

启动服务

在 compose 文件所在目录执行：

docker compose up -d

启动后 Graphiti REST API 服务位于http://localhost:8000（如果你修改了 compose 文件中的端口映射，则按你映射的端口访问）。容器内服务监听 8000 端口是 Dockerfile 中ENV PORT=8000和EXPOSE 8000固定的。

一个容易踩的坑：OPENAI_API_KEY缺失时服务无法启动（AGENTS.md 中明确说明Settings要求该变量存在，否则启动失败）。这里只要求变量存在且非空；真正执行入库、搜索等需要调用 LLM 和嵌入的接口时，才需要一个有效的 Key。

验证 /docs 与 /healthcheck

服务起来后做两项检查：

1. 访问 Swagger 文档页

在浏览器打开http://localhost:8000/docs，应能看到 Graphiti 服务的 OpenAPI 交互文档；README 还提到http://localhost:8000/redoc提供 Redoc 视图。如果你需要确认 Neo4j 侧也正常，可以访问http://localhost:7474打开 Neo4j Browser（端口取决于你实际使用的 Neo4j 实例）。

2. 请求健康检查接口

/healthcheck端点定义在 server/graph_service/main.py 中，实现是一个GET /healthcheck路由，返回 200 和 JSON 内容{"status": "healthy"}。可以直接用 curl 验证：

curl http://localhost:8000/healthcheck

预期返回（文档中实现的固定响应体）：

{"status": "healthy"}

HTTP 状态码应为 200。仓库内的集成测试 test_live_falkordb_int.py 也是按同样的标准断言的：请求/healthcheck后检查status_code == 200且响应体中status字段等于'healthy'。

两项都通过后，REST API 服务与 Neo4j 的连接配置就部署完成了。

边界与注意事项

• 版本示例差异：server/README.md 的 compose 示例使用neo4j:5.22.0，而根目录 docker-compose.yml 使用neo4j:5.26.2。两处文档没有说明选择规则，本文按 server/README.md 的5.22.0作为镜像部署主路径；如果你已有其他版本的 Neo4j（Cloud、桌面版），直接使用即可，只需保证 Bolt 连接信息正确。
• /healthcheck的语义：它表示 FastAPI 服务本身已启动并响应请求。它不代表 Neo4j 中已有数据，也不代表 LLM 调用可用——OPENAI_API_KEY无效时，/healthcheck依然可能返回 200，但/search、/messages等需要 LLM 和嵌入的接口会失败。
• 可选的后端：db_backend配置项支持falkorDB等后端（server/graph_service/config.py 中可见falkordb_host、falkordb_port等字段），但这超出了本文 Neo4j 部署的范围，此处只作说明。

下一步如果你准备实际写入数据，可以从/docs页面里的/messages（异步入队消息）、/search等接口开始按 OpenAPI 文档调用，并使用一个有效的OPENAI_API_KEY。

【免费下载链接】graphitiBuild Real-Time Knowledge Graphs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/grap/graphiti