跳转到主要内容

HugeGraph-Vermeer 快速上手

Vermeer 高性能内存图计算:一次启动、多次执行,支持 15+ OLAP 算法及秒到分钟级计算,涵盖部署、数据加载、PageRank 和社区发现。

一、Vermeer 概述

1.1 运行架构

Vermeer 是使用 Go 编写的高性能内存优先图计算框架,支持一次启动、多次执行,以及 15+ OLAP 图算法的极速计算,大部分算法可在秒到分钟级完成。实际耗时取决于图规模、算法参数和可用资源。当前由一个 master 调度,可连接多个 worker。

master 是负责通信、转发、汇总的节点,计算量和占用资源量较少。worker 是计算节点,用于存储图数据和运行计算任务,占用大量内存和 cpu。grpc 和 rest 模块分别负责内部通信和外部调用。

启动时,程序先设置内置默认值,再读取工作目录下 config/<env>.ini 的 [default] 节,最后由显式命令行参数覆盖对应配置;例如 --env=master 读取 config/master.ini。Docker 镜像把仓库中的配置复制到 /go/bin/config/,并以 /go/bin/ 为工作目录。挂载宿主机目录到 /go/bin/config 会遮住镜像自带文件,因此该目录必须包含实际使用的 ini 文件。普通 INI 配置键不会自动映射环境变量。部署专用凭据设置还支持 VERMEER_PD_PASSWORD_FILE、VERMEER_PD_PEERS、VERMEER_HUGEGRAPH_CREDENTIALS_FILE 及文档中的签名因子/密码文件设置。

默认端口如下:

角色配置键默认地址用途
masterhttp_peer0.0.0.0:6688REST API;宿主机客户端访问此端口
mastergrpc_peer0.0.0.0:6689worker 连接 master 的 gRPC 端口
workerhttp_peer0.0.0.0:6788worker HTTP 服务
workergrpc_peer0.0.0.0:6789worker gRPC 监听地址,同时会通告给 master 供节点间通信

Docker 示例只把 master 的 HTTP 端口发布到宿主机回环地址 127.0.0.1:6688:6688;master 和 worker 的 gRPC 端口留在容器网络内部。

flowchart LR
  Client["curl / Python 客户端"] -->|"HTTP :6688"| Master["master"]
  Worker["worker"] <-->|"双向 gRPC:master :6689,worker :6789"| Master
  Master -->|"gRPC 查询分区"| PD["HugeGraph PD"]
  Worker -->|"gRPC 扫描分区"| Store["HugeGraph Store"]

1.2 运行方法

Helm:与 HugeGraph、Hubble 一起部署 Vermeer

HugeGraph Helm Chart 支持一键拉起原生 Vermeer 内存图计算引擎,默认保持关闭。 在 HugeGraph 仓库根目录下,开启 Vermeer 并启动:

1helm install hugegraph ./helm/hugegraph -n hugegraph --create-namespace \
2  -f helm/hugegraph/values-single.yaml \
3  --set vermeer.enabled=true --set vermeer.mode=standalone \
4  --wait --timeout 20m

Vermeer 核心文件与配置结构

  • helm/hugegraph/
    • examples/
      • values-vermeer-standalone.yaml单机预设(单个 Pod 同时运行 Master 与 Worker 容器)
      • values-vermeer-cluster.yaml集群预设(独立 Master Pod + 多 Worker Pods 分布式计算)
    • templates/
      • vermeer-master.yamlMaster 调度节点编排
      • vermeer-worker.yamlWorker 内存计算节点编排
      • vermeer-auth-secret.yaml管理员密码与 Hubble 内部调用服务令牌
    • docs/
      • vermeer.mdVermeer 算法调用、参数映射与运维指引

架构与运行模式:

  • 单机模式(standalone):Master 与 Worker 运行在同一个 Pod 中,开销小,适合小规模图计算测试。
  • 集群模式(cluster):设 vermeer.mode=cluster 与 vermeer.worker.replicas=3,提供独立的 Master 协调节点与多个分布式 Worker 计算节点。
  • 图服务协同:Master 通过 gRPC 向 PD 查询分区信息,Worker 直连 Store 扫描图数据切片;Hubble 会自动注入 Master 地址与通信令牌,在可视化界面中一键加载图并执行 15+ 种图算法。

核心注意事项:

  1. 保持元数据命名空间一致:保留 Chart 默认的 metadataCluster: hg-test。该值统一了 Server 的 HG_SERVER_CLUSTER 与 Store 的 PD_CLUSTER,确保 Schema 正确读取;切勿随意修改该值,以免计算加载时报 Schema missing。
  2. 访问原生 Web 控制台:easy 模式通过 <release>-vermeer-master Service 分配的 HTTP NodePort, 打开 http://<可达节点IP>:<NodePort>/;strict 默认 ClusterIP,可用 kubectl -n hugegraph port-forward svc/<release>-vermeer-master 6688:6688 在本机访问。 vermeer.service.type: null 继承模式默认值,显式 ClusterIP 保持私有,显式 NodePort 则开放需要登录的 HTTP/UI。 内部 Master/Worker RPC 与 Worker HTTP 仍保持私有;standalone / cluster 不改变上述访问选择。 在 Admin credential 处填入 <release>-vermeer-admin Secret 的 password(无需用户名),登录后获得 24 小时会话。 新密码在 easy 下为 6 位随机字母数字,strict 下为 16 位;升级与模式切换保留既有凭据。
  3. 详细镜像固定策略、持久卷配置及运维命令可参考 Helm 可选引擎指南 与 Vermeer 部署指南。
