# AutoRound

[AutoRound](https://github.com/intel/auto-round)は、2ビット精度でも高い精度を実現する高度な量子化アルゴリズムです。符号勾配降下法を活用し、丸め値とmin-maxクリッピングの閾値をわずか200ステップで微調整します。幅広い互換性を備えており、多数のLLMをシームレスにサポートするとともに、VLMへの対応も積極的に拡大しています。また、CPU、XPU、CUDAなど、複数のハードウェアプラットフォームでの量子化および推論に対応しています。

AutoRoundには、自動的な混合ビットチューニングおよび推論、MXFP4およびNVFP4データ型へのサポート、モデルフリーの量子化、GPTQ、AWQ、GGUF、LLM-Compressorなどの形式へのエクスポート、柔軟なチューニングレシピなど、さまざまな有用な機能が用意されています。包括的な概要や最新の更新情報については、AutoRoundの[README](https://github.com/intel/auto-round)をご覧ください。

AutoRound は当初、[Intel Neural Compressor](https://github.com/intel/neural-compressor)の一部として開発され、深層学習向けの汎用モデル圧縮ライブラリとして機能していました。その後、大規模言語モデル（LLM）の低精度最適化に特化したスタンドアロンライブラリへと進化しました。AutoRound は Intel Neural Compressor と引き続き完全に統合されており、詳細についてはリポジトリをご覧ください。

## インストール

```bash
pip install auto-round
```

## サポートされている量子化設定

AutoRoundは、以下の量子化設定をサポートしています：

1. **INT2〜INT8の重みのみ**
2. **混合ビット重みのみ**
3. **GGUF Q\*_K**
4. **MXFP**（サポートは限定的です）
5. **NVFP4**（サポートは限定的です）

## ハードウェアの互換性

量子化と推論の両方で、CPU、XPU、CUDAに対応します。

## 量子化とシリアライズ（オフライン）

現在、量子化モデルを生成するにはオフラインモードのみがサポートされています。

### コマンドラインでの使用

```bash
auto-round \
    --model Qwen/Qwen3-0.6B \
    --scheme "W4A16" \
    --group_size 128 \
    --output_dir ./tmp_autoround
```

AutoRoundでは、最適な精度と高速化をそれぞれ目指して設計された、`auto-round-best`、`auto-round-light`、`auto-round-opt-rtn`、`auto-round-rtn`という4つのレシピも提供されています。2ビットの場合、`auto-round-best`に`--enable_alg_ext`を付けて使用することを推奨します。

### AutoScheme の使用方法

AutoSchemeは、対象となる平均ビット幅の制約のもと、量子化対象の各レイヤーについて、利用可能なオプションから最適な量子化スキームを数分で自動的に選択する機能です。

```bash
auto-round \
    --model Qwen/Qwen3-0.6B \
    --options "W4A16,W2A16G64" \
    --target_bits 3.5 \
    --output_dir ./tmp_autoround
```

### アルゴリズムの組み合わせ

AutoRoundは、AutoRound、AutoRound + AWQ、AutoRound + AWQ + Hadamard（サポートは非常に限定的）など、複数のアルゴリズムを組み合わせることをサポートしています。現在、より多くのアルゴリズムへのサポートを拡充中です。これにより、特に量子化されたアクティベーションを伴うシナリオにおいて、量子化結果のさらなる最適化が可能になります。

```bash
auto-round \
    --model Qwen/Qwen3-0.6B \
    --algs "autoround,awq" \
    --output_dir ./tmp_autoround
```

### AutoRound API の使用方法

この設定は、精度とチューニングコストのバランスが優れており、すべてのシナリオで推奨されます。

```python
from auto_round import AutoRound

model_name = "Qwen/Qwen3-0.6B"
# mixed bits config
# layer_config = {"model.decoder.layers.6.self_attn.out_proj": {"bits": 2, "group_size": 32}}
ar = AutoRound(
    model_name,
    scheme="W4A16",
    # enable_torch_compile=True,
    # layer_config=layer_config,
)

output_dir = "./tmp_autoround"
# format= 'auto_round'(default), 'llm_compressor', "gguf:q4_k_m", 'auto_gptq', 'auto_awq'
ar.quantize_and_save(output_dir, format='auto_round') 
```

### AutoRoundのベストレシピ

この設定は、ほとんどのシナリオで最高の精度を提供しますが、標準的な AutoRound レシピよりも 4〜5 倍遅くなります。特に 2 ビット量子化に推奨され、十分なリソースが利用可能な場合の優れた選択肢です。

```python
from auto_round import AutoRound

model_name = "Qwen/Qwen3-0.6B"
ar = AutoRound(
    model_name,
    scheme="W4A16",
    nsamples=512,
    iters=1000,
)

output_dir = "./tmp_autoround"
ar.quantize_and_save(output_dir, format='auto_round') 
```

### AutoRoundLight レシピ

この設定は最速の速度（AutoRoundより2〜3倍速い）を提供しますが、小規模なモデルや2ビット量子化では精度が大幅に低下する可能性があります。4ビット設定および3B以上のモデルでの使用を推奨します。

```python
from transformers import AutoModelForCausalLM, AutoTokenizer
from auto_round import AutoRound

model_name = "Qwen/Qwen3-0.6B"
ar = AutoRound(
    model_name,
    iters=50,
    lr=5e-3,
)

output_dir = "./tmp_autoround"
ar.quantize_and_save(output_dir, format='auto_round') 
```

W4G128の13タスク（mmlu-pro、if_eval、gsm8kなど）の平均精度と時間コストの結果（PyTorch 2.6.0のenable_torch_compileを有効化した環境で、Nvidia A100 80Gを使用してテストを実施）：

| モデル   | Qwen2.5-0.5B-Instruct | Falcon3-3B    | Qwen2.5-7B-Instruct | Meta-Llama-3.1-8B-Instruct | Falcon3-10B   | Qwen2.5-72B-Instruct |
|---------|--------------------|---------------|------------------|----------------------------|---------------|-------------------|
| 16ビット  | 0.4192             | 0.5203        | 0.6470           | 0.6212                     | 0.6151        | 0.7229            |
| ベスト    | **0.4137**(7m)     | **0.5142**(23m) | 0.6426(58m)      | **0.6116**(65m)            | **0.6092**(81m) | 0.7242(575m)      |
| デフォルト | 0.4129(2m)         | 0.5133(6m)    | 0.6441(13m)      | 0.6106(13m)                | 0.6080(18m)   | **0.7252**(118m)  |
| ライト   | 0.4052(2m)         | 0.5108(3m)    | **0.6453**(5m)   | 0.6104(6m)                 | 0.6063(6m)    | 0.7243(37m)       |

## 推論

AutoRoundは、インストールされているライブラリに基づいて利用可能な最適なバックエンドを自動的に選択し、より優れたバックエンドが見つかった場合は、ユーザーに追加のライブラリのインストールを促します。

### CPU

2、4、8ビットをサポートしています。推論には、AutoRound Kernel (ARK) バックエンドの使用を推奨します。ARKを使用するには、PyTorch 2.8.0以降が必要です。

```python
from transformers import AutoModelForCausalLM, AutoTokenizer

model_name = "OPEA/Qwen2.5-1.5B-Instruct-int4-sym-inc"
model = AutoModelForCausalLM.from_pretrained(model_name, device_map="cpu", dtype="auto")
tokenizer = AutoTokenizer.from_pretrained(model_name)
text = "There is a girl who likes adventure,"
inputs = tokenizer(text, return_tensors="pt").to(model.device)
print(tokenizer.decode(model.generate(**inputs, max_new_tokens=50, do_sample=False)[0]))
```

### XPU

2、4、8ビットをサポートしています。推論には、AutoRound Kernel (ARK) バックエンドの使用を推奨します。ARKを使用するには、PyTorch 2.8.0以降が必要です。

```python
from transformers import AutoModelForCausalLM, AutoTokenizer

model_name = "OPEA/Qwen2.5-1.5B-Instruct-int4-sym-inc"
model = AutoModelForCausalLM.from_pretrained(model_name, device_map="xpu", dtype="auto")
tokenizer = AutoTokenizer.from_pretrained(model_name)
text = "There is a girl who likes adventure,"
inputs = tokenizer(text, return_tensors="pt").to(model.device)
print(tokenizer.decode(model.generate(**inputs, max_new_tokens=50, do_sample=False)[0]))
```

### CUDA

2〜8ビットをサポートしています。4ビットおよび8ビットの推論には、GPTQModelの使用を推奨します。

```python
from transformers import AutoModelForCausalLM, AutoTokenizer

model_name = "OPEA/Qwen2.5-1.5B-Instruct-int4-sym-inc"
model = AutoModelForCausalLM.from_pretrained(model_name, device_map="cuda", dtype="auto")
tokenizer = AutoTokenizer.from_pretrained(model_name)
text = "There is a girl who likes adventure,"
inputs = tokenizer(text, return_tensors="pt").to(model.device)
print(tokenizer.decode(model.generate(**inputs, max_new_tokens=50, do_sample=False)[0]))
```

### 推論バックエンドの指定

AutoRound は、互換性に基づいて各レイヤーのバックエンドを自動的に選択します。一般的には、優先順位は Marlin > ExLLaMAV2 > Triton ですが、最終的な選択は、グループサイズ、ビット幅、パッキング形式、ハードウェアデバイス、その他の実装詳細などの要因に依存します。詳細については、[backends](https://github.com/intel/auto-round?tab=readme-ov-file#specify-backend)を参照してください。

バックエンドが特定のデバイスに対して常に最適とは限りません。ニーズやハードウェアの互換性に応じて、CPUおよびXPU用の"ark"や、CUDA用の"marlin/exllamav2/triton"など、希望するバックエンドを指定できます。なお、対応する追加のライブラリが必要になる場合があります。

```python
from transformers import AutoModelForCausalLM, AutoTokenizer, AutoRoundConfig

model_name = "OPEA/Qwen2.5-1.5B-Instruct-int4-sym-inc"
quantization_config = AutoRoundConfig(backend="ark")
model = AutoModelForCausalLM.from_pretrained(model_name, device_map="cpu", quantization_config=quantization_config, dtype="auto")
tokenizer = AutoTokenizer.from_pretrained(model_name)
text = "There is a girl who likes adventure,"
inputs = tokenizer(text, return_tensors="pt").to(model.device)
print(tokenizer.decode(model.generate(**inputs, max_new_tokens=50, do_sample=False)[0]))
```

### GPTQ/AWQをAutoRoundに変換する

ほとんどのGPTQ/AWQモデルは、Intelデバイスとの互換性やサポートを向上させるために、AutoRound形式に変換できます。モデルがシリアライズされると、量子化設定が変更される点にご注意ください。

```python
from transformers import AutoModelForCausalLM, AutoTokenizer, AutoRoundConfig

model_name = "ybelkada/opt-125m-gptq-4bit"
quantization_config = AutoRoundConfig()
model = AutoModelForCausalLM.from_pretrained(model_name, device_map="cpu", quantization_config=quantization_config, dtype="auto")
tokenizer = AutoTokenizer.from_pretrained(model_name)
text = "There is a girl who likes adventure,"
inputs = tokenizer(text, return_tensors="pt").to(model.device)
print(tokenizer.decode(model.generate(**inputs, max_new_tokens=50, do_sample=False)[0]))
```

## 問題

transformers統合に関する問題が発生した場合は、[transformers](https://github.com/huggingface/transformers/issues)リポジトリで問題を報告してください。auto-roundに関する問題が発生した場合は、[AutoRound](https://github.com/intel/auto-round/issues)リポジトリで問題を報告してください。

## 謝辞

AutoGPTQ、AutoAWQ、GPTQModel、Triton、Marlin、ExLLaMAV2などのオープンソースの低精度ライブラリには、AutoRoundで活用されている低精度CUDAカーネルを提供していただき、心より感謝いたします。

## 貢献

[AutoRound](https://github.com/intel/auto-round/pulls)への貢献を大歓迎し、心より感謝いたします! バグの修正、ドキュメントの改善、新機能の追加、改善提案など、どのような形でも、あなたのサポートは常に大切にされています。