如何为 PentAGI 启用 Graphiti 知识图谱：compose 启动、LLM 预设与 healthcheck 验证

如何为 PentAGI 启用 Graphiti 知识图谱：compose 启动、LLM 预设与 healthcheck 验证

【免费下载链接】pentagiFully autonomous AI Agents system capable of performing complex penetration testing tasks项目地址: https://gitcode.com/GitHub_Trending/pe/pentagi

Graphiti 是 PentAGI 的可选集成，处于 beta 状态且默认关闭。它基于 Neo4j 构建一个时序知识图谱，异步地从 agent 交互中提取实体、关系、证据和时间上下文，并向启用的 agent 暴露graphiti_search工具；它补充而不是替代 PentAGI 主用的 pgvector 记忆。本文针对已有 PentAGI 部署的运维者：在.env中开启集成、挂载 LLM 预设、用docker-compose-graphiti.yml启动 Neo4j + Graphiti 栈，并通过 healthcheck 接口确认整条链路可用。

适用前提：Docker Compose 环境，基础栈docker-compose.yml已能正常启动。启用前需要理解两点文档明确的边界：搜索默认按 flow 隔离（GRAPHITI_SEARCH_SCOPE=flowid），新提交的事件是异步摄入的，提交后需要一段时间才能被检索到。

准备：确认基础栈已创建 pentagi-network

docker-compose-graphiti.yml中的网络声明是外部网络：

networks: pentagi-network: driver: bridge external: true name: pentagi-network

基础栈docker-compose.yml负责创建pentagi-network，Graphiti 栈依赖它才能启动。手动安装时，必须先启动docker-compose.yml，再叠加 Graphiti 文件；安装器（installer）会自动处理这个顺序。如果启动时报pentagi-network不存在的错误，就是顺序反了。

第一步：配置 .env 开启集成

在 PentAGI 的.env中添加捆绑栈（bundled stack）所需的最小配置：

GRAPHITI_ENABLED=true GRAPHITI_TIMEOUT=30 GRAPHITI_URL=http://graphiti:8000 GRAPHITI_LLM_CLIENT_TYPE=openai # Reused by the Graphiti OpenAI preset OPEN_AI_KEY=你的OpenAI API Key OPEN_AI_SERVER_URL=https://api.openai.com/v1 # Bundled Neo4j NEO4J_USER=neo4j NEO4J_DATABASE=neo4j NEO4J_PASSWORD=替换为强密码 NEO4J_URI=bolt://neo4j:7687

要点：

• PentAGI 只有同时满足GRAPHITI_ENABLED=true且GRAPHITI_URL非空才会启用客户端。GRAPHITI_ENABLED=true配空 URL 得到的仍是禁用状态。
• GRAPHITI_URL=http://graphiti:8000是内置部署的端点；若接入外部 Graphiti 部署，则指向其 API，并不要启动docker-compose-graphiti.yml，provider、embeddings、图数据库都在外部服务上配置。
• NEO4J_DATABASE对 Community Edition 无效：Neo4j 社区版只支持默认数据库，不要配置需要企业版多数据库能力的数据库名。

第二步：获取 compose 文件并启动两个栈

手动安装时，从 master 分支获取可选的 compose 文件：

curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose-graphiti.yml docker compose -f docker-compose.yml -f docker-compose-graphiti.yml up -d

docker-compose-graphiti.yml定义了两个服务：neo4j（镜像neo4j:5.26.2，HTTP 7474 / Bolt 7687 均绑定127.0.0.1）和graphiti（镜像vxcontrol/graphiti:latest，API 8000 端口绑定127.0.0.1）。graphiti通过depends_on: neo4j: condition: service_healthy等待 Neo4j 健康后才启动，两个容器都带有 compose 级 healthcheck。

预设目录的挂载：

GRAPHITI_CONFIG_PATH=./graphiti GRAPHITI_CONFIG_DIR=llm_configs

安装器会把仓库中的 examples/graphiti 复制到安装目录旁作为./graphiti；开发时GRAPHITI_CONFIG_PATH可以直接指向./examples/graphiti。GRAPHITI_CONFIG_DIR=llm_configs用于激活挂载的预设。文档说明了一个兼容性细节：如果较旧的.env缺少GRAPHITI_CONFIG_DIR，新版 compose 文件会把空目录挂载到未使用的configs路径，而不是用空目录盖掉镜像内置的预设。

同理，安装器会把examples/neo4j（含conf/neo4j.conf、conf/apoc.conf和锁定版本的 APOC 插件 jar）复制到./neo4j，由NEO4J_DIR=./neo4j控制挂载；conf/与plugins/为只读挂载，目录缺失时栈仍可用 Neo4j 内置默认值（无 APOC）启动。

第三步：选择 LLM 预设

GRAPHITI_LLM_CLIENT_TYPE选择整个 Graphiti 部署唯一的预设；模型名和调用参数不是环境变量，而是放在graphiti/<provider>.yaml里。文档给出的预设对照：

仓库中随附的示例预设可直接参考：openai.yaml、gemini.yaml、custom.yaml、litellm.yaml。注意上表是 README 的对照值，而examples/graphiti/下当前的 YAML 示例里model字段是另一组名称（如 openai 示例用gpt-5.6-luna）；生效值以实际挂载的 YAML 文件为准，两处不一致时应核对实际文件。

每个预设文件必须包含与预设匹配的provider，以及MODEL_NAME和SMALL_MODEL_NAME两段映射。小模型用于 reranking 和轻量调用。支持的调用设置包括 temperature、token 上限、采样与惩罚参数、JSON mode、reasoning effort、verbosity、pricing 元数据以及 provider 专属extra_body。以 custom.yaml 为例：