警告

生产环境必须启用 HugeGraph Server 认证与授权、IP 白名单和最小权限授权,并保留 audit-*.log 审计记录。Server Auth 不会保护 Vermeer、PD 和 Store 的独立接口;这些 HTTP、gRPC 端口必须限制在可信网络及调用方范围内,Vermeer 对外入口需配置访问控制。

独立手动部署时,默认 master.ini 配置为 auth=none,下方 Docker 示例仅发布至回环地址;若需远程访问,务必在配置文件中启用 auth=token。Helm 部署在两种模式下均要求 Token 鉴权,easy 默认仅通过 NodePort 开放原生 HTTP/UI。

下面两种 Docker 启动方式都需要先准备一个宿主机配置目录。请在 Vermeer 仓库根目录执行,将项目提供的 master.ini 和 worker.ini 模板复制到该目录;挂载会覆盖镜像里的 /go/bin/config,所以不要把空目录或整个用户主目录挂进去:

1CONFIG_DIR="$HOME/vermeer-config"
2mkdir -p "$CONFIG_DIR"
3cp config/master.ini config/worker.ini "$CONFIG_DIR/"

master.ini 保留 HTTP/gRPC 监听地址 0.0.0.0:6688 和 0.0.0.0:6689。Compose 示例为网络分配固定地址 172.20.0.10(master)和 172.20.0.11(worker),因此将复制后的 worker.ini 中这些配置设为:

1[default]
2http_peer=0.0.0.0:6788
3grpc_peer=172.20.0.11:6789
4master_peer=172.20.0.10:6689
5run_mode=worker
6worker_group=$

此单 worker 示例将 worker_group 设为 $,表示未绑定命名组时使用的通用组;请在 ini 文件中原样写入美元符号。仓库模板默认是 worker_group=default,若保留命名组,需先将它绑定到任务所在的空间或图,再提交任务。例如默认空间为 $DEFAULT 时,可执行:

1curl --fail --show-error -X POST \
2  'http://localhost:6688/admin/workers/alloc/default/%24DEFAULT'

该接口响应 errcode=0 表示绑定成功;启用 token 鉴权时还需带上授权请求头。master_peer 必须指向 worker 所在网络能访问的 master gRPC 地址。grpc_peer 同时用于 worker 监听和向 master 通告自己的地址,不能设为不可从其他容器访问的 0.0.0.0。如果更改网络子网或地址,需同步修改此处的 IP;多个 worker 还需要各自唯一且可互相访问的 grpc_peer 地址。

  1. 方案一:Docker Compose(推荐)

在 Vermeer 仓库根目录运行。可以修改仓库已有的 docker-compose.yaml,也可以使用下面的配置。仓库文件当前将整个 ~/ 挂载到配置目录且没有发布 master HTTP 端口,运行前必须按示例更换挂载路径并增加端口映射:

 1services:
 2  vermeer-master:
 3    image: hugegraph/vermeer
 4    container_name: vermeer-master
 5    ports:
 6      - "127.0.0.1:6688:6688"
 7    volumes:
 8      - /home/user/vermeer-config:/go/bin/config:ro
 9    command: --env=master
10    networks:
11      vermeer_network:
12        ipv4_address: 172.20.0.10 # master 固定地址
13
14  vermeer-worker:
15    image: hugegraph/vermeer
16    container_name: vermeer-worker
17    volumes:
18      - /home/user/vermeer-config:/go/bin/config:ro
19    command: --env=worker
20    networks:
21      vermeer_network:
22        ipv4_address: 172.20.0.11 # worker 固定地址
23
24networks:
25  vermeer_network:
26    driver: bridge
27    ipam:
28      config:
29        - subnet: 172.20.0.0/24 # 按需更换子网

把 /home/user/vermeer-config 换成上面实际的配置目录绝对路径。若修改 vermeer_network 的子网或固定 IP,也要同步更新 worker.ini 中的 grpc_peer 和 master_peer。不要复用默认 worker.ini 的 grpc_peer=0.0.0.0:6789 作为容器间通告地址。

在项目目录构建镜像并启动:

1# 构建镜像(在项目根 vermeer 目录)
2docker build -t hugegraph/vermeer .
3
4# 启动(在 vermeer 根目录)
5docker-compose up -d
6# 或使用新版 CLI:
7# docker compose up -d

查看日志 / 停止 / 删除:

1docker-compose logs -f
2docker-compose down
  1. 方案二:通过 docker run 单独启动(手动创建网络并分配静态 IP)

将 CONFIG_DIR 设为上面准备的配置目录,并确保复制后的 worker.ini 已按固定容器地址设置 grpc_peer 和 master_peer。该示例中的 CONFIG_DIR 需替换为实际的绝对路径。

构建镜像:

1docker build -t hugegraph/vermeer .

