阿里巴巴推出的一站式大规模图计算系统

🎉 请查看我们正在推进的 GraphScope Flex：一款受乐高启发、模块化且用户友好的 GraphScope 升级版本。🎉

GraphScope 是一个统一的分布式图计算平台，通过友好的 Python 接口，在计算机集群上提供一站式环境，用于执行各种图操作。GraphScope 将阿里巴巴的多项关键技术相结合，使得在计算集群上对大规模图数据进行多阶段处理变得简单易行：其中包括用于分析、交互式查询和图神经网络（GNN）计算的 GRAPE、MaxGraph 和 Graph-Learn（GL），以及提供高效内存间数据传输的存储系统 Vineyard。

访问我们的官网 graphscope.io，了解更多详情。

最新消息

• [2025年4月21日] 🏆 GraphScope 使用声明式查询语言 CYPHER，在 LDBC 社交网络基准交互式工作负载 上取得了突破性成果，SF300 规模下的吞吐量比此前的纪录保持者高出 2.0 倍！🏆
• [2024年7月31日] 🎢 我们上线了一个可视化页面，展示了 GraphScope 在图计算领域的演进历程。立即查看！
• [2024年5月30日] 🏅 LDBC 宣布，GraphScope Flex 创下了新的 [SNB Interactive 审计结果] 纪录，相关消息已在 X（Twitter） 上发布！
• [2024年3月25日] 🙌🏻 我们将图文件格式 GraphAr 捐赠给 Apache 软件基金会，作为孵化项目。
• [2024年2月5日] 🎉 GraphScope Flex 的论文 (arXiv.org) 已被 SIGMOD 2024 行业赛道收录。智利见！
• [2023年12月19日] 📑 介绍 GraphScope Flex 的论文已在 arXiv.org 上发布。
• [2023年7月20日] 🏆 GraphScope 在 LDBC 社交网络基准交互式工作负载 上再次刷新纪录，SF300 规模下的吞吐量比之前的纪录保持者高出 2.45 倍！🏆
• [2023年7月4日] 🚀 GraphScope Flex 技术预览版随 v0.23.0 一同发布。

目录

• 快速入门
  • 单机模式安装
• 示例：引用网络上的节点分类
  • 加载图
  • 交互式查询
  • 图数据分析
  • 图神经网络（GNNs）
• Kubernetes 集群上的图处理
  • 创建会话
  • 加载图与图计算任务
  • 关闭会话
• 开发
  • 本地构建
  • 构建 Docker 镜像
  • 构建客户端库
  • 测试
• 文档
• 许可证
• 出版物
• 加入我们的社区！

快速入门

我们提供一个托管的 JupyterLab 环境 Playground。您可以在浏览器中直接体验 GraphScope！

GraphScope 支持单机模式运行，也支持在由 Kubernetes 管理的容器集群上运行。为了快速上手，我们先从单机模式开始吧。

单机模式安装

GraphScope 的预编译包以 Python 包的形式分发，可以使用 pip 轻松安装。

pip3 install graphscope

请注意，graphscope 需要 Python >= 3.8 以及 pip >= 19.3。该包针对最流行的 Linux 发行版（Ubuntu 20.04+ / CentOS 7+）和 macOS 12+（Intel/Apple Silicon）进行了构建和测试。对于 Windows 用户，建议在 WSL2 上安装 Ubuntu 来使用此包。

接下来，我们将通过一个具体示例，展示数据科学家如何利用 GraphScope 有效地分析大型图数据。

演示：引用网络上的节点分类

ogbn-mag 是一个异构网络，由 Microsoft 学术图谱的一个子集构成。它包含 4 种类型的实体（即论文、作者、机构和研究领域），以及四种连接两种实体的有向关系。

给定异构的 ogbn-mag 数据，任务是预测每篇论文的类别。节点分类可以识别出属于多个期刊或会议的论文，这些期刊或会议代表了不同主题下的科学工作群体。我们同时利用属性信息和结构信息来对论文进行分类。在图中，每篇论文节点包含一个 128 维的 word2vec 向量，用于表示其内容，该向量通过对标题和摘要中单词嵌入的平均得到。单个单词的嵌入是预先训练好的。而结构信息则是在运行时动态计算的。

