apache/incubator-gluten - 项目详情

项目介绍快速开始学习路径项目截图 3 贡献者 173 增长趋势代码统计生态关系项目时间线项目竞品依赖分析上榜历史

5分钟上手 Apache Gluten

本指南将帮助你在5分钟内搭建一个简单的Apache Gluten环境，并运行一个Spark SQL查询来体验性能提升。

环境要求

支持的操作系统

Linux macOS

运行环境

Java >= 8 必需

Spark 3.2, 3.3, 3.4, 或 3.5 必需

所需工具

Git

克隆项目仓库

必需

Maven

构建项目

必需

操作步骤

克隆项目并构建

从GitHub克隆Apache Gluten项目，并使用Maven构建。这里我们以支持Velox后端为例。

克隆项目到本地

git clone https://github.com/apache/incubator-gluten.git

进入项目目录

cd incubator-gluten

构建支持Velox后端和Spark 3.5的Gluten JAR包（请根据你的Spark版本调整 `-Pspark-3.5` 参数）

mvn clean package -Pbackends-velox -Pspark-3.5 -DskipTests

预期结果：构建成功，在 `backends-velox/target/` 目录下生成 `gluten-velox-bundle-spark3.5_2.12-<version>-bundle.jar` 文件。

构建过程可能需要几分钟，取决于网络和机器性能。确保Maven已正确配置。

启动Spark Shell并加载Gluten

使用Spark Shell，并通过 `--jars` 参数加载上一步构建的Gluten JAR包。

启动Spark Shell并启用Gluten插件。请将 `path/to/your/spark-shell` 替换为你的Spark安装路径下的spark-shell脚本路径。

path/to/your/spark-shell --master local[*] --jars backends-velox/target/gluten-velox-bundle-spark3.5_2.12-*-bundle.jar --conf spark.plugins=io.glutenproject.GlutenPlugin --conf spark.gluten.sql.columnar.backend.lib=velox

预期结果：成功进入Spark Shell交互界面，看到Scala提示符 `scala>`。

如果Spark已加入系统PATH，可以直接使用 `spark-shell` 命令。

运行一个简单的Spark SQL查询

在Spark Shell中创建一个DataFrame并执行一个简单的聚合查询，观察执行计划中是否出现 `Gluten` 字样，表示查询已由Gluten处理。

创建一个包含100万行测试数据的DataFrame

val df = spark.range(1000000).selectExpr("id", "id % 10 as key", "rand() as value")

注册为临时视图

df.createOrReplaceTempView("test_table")

执行一个分组聚合查询并打印详细的执行计划

spark.sql("SELECT key, avg(value) FROM test_table GROUP BY key").explain("extended")

实际执行查询并显示结果

spark.sql("SELECT key, avg(value) FROM test_table GROUP BY key").show()

预期结果：1. 执行计划中应出现 `*GlutenVeloxColumnarToRow` 或类似包含 `Gluten` 的算子名称，表明查询计划已由Gluten处理。 2. 查询成功执行，并打印出10个分组（key从0到9）的平均值。

如果执行计划中没有出现Gluten算子，请检查步骤2中的 `--conf` 配置是否正确。

验证成功

成功运行Spark SQL查询，并且在查询的物理执行计划中看到 `Gluten` 相关的算子。

Spark Shell成功启动并加载了Gluten JAR包。

执行 `explain` 命令后，在输出计划中看到 `Gluten` 字样。

查询成功执行并返回了正确的结果。

快速提示

配置

首次构建时，Maven需要下载大量依赖，请确保网络通畅。可以使用阿里云等国内镜像加速。

性能

Gluten目前主要支持聚合、过滤、投影等常见算子。复杂的UDF或某些特定算子可能会回退到原生Spark执行（Fallback）。

调试

在Spark UI (通常为 http://localhost:4040) 中，可以查看Gluten特有的监控指标，帮助分析性能。

常见问题

Maven构建失败，提示依赖下载错误或版本冲突。

1. 检查网络，或配置Maven国内镜像。 2. 确保Java版本符合要求。 3. 尝试清理本地Maven仓库后重新构建：`mvn clean package -Pbackends-velox -Pspark-3.5 -DskipTests -U` (使用 `-U` 强制更新快照依赖)。

启动Spark Shell时提示找不到主类或JAR包加载失败。

1. 确认 `--jars` 参数指向的JAR文件路径正确且文件存在。 2. 确认Spark版本与构建时指定的版本（如 `-Pspark-3.5`）一致。 3. 检查Spark和Scala版本兼容性。

执行查询时没有看到Gluten算子，或者查询报错。

1. 在Spark Shell启动命令中，确保 `--conf spark.plugins=io.glutenproject.GlutenPlugin` 和 `--conf spark.gluten.sql.columnar.backend.lib=velox` 配置正确。 2. 尝试一个更简单的查询，例如 `spark.sql("SELECT 1").explain("extended")`，看是否有Gluten参与。 3. 检查Spark日志中是否有关于Gluten插件加载失败的ERROR信息。

下一步

阅读官方文档

访问项目官网或GitHub Wiki，深入了解配置选项、支持的操作符、性能调优和高级用法。

尝试TPC-H基准测试

使用项目自带的TPC-H基准测试脚本，定量评估Gluten带来的性能提升。

探索其他后端

尝试构建并配置使用ClickHouse作为后端，比较不同后端的特性与性能。