# SINQ

[Sinkhorn-Normalized Quantization (SINQ)](https://github.com/huawei-csl/SINQ/tree/main) là một kỹ thuật lượng tử hóa nhanh, có thể tích hợp ngay lập tức và không phụ thuộc vào mô hình, mang lại hiệu suất tiên tiến cho các Mô hình Ngôn ngữ Lớn mà không làm giảm độ chính xác.

### 🔍 Những gì bạn sẽ tìm thấy ở đây

- [1. Lượng tử hóa (và lưu) bất kỳ LLM nào bằng SINQ](#1-quantize-any-llm-with-sinq)
- [2. Cách trích dẫn công trình này](#2-how-to-cite-this-work)
- [3. Những hạn chế hiện tại](#3-current-limitations)

#### 📊 So sánh tính năng: SINQ so với HQQ _(không cần hiệu chuẩn)_ và A-SINQ so với AWQ _(đã hiệu chuẩn)_

| Tính năng | **SINQ** | **HQQ** | **A-SINQ** | **AWQ** |
|------------|:--------:|:--------:|:----------:|:-------:|
| 🎯 Hiệu chuẩn | Không cần hiệu chuẩn | Không cần hiệu chuẩn |  Đã hiệu chuẩn | Đã hiệu chuẩn |
| 🧮 Loại lượng tử hóa | Đối xứng & Không đối xứng | Chỉ không đối xứng | Đối xứng & Không đối xứng | Đối xứng & Không đối xứng |
| 📦 Hỗ trợ NF4 | **Có** | Không | **Có** | Không |
| ⚡ Tốc độ lượng tử hóa | ~2× **Nhanh hơn** so với HQQ | Chậm hơn | ~4× **Nhanh hơn** so với AWQ | Chậm hơn |
| 📈 Chất lượng Mô hình | **Cao hơn** | Thấp hơn | **Cao hơn** | Thấp hơn |

📄 **Bạn muốn biết thêm?**
- Đọc bài báo của chúng tôi trên [**arXiv**](http://arxiv.org/abs/2509.22944)
- Kiểm tra kho github chính thức của [**SINQ**](https://github.com/huawei-csl/SINQ/tree/main)

--- 

## 1. Lượng tử hóa bất kỳ LLM nào bằng SINQ

### Cài đặt & Bắt đầu nhanh

Đầu tiên, hãy cài đặt gói. Bạn có thể thực hiện theo hai cách:
- Từ mã nguồn bằng cách sử dụng kho lưu trữ Github chính thức [**SINQ**](https://github.com/huawei-csl/SINQ/tree/main) **[Đề xuất]**
- Sử dụng gói pip:
```bash
pip install sinq
```

---

### Lượng tử hóa chỉ với vài dòng

Việc lượng tử hóa bất kỳ mô hình 🤗 Hugging Face nào bằng SINQ rất đơn giản và chỉ cần vài dòng mã. Trước tiên, hãy tạo một [SinqConfig](/docs/transformers/v5.23.0/vi/main_classes/quantization#transformers.SinqConfig) và chỉ định các tham số sau:

| Cờ | Mô tả | Loại | Tùy chọn | Mặc định |
|------|-------------|---------|---------|----------|
| `--nbits` | Độ rộng bit cho lượng tử hóa trọng số | int | 2, 3, 4, 5, 6, 8 | 4 |
| `--tiling_mode` | Chiến lược chia nhỏ ma trận trọng số | str | 1D, 2D | 1D |
| `--group_size` | Số lượng trọng số trên mỗi nhóm lượng tử hóa | int | 64, 128 | 64 |
| `--method` | Phương pháp lượng tử hóa | str | sinq, asinq | sinq |
| `--modules_to_not_convert` | Danh sách các lớp KHÔNG được lượng tử hóa | Danh sách str | [lm_head, ...] | [lm_head] |

Sau đó, chỉ định mô hình bạn muốn lượng tử hóa và truyền SinqConfig dưới dạng tùy chọn cấu hình lượng tử hóa

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

```

✅ Xong. Mô hình của bạn giờ đã được lượng tử hóa bằng **SINQ** và sẵn sàng để suy luận hoặc lưu trữ.

> Hãy xem kho lưu trữ github chính thức [**SINQ**](https://github.com/huawei-csl/SINQ/tree/main) của chúng tôi để cập nhật thông tin mới nhất!

---

### Lưu & tải lại

Nếu bạn muốn tái sử dụng một mô hình đã lượng tử hóa sau này, hãy lưu nó xuống đĩa hoặc đẩy lên HuggingFace Hub và tải lại mà không cần trọng số FP gốc. Nếu bạn đã cài đặt SINQ từ mã nguồn, bạn nên gọi hàm *patch_hf_pretrained_io* khi tải lại một mô hình đã lượng tử hóa:
```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)
```
Ngược lại, nếu bạn đã cài đặt SINQ thông qua pip, bạn có thể đơn giản sử dụng các hàm tích hợp sẵn của 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)

```

✅ Mô hình của bạn hiện đã được tải và sẵn sàng để suy luận!

> Lưu ý: Nếu mô hình đã được lượng tử hóa ở 4 bit và thư viện `gemlite` được cài đặt, kernel nhanh hơn của gemlite sẽ được sử dụng để chạy suy luận.

---

### Tương thích với khung đánh giá [`lm-eval`](https://github.com/EleutherAI/lm-evaluation-harness)

Dưới đây là một ví dụ tối giản cho thấy cách đánh giá một mô hình đã lượng tử hóa SINQ trên một bộ dữ liệu chuẩn:

```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. Cách trích dẫn công việc này

Nếu bạn thấy **SINQ** hữu ích trong nghiên cứu hoặc ứng dụng của mình
- Hỗ trợ dự án của chúng tôi bằng cách đặt một ngôi sao ⭐️ trong kho github [**SINQ**](https://github.com/huawei-csl/SINQ/tree/main)
- Vui lòng trích dẫn bài báo của chúng tôi:

```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. Những hạn chế hiện tại

Hiện tại, phương pháp A-SINQ chưa được hỗ trợ trong Hugging Face. Vui lòng tham khảo [kho SINQ chính thức](https://github.com/huawei-csl/SINQ/tree/main) để lượng tử hóa mô hình bằng chiến lược này. Hiện chiến lược lượng tử hóa SINQ và các mô hình đã được lượng tử hóa bằng SINQ không hỗ trợ tùy chọn Multi-GPU, do đó nếu hệ thống của bạn có nhiều GPU, hãy chỉ định GPU nào cần được sử dụng.