创建自定义 bridge 网络(一次性操作):

1docker network create --driver bridge \
2  --subnet 172.20.0.0/24 \
3  vermeer_network

运行 master(调整 CONFIG_DIR 为您的绝对配置路径,可以根据实际情况调整IP):

1CONFIG_DIR=/home/user/vermeer-config
2
3docker run -d \
4  --name vermeer-master \
5  --network vermeer_network --ip 172.20.0.10 \
6  -p 127.0.0.1:6688:6688 \
7  -v ${CONFIG_DIR}:/go/bin/config:ro \
8  hugegraph/vermeer \
9  --env=master

运行 worker:

1docker run -d \
2  --name vermeer-worker \
3  --network vermeer_network --ip 172.20.0.11 \
4  -v ${CONFIG_DIR}:/go/bin/config:ro \
5  hugegraph/vermeer \
6  --env=worker

查看日志 / 停止 / 删除:

1docker logs -f vermeer-master
2docker logs -f vermeer-worker
3
4docker stop vermeer-master vermeer-worker
5docker rm vermeer-master vermeer-worker
6
7# 删除自定义网络(如果需要)
8docker network rm vermeer_network
  1. 方案三:从源码构建

构建。具体请参照 Vermeer Readme。

1go build

从 Vermeer 仓库根目录启动,例如 ./vermeer --env=master 和 ./vermeer --env=worker01。worker01.ini 中的 grpc_peer 应填写可由 master 和其他 worker 访问、且本机可以绑定的地址;master_peer 指向 master 的 gRPC 监听地址。

启动 master 后,在宿主机验证 HTTP 端口:

1curl --fail --show-error http://localhost:6688/graphs

请求应返回 HTTP 200,JSON 响应中的 errcode 为 0。

1.3 身份认证、Token 工具与部署凭据

当在 master.ini 中启用 auth=token(或命令行参数 -auth token)时,应将 Master 签名因子保存在受保护的独立文件(0600 权限)中, 而非放置在启动参数内。基于文件的认证机制采用 v2 HMAC-SHA256 Base58 编码 token,具备恒定时间 MAC 校验能力,防止降级为不安全的旧协议。

1. 生成基于文件的签名因子

启动 Master 前先生成签名因子文件:

1umask 077
2openssl rand -hex 32 > config/token-factor

配置环境变量 VERMEER_AUTH_TOKEN_FACTOR_FILE=/path/to/token-factor,或在 master.ini 中设置 auth_token_factor_file。环境变量优先级高于 INI 文件, 两者均高于行内 auth_token_factor。文件必须为有效的 UTF-8 编码且至少包含 16 个有效字符,不可全为空白字符。配置无效或不可读的文件会导致 Master 在监听网络端口前直接退出(Fail-Closed),绝不会静默回退至行内或默认签名因子。

2. 使用 /go/bin/vermeer-token 生成认证 Token

Vermeer 运行时容器镜像已内置打包 /go/bin/vermeer-token CLI 工具(源自 cmd/vermeer-token)。该工具无需运行 Master 或访问 Kubernetes API, 即可直接生成合法的 v2 Base58 token:

Docker 命令
1docker run --rm --user "$(id -u):$(id -g)" -v "$PWD/config:/tokens" \
2  --entrypoint /go/bin/vermeer-token \
3  hugegraph/vermeer:latest -user admin -space '$DEFAULT' \
4  -factor-file /tokens/token-factor -output-file /tokens/admin-token -i -quiet
Go 源码
1go run ./cmd/vermeer-token -user admin -space '$DEFAULT' \
2  -factor-file config/token-factor -output-file config/admin-token -i -quiet

参数说明:

  • -user:用户名(默认:foo)。
  • -space:图空间名称(默认:bar;系统默认空间填写 $DEFAULT)。
  • -factor-file:签名因子文件路径(必填;不再接受行内 -factor)。
  • -output-file:以 0600 权限将 Base58 token 原子写入指定文件,不会向标准输出打印密钥。
  • -quiet:在未指定 -output-file 时仅输出 token 字符串,方便脚本捕获。
  • -client:客户端标识(默认:hg)。
  • -i:生成永不过期的永久 token(普通 token 默认 24 小时过期)。

调用 REST 接口时,将 token 填入 HTTP 请求头:

1curl -H "Authorization: Bearer <token>" http://localhost:6688/graphs

3. Kubernetes Secret 密码文件与凭据隔离

为了方便直接挂载 Kubernetes Secret 原始密码文件而无需封装为 JSON,Worker 支持通过密码文件注入连接凭据:

  • 配置 VERMEER_HUGEGRAPH_USERNAME 与 VERMEER_HUGEGRAPH_PASSWORD_FILE(或在 worker.ini 中配置 hugegraph_username 与 hugegraph_password_file)。 两项配置必须成对提供;若任一项配置后文件缺失或不可读,数据加载将直接失败。
  • 密码文件内容被原样读取,完整保留引号、反斜杠、空格及末尾换行符。
  • 若同时配置了显式 JSON 凭据文件(VERMEER_HUGEGRAPH_CREDENTIALS_FILE 或 hugegraph_credentials_file),JSON 文件拥有更高优先级。
  • PD 认证凭据:支持挂载 VERMEER_PD_PASSWORD_FILE(或 pd_password_file)。使用部署凭据时,必须同时配置 VERMEER_PD_PEERS(pd_peers), 确保 Worker 仅通过受信任的 PD 节点发现 Schema。
  • 部署凭据仅在进程内部加载时使用,绝不会持久化至任务元数据中,也不会通过查询接口泄露。
  • 可通过 grpc_dial_timeout 或 VERMEER_GRPC_DIAL_TIMEOUT(默认 5s)设定 Worker 建立 gRPC 连接的超时阈值。

