GraphScope：阿里一站式大规模图计算系统快速开始指南

一、项目官方信息

二、项目背景

按照官方 README 的定义，GraphScope 是阿里巴巴开源的一站式大规模图计算系统（A One-Stop Large-Scale Graph Computing System from Alibaba）。它是一个统一的分布式图计算平台，通过用户友好的 Python 接口，在一组计算机组成的集群上提供执行各种图操作的一站式环境。

README 说明，GraphScope 把阿里巴巴多项重要技术组合在一起，让大规模图数据的多阶段处理在计算集群上变得简单：包括 GRAPE（面向图分析）、MaxGraph（面向交互式查询）、Graph-Learn（GL，面向图神经网络 GNN 计算），以及负责高效内存数据传输的 Vineyard 存储。也就是说，一个系统覆盖了图分析、交互式图查询、图学习三类任务，且中间数据通过 Vineyard 在内存里高效流转，不必落盘。

它的典型工作流是：先用 Python 接口把图加载进来，再用 Gremlin 做交互式探查，接着跑内置图分析算法，最后基于图特征训练 GNN 模型——整条链路在同一个集群里完成，避免了把数据从一个系统搬到另一个系统的开销。这正是 README 所说"一站式"（one-stop）的含义。对数据科学家而言，全部操作都收敛在熟悉的 Python 接口里，不需要学习多套底层引擎的命令。

README 还特别宣传正在进行的 GraphScope Flex：一个乐高式（LEGO-inspired）、模块化、对用户友好的 GraphScope 演进版本，其论文已被 SIGMOD 2024 工业 track 录用。Flex 的目标是把各引擎拆成可独立组合的模块，让用户按需拼装，而不必引入整个平台。

三、最新动态（README News 节选）

README 的 Latest News 列出了若干里程碑：

• [2025-04-21] GraphScope 在 LDBC 社交网络基准交互式负载上用声明式查询语言 CYPHER 取得破纪录成绩，SF300 上吞吐比此前纪录保持者高 2.0 倍；
• [2024-07-31] 上线可视化 GraphScope 图计算历程的网页；
• [2024-05-30] GraphScope Flex 在 LDBC 交互式审计中再创纪录；
• [2024-03-25] 图文件格式 GraphAr 捐赠给 Apache 软件基金会成为孵化项目；
• [2024-02-05] GraphScope Flex 论文被 SIGMOD 2024 工业 track 录用；
• [2023-07-20] GraphScope 在 LDBC 交互式负载上 SF300 吞吐比此前纪录保持者高 2.45 倍。

这些动态说明 GraphScope 在图计算基准上持续保持领先，并在推动图数据格式标准化（GraphAr）与模块化架构（Flex）。

四、官方图片

上图为 GraphScope 仓库在 GitHub 上的官方封面图。README 中还附有属性图示例图与集群执行流程图，可在官方文档查看。建议第一次接触的读者先打开 try.graphscope.io 的托管 JupyterLab，实际跑一遍节点分类示例，再对照本文理解 README 的安装与集群模式说明。也可以直接在 Colab 上运行示例笔记本，无需配置任何环境。

五、环境要求与安装

5.1 单机模式安装

GraphScope 预编译包以 Python 包形式分发，可直接用 pip 安装：

pip3 install graphscope

README 说明的要求：graphscope 需要 Python >= 3.8 且 pip >= 19.3；包为最流行的 Linux 发行版（Ubuntu 20.04+ / CentOS 7+）与 macOS 12+（Intel/Apple 芯片）构建并测试；Windows 用户可在 WSL2 上安装 Ubuntu 来使用该包。安装完成后，README 会用一个具体例子说明数据科学家如何用 GraphScope 高效分析大图——也就是下一节的引用网络节点分类。

5.2 在线体验

README 提供了一个托管 JupyterLab 的 Playground，可直接在浏览器中试用，无需本地安装。

六、快速开始：引用网络节点分类示例

README 用一个完整示例演示 GraphScope 的用法：在引用网络上做节点分类。数据集为 ogbn-mag，它是由微软学术图子集构成的异质网络，包含 4 类实体（论文、作者、机构、研究领域）以及 4 种有向关系。任务是预测每篇论文的类别——节点分类能识别不同会议上的论文，代表不同主题的科研工作。README 说明：图中每个论文节点含一个 128 维 word2vec 向量表示其内容（由标题与摘要词的 embedding 平均得到，词 embedding 预训练），结构信息则在运行时计算。

6.1 加载图

GraphScope 把图数据建模为属性图（property graph）：边/顶点都有标签并带若干属性。以 ogbn-mag 为例，图有四类顶点，标签为 paper、author、institution、field_of_study；四类边分别连接它们，例如 cites 边连接两个 paper 顶点，writes 边要求源点是 author、终点是 paper；所有顶点和边都可以有属性，如论文顶点有特征、发表年份、学科标签等。加载代码：

