hugegraph/vermeer

Vermeer - 高性能内存图计算平台

镜像概述和主要用途

Vermeer是一个高性能内存图计算平台，采用单二进制部署模式。它提供20多种图算法、自定义算法扩展功能，并能与HugeGraph无缝集成。该平台专为中大型图数据的快速迭代计算设计，支持主从架构实现横向扩展，可通过REST API和gRPC轻松与现有系统集成，并提供内置的Web UI仪表板用于监控和作业管理。

核心功能和特性

• 单二进制部署：零外部依赖，可在任何环境运行
• 内存计算性能：针对中大型图的快速迭代进行优化
• 主从架构：通过添加工作节点实现横向扩展
• REST API + gRPC：便于与现有系统集成
• Web UI仪表板：内置监控和作业管理功能
• 多数据源支持：HugeGraph、本地CSV、HDFS
• 20+图算法：生产级别的算法实现

架构

mermaid
graph TB
    subgraph Client["客户端层"]
        API[REST API客户端]
        UI[Web UI仪表板]
    end

    subgraph Master["主节点"]
        HTTP[HTTP服务器 :6688]
        GRPC_M[gRPC服务器 :6689]
        GM[图管理器]
        TM[任务管理器]
        WM[工作节点管理器]
        SCH[调度器]
    end

    subgraph Workers["工作节点"]
        W1[工作节点1 :6789]
        W2[工作节点2 :6789]
        W3[工作节点N :6789]
    end

    subgraph DataSources["数据源"]
        HG[(HugeGraph)]
        CSV[本地CSV]
        HDFS[HDFS]
    end

    API --> HTTP
    UI --> HTTP
    HTTP --> GM
    HTTP --> TM
    GRPC_M <--> W1
    GRPC_M <--> W2
    GRPC_M <--> W3

    W1 <--> HG
    W2 <--> HG
    W3 <--> HG
    W1 <--> CSV
    W1 <--> HDFS

    style Master fill:#e1f5fe
    style Workers fill:#fff3e0
    style DataSources fill:#f1f8e9

目录结构

vermeer/
├── main.go              # 单二进制入口点
├── Makefile             # 构建自动化
├── algorithms/          # 20+算法实现
│   ├── pagerank.go
│   ├── louvain.go
│   ├── sssp.go
│   └── ...
├── apps/
│   ├── master/          # 主服务
│   │   ├── services/    # HTTP处理器
│   │   ├── workers/     # 工作节点管理
|   |   ├── schedules/    # 任务调度策略
│   │   └── tasks/       # 任务调度
│   ├── compute/         # 工作节点计算逻辑
│   ├── graphio/         # 图I/O（HugeGraph、CSV、HDFS）
│   │   └── hugegraph.go # HugeGraph集成
│   ├── protos/          # gRPC定义
│   └── common/          # 工具类、日志、指标
├── config/              # 配置模板
│   ├── master.ini
│   └── worker.ini
├── tools/               # 二进制依赖（supervisord、protoc）
└── ui/                  # Web仪表板

使用场景和适用范围

• 中大型图数据的快速迭代计算
• 图算法分析（如PageRank、社区检测、路径查找等）
• 与HugeGraph集成的图数据处理流程
• 需要横向扩展的分布式图计算任务
• 自定义图算法的开发和部署

使用方法和配置说明

快速开始

选项1：Docker（推荐）

拉取镜像：

bash
docker pull hugegraph/vermeer:latest

创建专用配置目录（例如 ~/vermeer-config/），并在其中放置 master.ini 和 worker.ini 文件（参见配置部分）。

使用Docker运行：

bash
# 主节点
docker run -v ~/vermeer-config:/go/bin/config hugegraph/vermeer --env=master

# 工作节点
docker run -v ~/vermeer-config:/go/bin/config hugegraph/vermeer --env=worker

安全注意：仅挂载包含Vermeer配置文件的目录。避免挂载整个主目录以最小化安全风险。

Docker Compose