二、任务创建类 rest api

2.1 简介

创建任务的流程是先提交 load 任务,等待图加载完成,再提交 compute 任务。同一张已加载的图可重复用于计算,不会因任务完成而自动删除。异步接口返回创建结果和任务信息(包括任务 ID),不代表任务已经完成;同步接口会一直等待任务进入成功或失败状态,调用方及代理的 HTTP 超时需足够长。任务状态可通过查询接口读取:加载成功为 loaded,计算成功为 complete,失败为 error,取消为 canceled,其余状态仍在等待或执行中。图在加载中或错误状态时不能用于计算;删除图要求图处于可删除状态且当前未被使用。

可以使用的 url 如下:

  • 异步接口:POST http://master_ip:port/tasks/create,从响应的 task.id 取得任务 ID。
  • 同步接口:POST http://master_ip:port/tasks/create/sync,等待该任务结束后返回。
  • 查询单个任务:GET http://master_ip:port/task/{task_id};响应中的 errcode 为 0 表示查询成功,再按 task.state 判断业务状态。异步任务应在客户端设置轮询截止时间;到时只停止客户端等待,不会自动取消服务端任务。
  • 查询保留结果:GET http://master_ip:port/tasks/value/{task_id}(或 /api/v1/tasks/value/{id})。
  • 集群健康与遥测快照:GET http://master_ip:port/api/v1/admin/cluster(需管理员 token;参见第四节)。
  • 图空间计算可用性探针:GET http://master_ip:port/api/v1/workers/availability(图空间粒度就绪检测)。

原生客户端使用 POST /api/v1/tasks/create,请求包含 graph、task_type(load、reload 或 compute)及扁平的字符串 params 映射。 计算算法名填写 params["compute.algorithm"],不是顶层 algorithm。 响应中的原生 task.id 通过 GET /api/v1/task/{id} 查询状态,通过 GET /api/v1/tasks/value/{id} 查询保留结果。 POST /api/v1/tasks 不提交任务:修复后返回 HTTP 405 和 Allow: GET;旧构建可能返回误导性的 {"code":200},但实际并未创建任务。 详见 原生 API 示例。

Vermeer Master HTTP 遵循 Helm 模式默认值:easy 为 NodePort,strict 为 ClusterIP;RPC 与 Worker 端口保持内部访问。 原生 UI 管理员使用 <release>-vermeer-admin 中的密码。自动化 API 使用服务 token,放入 Authorization: Bearer <token>, UI 管理密码不能当作该 token。Chart 会自动为 Hubble 配置服务 token。

2.2 加载图数据

以下示例列出常用的加载参数;引擎会按具体加载器读取参数,未被加载器使用的键不会改变行为。

vermeer提供三种加载方式:

  1. 从本地加载

load.vertex_files 和 load.edge_files 是“worker 地址主机部分到文件路径”的映射;路径由对应 worker 进程读取。容器部署时,数据文件必须先挂载进 worker 容器,并填写容器内路径。在上面的 Compose 示例中,应将主机数据目录挂到 worker 的 /data(例如增加 - /host/data:/data:ro),并把映射键设为 grpc_peer 中的 172.20.0.11;其他部署则使用各自 worker 上报地址的主机部分。

可以预先获取数据集,例如 twitter-2010 数据集。获取方式:https://snap.stanford.edu/data/twitter-2010.html,第一个 twitter-2010.txt.gz 即可。

request 示例:

 1POST http://localhost:6688/tasks/create
 2{
 3 "task_type": "load",
 4 "graph": "testdb",
 5 "params": {
 6  "load.parallel": "50",
 7  "load.type": "local",
 8  "load.vertex_files": "{\"172.20.0.11\":\"/data/twitter-2010.v_[0,99]\"}",
 9  "load.edge_files": "{\"172.20.0.11\":\"/data/twitter-2010.e_[0,99]\"}",
10  "load.use_out_degree": "1",
11  "load.use_outedge": "1"
12 }
13}
  1. 从hugegraph加载

request 示例:

将请求中的地址、图名和凭据替换为实际连接信息。

 1POST http://localhost:6688/tasks/create
 2{
 3  "task_type": "load",
 4  "graph": "testdb",
 5  "params": {
 6    "load.parallel": "50",
 7    "load.type": "hugegraph",
 8    "load.hg_pd_peers": "[\"<pd-address-reachable-from-vermeer>:8686\"]",
 9    "load.hugegraph_name": "DEFAULT/hugegraph2/g",
10    "load.hugegraph_username": "admin",
11    "load.hugegraph_password": "<your-password-here>",
12    "load.use_out_degree": "1",
13    "load.use_outedge": "1"
14  }
15}

