GraphScope

<h1 align="center"> <img src="https://yellow-cdn.veclightyear.com/ab5030c0/0f301150-fe46-40f3-9d6d-df6869ea516b.svg" width="400" alt="graphscope-logo"> </h1> <p align="center"> 阿里巴巴一站式大规模图计算系统 </p>

🎉 了解我们正在进行的GraphScope Flex项目：一个受乐高启发的、模块化且用户友好的GraphScope演进版本。🎉

GraphScope是一个统一的分布式图计算平台，通过用户友好的Python接口，为用户提供在计算机集群上执行各种图操作的一站式环境。GraphScope通过结合阿里巴巴的几项重要技术，简化了在计算集群上进行大规模图数据的多阶段处理：包括用于分析、交互和图神经网络(GNN)计算的GRAPE、MaxGraph和Graph-Learn(GL)，以及提供高效内存数据传输的Vineyard存储。

访问我们的网站graphscope.io了解更多信息。

快速开始

我们提供了一个带有托管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 Academic Graph子集组成的异构网络。它包含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的高级语言进行图遍历，并提供高效的大规模执行。在这个示例中，我们使用图遍历来计算两位给定作者共同撰写的论文数量。为了简化查询，我们假设这两位作者可以分别通过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.append("kcore")
paper_features.append("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 作为神经网络后端来训练 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")

会话尝试启动一个 coordinator，它是后端引擎的入口。coordinator 管理一组资源（k8s 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 进行图查询，调用各种图算法，或运行基于图的神经网络任务。我们不在此重复代码，但在 Playground 上提供了一个在 k8s 上处理分类任务的 .ipynb 文件。

关闭会话

在分发中还有一个额外步骤是会话关闭。我们在处理完所有图任务后关闭会话。

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

# 或者构建单个引擎组件
# make interactive
# make analytical
# make learning

构建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轮子。

测试

为验证你开发的功能的正确性，你的代码修改应通过我们的测试。

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

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-like Graph Computing Stack. 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: A Unified Engine For Big Graph Processing. 第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: A One-Stop Large Graph Processing System. 第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}
}