[Example] Attention and R3 Examples (#2132)

# Attention Quantization in LLM Compressor #
LLM Compressor supports applying static attention quantization to
models. Please note that attention quantization support in vLLM is still
ongoing and is not fully supported as of this writing.

## FP8 Attention Example ##
For an example applying attention quantization, see
[llama3_attention.py](/experimental/attention/llama3_attention.py).

```python
recipe = QuantizationModifier(
    config_groups={
        "attention": QuantizationScheme(
            targets=["LlamaAttention"],
            input_activations=QuantizationArgs(
                num_bits=8, type="float", strategy="attn_head"
            ),
        )
    }
)
```

Note that attention quantization also implicitly applies kv cache
quantization with the same quantization arguments.

## NVFP4 Attention + R3 Example ##
Attention quantization can be improved using the R3 transform, as
described by [SpinQuant](https://arxiv.org/abs/2405.16406). This
transform reduces the presence of outliers in the attention activation
distribution, thereby improving accurcy recovery.

```python
recipe = [
    SpinQuantModifier(rotations=["R3"]),
    QuantizationModifier(
        config_groups={
            "attention": QuantizationScheme(
                targets=["LlamaAttention"],
                input_activations=NVFP4["input_activations"],
            )
        }
    ),
]
```

### Evaluations ###
Utilizing the R3 transform has been shown to improve accuracy recovery
for the `meta-llama/Llama-3.2-1B-Instruct` model when using NVFP4
attention quantization.

Without R3 Transform
```
../llm-compressor/Llama-3.2-1B-Instruct-attention-nvfp4/
|    Tasks     |Version|     Filter     |n-shot|  Metric   |   |Value |   |Stderr|
|--------------|------:|----------------|-----:|-----------|---|-----:|---|-----:|
|gsm8k_platinum|      3|flexible-extract|     5|exact_match|↑  |0.2680|±  |0.0127|
|              |       |strict-match    |     5|exact_match|↑  |0.1836|±  |0.0111|
```

With R3 Transform
```
../llm-compressor/Llama-3.2-1B-Instruct-r3-attention-nvfp4/
|    Tasks     |Version|     Filter     |n-shot|  Metric   |   |Value |   |Stderr|
|--------------|------:|----------------|-----:|-----------|---|-----:|---|-----:|
|gsm8k_platinum|      3|flexible-extract|     5|exact_match|↑  |0.2961|±  |0.0131|
|              |       |strict-match    |     5|exact_match|↑  |0.2283|±  |0.0121|
```

---------

Signed-off-by: Kyle Sayers <kylesayrs@gmail.com>
Co-authored-by: Dipika Sikka <dipikasikka1@gmail.com>

Author: kylesayrs

README.md

@@ -81,6 +81,9 @@ Applying quantization with `llmcompressor`:
 * [Weight only quantization to `int4` using GPTQ](examples/quantization_w4a16/README.md)
 * [Weight only quantization to `int4` using AWQ](examples/awq/README.md)
 * [Weight only quantization to `int4` using AutoRound](examples/autoround/README.md)
+* [KV Cache quantization to `fp8`](examples/quantization_kv_cache/README.md)
+* [Attention quantization to `fp8` (experimental)](experimental/attention/README.md)
+* [Attention quantization to `nvfp4` with SpinQuant (experimental)](experimental/attention/README.md)
 * [Quantizing MoE LLMs](examples/quantizing_moe/README.md)
 * [Quantizing Vision-Language Models](examples/multimodal_vision/README.md)
 * [Quantizing Audio-Language Models](examples/multimodal_audio/README.md)

experimental/attention/README.md

@@ -0,0 +1,58 @@
+# Attention Quantization in LLM Compressor #
+LLM Compressor supports applying static attention quantization to models. Please note that attention quantization support in vLLM is still ongoing and is not fully supported as of this writing.
+
+## FP8 Attention Example ##
+For an example applying attention quantization, see [llama3_attention.py](/experimental/attention/llama3_attention.py).
+
+```python
+recipe = QuantizationModifier(
+    config_groups={
+        "attention": QuantizationScheme(
+            targets=["LlamaAttention"],
+            input_activations=QuantizationArgs(
+                num_bits=8, type="float", strategy="attn_head"
+            ),
+        )
+    }
+)
+```
+
+Note that attention quantization also implicitly applies kv cache quantization with the same quantization arguments.
+
+## NVFP4 Attention + R3 Example ##
+Attention quantization can be improved using the R3 transform, as described by [SpinQuant](https://arxiv.org/abs/2405.16406). This transform reduces the presence of outliers in the attention activation distribution, thereby improving accurcy recovery.
+
+```python
+recipe = [
+    SpinQuantModifier(rotations=["R3"]),
+    QuantizationModifier(
+        config_groups={
+            "attention": QuantizationScheme(
+                targets=["LlamaAttention"],
+                input_activations=NVFP4["input_activations"],
+            )
+        }
+    ),
+]
+```
+
+### Evaluations ###
+Utilizing the R3 transform has been shown to improve accuracy recovery for the `meta-llama/Llama-3.2-1B-Instruct` model when using NVFP4 attention quantization.
+
+Without R3 Transform
+```
+../llm-compressor/Llama-3.2-1B-Instruct-attention-nvfp4/
+|    Tasks     |Version|     Filter     |n-shot|  Metric   |   |Value |   |Stderr|
+|--------------|------:|----------------|-----:|-----------|---|-----:|---|-----:|
+|gsm8k_platinum|      3|flexible-extract|     5|exact_match|↑  |0.2680|±  |0.0127|
+|              |       |strict-match    |     5|exact_match|↑  |0.1836|±  |0.0111|
+```
+
+With R3 Transform
+```
+../llm-compressor/Llama-3.2-1B-Instruct-r3-attention-nvfp4/
+|    Tasks     |Version|     Filter     |n-shot|  Metric   |   |Value |   |Stderr|
+|--------------|------:|----------------|-----:|-----------|---|-----:|---|-----:|
+|gsm8k_platinum|      3|flexible-extract|     5|exact_match|↑  |0.2961|±  |0.0131|
+|              |       |strict-match    |     5|exact_match|↑  |0.2283|±  |0.0121|
+```

experimental/llama3_attention.py …perimental/attention/llama3_attention.pyexperimental/llama3_attention.py renamed to experimental/attention/llama3_attention.py experimental/llama3_attention.py renamed to experimental/attention/llama3_attention.py

@@ -0,0 +1,90 @@
+from datasets import load_dataset
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+from llmcompressor import oneshot
+from llmcompressor.modifiers.quantization import QuantizationModifier
+from llmcompressor.modifiers.transform import SpinQuantModifier
+from llmcompressor.utils import dispatch_for_generation
+from compressed_tensors.quantization import QuantizationScheme
+from compressed_tensors.quantization.quant_scheme import NVFP4
+
+# Select model and load it.
+model_id = "meta-llama/Meta-Llama-3-8B-Instruct"
+model = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype="auto")
+tokenizer = AutoTokenizer.from_pretrained(model_id)
+
+# Select calibration dataset.
+DATASET_ID = "HuggingFaceH4/ultrachat_200k"
+DATASET_SPLIT = "train_sft"
+
+# Select number of samples. 512 samples is a good place to start.
+# Increasing the number of samples can improve accuracy.
+NUM_CALIBRATION_SAMPLES = 512
+MAX_SEQUENCE_LENGTH = 2048
+
+# Load dataset and preprocess.
+ds = load_dataset(DATASET_ID, split=f"{DATASET_SPLIT}[:{NUM_CALIBRATION_SAMPLES}]")
+ds = ds.shuffle(seed=42)
+
+
+def preprocess(example):
+    return {
+        "text": tokenizer.apply_chat_template(
+            example["messages"],
+            tokenize=False,
+        )
+    }
+
+
+ds = ds.map(preprocess)
+
+
+# Tokenize inputs.
+def tokenize(sample):
+    return tokenizer(
+        sample["text"],
+        padding=False,
+        max_length=MAX_SEQUENCE_LENGTH,
+        truncation=True,
+        add_special_tokens=False,
+    )
+
+
+ds = ds.map(tokenize, remove_columns=ds.column_names)
+
+# Configure the quantization algorithm to run.
+recipe = [
+    SpinQuantModifier(rotations=["R3"]),
+    QuantizationModifier(
+        config_groups={
+            "attention": QuantizationScheme(
+                targets=["LlamaAttention"],
+                input_activations=NVFP4["input_activations"],
+            )
+        }
+    ),
+]
+
+# Apply algorithms.
+oneshot(
+    model=model,
+    dataset=ds,
+    recipe=recipe,
+    max_seq_length=MAX_SEQUENCE_LENGTH,
+    num_calibration_samples=NUM_CALIBRATION_SAMPLES,
+)
+
+# Confirm generations of the quantized model look sane.
+print("\n\n")
+print("========== SAMPLE GENERATION ==============")
+dispatch_for_generation(model)
+sample = tokenizer("Hello my name is", return_tensors="pt")
+sample = {key: value.to(model.device) for key, value in sample.items()}
+output = model.generate(**sample, max_new_tokens=100)
+print(tokenizer.decode(output[0]))
+print("==========================================\n\n")
+
+# Save to disk compressed.
+SAVE_DIR = model_id.rstrip("/").split("/")[-1] + "-r3-attention-nvfp4"
+model.save_pretrained(SAVE_DIR, save_compressed=True)
+tokenizer.save_pretrained(SAVE_DIR)