import graphscope
from graphscope.dataset import load_ogbn_mag

g = load_ogbn_mag()

README 提供了一组从 ogb 与 snap 加载图数据集的函数，方便快速上手；要使用自己的图数据，可参考按标签加载顶点与边的文档。

6.2 交互式查询

交互式查询允许用户以探索方式直接探查、检验和展示图数据，以便及时定位特定或深入的信息。GraphScope 采用 Gremlin 这一高层图遍历语言，并提供大规模下的高效执行。示例中，graphscope.gremlin(g) 拿到在图 g 上提交 Gremlin 查询的入口，查询语句从 id 为 2 的作者出发，沿 writes 边找到其论文，再用 where 过滤出这些论文里同样被 id 为 4307 的作者 writes 的，最后 count() 计数并取 .one() 得到合著论文数：

# get the endpoint for submitting Gremlin queries on graph g.
interactive = graphscope.gremlin(g)

# count the number of papers two authors (with id 2 and 4307) have co-authored
papers = interactive.execute("g.V().has('author', 'id', 2).out('writes').where(__.in('writes').has('id', 4307)).count()").one()

6.3 图分析

图分析在真实世界应用广泛，社区检测、路径与连通性、中心性等算法已被证明在各种业务中非常有用。GraphScope 内置一组算法，用户可方便地分析自己的图数据。示例先用 Gremlin 抽取某时间段内的出版物子图，再运行 k-core 分解与三角形计数，生成每个论文节点的结构特征：

# extract a subgraph of publication within a time range
sub_graph = interactive.subgraph("g.V().has('year', gte(2014).and(lte(2020))).outE('cites')")

# project the projected graph to simple graph.
simple_g = sub_graph.project(vertices={"paper": []}, edges={"cites": []})

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

# add the results as new columns to the citation graph
sub_graph = sub_graph.add_column(ret1, {"kcore": "r"})
sub_graph = sub_graph.add_column(ret2, {"tc": "r"})

README 提醒：很多算法只在同构图上工作，因此对属性图需要先投影成简单图。示例中 sub_graph.project(vertices={"paper": []}, edges={"cites": []}) 就是把异质属性图投影为只含 paper 顶点与 cites 边的简单图，然后再跑 k_core(k=5) 与 triangles，最后把结果作为新列 kcore、tc 加回引用图。这一步的意义是：把前面抽出的时间范围内的引用子图，转成算法可接受的同构形式，计算完再把结构特征拼回原图，供后续 GNN 使用。用户还可以用 Pregel 模型与 PIE 模型编写自己的算法。

6.4 图神经网络（GNN）

图神经网络（GNN）结合了图分析与机器学习的优势，能把图中结构与属性信息压缩成每个节点上的低维 embedding 向量，再喂给下游机器学习任务。示例训练一个 GCN 模型，把论文节点分类到 349 个类别（每个类别代表一个会议/出版场所）：

# define the features for learning
paper_features = [f"feat_{i}" for i in range(128)]

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

# launch a learning engine.
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 定义训练过程并运行：先启动学习引擎，按上一步的子图构建带特征的图，用 graphlearn 生成训练/验证/测试的标签划分，再用 EgoGraphSAGE 模型、EgoSAGESupervisedDataLoader 数据加载器与 LocalTrainer 训练器跑训练与测试。示例输入维度是 130（128 维 word2vec + kcore + 三角形计数），输出维度 349，对应 349 个会议类别。完整脚本见 Colab 笔记本，读者可自行打开试跑。

七、在 Kubernetes 集群上处理大图

GraphScope 面向大规模图设计，这类图通常装不进单机内存。它以 Vineyard 作为分布式内存数据管理器，支持在 Kubernetes 管理的集群上以容器方式运行。

继续这个教程需要先有一个 k8s 管理的集群并知道集群凭证（如 k8s API server 地址，通常存在 ~/.kube/config）；也可以用 Kind 在本地起一个 k8s 测试集群。

如未安装完整包，可只装客户端：

pip3 install graphscope-client

集群模式执行流程为：创建会话 → 加载图 → 查询/分析/学习 → 关闭会话。创建会话：

import graphscope

sess = graphscope.session(with_dataset=True)

macOS 上需用 LoadBalancer 服务类型：

import graphscope

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

会话会启动一个 coordinator（后端引擎入口），由它管理 k8s pod 资源，交互式/分析/学习引擎运行在这些 pod 上，每个 pod 有一个 Vineyard 实例提供分布式内存数据。README 说明，集群模式下用户在 Python 客户端运行代码的流程与单机模式几乎一致：创建会话、加载图、查询/分析/学习、关闭会话，唯一区别是 graphscope.gremlin 与 graphscope.graphlearn 要改成 sess.gremlin 与 sess.graphlearn（sess 是创建的会话实例）。这样在分布式环境里处理大图，就像在单机上分析小图一样。加载图后进行查询、算法、GNN 任务，最后关闭会话：

