# Unsloth — дообучение в 2 раза быстрее

Unsloth переписывает критичные для производительности части HuggingFace Transformers с помощью вручную оптимизированных ядер Triton, обеспечивая **2x скорость обучения** и **сокращение использования видеопамяти на 70%** без потери точности. Это взаимозаменяемая замена — ваши существующие скрипты TRL/PEFT работают без изменений после замены импорта.

{% hint style="success" %}
Все примеры запускаются на GPU-серверах, арендованных через [CLORE.AI Marketplace](https://clore.ai/marketplace).
{% endhint %}

## Ключевые особенности

* **Обучение в 2 раза быстрее** — кастомные ядра Triton для attention, RoPE, кросс-энтропии и RMS нормализации
* **На 70% меньше видеопамяти** — интеллектуальное чекпоинтирование градиентов и отображение весов в память
* **Drop-in замена для HuggingFace** — смена только одного импорта, ничего больше
* **QLoRA / LoRA / полная дообучение** — все режимы поддерживаются из коробки
* **Нативный экспорт** — сохраняйте напрямую в GGUF (все типы квантизации), LoRA адаптеры или объединённые 16-битные модели
* **Широкое покрытие моделей** — Llama 3.x, Mistral, Qwen 2.5, Gemma 2, DeepSeek-R1, Phi-4 и другие
* **Свободное и открытое ПО** (Apache 2.0)

## Требования

| Компонент | Минимум        | Рекомендуется  |
| --------- | -------------- | -------------- |
| GPU       | RTX 3060 12 ГБ | RTX 4090 24 ГБ |
| VRAM      | 10 ГБ          | 24 ГБ          |
| ОЗУ       | 16 ГБ          | 32 ГБ          |
| Диск      | 40 ГБ          | 80 ГБ          |
| CUDA      | 11.8           | 12.1+          |
| Python    | 3.10           | 3.11           |

**Цены Clore.ai:** RTX 4090 ≈ $0.5–2/день · RTX 3090 ≈ $0.3–1/день · RTX 3060 ≈ $0.15–0.3/день

Модель 7B с 4-битным QLoRA помещается в **\~10 GB видеопамяти**, что делает жизнеспособным даже RTX 3060.

## Быстрый старт

### 1. Установите Unsloth

```bash
# Создайте venv (рекомендуется)
python -m venv /workspace/unsloth-env
source /workspace/unsloth-env/bin/activate

pip install --upgrade pip
pip install "unsloth[colab-new] @ git+https://github.com/unslothai/unsloth.git"
pip install --no-deps trl peft accelerate bitsandbytes xformers
```

### 2. Загрузите модель с 4-битной квантизацией

```python
from unsloth import FastLanguageModel
import torch

model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="unsloth/Meta-Llama-3.1-8B-Instruct-bnb-4bit",
    max_seq_length=2048,
    dtype=None,            # авто-определение (float16 на Ampere, bfloat16 на Ada)
    load_in_4bit=True,
)
```

### 3. Примените LoRA адаптеры

```python
model = FastLanguageModel.get_peft_model(
    model,
    r=16,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj",
                     "gate_proj", "up_proj", "down_proj"],
    lora_alpha=16,
    lora_dropout=0,
    bias="none",
    use_gradient_checkpointing="unsloth",   # сокращение видеопамяти на 70%
    random_state=42,
    use_rslora=False,
    loftq_config=None,
)
```

### 4. Подготовьте данные и обучите

```python
from datasets import load_dataset
from trl import SFTTrainer
from transformers import TrainingArguments

dataset = load_dataset("yahma/alpaca-cleaned", split="train")

trainer = SFTTrainer(
    model=model,
    tokenizer=tokenizer,
    train_dataset=dataset,
    dataset_text_field="text",
    max_seq_length=2048,
    dataset_num_proc=2,
    packing=True,
    args=TrainingArguments(
        per_device_train_batch_size=2,
        gradient_accumulation_steps=4,
        warmup_steps=10,
        num_train_epochs=1,
        learning_rate=2e-4,
        fp16=not torch.cuda.is_bf16_supported(),
        bf16=torch.cuda.is_bf16_supported(),
        logging_steps=10,
        optim="adamw_8bit",
        weight_decay=0.01,
        lr_scheduler_type="linear",
        seed=42,
        output_dir="/workspace/outputs",
    ),
)

stats = trainer.train()
print(f"Training loss: {stats.training_loss:.4f}")
```

## Экспорт модели

### Сохранить только LoRA адаптер

```python
model.save_pretrained("/workspace/lora-adapter")
tokenizer.save_pretrained("/workspace/lora-adapter")
```

### Объединить и сохранить полную модель (float16)

```python
model.save_pretrained_merged(
    "/workspace/merged-model",
    tokenizer,
    save_method="merged_16bit",
)
```

### Экспорт в GGUF для Ollama / llama.cpp

```python
# Квантизировать в Q4_K_M (хороший баланс размера и качества)
model.save_pretrained_gguf(
    "/workspace/gguf-output",
    tokenizer,
    quantization_method="q4_k_m",
)

# Другие опции: q5_k_m, q8_0, f16
```

После экспорта разверните с Ollama:

```bash
# Создайте Modelfile для Ollama
cat > Modelfile <<EOF
FROM /workspace/gguf-output/unsloth.Q4_K_M.gguf
TEMPLATE "{{ .System }}\n{{ .Prompt }}"
PARAMETER temperature 0.7
EOF

ollama create my-finetuned -f Modelfile
ollama run my-finetuned "Summarize the key points of transformers architecture"
```

## Примеры использования

### Дообучение на кастомном наборе данных для чата

```python
from unsloth.chat_templates import get_chat_template

tokenizer = get_chat_template(tokenizer, chat_template="llama-3.1")

def format_chat(example):
    messages = [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": example["instruction"]},
        {"role": "assistant", "content": example["output"]},
    ]
    return {"text": tokenizer.apply_chat_template(messages, tokenize=False)}

dataset = dataset.map(format_chat)
```

### DPO / ORPO выравнивающее обучение

```python
from trl import DPOTrainer, DPOConfig

dpo_trainer = DPOTrainer(
    model=model,
    ref_model=None,          # Unsloth обрабатывает референсную модель внутренне
    args=DPOConfig(
        per_device_train_batch_size=2,
        gradient_accumulation_steps=4,
        learning_rate=5e-6,
        num_train_epochs=1,
        beta=0.1,
        output_dir="/workspace/dpo-output",
    ),
    train_dataset=dpo_dataset,
    tokenizer=tokenizer,
)
dpo_trainer.train()
```

## Справочник по использованию видеопамяти

| Модель         | Квантизация | Метод | VRAM    | GPU         |
| -------------- | ----------- | ----- | ------- | ----------- |
| Llama 3.1 8B   | 4-бит       | QLoRA | \~10 ГБ | RTX 3060    |
| Llama 3.1 8B   | 16-бит      | LoRA  | \~18 GB | RTX 3090    |
| Qwen 2.5 14B   | 4-бит       | QLoRA | \~14 GB | RTX 3090    |
| Mistral 7B     | 4-бит       | QLoRA | \~9 GB  | RTX 3060    |
| DeepSeek-R1 7B | 4-бит       | QLoRA | \~10 ГБ | RTX 3060    |
| Llama 3.3 70B  | 4-бит       | QLoRA | \~44 GB | 2× RTX 3090 |

## Советы

* **Всегда используйте `use_gradient_checkpointing="unsloth"`** — это самый большой экономитель видеопамяти, уникальный для Unsloth
* **Установите `lora_dropout=0`** — Triton-ядра Unsloth оптимизированы для нулевого dropout и работают быстрее
* **Используйте `packing=True`** в SFTTrainer, чтобы избежать потерь на паддинге для коротких примеров
* **Начните с `r=16`** для ранга LoRA — повышайте до 32 или 64 только если валидационная потеря выравнивается
* **Мониторьте с помощью wandb** — добавьте `report_to="wandb"` в TrainingArguments для отслеживания loss
* **Настройка размера батча** — увеличьте `per_device_train_batch_size` пока не приблизитесь к лимиту видеопамяти, затем компенсируйте с помощью `gradient_accumulation_steps`

## Устранение неполадок

| Проблема                             | Решение                                                                                       |
| ------------------------------------ | --------------------------------------------------------------------------------------------- |
| `OutOfMemoryError` во время обучения | Уменьшите размер батча до 1, уменьшите `max_seq_length`, или используйте 4-битную квантизацию |
| Ошибки компиляции ядра Triton        | Запустите `pip install triton --upgrade` и убедитесь, что CUDA toolkit совпадает              |
| Медленный первый шаг (компиляция)    | Нормально — Triton компилирует ядра при первом запуске, затем они кешируются                  |
| `bitsandbytes` Ошибка версии CUDA    | Установите соответствующую версию: `pip install bitsandbytes --upgrade`                       |
| Пики loss во время обучения          | Понизьте скорость обучения до 1e-4, добавьте warmup шаги                                      |
| Аварии при экспорте в GGUF           | Убедитесь в наличии достаточного ОЗУ (2× размер модели) и места на диске для конверсии        |

## Ресурсы

* [Unsloth на GitHub](https://github.com/unslothai/unsloth)
* [Unsloth Wiki — Все ноутбуки](https://github.com/unslothai/unsloth/wiki)
* [CLORE.AI Marketplace](https://clore.ai/marketplace)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-ru/obuchenie/unsloth-finetune.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.