Vermeer master 使用 load.hg_pd_peers 连接 PD 并查询分区,worker 再连接 PD 返回的 Store 地址读取数据。因此这些服务地址必须能从对应的 Vermeer 容器或主机访问;在 Docker 容器里,127.0.0.1 指向容器自身,不能用来代替宿主机或另一容器的地址。

  1. 从hdfs加载

request 示例:

 1POST http://localhost:6688/tasks/create
 2{
 3  "task_type": "load",
 4  "graph": "testdb",
 5  "params": {
 6    "load.parallel": "50",
 7    "load.type": "hdfs",
 8    "load.hdfs_namenode": "name_node1:9000",
 9    "load.hdfs_conf_path": "/path/to/conf",
10    "load.krb_realm": "EXAMPLE.COM",
11    "load.krb_name": "user@EXAMPLE.COM",
12    "load.krb_keytab_path": "/path/to/keytab",
13    "load.krb_conf_path": "/path/to/krb5.conf",
14    "load.hdfs_use_krb": "1",
15    "load.vertex_files": "/data/graph/vertices",
16    "load.edge_files": "/data/graph/edges",
17    "load.use_out_degree": "1",
18    "load.use_outedge": "1"
19  }
20}

2.3 输出计算结果

当前有实际写入器的结果方式为 local、hdfs 和 hugegraph,通过 output.type 指定;none 表示不写出结果。源码保留 afs 类型常量,但当前主线没有注册 AFS 加载器或写入器。指定 output.need_statistics 为 1 时,统计结果会写入任务信息;统计算子的适用范围取决于对应算法实现。

以下示例列出常用的计算和结果输出参数;算法支持的参数以 Vermeer 当前实现为准。

request 示例:

 1POST http://localhost:6688/tasks/create
 2{
 3 "task_type": "compute",
 4 "graph": "testdb",
 5 "params": {
 6 "compute.algorithm": "pagerank",
 7 "compute.parallel": "10",
 8 "compute.max_step": "10",
 9 "output.type": "local",
10 "output.parallel": "1",
11 "output.file_path": "result/pagerank"
12  }
13}

output.type=local 的结果写在执行任务的 worker 本地文件系统中;容器部署时,如需从宿主机读取结果,请将 worker 的输出目录挂载出来。

2.4 通过 Hubble 提交与集成

使用 Chart 管理的原生集成时,POST /api/v1.3/vermeer/task 用于加载或重新加载图,不是计算接口。 该接口接收 graphspace、graph、task_type:"load" 与可选加载调优参数;等图加载完成后,再通过图级计算接口提交算法:

1curl -b hubble.cookies -X POST \
2  'http://localhost:8088/api/v1.3/graphspaces/DEFAULT/graphs/hugegraph/algorithms/vermeer' \
3  -H 'Content-Type: application/json' \
4  -d '{"params":{"compute.algorithm":"pagerank","compute.parallel":1,"compute.max_step":10,"pagerank.damping":0.85,"pagerank.diff_threshold":0.00001}}'

参数名与示例值来自当前 Hubble PageRank 表单:

参数含义示例
compute.algorithm支持的算法名pagerank
compute.parallel计算并行度1
compute.max_step最大迭代步数10
pagerank.dampingPageRank 阻尼系数0.85
pagerank.diff_threshold收敛阈值0.00001

当前 Hubble 接受 pagerank、wcc、lpa、degree、closeness_centrality、betweenness_centrality、triangle_count、kcore 与 sssp。 其他算法请使用对应表单中的参数,不能沿用 PageRank 的专属键。 直连适配器接受 compute.*、当前算法的 <algorithm>.* 与 output.need_statistics,具体参数值仍由 Vermeer 校验。 输出存储由 Hubble 管理,不能指定任意输出路径或传入 Server 凭据。

Hubble 响应封装的 data.task_id 是任务 ID,请保留正负号:原生 Vermeer 任务会映射为负数 ID。 使用同一图的 GET /api/v1.3/graphspaces/DEFAULT/graphs/hugegraph/async-tasks/{id} 查询状态; 成功后通过 GET .../async-tasks/{id}/values?cursor=0&limit=100 读取结果分页。 不要把 Hubble ID 直接传给 Server 原生 /tasks/{id}。 图状态 loaded 只表示加载成功。计算返回 HTTP 400 时,应结合被拒绝的完整请求与响应排查定位。

三、支持的算法

3.1 PageRank

PageRank 算法又称网页排名算法,是一种由搜索引擎根据网页(节点)之间相互的超链接进行计算的技

术,用来体现网页(节点)的相关性和重要性。

  • 如果一个网页被很多其他网页链接到,说明这个网页比较重要,也就是其 PageRank 值会相对较高。
  • 如果一个 PageRank 值很高的网页链接到其他网页,那么被链接到的网页的 PageRank 值会相应地提高。

PageRank 算法适用于网页排序、社交网络重点人物发掘等场景。