加载图

GraphScope 将图数据建模为属性图，在这种模型中，边和顶点都有标签，并且可以拥有多种属性。 以 ogbn-mag 为例，下图展示了属性图的模型。

该图有四种类型的顶点，分别标记为 paper、author、institution 和 field_of_study。它们之间存在四类边，每种边都有一个标签，并指定了其两端顶点的类型。例如，cites 边连接两个标记为 paper 的顶点。另一个例子是 writes，它要求源顶点标记为 author，目标顶点标记为 paper。所有的顶点和边都可以具有属性，比如 paper 顶点可能包含特征、发表年份、学科标签等属性。

要使用我们的检索模块将此图加载到 GraphScope 中，请使用以下代码：

import graphscope
from graphscope.dataset import load_ogbn_mag

g = load_ogbn_mag()

我们提供了一组函数，用于从 ogb 和 snap 加载图数据集，以方便用户使用。所有可用的图可以在 这里 找到。如果您想使用自己的图数据，请参考 这篇文档，按照标签加载顶点和边。

交互式查询

交互式查询允许用户以探索性的方式直接浏览、检查和展示图数据，以便及时找到特定或深入的信息。 GraphScope 采用一种称为 Gremlin 的高级语言来进行图遍历，并提供了大规模下的高效执行能力 [interactive_engine/benchmark/]。

在本例中，我们使用图遍历统计两位给定作者共同撰写的论文数量。为了简化查询，我们假设这两位作者可以通过 ID 分别唯一地标识为 2 和 4307。

# 获取在图 g 上提交 Gremlin 查询的端点。
interactive = graphscope.gremlin(g)

# 统计两位作者（ID 分别为 2 和 4307）共同撰写的论文数量
papers = interactive.execute("g.V().has('author', 'id', 2).out('writes').where(__.in('writes').has('id', 4307)).count()").one()

图分析

图分析在现实世界中被广泛应用。许多算法，如社区检测、路径与连通性、中心性等，已被证明在各种业务场景中非常有用。 GraphScope 内置了一组 内置算法，使用户能够轻松地分析他们的图数据。

继续我们的示例，下面我们将首先通过提取整个图中特定时间段内的出版物来构建一个子图（使用 Gremlin!），然后运行 k-core 分解和三角形计数，以生成每个论文节点的结构特征。

请注意，许多算法可能只适用于 同质 图，因此，要在属性图上评估这些算法，我们需要先将其投影为简单图。

# 提取一个时间范围内的出版物子图
sub_graph = interactive.subgraph("g.V().has('year', gte(2014).and(lte(2020))).outE('cites')")

# 将投影后的图转换为简单图。
simple_g = sub_graph.project(vertices={"paper": []}, edges={"cites": []})

ret1 = graphscope.k_core(simple_g, k=5)
ret2 = graphscope.triangles(simple_g)

# 将结果作为新列添加到引用图中
sub_graph = sub_graph.add_column(ret1, {"kcore": "r"})
sub_graph = sub_graph.add_column(ret2, {"tc": "r"})

此外，用户还可以在 GraphScope 中编写自己的算法。 目前，GraphScope 支持用户基于 Pregel 模型和 PIE 模型编写自定义算法。

图神经网络 (GNNs)

图神经网络 (GNNs) 结合了图分析和机器学习的优势。GNN 算法可以将图中的结构和属性信息压缩成每个节点上的低维嵌入向量。这些嵌入可以进一步输入到下游的机器学习任务中。

在我们的示例中，我们训练了一个 GCN 模型，将节点（论文）分类为 349 个类别， 每个类别代表一个期刊或会议（例如预印本和会议）。 为此，我们首先启动一个学习引擎，并按照上一步骤构建带有特征的图。

