从 Velox 迁移到 Bolt 后端的指南

本文档为已经使用 Velox 后端运行 Gluten 的用户提供详细指引，帮助其平稳迁移至 Bolt 后端，并充分利用其统一的湖仓加速能力。

迁移步骤概览

验证后端构建：确认 Gluten JAR 是使用 -Pbackends-bolt Maven profile 构建的（例如通过 jar_spark3x Makefile 目标）。如有必要，解压该 JAR 并验证 libbolt_backend.so 是否存在。
环境准备与构建：
- 准备构建环境：确保构建主机满足《环境与构建说明》→《前置条件》章节中列出的要求（Linux 操作系统、GCC/Clang 工具链、安装了 Conan 的 Python、兼容的内核版本等）。
- 构建并打包产物：依次执行 make bolt-recipe、make release、make arrow 和 make jar_spark3x，以生成集成 Bolt 后端的 Gluten JAR。
部署 JAR 并启用 Gluten 插件：将新构建的 JAR 部署到集群。在 Spark 配置中，使用 spark.plugins=org.apache.gluten.GlutenPlugin 启用该插件，开启堆外内存分配，并采用列式 Shuffle 管理器。
迁移配置项：将现有配置从 spark.gluten.sql.columnar.backend.velox.* 命名空间切换到 spark.gluten.sql.columnar.backend.bolt.*，具体可参考 bolt-configuration 和 bolt-spark-configuration 中提供的配置映射。
验证迁移结果并准备回退：通过 Spark UI、服务日志和执行计划确认当前生效的后端为 Bolt。若出现兼容性问题，请按照《回滚与降级策略》回退到 Velox 后端，或降级回原生 Spark。

1. 环境与构建说明

在调整 Spark 和 Gluten 配置之前，您必须确保 Bolt 后端已在您的环境中正确编译和打包。本节详细介绍所需的构建环境以及相应的打包流程。

前置条件

有关详细的环境要求，请参阅：Bolt 后端 README

构建与打包

从 Velox 迁移到 Bolt 后端，主要涉及在构建过程中调整 Maven profile 和 Makefile 目标，这为后续的配置和部署步骤奠定基础。

第 1 步：构建原生 C++ 后端

首先为 Gluten 编译 Bolt 后端，这可以通过提供的 Makefile 完成，具体子步骤如下：

安装 Bolt Recipe：此命令会下载 Bolt 源代码，安装其依赖项，并将其 C++ 包 recipe 添加到您的本地 Conan 缓存中。
```
# Use the main branch of Bolt
make bolt-recipe BOLT_BUILD_VERSION=main
```
你可以指定 BOLT_BUILD_VERSION 来选择 Bolt 的某个特定分支或标签，默认使用 main 分支
编译 Gluten 的 C++ 组件：该命令会编译 Gluten 自身的 C++ 代码，并将其与上一子步骤中准备好的 Bolt 后端进行链接。
```
# Compile the Release version
make release

# or specific the version for Bolt, and the version for Gluten
make release BOLT_BUILD_VERSION=main GLUTEN_BUILD_VERSION=main
```
- 此命令将生成原生库 libbolt_backend.so，位于 cpp/build/releases/ 目录中。
- 首次构建时，Conan 会自动编译所有缺失的第三方依赖，这可能需要相当长的时间。

第二步：打包 Java JAR

原生组件编译完成后，将 libbolt_backend.so 与所有 Java/Scala 代码一起打包为最终的 Gluten JAR。

准备 Arrow 依赖：Gluten 依赖特定版本的 Arrow 库。运行以下命令进行构建和安装。
```
make arrow
```
打包 JAR：使用 Maven 进行打包。关键在于将 profile 从 -Pbackends-velox 切换到 -Pbackends-bolt。根据您的 Spark 版本选择相应的 jar_sparkXX 目标。
```
# Example: Package for Spark 3.5
make jar_spark35
```
该命令等价于运行 mvn package -Pbackends-bolt -Pspark-3.5 ...。Maven 会自动处理依赖，并将 libbolt_backend.so 打包到最终的 JAR 文件中。

构建产物

构建完成后，你将得到以下关键产物：

Gluten JAR：位于 output/ 目录中，文件名类似 gluten-spark3.5_2.12-1.0.0-SNAPSHOT-jar-with-dependencies.jar。该 JAR 包含所有 Java/Scala 代码以及 libbolt_backend.so 本地库。

2. 配置切换

将 Spark 作业从 Velox 后端切换到 Bolt 后端，主要涉及调整 Spark 配置设置。

2.1. 核心 Spark 配置

以下是启用 Gluten 与 Bolt 后端所需的最小配置集。请确保将这些设置添加到你的 spark-defaults.conf 文件中，或包含在 spark-submit 命令中。

# 1. Enable the Gluten plugin
spark.plugins=org.apache.gluten.GlutenPlugin

