# SINQ

[Sinkhorn-Normalized Quantization (SINQ)](https://github.com/huawei-csl/SINQ/tree/main) 是一种快速、即插即用且与模型无关的量化技术，能够在不牺牲精度的前提下，为大语言模型提供最先进的性能。

### 🔍 这里有什么

- [1. 使用 SINQ 量化（并保存）任意 LLM](#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 支持 | **是** | No | **是** | No |
| ⚡ 量化速度 | ~2× **更快** 于 HQQ | 较慢 | ~4× **更快** 比 AWQ | 较慢 |
| 📈 模型质量 | **更高** | 降低 | **更高** | 降低 |

📄 **想了解更多？**
- 阅读我们在 [**arXiv**](http://arxiv.org/abs/2509.22944) 上发表的论文
- 查看官方的 [**SINQ**](https://github.com/huawei-csl/SINQ/tree/main) GitHub 仓库

--- 

## 1. 使用 SINQ 量化任意 LLM

### 设置与快速入门

首先，安装该包。可以通过以下两种方式完成：
- 使用官方 Github 仓库 [**SINQ**](https://github.com/huawei-csl/SINQ/tree/main) 从源代码安装 **[推荐]**
- 使用 pip 软件包：
```bash
pip install sinq
```

---

### 几行代码完成量化

使用 SINQ 量化任何 🤗 Hugging Face 模型非常简单，只需几行代码。首先，创建一个 [SinqConfig](/docs/transformers/v5.23.0/zh/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)
```
否则，如果您通过 pip 安装了 SINQ，则可以直接使用 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. 当前局限性

目前，Hugging Face 尚不支持 A-SINQ 方法。请参阅官方的 [SINQ 仓库](https://github.com/huawei-csl/SINQ/tree/main)，以使用此策略对模型进行量化。当前，SINQ 量化策略和 SINQ 量化模型均不支持多 GPU 选项，因此如果您的系统包含多个 GPU，请指定要使用哪一个。

