Unsloth: практическое руководство по дообучению LLM

Unsloth — открытый инструмент для запуска и дообучения языковых моделей с пониженным потреблением видеопамяти. Он поддерживает LoRA, QLoRA, полное дообучение, supervised fine-tuning, обучение с подкреплением и экспорт модели для локального или серверного запуска.

Что умеет Unsloth

Unsloth работает поверх экосистемы Hugging Face и оптимизирует загрузку модели, обучение и инференс. Для работы доступны несколько вариантов.

Основной практический сценарий Unsloth Core: загрузить instruct-модель в четырёхбитном формате, подключить LoRA-адаптеры, обучить их на собственном датасете и сохранить отдельно либо объединить с исходной моделью.

Сравнение Unsloth, Ollama и LM Studio

Unsloth, Ollama и LM Studio работают с открытыми моделями, но закрывают разные части процесса. Unsloth нужен для подготовки датасета, дообучения и экспорта. Ollama и LM Studio помогают запускать готовую модель на компьютере или сервере.

Перенос модели из Unsloth в Ollama

После экспорта сначала найдите фактический GGUF-файл: Unsloth создаёт артефакты в указанном каталоге, но точное имя зависит от модели и версии экспортёра.

find ./unsloth-model -name "*.gguf"

Создайте Modelfile, указав реальный путь к найденному файлу:

FROM /absolute/path/to/model-Q4_K_M.gguf

PARAMETER temperature 0.2
PARAMETER num_ctx 4096

Импортируйте и запустите модель:

ollama create my-finetuned-model -f Modelfile
ollama run my-finetuned-model

Для QLoRA это основной рекомендуемый путь: объединённая модель → GGUF → Ollama.

Прямое подключение отдельного адаптера — расширенный сценарий:

FROM <exact-base-model>
ADAPTER /path/to/safetensors/adapter/directory

Он требует точного совпадения базовой модели и поддерживаемой Ollama архитектуры. Из-за различий в квантизации Ollama рекомендует для прямого импорта прежде всего неквантизированные, то есть не QLoRA-адаптеры. Если ответы нестабильны, экспортируйте объединённую модель в GGUF.

Запуск модели в LM Studio

Импортируйте фактически созданный GGUF-файл. Команда lms import пока помечена LM Studio как экспериментальная; при ошибке используйте импорт через интерфейс или поместите файл в каталог моделей вручную.

lms import /absolute/path/to/model-Q4_K_M.gguf
lms ls

lms ls покажет идентификатор модели. После этого её можно открыть в чате, сравнить с исходной версией и поднять через локальный API:

lms load <model-identifier> --identifier="my-finetuned-model"
lms server start --port 1234

Проверочный запрос:

curl http://localhost:1234/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-finetuned-model",
    "messages": [
      {
        "role": "user",
        "content": "Выполни контрольное задание"
      }
    ]
  }'

Выбор инструмента после обучения

• LM Studio подходит для ручного тестирования, визуального сравнения моделей и работы без терминала.
• Ollama подходит для локального API, фонового сервиса, автоматизаций, агентов и подключения нескольких клиентов.
• Unsloth Studio можно оставить основным интерфейсом, если нужно продолжать обучение, сравнивать checkpoints и экспортировать новые версии.
• vLLM разумнее для высокой серверной нагрузки и нескольких одновременных пользователей.

Когда требуется дообучение

Дообучение подходит, если модель должна стабильно воспроизводить конкретное поведение:

• отвечать в заданном формате;
• выполнять узкую классификацию или извлечение данных;
• поддерживать специальный стиль диалога;
• применять повторяющуюся процедуру на примерах;
• лучше работать с терминологией определённой области.

Для часто меняющихся фактов обычно удобнее RAG, то есть передача нужных документов в контекст во время запроса. Дообучение можно объединить с RAG: адаптер отвечает за поведение и формат, а внешняя база предоставляет актуальные данные.

Перед обучением подготовьте небольшой тестовый набор запросов и запишите ответы исходной модели. Этот baseline позволит проверить, принесло ли обучение измеримое улучшение.

Полезные сценарии для пользователей

