This is an automated email from the ASF dual-hosted git repository.
chengchengjin pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-gluten.git
The following commit(s) were added to refs/heads/main by this push:
new 5d8691c9fe [GLUTEN-9930][VL] Update GPU document (#10061)
5d8691c9fe is described below
commit 5d8691c9fecebad5e01ad59d05babda3e8f7f5b3
Author: Jin Chengcheng <[email protected]>
AuthorDate: Fri Jun 27 07:33:30 2025 +0100
[GLUTEN-9930][VL] Update GPU document (#10061)
---
docs/get-started/VeloxGPU.md | 86 ++++++++++++++++++++++++++++------------
docs/get-started/VeloxIceberg.md | 6 +++
2 files changed, 66 insertions(+), 26 deletions(-)
diff --git a/docs/get-started/VeloxGPU.md b/docs/get-started/VeloxGPU.md
index 440d1d8032..9677649012 100644
--- a/docs/get-started/VeloxGPU.md
+++ b/docs/get-started/VeloxGPU.md
@@ -5,44 +5,78 @@ nav_order: 9
parent: Getting-Started
---
-# GPU Support in Velox Backend
-This is an experimental feature in velox, so as Gluten. Now it only supports
OrderBy operator.
+# GPU Acceleration in Velox/Gluten
+*Unified execution engine leveraging CUDF for hardware-accelerated Spark SQL
queries*
-Velox has several GPU support implementations, Gluten only enables cudf.
+---
+
+## **1. Overview**
+- **Purpose**: Accelerate Velox operators via CUDF APIs, replacing CPU
execution when enabled.
+- **Status**: Experimental (TPC-H SF1 validated). Integrates RAPIDS ecosystem
with Apache Spark via Gluten .
+- **Key Benefit**: Some queries achieved up to **8.1x speedup** on x86 vs.
Spark Java engine .
-## GPU environment
+---
-It requires to install the cuda 12.8.0, driver and the
nvidia-container-toolkit.
+## **2. Prerequisites**
+- **CUDA Toolkit**: 12.8.0
([download](https://developer.nvidia.com/cuda-downloads?target_os=Linux)).
+- **NVIDIA Drivers**: Compatible with CUDA 12.8.
+- **Container Toolkit**: Install `nvidia-container-toolkit`
([guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)).
+- **System Reboot**: Required after driver installation.
+- **Environment Setup**: Use
[`start_cudf.sh`](https://github.com/apache/incubator-gluten/tree/main/dev/start_cudf.sh)
for host configuration .
-Refers to
[start_cudf.sh](https://github.com/apache/incubator-gluten/tree/main/dev/start_cudf.sh)
-to set the ``host`` environment and start the container.
+---
-> You may need to reboot after install the GPU driver.
+## **3. Implementation Mechanics**
+- **Operator Conversion**:
+ - Velox PlanNodes → **GPU operators** when
`spark.gluten.sql.columnar.cudf=true`.
+ - Falls back to CPU operators if GPU unsupported (triggers row/columnar
data conversion) .
+- **Debugging**: Enable `spark.gluten.debug.enabled.cudf=true` for operator
replacement logs.
+- **Memory**: Global [RMM](https://docs.rapids.ai/api/librmm/stable/) memory
manager, cannot align with Spark memory system.
-## GPU implementation
+---
-Invokes [CUDF](https://docs.rapids.ai/api/cudf/stable/libcudf_docs/) API to
support the Velox operators.
+## **4. Docker Deployment**
+```bash
+docker pull apache/gluten:centos-9-jdk8-cudf # Pre-built GPU image
+docker run --name gpu_gluten_container --gpus all -it
apache/gluten:centos-9-jdk8-cudf
+```
+- **Image Includes**: Native build cache, Gluten dependencies, Spark 3.4
environment.
-Suppose we have a velox PlanNode, convert it to the GPU operator or CPU
operator depending on the
-config `spark.gluten.sql.columnar.cudf` which decides registering cudf driver
adapter or not.
+---
-Besides, config `spark.gluten.debug.enabled` true can print the operator
replacement information.
+## **5. Build & Deployment**
+#### **Dependencies**
+The OS, Spark version, Java version aligns with Gluten CPU.
-## Docker images
-This docker image contains Spark at env $SPARK_HOME, Gluten at /opt/gluten,
take a try if you are interested on it.
-The Gluten has been built with Spark3.4.
-```
-docker pull apache/gluten:centos-9-jdk8-cudf
-docker run --name gpu_gluten_container --gpus all -itd
apache/gluten:centos-9-jdk8-cudf
+### **Compilation Commands**
+If building in the docker image, no need to set up script and build arrow.
+```bash
+./dev/buildbundle-veloxbe.sh --run_setup_script=OFF --build_arrow=OFF
--enable_cudf=ON
```
-# Branch
-The [PR](https://github.com/facebookincubator/velox/pull/12735/) has not been
merged to
-facebookincubator/velox, so use a fixed Gluten branch `cudf` and corresponding
oap-project velox branch `cudf`.
+---
+
+## **6. GPU Operator Support Status**
+| **Operator** | **Status** | **Notes** |
+|-----------------|-----------------|--------------------------|
+| **Scan** | ❌ Not supported| In Development |
+| **Project** | ⚠️ Partial | Function TPCH-compatible |
+| **Filter** | ✅ Implemented | Core operator |
+| **OrderBy** | ✅ Implemented | Merged in Velox #12735 |
+| **Aggregation** | ⚠️ Partial | TPCH-compatible |
+| **Join** | ⚠️ Partial | TPCH-compatible |
+| **Spill** | ❌ Not supported | In Planning |
+
+---
-# Relevant link
+## **7. Performance Validation**
+
+GPU performs better on operator HashJoin and HashAggregation.
+Single Operator like Hash Agg shows 5x speedup.
+
+---
-Cuda Toolkit 12.8: https://developer.nvidia.com/cuda-downloads?target_os=Linux
-Cuda Container ToolKit:
https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
-Cudf Document: https://docs.rapids.ai/api/libcudf/legacy/namespacecudf
+## **8. Relevant Resources**
+1. [CUDF Docs](https://docs.rapids.ai/api/cudf/stable/libcudf_docs/) - GPU
operator APIs.
+2. [Gluten GPU Issue
#9098](https://github.com/apache/incubator-gluten/issues/8851) - Development
tracker.
diff --git a/docs/get-started/VeloxIceberg.md b/docs/get-started/VeloxIceberg.md
index 82850acf95..a0cdecca48 100644
--- a/docs/get-started/VeloxIceberg.md
+++ b/docs/get-started/VeloxIceberg.md
@@ -91,6 +91,12 @@ Not support avro format.
## SQL
Only support SELECT.
+## Schema evolution
+PartialOffload
+
+Gluten uses column name to match the parquet file, so if the column is renamed
or
+the added column name is same to the deleted column, the scan will fall back.
+
## Configuration
### Catalogs
Supports all the catalog options, which is not used in native engine.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