# 定义用于学习的特征
paper_features = [f"feat_{i}" for i in range 128]

paper_features.extend(["kcore", "tc"])

# 启动一个学习引擎。
lg = graphscope.graphlearn(sub_graph, nodes=[("paper", paper_features)],
                  edges=[("paper", "cites", "paper")],
                  gen_labels=[
                      ("train", "paper", 100, (0, 75)),
                      ("val", "paper", 100, (75, 85)),
                      ("test", "paper", 100, (85, 100))
                  ])

然后我们定义训练过程并运行它。

# 注意：这里我们使用 tensorflow 作为 NN 后端来训练 GNN 模型。因此请安装 tensorflow。
try:
    # https://www.tensorflow.org/guide/migrate
    import tensorflow.compat.v1 as tf
    tf.disable_v2_behavior()
except ImportError:
    import tensorflow as tf

import graphscope.learning
from graphscope.learning.examples import EgoGraphSAGE
from graphscope.learning.examples import EgoSAGESupervisedDataLoader
from graphscope.learning.examples.tf.trainer import LocalTrainer

# 有监督的 GCN。
def train_gcn(graph, node_type, edge_type, class_num, features_num,
              hops_num=2, nbrs_num=[25, 10], epochs=2,
              hidden_dim=256, in_drop_rate=0.5, learning_rate=0.01,
):
    graphscope.learning.reset_default_tf_graph()

    dimensions = [features_num] + [hidden_dim] * (hops_num - 1) + [class_num]
    model = EgoGraphSAGE(dimensions, act_func=tf.nn.relu, dropout=in_drop_rate)

    # 准备训练数据集
    train_data = EgoSAGESupervisedDataLoader(
        graph, graphscope.learning.Mask.TRAIN,
        node_type=node_type, edge_type=edge_type, nbrs_num=nbrs_num, hops_num=hops_num,
    )
    train_embedding = model.forward(train_data.src_ego)
    train_labels = train_data.src_ego.src.labels
    loss = tf.reduce_mean(
        tf.nn.sparse_softmax_cross_entropy_with_logits(
            labels=train_labels, logits=train_embedding,
        )
    )
    optimizer = tf.train.AdamOptimizer(learning_rate=learning_rate)

    # 准备测试数据集
    test_data = EgoSAGESupervisedDataLoader(
        graph, graphscope.learning.Mask.TEST,
        node_type=node_type, edge_type=edge_type, nbrs_num=nbrs_num, hops_num=hops_num,
    )
    test_embedding = model.forward(test_data.src_ego)
    test_labels = test_data.src_ego.src.labels
    test_indices = tf.math.argmax(test_embedding, 1, output_type=tf.int32)
    test_acc = tf.div(
        tf.reduce_sum(tf.cast(tf.math.equal(test_indices, test_labels), tf.float32)),
        tf.cast(tf.shape(test_labels)[0], tf.float32),
    )

    # 训练和测试
    trainer = LocalTrainer()
    trainer.train(train_data.iterator, loss, optimizer, epochs=epochs)
    trainer.test(test_data.iterator, test_acc)

train_gcn(lg, node_type="paper", edge_type="cites",
          class_num=349,  # 输出维度
          features_num=130,  # 输入维度，128 + kcore + 三角形计数
)

包含整个流程的 Python 脚本可在这里找到，您可以自行尝试。

在 Kubernetes 集群上处理大规模图

GraphScope 专为处理大规模图而设计，这类图通常难以容纳在单台机器的内存中。借助 Vineyard 作为分布式内存数据管理器，GraphScope 支持在由 Kubernetes (k8s) 管理的集群上运行。

要继续本教程，请确保您拥有一个由 k8s 管理的集群，并了解该集群的凭据（例如 k8s API 服务器的地址，通常存储在 ~/.kube/config 文件中）。

或者，您也可以使用 Kind 设置一个本地 k8s 集群进行测试。您可以参考 快速入门 安装并部署 Kind。

如果您在上述步骤中未安装 graphscope 包，可以仅安装包含客户端功能的子集：