更新 ~/worker.ini 中的 master_peer 为 172.20.0.10:6689，并编辑 docker-compose.yml 以挂载配置目录：

yaml
    volumes:
      - ~/:/go/bin/config # 在此处更改为实际配置路径

bash
docker-compose up -d

选项2：二进制下载

bash
# 下载二进制文件（替换版本和平台）
wget https://github.com/apache/hugegraph-computer/releases/download/vX.X.X/vermeer-linux-amd64.tar.gz
tar -xzf vermeer-linux-amd64.tar.gz
cd vermeer

# 运行主节点和工作节点
./vermeer --env=master &
./vermeer --env=worker &

--env 参数指定 config/ 文件夹中的配置文件名（例如 master.ini、worker.ini）。

使用Shell脚本

在 vermeer.sh 中配置参数，然后：

bash
./vermeer.sh start master
./vermeer.sh start worker

选项3：从源码构建

前提条件

• Go 1.23或更高版本
• curl 和 unzip 工具（用于下载依赖）
• 网络连接（首次设置时需要）

构建步骤

推荐：使用Makefile：

bash
# 首次设置（下载supervisord和protoc二进制文件）
make init

# 为当前平台构建
make

# 或为特定平台构建
make build-linux-amd64
make build-linux-arm64

替代方案：使用构建脚本：

bash
# 自动检测平台
./build.sh

# 或指定架构
./build.sh amd64
./build.sh arm64

开发构建

用于Web UI热重载的开发模式：

bash
go build -tags=dev

清理构建产物

bash
make clean      # 移除二进制文件和生成的资源
make clean-all  # 同时移除下载的工具（supervisord、protoc）

配置

主节点配置（master.ini）

ini
[default]
# 主节点HTTP监听地址
http_peer = 0.0.0.0:6688

# 主节点gRPC监听地址
grpc_peer = 0.0.0.0:6689

# 主节点对等地址（工作节点引用）
master_peer = 127.0.0.1:6689

# 运行模式
run_mode = master

# 任务调度策略
task_strategy = 1

# 并行任务数量
task_parallel_num = 1

注意：HugeGraph连接详情（pd_peers、server、graph）在图加载API请求中提供，而非配置文件。详见HugeGraph集成部分。

工作节点配置（worker.ini）

ini
[default]
# 工作节点HTTP监听地址
http_peer = 0.0.0.0:6788

# 工作节点gRPC监听地址
grpc_peer = 0.0.0.0:6789

# 要连接的主节点gRPC地址
master_peer = 127.0.0.1:6689

# 运行模式
run_mode = worker

# 工作节点组标识符
worker_group = default

可用算法

API概述

Vermeer在端口 6688（可在 master.ini 中配置）上公开REST API。

主要端点

示例：运行PageRank

bash
# 1. 从HugeGraph加载图
curl -X POST http://localhost:6688/api/v1/graphs \
  -H "Content-Type: application/json" \
  -d '{
    "graph_name": "my_graph",
    "load_type": "hugegraph",
    "hugegraph": {
      "pd_peers": ["127.0.0.1:8686"],
      "graph_name": "hugegraph"
    }
  }'

# 2. 运行PageRank
curl -X POST http://localhost:6688/api/v1/compute \
  -H "Content-Type: application/json" \
  -d '{
    "graph_name": "my_graph",
    "algorithm": "pagerank",
    "params": {
      "max_iterations": 20,
      "damping_factor": 0.85
    },
    "output": {
      "type": "hugegraph",
      "property_name": "pagerank_value"
    }
  }'

# 3. 检查任务状态
curl http://localhost:6688/api/v1/tasks/{task_id}

OLAP与OLTP模式

• OLAP模式：将整个图加载到内存中，运行多个算法
• OLTP模式：查询驱动，按需加载子图（计划功能）

数据源

HugeGraph集成

Vermeer通过以下方式与HugeGraph集成：

1. 元数据查询：通过gRPC查询HugeGraph PD（元数据服务）获取分区信息
2. 数据加载：通过gRPC（ScanPartition）从HugeGraph Store流式传输顶点/边
3. 结果写入：通过HugeGraph REST API将计算结果写回（添加顶点属性）

