如何用 zepai/graphiti 容器镜像和 Neo4j 部署 Graphiti REST API 服务并验证 /docs 与 /healthcheck【免费下载链接】graphitiBuild Real-Time Knowledge Graphs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/grap/graphitiGraphiti 仓库的server/子目录实现了一个基于 FastAPI 的 REST API 服务官方会把它构建成zepai/graphiti容器镜像发布到 Docker Hubserver/README.md。这篇文章覆盖一个明确的任务在本地用 Docker Compose 拉起zepai/graphiti镜像和配套的 Neo4j 实例然后确认服务的 Swagger 文档页/docs和健康检查接口/healthcheck都能正常访问。开始前你的机器上需要安装 Docker 和 Docker Compose并且能提供一个 OpenAI API Key 和一组 Neo4j 账号密码。镜像与版本信息根据 server/README.md容器镜像的基本信息如下镜像zepai/graphiti可用 taglatest最新稳定版和具体版本号与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用于连接 Neo4jdb_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_URIbolt://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_URIbolt://neo4j:${NEO4J_PORT}访问 Neo4jneo4j是 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 PORT8000和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作为镜像部署主路径如果你已有其他版本的 Neo4jCloud、桌面版直接使用即可只需保证 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 如何用 zepai/graphiti 容器镜像和 Neo4j 部署 Graphiti REST API 服务并验证 /docs 与 /healthcheck？
如何用 zepai/graphiti 容器镜像和 Neo4j 部署 Graphiti REST API 服务并验证 /docs 与 /healthcheck【免费下载链接】graphitiBuild Real-Time Knowledge Graphs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/grap/graphitiGraphiti 仓库的server/子目录实现了一个基于 FastAPI 的 REST API 服务官方会把它构建成zepai/graphiti容器镜像发布到 Docker Hubserver/README.md。这篇文章覆盖一个明确的任务在本地用 Docker Compose 拉起zepai/graphiti镜像和配套的 Neo4j 实例然后确认服务的 Swagger 文档页/docs和健康检查接口/healthcheck都能正常访问。开始前你的机器上需要安装 Docker 和 Docker Compose并且能提供一个 OpenAI API Key 和一组 Neo4j 账号密码。镜像与版本信息根据 server/README.md容器镜像的基本信息如下镜像zepai/graphiti可用 taglatest最新稳定版和具体版本号与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用于连接 Neo4jdb_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_URIbolt://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_URIbolt://neo4j:${NEO4J_PORT}访问 Neo4jneo4j是 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 PORT8000和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作为镜像部署主路径如果你已有其他版本的 Neo4jCloud、桌面版直接使用即可只需保证 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考