pip3 install graphscope-client

接下来，让我们通过在集群上运行来重新审视这个示例。

该图展示了集群模式下的执行流程。当用户在 Python 客户端中运行代码时，它将：

• 步骤 1：在 GraphScope 中创建会话或工作空间。
• 步骤 2 至步骤 5：通过 Python 接口加载图、查询、分析并在该图上运行学习任务。这些步骤与本地模式相同，因此用户可以在分布式环境中处理大型图，就像在单台机器上分析小型图一样。（请注意，graphscope.gremlin 和 graphscope.graphlearn 需分别替换为 sess.gremlin 和 sess.graphlearn，其中 sess 是用户创建的 Session 实例的名称。）
• 步骤 6：关闭会话。

创建会话

要在分布式环境中使用 GraphScope，我们需要在 Python 解释器中建立一个会话。

为了方便起见，我们提供了几个演示数据集，并提供了一个 with_dataset 选项，用于将数据集挂载到 GraphScope 集群中。这些数据集将被挂载到 Pod 中的 /dataset 目录下。如果您想在 k8s 集群上使用自己的数据，请参阅此处。

import graphscope

sess = graphscope.session(with_dataset=True)

对于 macOS 系统，会话需要以 LoadBalancer 服务类型启动（默认为 NodePort）。

import graphscope

sess = graphscope.session(with_dataset=True, k8s_service_type="LoadBalancer")

会话会尝试启动一个协调器，它是后端引擎的入口。协调器管理着一组资源（k8s Pod），以及在这些 Pod 上运行的交互式、分析和学习引擎。集群中的每个 Pod 都有一个 Vineyard 实例，用于提供分布式内存数据服务。

加载图并处理计算任务

与独立模式类似，我们仍然可以使用函数轻松加载图。

from graphscope.dataset import load_ogbn_mag

# 注意我们已将演示数据集挂载到 /dataset，
# 其中包括 ogbn_mag_small 等多个数据集，
# 用户可以进入引擎容器探索该目录。
g = load_ogbn_mag(sess, "/dataset/ogbn_mag_small/")

在这里，图 g 通过 Vineyard 并行加载，并存储在由会话管理的集群中的 Vineyard 实例中。

接下来，我们可以像在独立模式中一样，使用 Gremlin 进行图查询、调用各种图算法，或运行基于图的神经网络任务。这里不再重复代码，但一个在 k8s 上处理分类任务的 .ipynb 文件已在 Playground 上提供。

关闭会话

分布式环境中的另一个额外步骤是关闭会话。在完成所有图任务后，我们关闭会话。

sess.close()

此操作将通知后端引擎和 Vineyard 安全地卸载图及其应用程序，然后协调器将释放 k8s 集群中所有已申请的资源。

请注意，我们尚未针对生产环境对这一发布版本进行加固，它缺乏身份验证和加密等重要安全特性，因此目前不建议用于生产环境！

开发

在本地构建

要构建 GraphScope 的 Python 包和引擎二进制文件，您需要安装一些依赖项和构建工具。

python3 gsctl.py install-deps dev

# 如果您在中国，可使用 --cn 参数加速下载。
python3 gsctl.py install-deps dev --cn

然后，您可以使用预配置的 make 命令构建 GraphScope。

# 构建完整的 GraphScope 包，包括 Python 包和引擎二进制文件。
sudo make install

# 或者构建引擎组件

# 使具有交互性
# 使具有分析性
# 使具有学习性

构建 Docker 镜像

GraphScope 自带一个 Dockerfile，可用于构建用于发布的 Docker 镜像。这些镜像是基于一个安装了所有依赖项的 builder 镜像构建的，随后将内容复制到 runtime-base 镜像中。要构建最新版本的 GraphScope 镜像，请进入根目录下的 k8s/internal 目录，并运行以下命令。

# 默认情况下，构建的镜像会被打上标签 graphscope/graphscope:SHORTSHA
# cd k8s
make graphscope

