# SINQ

[Sinkhorn-Normalized Quantization (SINQ)](https://github.com/huawei-csl/SINQ/tree/main) — это быстрый, универсальный и не требующий доработок метод квантования, обеспечивающий передовые результаты для больших языковых моделей без потери точности.

### 🔍 Что вы найдёте здесь

- [1. Квантование (и сохранение) любой LLM с помощью SINQ](#1-quantize-any-llm-with-sinq)
- [2. Как цитировать эту работу](#2-how-to-cite-this-work)
- [3. Ограничения](#3-current-limitations)

#### 📊 Сравнение возможностей: SINQ и HQQ _(без калибровки)_, а также A-SINQ и AWQ _(с калибровкой)_

| Возможность | **SINQ** | **HQQ** | **A-SINQ** | **AWQ** |
|------------|:--------:|:--------:|:----------:|:-------:|
| 🎯 Калибровка | Без калибровки | Без калибровки |  Откалиброванный | Откалиброванный |
| 🧮 Тип квантования | Симметрические и асимметрические | Только асимметричный | Симметрические и асимметрические | Симметрические и асимметрические |
| 📦 Поддержка NF4 | **Да** | Нет | **Да** | Нет |
| ⚡ Скорость квантования | ~2× **быстрее**, чем HQQ | Медленнее | ~4× **Быстрее**, чем AWQ | Медленнее |
| 📈 Качество модели | **Выше** | Ниже | **Выше** | Ниже |

📄 **Хотите узнать больше?**
- Прочитайте нашу статью на [**arXiv**](http://arxiv.org/abs/2509.22944)
- Проверьте официальный репозиторий [**SINQ**](https://github.com/huawei-csl/SINQ/tree/main) на GitHub

--- 

## 1. Квантование любой LLM с помощью SINQ

### Настройка и быстрый старт

Сначала установите пакет. Это можно сделать двумя способами:
- Из исходного кода с официального репозитория на Github [**SINQ**](https://github.com/huawei-csl/SINQ/tree/main) **[Рекомендуется]**
- Использование пакета pip:
```bash
pip install sinq
```

---

### Квантование в несколько строк

Квантование любой модели 🤗 Hugging Face с помощью SINQ — это просто, и для этого требуется всего несколько строк кода. Сначала создайте [SinqConfig](/docs/transformers/main/ru/main_classes/quantization#transformers.SinqConfig) и укажите следующие параметры:

| Флаг | Описание | Тип | Параметры | По умолчанию |
|------|-------------|---------|---------|----------|
| `--nbits` | Разрядность для квантования весов | int | 2, 3, 4, 5, 6, 8 | 4 |
| `--tiling_mode` | Стратегия тайлинга матрицы весов | str | 1D, 2D | 1D |
| `--group_size` | Весов на группу квантования | int | 64, 128 | 64 |
| `--method` | Метод квантования | str | sinq, asinq | sinq |
| `--modules_to_not_convert` | Список слоёв, которые НЕ квантуются | Список str | [lm_head, ...] | [lm_head] |

Затем укажите модель, которую вы хотите квантовать, и передайте SinqConfig в качестве параметра конфигурации квантования

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

```

✅ Всё готово. Ваша модель теперь квантована с помощью **SINQ** и готова для инференса или сохранения.

> Следите за последними обновлениями в нашем официальном репозитории [**SINQ**](https://github.com/huawei-csl/SINQ/tree/main) на GitHub!

---

### Сохранение и перезагрузка

Если вы хотите повторно использовать квантованную модель позже, сохраните её на диск или загрузите на HuggingFace Hub и перезагрузите без необходимости в базовых FP-весах. Если вы установили SINQ из исходного кода, при перезагрузке квантованной модели следует вызвать функцию *patch_hf_pretrained_io*:
```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)
```
В противном случае, если вы установили SINQ через pip, вы можете просто использовать встроенные функции 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)

```

✅ Ваша модель теперь загружена и готова для инференса!

> Примечание: если модель была квантована в 4 бита и библиотека `gemlite` установлена, для выполнения инференса используется более быстрый ядро gemlite.

---

### Совместимо с фреймворком оценки [`lm-eval`](https://github.com/EleutherAI/lm-evaluation-harness)

Ниже приведен минимальный пример, показывающий, как оценить модель, квантованную с помощью SINQ, на наборе данных для бенчмаркинга:

```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. Как цитировать эту работу

Если вы находите **SINQ** полезным в своих исследованиях или приложениях
- Поддержите наш проект, поставив звёздочку ⭐️ в репозитории [**SINQ**](https://github.com/huawei-csl/SINQ/tree/main) на GitHub
- Пожалуйста, цитируйте нашу статью:

```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. Ограничения

В настоящее время метод A-SINQ не поддерживается в Hugging Face. Для квантования модели с использованием этой стратегии обратитесь к официальному [репозиторию SINQ](https://github.com/huawei-csl/SINQ/tree/main). На данный момент стратегия квантования SINQ и модели, квантованные с её помощью, не поддерживают опцию Multi-GPU, поэтому, если в вашей системе несколько GPU, укажите, какой именно из них следует использовать.