provider: custom MODEL_NAME: model: Qwen/Qwen3.6-27B-FP8 temperature: 1.0 max_tokens: 32768 json: true extra_body: chat_template_kwargs: enable_thinking: false SMALL_MODEL_NAME: model: Qwen/Qwen3.6-27B-FP8 temperature: 1.0 max_tokens: 32768 json: true extra_body: chat_template_kwargs: enable_thinking: false

选择预设时的两条文档限制：

• LLM_CLIENT_TYPE=openai会拒绝本地/自定义模型前缀；OpenAI 兼容的本地服务应使用custom预设。
• gemini预设走的是 Graphiti 的 LiteLLM/OpenAI 兼容客户端路径；如果原生 Gemini 端点不提供所需的 OpenAI 兼容 API，需要把GEMINI_SERVER_URL指向一个兼容网关。

GRAPHITI_MODEL_NAME已废弃且被忽略，改模型请直接编辑生效的 YAML 预设并重启 Graphiti 容器。

可选分支——独立 embedding 端点。默认情况下 Graphiti 使用当前 LLM 预设的凭据及其默认 OpenAI embedding 模型。要显式使用 PentAGI 共享的 embedding 端点：

GRAPHITI_SEPARATE_EMBEDDING=true EMBEDDING_URL=https://embedding.example.com/v1 EMBEDDING_KEY=你的embedding API Key EMBEDDING_MODEL=openai/text-embedding-3-large

其中 URL 与 key 按你的实际端点替换。Graphiti 的 embedder 是 OpenAI 兼容的；EMBEDDING_PROVIDER只被 PentAGI 使用、不会传给 Graphiti，非 OpenAI 兼容的 embedding provider 无法直接共享。

第四步：healthcheck 与状态验证

启动后按以下命令检查服务健康、队列状态与日志：

docker compose -f docker-compose.yml -f docker-compose-graphiti.yml ps graphiti neo4j docker compose -f docker-compose.yml -f docker-compose-graphiti.yml logs -f graphiti curl -fsS http://localhost:8000/healthcheck curl -fsS http://localhost:8000/queue-size

• ps中两个容器都应为 running/healthy。compose 文件内置了检查：Neo4j 用wget -qO- http://127.0.0.1:7474，Graphiti 用curl -f http://127.0.0.1:8000/healthcheck，间隔分别为 1s 与 30s。
• curl http://localhost:8000/healthcheck对应 compose 中定义的 Graphiti healthcheck 端点；/queue-size报告 waiting、processing、active-group 与 dropped 计数。
• Neo4j Browser 在http://localhost:7474，Graphiti 的 OpenAPI UI 在http://localhost:8000/docs，两者都由默认 compose 绑定在 localhost。

PentAGI 侧的连接判定：启动时执行 3 次 health-check 尝试、2 秒退避。若全部失败，PentAGI 记录警告并带着 Graphiti 禁用状态继续运行。因此ps显示健康而 PentAGI 日志里出现 Graphiti 启动检查失败警告时，应检查GRAPHITI_URL可达性与启动顺序（Graphiti 栈需在 PentAGI 之前就绪，安装器保证这一点）。

常见失败与限制

文档列出的常见启动失败，可直接对照排查：

• 所选预设缺少 API key 或 base URL、缺少 YAML 文件、或 YAML 中provider不匹配，都会导致 Graphiti 容器启动验证失败。
• 无效的 retry、timeout 或 anchor 取值范围会导致启动失败，而不是被静默归一化。
• 在flowid搜索模式下，缺少 group ID 的请求会被拒绝；PentAGI 自动提供 flow 派生的 group ID，所以这条主要影响直接调用 API 的场景。
• 有界全量队列返回 HTTP 429，此时用/queue-size查看 dropped 计数。

使用上的限制与后续维护注意点：

• Graphiti 是 beta，应用内没有图谱浏览器；一个 provider 预设对整个 Graphiti 部署生效，不能按 PentAGI agent 或 flow 选择。
• Graphiti 的抽取、reranking 与 embedding 计费独立于主 flow 所用模型。
• 捆绑服务的 Graphiti HTTP API 没有认证层，默认 compose 将 API 与 Neo4j 绑定到127.0.0.1；对外暴露需通过网络控制与可信反向代理上的认证来防护。
• agent 与工具输出可能包含凭据和利用证据，Neo4j 数据、日志、dead letter 与备份要相应保护；GRAPHITI_COMBINED_DIAGNOSTIC_SAMPLES保持关闭，因为诊断样例可能带出凭据。
• 升级时.env、docker-compose-graphiti.yml、Graphiti 镜像和graphiti预设目录要一起更新——只拉新镜像会保留旧 compose 默认值，静默改变抽取行为。

验证完成后，Graphiti 即为启用的 agent 提供 flow 内检索：PentAGI 把 agent 响应、工具执行细节与 flow/task/subtask 上下文异步送入图谱。由于摄入是异步的，刚提交的事件不会立即可搜；用/queue-size观察积压是否收敛，用logs -f graphiti查看处理情况。需要显式关闭集成时，将GRAPHITI_ENABLED=false即可；Graphiti 不可用时 PentAGI 也会回退到主记忆与向量库继续工作。

【免费下载链接】pentagiFully autonomous AI Agents system capable of performing complex penetration testing tasks项目地址: https://gitcode.com/GitHub_Trending/pe/pentagi