request 示例:

 1POST http://localhost:6688/tasks/create
 2{
 3 "task_type": "compute",
 4 "graph": "testdb",
 5 "params": {
 6 "compute.algorithm": "pagerank",
 7 "compute.parallel":"10",
 8 "output.type":"local",
 9 "output.parallel":"1",
10 "output.file_path":"result/pagerank",
11 "compute.max_step":"10"
12 }
13}

3.2 WCC(弱连通分量)

弱连通分量,计算无向图中所有联通的子图,输出各顶点所属的弱联通子图 id,表明各个点之间的连通性,区分不同的连通社区。

request 示例:

 1POST http://localhost:6688/tasks/create
 2{
 3 "task_type": "compute",
 4 "graph": "testdb",
 5 "params": {
 6 "compute.algorithm": "wcc",
 7 "compute.parallel":"10",
 8 "output.type":"local",
 9 "output.parallel":"1",
10 "output.file_path":"result/wcc",
11 "compute.max_step":"10"
12 }
13}

3.3 LPA(标签传播)

标签传递算法,是一种图聚类算法,常用在社交网络中,用于发现潜在的社区。

request 示例:

 1POST http://localhost:6688/tasks/create
 2{
 3 "task_type": "compute",
 4 "graph": "testdb",
 5 "params": {
 6 "compute.algorithm": "lpa",
 7 "compute.parallel":"10",
 8 "output.type":"local",
 9 "output.parallel":"1",
10 "output.file_path":"result/lpa",
11 "compute.max_step":"10"
12 }
13}

3.4 Degree Centrality(度中心性)

度中心性算法,算法用于计算图中每个节点的度中心性值,支持无向图和有向图。度中心性是衡量节点重要性的重要指标,节点与其它节点的边越多,则节点的度中心性值越大,节点在图中的重要性也就越高。在无向图中,度中心性的计算是基于边信息统计节点出现次数,得出节点的度中心性的值,在有向图中则基于边的方向进行筛选,基于输入边或输出边信息统计节点出现次数,得到节点的入度值或出度值。它表明各个点的重要性,一般越重要的点度数越高。

request 示例:

 1POST http://localhost:6688/tasks/create
 2{
 3 "task_type": "compute",
 4 "graph": "testdb",
 5 "params": {
 6 "compute.algorithm": "degree",
 7 "compute.parallel":"10",
 8 "output.type":"local",
 9 "output.parallel":"1",
10 "output.file_path":"result/degree",
11 "degree.direction":"both"
12 }
13}

3.5 Closeness Centrality(紧密中心性)

紧密中心性(Closeness Centrality)用于计算一个节点到所有其他可达节点的最短距离的倒数,进行累积后归一化的值。紧密中心度可以用来衡量信息从该节点传输到其他节点的时间长短。节点的“Closeness Centrality”越大,其在所在图中的位置越靠近中心,适用于社交网络中关键节点发掘等场景。

request 示例:

 1POST http://localhost:6688/tasks/create
 2{
 3 "task_type": "compute",
 4 "graph": "testdb",
 5 "params": {
 6 "compute.algorithm": "closeness_centrality",
 7 "compute.parallel":"10",
 8 "output.type":"local",
 9 "output.parallel":"1",
10 "output.file_path":"result/closeness_centrality",
11 "closeness_centrality.sample_rate":"0.01"
12 }
13}

3.6 Betweenness Centrality(中介中心性算法)

中介中心性算法(Betweeness Centrality)判断一个节点具有"桥梁"节点的值,值越大说明它作为图中两点间必经路径的可能性越大,典型的例子包括社交网络中的共同关注的人。适用于衡量社群围绕某个节点的聚集程度。

request 示例:

 1POST http://localhost:6688/tasks/create
 2{
 3 "task_type": "compute",
 4 "graph": "testdb",
 5 "params": {
 6 "compute.algorithm": "betweenness_centrality",
 7 "compute.parallel":"10",
 8 "output.type":"local",
 9 "output.parallel":"1",
10 "output.file_path":"result/betweenness_centrality",
11 "betweenness_centrality.sample_rate":"0.01"
12 }
13}

3.7 Triangle Count(三角形计数)

三角形计数算法,用于计算通过每个顶点的三角形个数,适用于计算用户之间的关系,关联性是不是成三角形。三角形越多,代表图中节点关联程度越高,组织关系越严密。社交网络中的三角形表示存在有凝聚力的社区,识别三角形有助于理解网络中个人或群体的聚类和相互联系。在金融网络或交易网络中,三角形的存在可能表示存在可疑或欺诈活动,三角形计数可以帮助识别可能需要进一步调查的交易模式。

输出的结果为 每个顶点对应一个 Triangle Count,即为每个顶点所在三角形的个数。

注:该算法为无向图算法,忽略边的方向。

request 示例:

 1POST http://localhost:6688/tasks/create
 2{
 3 "task_type": "compute",
 4 "graph": "testdb",
 5 "params": {
 6 "compute.algorithm": "triangle_count",
 7 "compute.parallel":"10",
 8 "output.type":"local",
 9 "output.parallel":"1",
10 "output.file_path":"result/triangle_count"
11 }
12}

3.8 K-Core

K-Core 算法,标记所有度数为 K 的顶点,适用于图的剪枝,查找图的核心部分。