图加载请求中的配置：

json
{
  "load_type": "hugegraph",
  "hugegraph": {
    "pd_peers": ["127.0.0.1:8686"],
    "graph_name": "hugegraph",
    "vertex_label": "person",
    "edge_label": "knows"
  }
}

本地CSV文件

从本地CSV文件加载图：

json
{
  "load_type": "csv",
  "csv": {
    "vertex_file": "/path/to/vertices.csv",
    "edge_file": "/path/to/edges.csv",
    "delimiter": ","
  }
}

HDFS

从Hadoop分布式文件系统加载：

json
{
  "load_type": "hdfs",
  "hdfs": {
    "namenode": "hdfs://namenode:9000",
    "vertex_path": "/graph/vertices",
    "edge_path": "/graph/edges"
  }
}

开发自定义算法

自定义算法需实现 algorithms/algorithms.go 中的 Algorithm 接口：

注意：以下是简化的概念性接口，用于说明。实际算法实现需参见 apps/compute/api.go 中定义的 WorkerComputer 和 MasterComputer 接口。

go
type Algorithm interface {
    // 初始化算法
    Init(params map[string]interface{}) error

    // 为顶点计算一次迭代
    Compute(vertex *Vertex, messages []Message) (halt bool, outMessages []Message)

    // 聚合全局状态（可选）
    Aggregate() interface{}

    // 检查终止条件
    Terminate(iteration int) bool
}

示例：简单度计数

注意：这是简化的概念示例。实际算法必须实现 WorkerComputer 接口。详见 vermeer/algorithms/degree.go 获取工作示例。

go
package algorithms

type DegreeCount struct {
    maxIter int
}

func (dc *DegreeCount) Init(params map[string]interface{}) error {
    dc.maxIter = params["max_iterations"].(int)
    return nil
}

func (dc *DegreeCount) Compute(vertex *Vertex, messages []Message) (bool, []Message) {
    // 将度存储为顶点值
    vertex.SetValue(float64(len(vertex.OutEdges)))

    // 第一次迭代后停止
    return true, nil
}

func (dc *DegreeCount) Terminate(iteration int) bool {
    return iteration >= dc.maxIter
}

在 algorithms/algorithms.go 中注册算法：

go
func init() {
    RegisterAlgorithm("degree_count", &DegreeCount{})
}

内存管理

Vermeer采用内存优先的方法：

1. 图加载：顶点和边分布在工作节点上并存储在内存中
2. 自动分区：主节点根据容量将分区分配给工作节点
3. 内存监控：工作节点向主节点报告内存使用情况
4. 优雅降级：如果内存不足，算法可能失败（磁盘溢出尚未实现）

最佳实践：确保工作节点总内存超过图大小2-3倍，以提供算法工作空间。

Supervisord集成

将Vermeer作为守护进程运行，支持自动重启和日志轮转：

bash
# 配置位于 config/supervisor.conf
./tools/supervisord -c config/supervisor.conf -d

示例supervisor配置：

ini
[program:vermeer-master]
command=/path/to/vermeer --env=master
autostart=true
autorestart=true
stdout_logfile=/var/log/vermeer-master.log

Protobuf开发

如果修改 .proto 文件，需重新生成Go代码：

bash
# 安装protobuf Go插件
go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.28.0
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.2.0

# 生成（根据平台调整protoc路径）
vermeer/tools/protoc/linux64/protoc vermeer/apps/protos/*.proto --go-grpc_out=vermeer/apps/protos/. --go_out=vermeer/apps/protos/. # 请注意移除任何许可证头

性能调优

主节点配置

• task_parallel_num：并行任务数量（默认：1）。增加此值可提高任务调度吞吐量。

算法特定调优

• PageRank：使用 damping_factor=0.85、tolerance=0.0001 以加快收敛
• Louvain：仅在边权重有意义时启用 weighted=true
• SSSP