sess.close()

关闭会话会通知后端引擎与 Vineyard 安全卸载图，再由 coordinator 释放 k8s 集群资源。README 明确提醒：该版本尚未为生产环境硬化，缺少认证与加密等安全特性，暂不推荐用于生产环境。

在集群上加载图时，可使用 with_dataset=True 选项把 demo 数据集挂载到 graphscope 集群（pod 内挂载到 /dataset），例如 load_ogbn_mag(sess, "/dataset/ogbn_mag_small/")；加载后的图通过 Vineyard 并行存入集群中的 Vineyard 实例，之后即可像单机模式一样跑 Gremlin 查询、调用算法或运行 GNN 任务。

八、开发与构建

README 给出的开发流程：构建 graphscope Python 包与引擎二进制需要先安装依赖与构建工具，命令为：

python3 gsctl.py install-deps dev

# 国内用户可加 --cn 加速下载
python3 gsctl.py install-deps dev --cn

其中 --cn 参数用于国内网络环境下加速依赖下载。

然后用预配置的 make 命令构建：

# 构建完整包（python 包 + 引擎二进制）
sudo make install

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

构建 Docker 镜像进入 k8s/internal 目录执行 make graphscope（默认镜像 tag 为 graphscope/graphscope:SHORTSHA）；构建客户端库用 make client（注意学习引擎客户端含 C/C++ 扩展，本地默认构建不含学习引擎支持，需要时参考构建 Python Wheels 文档）；跑测试用 make test；生成文档用 make graphscope-docs，在线文档最新版见 graphscope.io/docs。

README 还列出了三篇论文：GraphScope Flex 乐高式图计算栈（SIGMOD 2024 工业 track）、GraphScope 统一大图处理引擎（VLDB 2021）、GraphScope 一站式大规模图处理系统（VLDB 2021 demo），并给出了引用 BibTeX。

九、常见问题（FAQ）

• 问：支持哪些 Python 版本？ 答：README 要求 Python >= 3.8、pip >= 19.3。
• 问：Windows 怎么用？ 答：README 建议在 WSL2 上安装 Ubuntu 再使用 graphscope 包。
• 问：单机能跑吗？ 答：可以，单机模式直接 pip3 install graphscope 即可；大图才需要 Kubernetes 集群。
• 问：生产环境能用吗？ 答：README 明确暂不推荐，缺少认证与加密等安全特性。
• 问：图数据怎么加载？ 答：内置 ogb/snap 数据集加载函数；自定义数据按标签加载顶点与边，见加载文档。
• 问：用什么查询语言？ 答：交互式查询用 Gremlin；分析侧内置算法，也支持 Pregel 与 PIE 模型自定义算法。
• 问：开源协议？ 答：Apache License 2.0；注意第三方库可能协议不同。
• 问：如何贡献？ 答：README 欢迎通过 Slack 频道讨论、提交 GitHub issue 报告 bug、提交 pull request。
• 问：自定义算法怎么写？ 答：README 说明 GraphScope 支持用 Pregel 模型与 PIE 模型编写自定义算法。
• 问：有哪些内置数据集？ 答：README 提供从 ogb 与 snap 加载图数据集的一组函数，完整列表见仓库 dataset 目录。
• 问：集群模式入口怎么建？ 答：用 graphscope.session(with_dataset=True) 创建会话，macOS 需加 k8s_service_type="LoadBalancer"。
• 问：怎么验证代码正确性？ 答：README 建议跑 make test 跑整套测试。

十、跳转链接

• GitHub 仓库
• 官方文档（中文版）
• 在线 Playground · Colab 示例
• GraphScope Flex
• GRAPE (libgrape-lite) · Graph-Learn · Vineyard
• LDBC 基准 · GraphAr (Apache)
• Slack 社区 · FAQ

综上，GraphScope README 传递的核心信息是：它是阿里开源的一站式大规模图计算系统，一个系统覆盖图分析、交互式查询与 GNN 三类任务，单机用 pip3 install graphscope 即可开始（需 Python >= 3.8），大图跑在 Kubernetes 集群上并以 Vineyard 做分布式内存管理，提供 Gremlin 查询与内置算法，且在 LDBC 基准上持续保持领先。对图计算方向的数据团队，它是一个值得评估的开源平台，尤其适合需要在一个系统内同时做图分析、交互式查询与 GNN 训练的场景，而不必在多套工具间搬运数据，这也是它作为"一站式"系统的核心价值，README 全文都在强调这一点，值得仔细阅读参考。