From 5e90233bdba013838c1a69df7738e08bd5c058d5 Mon Sep 17 00:00:00 2001 From: lhez Date: Tue, 4 Nov 2025 16:02:36 -0800 Subject: [PATCH] opencl: update doc (#17011) * opencl: update docs * opencl: update docs * opencl: fix link * opencl: update doc --- docs/backend/OPENCL.md | 28 +++++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/docs/backend/OPENCL.md b/docs/backend/OPENCL.md index 07146f7102..e52baffdff 100644 --- a/docs/backend/OPENCL.md +++ b/docs/backend/OPENCL.md @@ -39,18 +39,23 @@ The llama.cpp OpenCL backend is designed to enable llama.cpp on **Qualcomm Adren | Adreno 830 (Snapdragon 8 Elite) | Support | | Adreno X85 (Snapdragon X Elite) | Support | +> A6x GPUs with a recent driver and compiler are supported; they are usually found in IoT platforms. +However, A6x GPUs in phones are likely not supported due to the outdated driver and compiler. + ## DataType Supports | DataType | Status | |:----------------------:|:--------------------------:| | Q4_0 | Support | | Q6_K | Support, but not optimized | +| Q8_0 | Support | +| MXFP4 | Support | ## Model Preparation -You can refer to the general [*Prepare and Quantize*](README.md#prepare-and-quantize) guide for model prepration. +You can refer to the general [llama-quantize tool](/tools/quantize/README.md) for steps to convert a model in Hugging Face safetensor format to GGUF with quantization. -Currently we support `Q4_0` quantization and have optimize for it. To achieve best performance on Adreno GPU, add `--pure` to `llama-quantize`. For example, +Currently we support `Q4_0` quantization and have optimized for it. To achieve best performance on Adreno GPU, add `--pure` to `llama-quantize` (i.e., make all weights in `Q4_0`). For example, ```sh ./llama-quantize --pure ggml-model-qwen2.5-3b-f16.gguf ggml-model-qwen-3b-Q4_0.gguf Q4_0 @@ -58,6 +63,17 @@ Currently we support `Q4_0` quantization and have optimize for it. To achieve be Since `Q6_K` is also supported, `Q4_0` quantization without `--pure` will also work. However, the performance will be worse compared to pure `Q4_0` quantization. +### `MXFP4` MoE Models + +OpenAI gpt-oss models are MoE models in `MXFP4`. The quantized model will be in `MXFP4_MOE`, a mixture of `MXFP4` and `Q8_0`. +For this quantization, there is no need to specify `--pure`. +For gpt-oss-20b model, you can directly [download](https://huggingface.co/ggml-org/gpt-oss-20b-GGUF) the quantized GGUF file in `MXFP4_MOE` from Hugging Face. + +Although it is possible to quantize gpt-oss-20b model in pure `Q4_0` (all weights in `Q4_0`), it is not recommended since `MXFP4` has been optimized for MoE while `Q4_0` is not. In addition, accuracy should degrade with such pure `Q4_0` quantization. +Hence, using the default `MXFP4_MOE` quantization (see the link above) is recommended for this model. + +> Note that the `Q4_0` model found [here](https://huggingface.co/unsloth/gpt-oss-20b-GGUF/blob/main/gpt-oss-20b-Q4_0.gguf) is a mixture of `Q4_0`, `Q8_0` and `MXFP4` and gives better performance than `MXFP4_MOE` quantization. + ## CMake Options The OpenCL backend has the following CMake options that control the behavior of the backend. @@ -146,10 +162,13 @@ A Snapdragon X Elite device with Windows 11 Arm64 is used. Make sure the followi * Ninja * Visual Studio 2022 * Powershell 7 +* Python Visual Studio provides necessary headers and libraries although it is not directly used for building. Alternatively, Visual Studio Build Tools can be installed instead of the full Visual Studio. +> Note that building using Visual Studio's cl compiler is not supported. Clang must be used. Clang depends on libraries provided by Visual Studio to work. Therefore, Visual Studio must be installed. Alternatively, Visual Studio Build Tools can be installed instead of the full Visual Studio. + Powershell 7 is used for the following commands. If an older version of Powershell is used, these commands may not work as they are. @@ -201,9 +220,12 @@ ninja ## Known Issues -- Currently OpenCL backend does not work on Adreno 6xx GPUs. +- Flash attention does not always improve performance. +- Currently OpenCL backend works on A6xx GPUs with recent drivers and compilers (usually found in IoT platforms). + However, it does not work on A6xx GPUs found in phones with old drivers and compilers. ## TODO - Optimization for Q6_K - Support and optimization for Q4_K +- Improve flash attention