构建客户端库

GraphScope 的 Python 接口与引擎镜像是分开的。如果您正在开发 Python 客户端且未修改 Protobuf 文件，则无需重新构建引擎镜像。

您可能希望在本地重新安装 Python 客户端：

make client

请注意，学习引擎客户端包含 C/C++ 扩展模块，搭建构建环境较为繁琐。默认情况下，本地构建的客户端库不包含对学习引擎的支持。如果您希望构建支持学习引擎的客户端库，请参阅 构建 Python Wheels。

测试

为了验证您开发的功能是否正确，您的代码更改应通过我们的测试。

您可以使用以下命令运行整个测试套件：

make test

文档

文档可以使用 Sphinx 生成。用户可以通过以下命令构建文档：

# 构建文档
make graphscope-docs

# 在本地打开预览
open docs/_build/latest/html/index.html

最新版在线文档可在 https://graphscope.io/docs 找到。

许可证

GraphScope 采用 Apache License 2.0 许可证发布。请注意，第三方库的许可证可能与 GraphScope 不同。

出版物

• Tao He, Shuxian Hu, Longbin Lai, Dongze Li, Neng Li, Xue Li, Lexiao Liu, Xiaojian Luo, Binqing Lyu, Ke Meng, Sijie Shen, Li Su, Lei Wang, Jingbo Xu, Wenyuan Yu, Weibin Zeng, Lei Zhang, Siyuan Zhang, Jingren Zhou, Xiaoli Zhou, Diwen Zhu. GraphScope Flex: LEGO 式图计算栈。2024 年国际数据管理会议 (SIGMOD) 行业分会场论文，2024 年。
• Wenfei Fan, Tao He, Longbin Lai, Xue Li, Yong Li, Zhao Li, Zhengping Qian, Chao Tian, Lei Wang, Jingbo Xu, Youyang Yao, Qiang Yin, Wenyuan Yu, Jingren Zhou, Diwen Zhu, Rong Zhu. GraphScope：用于大规模图处理的统一引擎。第 47 届国际大型数据库会议 (VLDB)，行业分会场论文，2021 年。
• Jingbo Xu, Zhanning Bai, Wenfei Fan, Longbin Lai, Xue Li, Zhao Li, Zhengping Qian, Lei Wang, Yanyan Wang, Wenyuan Yu, Jingren Zhou. GraphScope：一站式大规模图处理系统。第 47 届国际大型数据库会议 (VLDB)，演示论文，2021 年。

如果您使用本软件，请使用以下元数据引用我们的论文：

