# AutoRound

[AutoRound](https://github.com/intel/auto-round) é um algoritmo avançado de quantização que oferece alta precisão, mesmo em 2 bits. Ele utiliza descida de gradiente de sinal para ajustar finamente tanto os valores de arredondamento quanto os limites de corte min-max em apenas 200 passos. Projetado para ampla compatibilidade, ele suporta de forma transparente uma ampla variedade de LLMs e está em expansão ativa para cobrir mais VLMs. Ele também suporta quantização e inferência em várias plataformas de hardware, incluindo CPU, XPU e CUDA.

O AutoRound também oferece uma variedade de recursos úteis, incluindo ajuste e inferência automáticos com bits mistos, suporte para os tipos de dados MXFP4 e NVFP4, quantização sem modelo, exportação para formatos como GPTQ, AWQ, GGUF e LLM-Compressor, e receitas de ajuste flexíveis. Para uma visão abrangente e as atualizações mais recentes, consulte o [README](https://github.com/intel/auto-round) do AutoRound.

O AutoRound foi originalmente desenvolvido como parte do [Intel Neural Compressor](https://github.com/intel/neural-compressor), servindo como uma biblioteca de compressão de modelos de uso geral para aprendizado profundo. Desde então, evoluiu para uma biblioteca independente focada especificamente em otimização de baixa precisão para modelos de linguagem grandes (LLMs). O AutoRound permanece totalmente integrado ao Intel Neural Compressor, e você pode explorar o repositório para mais detalhes.

## Instalação

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

## Configurações de Quantização Suportadas

O AutoRound suporta as seguintes configurações de quantização:

1. **Pesos apenas INT2–INT8**
2. **Pesos Somente em Bits Mistos**
3. **GGUF Q\*_K**
4. **MXFP** (suporte limitado)
5. **NVFP4** (suporte limitado)

## Compatibilidade de Hardware

CPU, XPU e CUDA para quantização e inferência.

## Quantização e Serialização (offline)

Atualmente, apenas o modo offline é suportado para gerar modelos quantizados.

### Uso da Linha de Comando

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

O AutoRound também oferece outras quatro receitas, `auto-round-best`, `auto-round-light`,`auto-round-opt-rtn`,`auto-round-rtn`, projetadas para precisão ótima e velocidade aprimorada, respectivamente. Para 2 bits, recomendamos usar `auto-round-best` com `--enable_alg_ext`.

### Uso do AutoScheme

AutoScheme é um recurso que seleciona automaticamente o melhor esquema de quantização entre as opções disponíveis para cada camada a ser quantizada em minutos, sujeito a uma largura média de bits alvo.

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

### Combinações de Algoritmos

O AutoRound suporta a combinação de múltiplos algoritmos, como AutoRound, AutoRound + AWQ e AutoRound + AWQ + Hadamard (suporte muito limitado). Estamos atualmente expandindo o suporte para mais algoritmos. Isso permite uma otimização adicional dos resultados de quantização, especialmente para cenários que envolvem ativações quantizadas.

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

### Uso da API do AutoRound

Essa configuração oferece um melhor equilíbrio entre precisão e custo de ajuste e é recomendada em todos os cenários.

```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') 
```

### AutoRoundMelhor receita

Essa configuração oferece a melhor precisão na maioria dos cenários, mas é 4–5× mais lenta do que a receita padrão do AutoRound. É especialmente recomendada para quantização de 2 bits e é uma boa escolha se houver recursos suficientes disponíveis.

```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') 
```

### Receita AutoRoundLight

Esta configuração oferece a melhor velocidade (2 a 3 vezes mais rápida que o AutoRound), mas pode causar uma queda significativa de precisão em modelos pequenos e na quantização de 2 bits. É recomendada para configurações de 4 bits e modelos maiores que 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') 
```

Média de precisão do W4G128 em 13 tarefas (mmlu-pro, if_eval, gsm8k, etc.) e resultados de custo de tempo (os testes foram realizados em uma Nvidia A100 80G usando a versão 2.6.0 do PyTorch com enable_torch_compile):

| Model   | Qwen2.5-0.5B-Instruct | Falcon3-3B    | Qwen2.5-7B-Instruct | Meta-Llama-3.1-8B-Instruct | Falcon3-10B   | Qwen2.5-72B-Instruct |
|---------|--------------------|---------------|------------------|----------------------------|---------------|-------------------|
| 16bits  | 0.4192             | 0.5203        | 0.6470           | 0.6212                     | 0.6151        | 0.7229            |
| Melhor    | **0.4137**(7m)     | **0.5142**(23m) | 0.6426(58m)      | **0.6116**(65m)            | **0.6092**(81m) | 0.7242(575m)      |
| Padrão | 0.4129(2m)         | 0.5133(6m)    | 0.6441(13m)      | 0.6106(13m)                | 0.6080(18m)   | **0.7252**(118m)  |
| Leve   | 0.4052(2m)         | 0.5108(3m)    | **0.6453**(5m)   | 0.6104(6m)                 | 0.6063(6m)    | 0.7243(37m)       |

## Inferência

O AutoRound seleciona automaticamente o melhor backend disponível com base nas bibliotecas instaladas e solicita ao usuário a instalação de bibliotecas adicionais quando um backend melhor é encontrado.

### CPU

Suporta 2, 4 e 8 bits. Recomendamos usar o backend AutoRound Kernel (ARK) para inferência. É necessário PyTorch 2.8.0 ou posterior com o ARK.

```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

Suporta 2, 4 e 8 bits. Recomendamos usar o backend AutoRound Kernel (ARK) para inferência. É necessário PyTorch 2.8.0 ou posterior com o ARK.

```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

Suporta de 2 a 8 bits. Recomendamos usar o GPTQModel para inferência em 4 e 8 bits.

```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]))
```

### Especificar o backend de inferência

O AutoRound seleciona automaticamente o backend para cada camada com base na compatibilidade. Em geral, a ordem de prioridade é Marlin > ExLLaMAV2 > Triton, mas a escolha final depende de fatores como tamanho do grupo, largura de bits, formato de empacotamento, dispositivo de hardware e outros detalhes de implementação. Para mais detalhes, consulte [backends](https://github.com/intel/auto-round?tab=readme-ov-file#specify-backend),

O backend nem sempre é o mais adequado para determinados dispositivos. Você pode especificar o backend de sua preferência, como "ark" para CPU e XPU, ou "marlin/exllamav2/triton" para CUDA, de acordo com suas necessidades ou compatibilidade de hardware. Observe que bibliotecas correspondentes adicionais podem ser necessárias.

```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]))
```

### Converter GPTQ/AWQ para AutoRound

A maioria dos modelos GPTQ/AWQ pode ser convertida para o formato AutoRound para obter melhor compatibilidade e suporte com dispositivos Intel. Observe que a configuração de quantização será alterada se o modelo for serializado.

```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]))
```

## Problemas

Se você encontrar algum problema com a integração do transformers, abra uma issue no repositório [transformers](https://github.com/huggingface/transformers/issues). Se você encontrar algum problema com o auto-round, abra uma issue no repositório [AutoRound](https://github.com/intel/auto-round/issues).

## Agradecimentos

Agradecimentos especiais às bibliotecas de código aberto de baixa precisão, como AutoGPTQ, AutoAWQ, GPTQModel, Triton, Marlin e ExLLaMAV2, por fornecerem kernels CUDA de baixa precisão, que são utilizados no AutoRound.

## Contribuição

Contribuições para o [AutoRound](https://github.com/intel/auto-round/pulls) são bem-vindas e muito apreciadas! Seja corrigindo bugs, melhorando a documentação, adicionando novos recursos ou sugerindo melhorias, sua ajuda é sempre valorizada.