Дообучение имеет смысл, когда можно собрать примеры правильного результата и проверить качество на новых данных. Ниже приведены задачи, которые можно начать с небольшой модели и QLoRA.

Поддержка и обработка обращений

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

В обучающую выборку нельзя без подготовки переносить персональные данные, платёжные реквизиты и конфиденциальную переписку.

Извлечение структурированных данных

Unsloth подходит для адаптации компактной модели под повторяемое преобразование текста в JSON. Примеры задач:

• счёт или акт → реквизиты, сумма и дата;
• резюме → навыки и опыт;
• обращение клиента → категория и приоритет;
• описание объекта → набор характеристик;
• расшифровка встречи → решения и задачи.

Сценарий легко проверяется автоматически: JSON должен проходить валидацию, а извлечённые поля сравниваются с эталоном.

Единый формат корпоративных документов

Дообученная модель может стабильно собирать отчёты по проекту, карточки базы знаний, описания инцидентов и технические задания по фиксированной схеме.

Факты для документа лучше передавать в текущем запросе или получать через RAG. Адаптер отвечает за структуру, язык и последовательность разделов.

Локальная обработка чувствительных данных

После обучения модель можно экспортировать в GGUF и запускать без внешнего API. Такой контур подходит для документов, которые нельзя отправлять в облачные сервисы.

Адаптация небольшой модели под устройство

Компактную модель можно дообучить для одной узкой операции и запускать на ноутбуке, рабочей станции или edge-устройстве. Это полезно при работе без интернета, большом количестве одинаковых запросов и необходимости зафиксировать конкретную версию модели.

Сначала определите ограничения целевого устройства, затем подбирайте размер модели и квантизацию. Проверку проводите на том же железе, где модель будет использоваться.

Когда дообучение не окупится

Не начинайте обучение, если:

• задача решается системным промптом и несколькими примерами;
• нужные факты регулярно меняются;
• нет эталонных ответов для проверки;
• датасет состоит из случайно собранных документов;
• требуется только поиск по внутренней базе;
• предполагается один редкий запрос;
• неизвестно, какую метрику нужно улучшить.

В этих случаях сначала проверьте prompting, RAG или готовую более сильную модель. Дообучение добавляйте после появления измеримого ограничения.

Быстрый путь через Unsloth Studio

Если не нужен собственный Python-пайплайн, начните с Unsloth Studio — локального веб-интерфейса, который на момент проверки находится в Beta.

1. Установите Unsloth Desktop либо запустите Studio по официальной инструкции.
2. Выберите актуальную instruct-модель из каталога и проверьте её лицензию.
3. Загрузите JSONL, CSV или документы и просмотрите получившиеся обучающие примеры.
4. Отложите отдельный набор контрольных запросов, который не попадёт в обучение.
5. Запустите короткий QLoRA-прогон с рекомендованным пресетом.
6. Сравните базовую и дообученную модели на одинаковых запросах.
7. Экспортируйте успешную версию в GGUF для LM Studio или Ollama.

Studio удобнее для первого эксперимента, наблюдения за loss и сравнения checkpoints. Unsloth Core нужен, когда важны воспроизводимость, автоматизация, собственная обработка данных и интеграция обучения в кодовый пайплайн.

Выбор способа работы и модели

Для первого эксперимента используйте актуальный conversational notebook Unsloth. В нём уже согласованы модель, tokenizer, chat template и параметры сохранения.

Пример ниже использует Llama 3.2 3B как компактную и понятную учебную модель, а не как безусловно лучший выбор в 2026 году. Для нового проекта сначала проверьте свежие model-specific notebooks, поддержку целевого языка, лицензию и ограничения будущего контура запуска.

При самостоятельной настройке начинайте с небольшой instruct-модели и QLoRA:

• load_in_4bit=True;
• max_seq_length=2048 для первого запуска;
• LoRA rank r=16;
• один короткий тестовый прогон на 60 шагов;
• затем полноценное обучение на 1–3 эпохи.

Размер модели выбирайте по доступной видеопамяти и длине примеров. Точные требования зависят от архитектуры, batch size и context length, поэтому сверяйтесь с карточкой выбранной модели и актуальным notebook.

Установка Unsloth Core