# 2. Enable off-heap memory (mandatory for Gluten)
spark.memory.offHeap.enabled=true
spark.memory.offHeap.size=20g # Adjust based on your hardware specifications and job requirements

# 3. Use Gluten's Columnar Shuffle Manager
spark.shuffle.manager=org.apache.spark.shuffle.sort.ColumnarShuffleManager

# 4. Specify the Gluten JAR path
spark.driver.extraClassPath=/path/to/gluten-spark3.5_...jar
spark.executor.extraClassPath=/path/to/gluten-spark3.5_...jar

2.2. 常见的 Velox 到 Bolt 配置键映射

Bolt 和 Velox 共享大部分性能调优配置；你只需在配置键中将 velox 替换为 bolt 即可。下表列出了一些常见配置项及其对应的迁移说明。

Velox 配置项 (`spark.gluten.sql.columnar.backend.velox.*`)	Bolt 配置项 (`spark.gluten.sql.columnar.backend.bolt.*`)	迁移说明
`IOThreads`	`IOThreads`	I/O 线程池大小。两个后端均支持此项，可保持不变。
`flushablePartialAggregation`	`flushablePartialAggregation`	启用可清空的部分聚合。Bolt 同样支持此功能，建议保持启用（`true`）。
`footerEstimatedSize`	`footerEstimatedSize`	Parquet 文件元数据的预估大小。可直接迁移。
`loadQuantum`	`loadQuantum`	文件扫描的读取单元大小。Bolt 支持此项，可根据存储情况进行调整。
`prefetchRowGroups`	`prefetchRowGroups`	预取的 Parquet 行组数量。Bolt 同样支持该优化。
`memoryUseHugePages`	`memoryUseHugePages`	是否使用大页。Bolt 同样适用，但需要操作系统支持。
`bloomFilter.expectedNumItems`	`bloomFilter.expectedNumItems`	布隆过滤器的预期元素数量。路径保持一致。
`bloomFilter.numBits`	`bloomFilter.numBits`	布隆过滤器的位数组大小。路径保持一致。
`filePreloadThreshold`	`filePreloadThreshold`	文件预加载阈值。路径保持一致。
`resizeBatches.shuffleInput`	`resizeBatches.shuffleInput`	在 shuffle 写入前是否调整批次大小。Bolt 支持此项。
`resizeBatches.shuffleOutput`	`resizeBatches.shuffleOutput`	在 shuffle 读取后是否调整批次大小。Bolt 支持此项。
`spillStrategy`	`spillStrategy`	落盘策略（`auto` 或 `none`）。Bolt 支持此配置，行为相似。
`ssdCachePath`	`ssdCachePath`	本地 SSD 缓存的路径。Bolt 支持此配置项，配置方式相同。
`ssdCacheSize`	`ssdCacheSize`	本地 SSD 缓存的大小。Bolt 支持此项。
`ssdCacheShards`	`ssdCacheShards`	本地 SSD 缓存的分片数量。Bolt 支持此项。

如需查看更详细的配置列表，请参阅官方文档：

3. 回滚与降级策略

如果迁移到 Bolt 后端后出现兼容性或稳定性问题，你可以通过以下回滚与降级流程恢复到 Velox 后端，或回退到原生 Spark。对于持续存在的问题，我们强烈建议在 Bolt GitHub 仓库上提交详细的 Issue，以便开发团队协助排查和解决。

完全回滚到 Velox：
1. 使用 -Pbackends-velox Maven profile 重新打包 Gluten JAR。
2. 将 Spark 作业中的 spark.driver.extraClassPath 和 spark.executor.extraClassPath 配置更新为指向新构建的 Velox 后端 JAR。
3. 将所有以 spark.gluten.sql.columnar.backend.bolt.* 为前缀的 Spark 配置恢复为 spark.gluten.sql.columnar.backend.velox.*。
临时禁用 Gluten（回退到原生 Spark）：最快的临时变通方法是完全禁用 Gluten 插件，使作业以原生 Spark 应用的方式运行。
```
# Set the value of spark.plugins to empty or comment it out
# spark.plugins=org.apache.gluten.GlutenPlugin
```
或者，通过添加如下配置在运行时禁用 Gluten：--conf spark.gluten.enabled=false。
禁用特定功能或算子：如果问题是由某个特定算子或功能触发的，你可以通过配置禁用有问题的组件来进行规避。这会强制查询中受影响的部分回退到 Vanilla Spark 执行，而查询的其余部分仍由 Bolt 继续加速。例如，如果怀疑窗口函数是根本原因，可以通过以下设置将其禁用：
```
spark.gluten.sql.columnar.window=false
```
这种方法能够在保留 Bolt 部分加速收益的同时，实现问题的隔离定位。

Velox 到 Bolt 迁移指南