# SINQ

[Quantização Normalizada por Sinkhorn (SINQ)](https://github.com/huawei-csl/SINQ/tree/main) é uma técnica de quantização rápida, plug-and-play e agnóstica ao modelo, que oferece desempenho de estado da arte para Modelos de Linguagem de Grande Escala sem sacrificar a precisão.

### 🔍 O que você encontrará aqui

- [1. Quantize (e salve) qualquer LLM com SINQ](#1-quantize-any-llm-with-sinq)
- [2. Como citar este trabalho](#2-how-to-cite-this-work)
- [3. Limitações atuais](#3-current-limitations)

#### 📊 Comparativo de recursos: SINQ vs HQQ _(sem calibração)_ e A-SINQ vs AWQ _(com calibração)_

| Recurso | **SINQ** | **HQQ** | **A-SINQ** | **AWQ** |
|------------|:--------:|:--------:|:----------:|:-------:|
| 🎯 Calibração | Sem calibração | Sem calibração |  Calibrado | Calibrado |
| 🧮 Tipo de quantização | Simétrico & Assimétrico | Somente assimétrico | Simétrico & Assimétrico | Simétrico & Assimétrico |
| 📦 Suporte a NF4 | **Sim** | Não | **Sim** | Não |
| ⚡ Velocidade de quantização | ~2× **mais rápido** que HQQ | Mais lento | ~4× **mais rápido** que AWQ | Mais lento |
| 📈 Qualidade do Modelo | **Superior** | Menor | **Superior** | Menor |

📄 **Quer saber mais?**
- Leia nosso artigo no [**arXiv**](http://arxiv.org/abs/2509.22944)
- Verifique o repositório oficial do [**SINQ**](https://github.com/huawei-csl/SINQ/tree/main) no github

--- 

## 1. Quantize qualquer LLM com SINQ

### Configuração e Início Rápido

Primeiro, instale o pacote. Isso pode ser feito de duas maneiras:
- A partir do código-fonte usando o repositório oficial do Github [**SINQ**](https://github.com/huawei-csl/SINQ/tree/main) **[Recomendado]**
- Usando o pacote pip:
```bash
pip install sinq
```

---

### Quantize em poucas linhas

Quantizar qualquer modelo do 🤗 Hugging Face com SINQ é simples e leva apenas algumas linhas de código. Primeiro, crie um [SinqConfig](/docs/transformers/main/pt/main_classes/quantization#transformers.SinqConfig) e especifique os seguintes parâmetros:

| Flag | Descrição | Tipo | Opções | Padrão |
|------|-------------|---------|---------|----------|
| `--nbits` | Largura de bits para quantização de pesos | int | 2, 3, 4, 5, 6, 8 | 4 |
| `--tiling_mode` | Estratégia de tiling da matriz de pesos | str | 1D, 2D | 1D |
| `--group_size` | Pesos por grupo de quantização | int | 64, 128 | 64 |
| `--method` | Método de quantização | str | síncrono, assíncrono | sinq |
| `--modules_to_not_convert` | Lista das camadas que NÃO são quantizadas | Lista de str | [lm_head, ...] | [lm_head] |

Em seguida, especifique o modelo que deseja quantizar e passe o SinqConfig como opção de configuração de quantização

```python
import torch
from transformers import AutoTokenizer, AutoModelForCausalLM, SinqConfig

model_name = "Qwen/Qwen3-1.7B"

cfg = SinqConfig(
    nbits=4,
    group_size=64,
    tiling_mode="1D",
    method="sinq",
    modules_to_not_convert=["lm_head"]
)

tok = AutoTokenizer.from_pretrained(model_name)
qmodel = AutoModelForCausalLM.from_pretrained(
    model_name,
    quantization_config=cfg,
    dtype=torch.bfloat16
)

```

✅ É isso. Seu modelo agora está quantizado com **SINQ** e pronto para inferência ou salvamento.

> Consulte nosso repositório oficial no GitHub [**SINQ**](https://github.com/huawei-csl/SINQ/tree/main) para se manter atualizado!

---

### Salvar e recarregar

Se você deseja reutilizar um modelo quantizado mais tarde, salve-o no disco ou envie-o para o HuggingFace Hub e recarregue-o sem precisar dos pesos base em FP. Se você instalou o SINQ a partir do código-fonte, deve chamar a função *patch_hf_pretrained_io* ao recarregar um modelo quantizado:
```python
# Save sinq quantized model
model.save_pretrained("/path/to/save/qwen3-1.7B-sinq-4bit")
model.push_to_hub("HF_Hub_username/qwen3-1.7B-sinq-4bit")
tokenizer.push_to_hub("HF_Hub_username/qwen3-1.7B-sinq-4bit")
```
```python
from sinq.hf_io import patch_hf_pretrained_io
patch_hf_pretrained_io()
# Reload a sinq quantized model
hf_hub_model = "HF_Hub_username/qwen3-1.7B-sinq-4bit"
tokenizer  = AutoTokenizer.from_pretrained(hf_hub_model)
model = AutoModelForCausalLM.from_pretrained(hf_hub_model)
```
Caso contrário, se você instalou o SINQ por meio do pip, pode simplesmente usar as funções embutidas do HF:

```python
# --- Save to a folder (sharded safetensors) ---

# 'model' must already be SINQ-quantized
# Locally save
qmodel.save_pretrained("/path/to/save/qwen3-1.7B-sinq-4bit")
# Push to the Hub
qmodel.push_to_hub("HF_Hub_username/qwen3-1.7B-sinq-4bit")
tok.push_to_hub("HF_Hub_username/qwen3-1.7B-sinq-4bit")

# --- Reload later--

save_dir = "/path/to/save/qwen3-1.7B-sinq-4bit"
hf_hub_model = "HF_Hub_username/qwen3-1.7B-sinq-4bit"

# From local directory
tok = AutoTokenizer.from_pretrained(save_dir)
qmodel = AutoModelForCausalLM.from_pretrained(save_dir)

# From HF Hub
tok = AutoTokenizer.from_pretrained(hf_hub_model)
qmodel = AutoModelForCausalLM.from_pretrained(hf_hub_model)

```

✅ Seu modelo agora está carregado e pronto para inferência!

> Observação: se o modelo tiver sido quantizado em 4 bits e a biblioteca `gemlite` estiver instalada, o kernel mais rápido do gemlite é usado para executar a inferência.

---

### Compatível com o framework de avaliação [`lm-eval`](https://github.com/EleutherAI/lm-evaluation-harness)

Abaixo está um exemplo mínimo mostrando como avaliar um modelo quantizado com SINQ em um conjunto de dados de referência:

```python
import torch
from lm_eval import evaluator
from lm_eval.models.huggingface import HFLM

device = torch.accelerator.current_accelerator().type if torch.accelerator.is_available() else "cpu"

# Wrap the already quantized model and tokenizer with HFLM
lm = HFLM(pretrained=qmodel, tokenizer=tok, device=device)

# Evaluate (many tasks available on lm-eval such as MMLU and HellaSwag)
results = evaluator.simple_evaluate(
    model=lm,
    tasks=["wikitext"],  # small and fast benchmark
    device=device
)
```

## 2. Como citar este trabalho

Se você encontrar o **SINQ** útil em suas pesquisas ou aplicações
- Apoie nosso projeto dando uma estrela ⭐️ no repositório do github [**SINQ**](https://github.com/huawei-csl/SINQ/tree/main)
- Por favor, cite nosso artigo:

```bibtex
@misc{muller2025sinq,
      title={SINQ: Sinkhorn-Normalized Quantization for Calibration-Free Low-Precision LLM Weights}, 
      author={Lorenz K. Muller and Philippe Bich and Jiawei Zhuang and Ahmet Celik and Luca Benfenati and Lukas Cavigelli},
      year={2025},
      eprint={2509.22944},
      archivePrefix={arXiv},
      primaryClass={cs.LG},
      url={http://arxiv.org/abs/2509.22944}
}
```

## 3. Limitações atuais

Atualmente, o método A-SINQ não é suportado no Hugging Face. Consulte o [repositório oficial do SINQ](https://github.com/huawei-csl/SINQ/tree/main) para quantizar um modelo com essa estratégia. No momento, a estratégia de quantização SINQ e os modelos quantizados com SINQ não suportam a opção Multi-GPU, portanto, se o seu sistema possui múltiplas GPUs, especifique qual delas deve ser utilizada.