Ниже приведён вариант для Linux или WSL. Для Windows, macOS, AMD и Intel используйте отдельные официальные инструкции.

curl -LsSf https://astral.sh/uv/install.sh | sh

uv venv unsloth_env --python 3.13
source unsloth_env/bin/activate

uv pip install unsloth --torch-backend=auto

# Зафиксировать фактически установленные версии
uv pip freeze | grep -E '^(unsloth|unsloth_zoo|trl|transformers|torch)=='
uv pip freeze > requirements-lock.txt

Проверьте, что PyTorch видит GPU:

python -c "import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'GPU not found')"

Для NVIDIA ожидается True и название видеокарты. Если выводится False, сначала проверьте драйвер, версию CUDA и выбранный PyTorch backend.

Подготовка датасета

Для диалоговой instruct-модели используйте conversational-схему: в каждой строке JSONL хранится массив messages. Это не обязательно буквальный ChatML — tokenizer преобразует сообщения в chat template конкретной модели. Не подставляйте чужой шаблон вручную.

{"messages":[{"role":"system","content":"Отвечай кратко и возвращай результат в JSON."},{"role":"user","content":"Извлеки город: встреча состоится в Казани."},{"role":"assistant","content":"{\"city\":\"Казань\"}"}]}
{"messages":[{"role":"system","content":"Отвечай кратко и возвращай результат в JSON."},{"role":"user","content":"Извлеки город: офис находится в Самаре."},{"role":"assistant","content":"{\"city\":\"Самара\"}"}]}

Правила подготовки:

• один пример содержит законченный запрос и эталонный ответ;
• формат соответствует реальному режиму использования модели;
• ответы не противоречат друг другу;
• редкие случаи представлены отдельными примерами;
• дубли, пустые строки и повреждённый JSON удалены;
• часть данных заранее отложена для проверки.

Сто примеров можно рассматривать только как техническую отправную точку для проверки пайплайна, а не как гарантию качества. Для устойчивого результата обычно нужен более крупный и разнообразный набор. Контрольную выборку отделите до обучения и сделайте достаточно большой для редких и критичных случаев: десять тестовых строк подходят только для smoke test. Качество примеров влияет сильнее простого увеличения их количества.

Запуск QLoRA-дообучения

Пример использует небольшую Llama 3.2 Instruct. Перед запуском проверьте имя модели в каталоге Unsloth.

from datasets import load_dataset
from trl import SFTConfig, SFTTrainer
from unsloth import FastLanguageModel, is_bfloat16_supported

MAX_LENGTH = 2048
MODEL_NAME = "unsloth/Llama-3.2-3B-Instruct-unsloth-bnb-4bit"

model, tokenizer = FastLanguageModel.from_pretrained(
    model_name=MODEL_NAME,
    max_seq_length=MAX_LENGTH,
    load_in_4bit=True,
)

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",
    random_state=3407,
)

raw_dataset = load_dataset(
    "json",
    data_files="train.jsonl",
    split="train",
)

split = raw_dataset.train_test_split(
    test_size=0.1,
    seed=3407,
)

def format_examples(batch):
    texts = [
        tokenizer.apply_chat_template(
            messages,
            tokenize=False,
            add_generation_prompt=False,
        )
        for messages in batch["messages"]
    ]
    return {"text": texts}

train_dataset = split["train"].map(format_examples, batched=True)
eval_dataset = split["test"].map(format_examples, batched=True)

trainer = SFTTrainer(
    model=model,
    processing_class=tokenizer,
    train_dataset=train_dataset,
    eval_dataset=eval_dataset,
    args=SFTConfig(
        dataset_text_field="text",
        max_length=MAX_LENGTH,
        per_device_train_batch_size=2,
        gradient_accumulation_steps=4,
        learning_rate=2e-4,
        warmup_steps=10,
        max_steps=60,
        logging_steps=1,
        eval_strategy="steps",
        eval_steps=20,
        per_device_eval_batch_size=1,
        fp16=not is_bfloat16_supported(),
        bf16=is_bfloat16_supported(),
        output_dir="outputs",
        optim="adamw_8bit",
        seed=3407,
        report_to="none",
    ),
)