request 示例:

 1POST http://localhost:6688/tasks/create
 2{
 3 "task_type": "compute",
 4 "graph": "testdb",
 5 "params": {
 6 "compute.algorithm": "kcore",
 7 "compute.parallel":"10",
 8 "output.type":"local",
 9 "output.parallel":"1",
10 "output.file_path":"result/kcore",
11 "kcore.degree_k":"5"
12 }
13}

3.9 SSSP(单元最短路径)

单源最短路径算法,求一个点到其他所有点的最短距离。

request 示例:

 1POST http://localhost:6688/tasks/create
 2{
 3 "task_type": "compute",
 4 "graph": "testdb",
 5 "params": {
 6 "compute.algorithm": "sssp",
 7 "compute.parallel":"10",
 8 "output.type":"local",
 9 "output.parallel":"1",
10 "output.file_path":"result/degree",
11 "sssp.source":"tom"
12 }
13}

3.10 KOUT

以一个点为起点,获取这个点的 k 层的节点。

request 示例:

 1POST http://localhost:6688/tasks/create
 2{
 3 "task_type": "compute",
 4 "graph": "testdb",
 5 "params": {
 6 "compute.algorithm": "kout",
 7 "compute.parallel":"10",
 8 "output.type":"local",
 9 "output.parallel":"1",
10 "output.file_path":"result/kout",
11 "kout.source":"tom",
12 "compute.max_step":"6"
13 }
14}

3.11 Louvain

Louvain 算法是一种基于模块度的社区发现算法。其基本思想是网络中节点尝试遍历所有邻居的社区标签,并选择最大化模块度增量的社区标签。在最大化模块度之后,每个社区看成一个新的节点,重复直到模块度不再增大。

Vermeer 上实现的分布式 Louvain 算法受节点顺序、并行计算等因素影响,并且由于 Louvain 算法由于其遍历顺序的随机导致社区压缩也具有一定的随机性,导致重复多次执行可能存在不同的结果。但整体趋势不会有大的变化。

request 示例:

 1POST http://localhost:6688/tasks/create
 2{
 3 "task_type": "compute",
 4 "graph": "testdb",
 5 "params": {
 6 "compute.algorithm": "louvain",
 7 "compute.parallel":"10",
 8 "compute.max_step":"1000",
 9 "louvain.threshold":"0.0000001",
10 "louvain.resolution":"1.0",
11 "louvain.step":"10",
12 "output.type":"local",
13 "output.parallel":"1",
14 "output.file_path":"result/louvain"
15  }
16 }

3.12 Jaccard 相似度系数

Jaccard index , 又称为 Jaccard 相似系数(Jaccard similarity coefficient)用于比较有限样本集之间的相似性与差异性。Jaccard 系数值越大,样本相似度越高。用于计算一个给定的源点,与图中其他所有点的 Jaccard 相似系数。

request 示例:

 1POST http://localhost:6688/tasks/create
 2{
 3 "task_type": "compute",
 4 "graph": "testdb",
 5 "params": {
 6 "compute.algorithm": "jaccard",
 7 "compute.parallel":"10",
 8 "compute.max_step":"2",
 9 "jaccard.source":"123",
10 "output.type":"local",
11 "output.parallel":"1",
12 "output.file_path":"result/jaccard"
13 }
14}

3.13 Personalized PageRank

个性化的 pagerank 的目标是要计算所有节点相对于用户 u 的相关度。从用户 u 对应的节点开始游走,每到一个节点都以 1-d 的概率停止游走并从 u 重新开始,或者以 d 的概率继续游走,从当前节点指向的节点中按照均匀分布随机选择一个节点往下游走。用于给定一个起点,计算此起点开始游走的个性化 pagerank 得分。适用于社交推荐等场景。

由于计算需要使用出度,需要在读取图时需要设置 load.use_out_degree 为 1。

request 示例:

 1POST http://localhost:6688/tasks/create
 2{
 3 "task_type": "compute",
 4 "graph": "testdb",
 5 "params": {
 6 "compute.algorithm": "ppr",
 7 "compute.parallel":"100",
 8 "compute.max_step":"10",
 9 "ppr.source":"123",
10 "ppr.damping":"0.85",
11 "ppr.diff_threshold":"0.00001",
12 "output.type":"local",
13 "output.parallel":"1",
14 "output.file_path":"result/ppr"
15 }
16}

3.14 全图 Kout

计算图的所有节点的k度邻居(不包含自己以及1~k-1度的邻居),由于全图kout算法内存膨胀比较厉害,目前k限制在1和2,另外,全局kout算法支持过滤功能( 参数如:“compute.filter”:“risk_level==1”),在计算第k度的是时候进行过滤条件的判断,符合过滤条件的进入最终结果集,算法最终输出是符合条件的邻居个数。

request 示例:

 1POST http://localhost:6688/tasks/create
 2{
 3 "task_type": "compute",
 4 "graph": "testdb",
 5 "params": {
 6 "compute.algorithm": "kout_all",
 7 "compute.parallel":"10",
 8 "output.type":"local",
 9 "output.parallel":"10",
10 "output.file_path":"result/kout",
11 "compute.max_step":"2",
12 "compute.filter":"risk_level==1"
13 }
14}

