You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@gluten.apache.org by ch...@apache.org on 2025/06/27 06:33:34 UTC

(incubator-gluten) branch main updated: [GLUTEN-9930][VL] Update GPU document (#10061)

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 <Ch...@ibm.com>
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: commits-unsubscribe@gluten.apache.org
For additional commands, e-mail: commits-help@gluten.apache.org