# GraphScope 论文
@article{fan2021graphscope,
  title={GraphScope: a unified engine for big graph processing},
  author={Fan, Wenfei and He, Tao and Lai, Longbin and Li, Xue and Li, Yong and Li, Zhao and Qian, Zhengping and Tian, Chao and Wang, Lei and Xu, Jingbo and others},
  journal={Proceedings of the VLDB Endowment},
  volume={14},
  number={12},
  pages={2879--2892},
  year={2021},
  publisher={VLDB Endowment}
}
# 或 GraphScope Flex 论文
@inproceedings{10.1145/3626246.3653383,
  title = {GraphScope Flex: LEGO-like Graph Computing Stack},
  author = {He, Tao and Hu, Shuxian and Lai, Longbin and Li, Dongze and Li, Neng and Li, Xue and Liu, Lexiao and Luo, Xiaojian and Lyu, Bingqing and Meng, Ke and Shen, Sijie and Su, Li and Wang, Lei and Xu, Jingbo and Yu, Wenyuan and Zeng, Weibin and Zhang, Lei and Zhang, Siyuan and Zhou, Jingren and Zhou, Xiaoli and Zhu, Diwen},
  year = {2024},
  isbn = {9798400704222},
  publisher = {Association for Computing Machinery},
  booktitle = {Companion of the 2024 International Conference on Management of Data},
  pages = {386–399},
  numpages = {14},
  location = {Santiago AA, Chile},
  series = {SIGMOD/PODS '24}
}

贡献

您的任何贡献都将受到高度赞赏！

• 加入 Slack 频道 进行讨论。
• 如发现错误，请提交 GitHub 问题。
• 请通过拉取请求提交您的贡献。

GraphScope 快速上手指南

GraphScope 是阿里巴巴开源的一站式大规模图计算系统，支持交互式查询、图分析和图神经网络（GNN）计算。本指南将帮助开发者在单机模式下快速体验 GraphScope 的核心功能。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：
  • Linux (推荐 Ubuntu 20.04+ 或 CentOS 7+)
  • macOS 12+ (支持 Intel 和 Apple Silicon)
  • Windows 用户建议通过 WSL2 安装 Ubuntu 子系统使用。
• Python 版本：>= 3.8
• 包管理工具：pip >= 19.3

安装步骤

GraphScope 以 Python 包形式发布，您可以直接使用 pip 进行安装。

pip3 install graphscope

提示：如果您在国内网络环境下遇到下载缓慢的问题，建议使用国内镜像源加速安装：

pip3 install graphscope -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

以下示例演示了如何加载一个引文网络数据集 (ogbn-mag)，并依次执行交互式查询、图分析和图神经网络训练。

1. 加载图数据

GraphScope 内置了多种常用数据集的加载函数。这里我们加载 heterogeneous graph（异构图）ogbn-mag，包含论文、作者、机构和研究领域四种实体。

import graphscope
from graphscope.dataset import load_ogbn_mag

# 加载数据集
g = load_ogbn_mag()

2. 交互式查询 (Interactive Query)

使用 Gremlin 语言进行灵活的图遍历查询。以下示例统计 ID 为 2 和 4307 的两位作者共同撰写的论文数量。

# 创建 Gremlin 查询入口
interactive = graphscope.gremlin(g)

# 执行查询：统计两位作者合著的论文数
papers = interactive.execute("g.V().has('author', 'id', 2).out('writes').where(__.in('writes').has('id', 4307)).count()").one()

print(f"Co-authored papers: {papers}")

3. 图分析 (Graph Analytics)

GraphScope 内置了丰富的图算法。由于许多算法仅适用于同构图，我们需要先将异构图投影（Project）为简单图，然后执行 k-core 分解和三角形计数。

# 1. 提取子图：筛选 2014-2020 年间的论文引用关系
sub_graph = interactive.subgraph("g.V().has('year', gte(2014).and(lte(2020))).outE('cites')")

# 2. 投影为简单图 (只保留 paper 节点和 cites 边)
simple_g = sub_graph.project(vertices={"paper": []}, edges={"cites": []})

# 3. 运行内置算法
ret_kcore = graphscope.k_core(simple_g, k=5)
ret_triangles = graphscope.triangles(simple_g)

# 4. 将计算结果作为新列添加回图中
sub_graph = sub_graph.add_column(ret_kcore, {"kcore": "r"})
sub_graph = sub_graph.add_column(ret_triangles, {"tc": "r"})

4. 图神经网络 (GNN)

利用提取的结构特征和原始属性特征，训练一个 GCN 模型进行节点分类（预测论文所属的学术 venue）。

# 定义用于学习的特征列
paper_features = [f"feat_{i}" for i in range(128)]
paper_features.extend(["kcore", "tc"]) # 加入刚才计算的结构特征

# 启动学习引擎并构建训练图
learn_g = sub_graph.project(
    vertices={"paper": paper_features}, 
    edges={"cites": []}
)

# 定义 GCN 模型并进行训练 (伪代码示例，具体配置视任务而定)
from graphscope import nns as gs
from graphscope.nns.models import GCN

model = GCN(learn_g, [128+2, 64, 349]) # 输入维度=128 特征 +2 结构特征
# 此处省略具体的 train/fit 代码，实际使用时请参考完整文档配置优化器和损失函数

---

更多高级用法（如 Kubernetes 集群部署、自定义算法开发），请访问 GraphScope 官方文档。