3.15 集聚系数 clustering coefficient

集聚系数表示一个图中节点聚集程度的系数。在现实的网络中,尤其是在特定的网络中,由于相对高密度连接点的关系,节点总是趋向于建立一组严密的组织关系。集聚系数算法(Cluster Coefficient)用于计算图中节点的聚集程度。本算法为局部集聚系数。局部集聚系数可以测量图中每一个结点附近的集聚程度。

request 示例:

 1POST http://localhost:6688/tasks/create
 2{
 3 "task_type": "compute",
 4 "graph": "testdb",
 5 "params": {
 6 "compute.algorithm": "clustering_coefficient",
 7 "compute.parallel":"100",
 8 "compute.max_step":"10",
 9 "output.type":"local",
10 "output.parallel":"1",
11 "output.file_path":"result/cc"
12 }
13}

3.16 SCC(强连通分量)

在有向图的数学理论中,如果一个图的每一个顶点都可从该图其他任意一点到达,则称该图是强连通的。在任意有向图中能够实现强连通的部分我们称其为强连通分量。它表明各个点之间的连通性,区分不同的连通社区。

 1POST http://localhost:6688/tasks/create
 2{
 3 "task_type": "compute",
 4 "graph": "testdb",
 5 "params": {
 6 "compute.algorithm": "scc",
 7 "compute.parallel":"10",
 8 "output.type":"local",
 9 "output.parallel":"1",
10 "output.file_path":"result/scc",
11 "compute.max_step":"200"
12 }
13}

四、集群监控与遥测(Cluster Monitoring & Telemetry)

Vermeer 提供了面向运维看板(如 Apache HugeGraph Hubble)和云原生编排系统(如 Kubernetes / Helm 探针)的专用 REST 接口。

4.1 集群健康与遥测快照(GET /api/v1/admin/cluster)

GET /api/v1/admin/cluster 返回只读、带版本号的集群运行状态快照(schema_version: 1)。在开启 auth=token 的部署中, 该接口需要管理员 token(Authorization: Bearer <admin-token>),并执行标准 /admin 鉴权过滤。

健康与就绪语义

  • 仅注册不代表就绪。Worker 必须已注册、连接 Master,并使 load、compute、superstep 三个任务流均就绪。
  • Master 未就绪、无 Worker 或存在未就绪 Worker 时,集群状态为 DEGRADED;聚合原因分别为 master_initializing / service_offline、no_workers 或 workers_not_ready。其余情况为 UP。
  • metric_status 是对象,包含 availability(AVAILABLE、UNAVAILABLE 或 UNSUPPORTED)、observed_at 与可选 reason。
  • Master 检查项为 http_ready、initialized、service_online;Worker 检查项为 registered、connection_ready 和三个 *_stream_ready 字段。
  • Worker 遥测在管理器锁外使用整批 800 ms 截止时间,不影响就绪判定。

请求与响应示例

1curl -H "Authorization: Bearer <admin-token>" \
2  http://localhost:6688/api/v1/admin/cluster
 1{
 2  "schema_version": 1,
 3  "observed_at": 1730419200000,
 4  "status": "UP",
 5  "registered_workers": 1,
 6  "ready_workers": 1,
 7  "master": {
 8    "id": "master", "name": "Vermeer Master", "role": "MASTER",
 9    "grpc_peer": "127.0.0.1:6689", "version": "1.8.0",
10    "launch_time": "2026-11-01T08:00:00Z", "status": "UP", "ready": true,
11    "checks": {"http_ready": true, "initialized": true, "service_online": true},
12    "metrics": {"cpu_cores": 0.15, "rss_bytes": 134217728, "sample_window_seconds": 10.0},
13    "metric_status": {"availability": "AVAILABLE", "observed_at": 1730419200000}
14  },
15  "workers": [{
16    "id": "worker-1", "name": "worker-1", "role": "WORKER", "group": "default",
17    "grpc_peer": "127.0.0.1:6789", "version": "1.8.0",
18    "launch_time": "2026-11-01T08:00:05Z", "status": "UP", "ready": true,
19    "checks": {"registered": true, "connection_ready": true, "load_stream_ready": true,
20      "compute_stream_ready": true, "superstep_stream_ready": true},
21    "metrics": {"cpu_cores": 1.42, "rss_bytes": 2147483648, "sample_window_seconds": 10.0},
22    "metric_status": {"availability": "AVAILABLE", "observed_at": 1730419200000}
23  }]
24}

4.2 图空间 Worker 可用性探针(GET /api/v1/workers/availability)

GET /api/v1/workers/availability 专为 Kubernetes 与 Helm 探针提供图空间粒度的计算可用性检测。

  • 请求方式:携带调用者凭据以确定目标图空间。
  • 响应格式:当目标图空间具备可用计算资源时返回 {"available": true},否则返回 {"available": false}。
  • 判定规则:当前空间可访问的 common、space 或 graph Worker 分组中必须至少包含一个 Worker,且该组内所有已注册 Worker 都必须通过全部就绪检查。 仅注册在其他空间分组的 Worker 不会计入当前空间的可用性。

🚧, 后续随时更新完善,欢迎随时提出建议和意见。