trainer.train()

Этот упрощённый пример считает loss по всей сформированной последовательности, включая инструкции пользователя. Для рабочего instruction-tuning изучите response-only или completion-only обучение в актуальном notebook выбранной модели, чтобы оптимизировать прежде всего ответы ассистента.

После запуска должны появиться training loss, eval_loss на шагах проверки и каталог outputs с checkpoints. Наличие этих файлов подтверждает работу пайплайна, но не качество модели.

max_steps=60 подходит для проверки пайплайна. Для полноценного запуска замените его на num_train_epochs=1 и при необходимости увеличьте до трёх эпох, наблюдая за validation loss.

Проверка результата

Снижение training loss подтверждает, что модель учится на датасете, но само по себе не доказывает полезность адаптера.

Проверяйте результат в три этапа:

1. Запустите одинаковые контрольные запросы на исходной и дообученной модели.
2. Проверьте точность формата, содержание и поведение на примерах, которых не было в обучении.
3. Убедитесь, что модель сохранила базовые навыки и не воспроизводит обучающие ответы механически.

Для классификации и извлечения данных считайте метрики на отдельной отложенной выборке. Для диалогового поведения подготовьте фиксированный набор сценариев и критерии ручной оценки. Порог успешности задайте до обучения, чтобы не выбирать метрику задним числом.

Признаки переобучения:

• training loss продолжает снижаться, а validation loss растёт;
• модель повторяет фразы из датасета;
• ответы становятся однообразными;
• качество падает на новых формулировках той же задачи.

Сохранение LoRA и экспорт в GGUF

Сохранение небольшого LoRA-адаптера:

model.save_pretrained("unsloth-lora")
tokenizer.save_pretrained("unsloth-lora")

Экспорт объединённой модели в GGUF для llama.cpp, Ollama или LM Studio:

model.save_pretrained_gguf(
    "unsloth-model",
    tokenizer,
    quantization_method="q4_k_m",
)

Артефакты будут сохранены в каталоге unsloth-model; точное имя файла не следует угадывать. Найдите созданный GGUF и используйте этот путь в LM Studio или Modelfile Ollama:

find ./unsloth-model -name "*.gguf"

q4_k_m подходит как начальный баланс размера и качества. Для более точной проверки можно дополнительно экспортировать q8_0 и сравнить ответы.

Для многопользовательского серверного инференса изучите экспорт в 16-bit и запуск через vLLM. GGUF в первую очередь удобен для локального исполнения через llama.cpp-совместимые инструменты.

Лицензии, данные и воспроизводимость

Перед обучением проверьте четыре независимых права и ограничения:

• лицензию Unsloth и используемых компонентов;
• лицензию базовой модели и её Acceptable Use Policy;
• право использовать документы, переписку и код в обучающем датасете;
• условия распространения получившегося адаптера или объединённой модели.

Для Llama 3.2 действует Llama 3.2 Community License. Для другого примера условия могут отличаться. Сохраняйте рядом с результатом название и revision базовой модели, chat template, версии пакетов, параметры обучения, seed и описание датасета. Без этого эксперимент трудно воспроизвести или проверить.

Типичные проблемы

Официальные ссылки

• Документация Unsloth
• Руководство по дообучению LLM
• Подготовка датасетов
• Установка
• Экспорт в GGUF
• Troubleshooting и FAQ
• Официальный репозиторий
• Каталог notebooks
• Импорт в LM Studio
• Импорт модели в Ollama
• Unsloth Studio
• Актуальный API SFTTrainer
• Карточка и лицензия Llama 3.2 3B Instruct

По теме

Следующий шаг

Ollama — локальный и облачный рантайм для языковых моделей

Связанные материалы

• Статья: Локальные модели в работе: Mac Studio, DAWalka и DeepSeek — рассказ Миши Иванова
• База знаний: LM Studio — локальный запуск LLM и агент Bionic
• База знаний: DeepSeek — линейка открытых моделей и API

Дообучение особенно полезно, когда у команды есть повторяемая задача, качественные примеры и понятный способ оценить результат. Отдельно стоит рассчитать требования к железу и дальнейший контур запуска модели.

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov