self-llm: Qwen3-8B — LoRA-дообучение и графики в SwanLab

О переводе

Полный перевод рецепта из сборника self-llm (Apache-2.0). Переведены текст и комментарии в коде; китайские строки данных оставлены (их видит модель), перевод — в комментариях. Полный рабочий код лежит в ноутбуке 05-Qwen3-8B-LoRA.ipynb рядом с рецептом — недостающие в тексте рецепта куски (загрузка датасета, get_peft_model) мы взяли оттуда и отметили. Наши пояснения — «Примечание переводчика».

Настройка окружения

# Переключаемся на зеркало Цинхуа
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

pip install modelscope==1.25.0
pip install transformers==4.51.3
pip install accelerate==1.6.0
pip install datasets==3.5.1
pip install peft==0.15.2
pip install swanlab==0.5.7

Поскольку у некоторых при настройке окружения бывают проблемы, мы подготовили на платформе AutoDL образ окружения для Qwen3: перейдите по ссылке ниже и сразу создайте экземпляр AutoDL. https://www.codewithgpu.com/i/datawhalechina/self-llm/Qwen3

Примечание переводчика

Зеркало Цинхуа вне Китая не нужно — пропустите первую строку. Версии закреплены на апрель 2025 года; Qwen3 требует transformers>=4.51. Ставьте всё в отдельное виртуальное окружение. PyTorch с CUDA должен быть установлен заранее.

Скачивание модели

model_download.py

# Не забудьте заменить cache_dir на свой путь
from modelscope import snapshot_download
model_dir = snapshot_download('Qwen/Qwen3-8B', cache_dir='ПОМЕНЯЙ_МЕНЯ', revision='master')  # укажите свой путь

print(f"Модель скачана, путь: {model_dir}")

Построение датасета

Данные для supervised-finetuning (sft, обучение с учителем) больших языковых моделей имеют такой формат:

{
  "instruction": "Ответь на вопрос пользователя, выведи только ответ.",
  "input": "Сколько будет 1+1?",
  "output": "2"
}

Примечание переводчика: язык данных

В оригинале все примеры данных, подсказки в коде и ответ модели — на китайском, как и сам датасет huanhuan.json. Мы перевели их на русский. Если обучать на оригинальном датасете, модель будет отвечать по-китайски; чтобы получить русскоязычного «персонажа», соберите такой же JSON из русских реплик.

Здесь instruction — указание пользователя: какую задачу должна решить модель; input — входные данные пользователя, нужные для выполнения указания; output — ответ, который должна дать модель.

Цель обучения с учителем — научить модель понимать указания пользователя и следовать им. Поэтому датасет нужно строить прицельно под нашу задачу. Например, если мы хотим на большом корпусе диалогов персонажей дообучить модель, которая умеет отыгрывать (role-play) манеру речи Чжэнь Хуань, пример данных в этом сценарии будет таким:

{
  "instruction": "Кто твой отец?",
  "input": "",
  "output": "Мой отец — Чжэнь Юаньдао, заместитель главы Далисы."
}

(Далисы — Палата судебного надзора.)

Все примеры датасетов для дообучения лежат в /dataset.

Примечание переводчика

huanhuan.json — 3729 реплик героини исторического сериала «Легенда о Чжэнь Хуань», в основном с пустым полем input. Это учебный датасет на «стиль речи»: эффект LoRA видно сразу, даже без метрик. Чем SFT отличается от предобучения и зачем нужен формат «указание — ответ» — уроки 6.1.1 и 6.1.2.

Подготовка данных

Данные для обучения LoRA (Low-Rank Adaptation) нужно отформатировать и закодировать, прежде чем подавать в модель: входной текст кодируем в input_ids, выходной — в labels; после кодирования получаются векторы. Сначала определим функцию предобработки: для каждого примера она кодирует и вход, и выход и возвращает словарь с закодированными данными:

def process_func(example):
    MAX_LENGTH = 1024 # максимальная длина последовательности — 1024 токена
    input_ids, attention_mask, labels = [], [], [] # инициализируем возвращаемые значения
    # подгоняем под chat_template
    instruction = tokenizer(
        f"<s><|im_start|>system\nТеперь ты играешь женщину при императоре — Чжэнь Хуань<|im_end|>\n"
        f"<|im_start|>user\n{example['instruction'] + example['input']}<|im_end|>\n"
        f"<|im_start|>assistant\n<think>\n\n</think>\n\n",
        add_special_tokens=False
    )
    response = tokenizer(f"{example['output']}", add_special_tokens=False)
    # склеиваем input_ids части instruction и части response и добавляем в конец токен eos как признак конца
    input_ids = instruction["input_ids"] + response["input_ids"] + [tokenizer.pad_token_id]
    # маска внимания: на какие позиции модель должна смотреть
    attention_mask = instruction["attention_mask"] + response["attention_mask"] + [1]
    # для instruction ставим -100: на этих позициях loss не считается (модели не нужно их предсказывать)
    labels = [-100] * len(instruction["input_ids"]) + response["input_ids"] + [tokenizer.pad_token_id]
    if len(input_ids) > MAX_LENGTH:  # обрезаем, если длиннее максимума
        input_ids = input_ids[:MAX_LENGTH]
        attention_mask = attention_mask[:MAX_LENGTH]
        labels = labels[:MAX_LENGTH]
    return {
        "input_ids": input_ids,
        "attention_mask": attention_mask,
        "labels": labels
    }

Примечание переводчика: разберём функцию на примере

Пусть instruction закодировалась в 30 токенов, а ответ «Мой отец — Чжэнь Юаньдао, заместитель главы Далисы.» — в 10. Тогда:

• input_ids — 30 + 10 + 1 = 41 число (последнее — pad_token_id, у Qwen3 это <|endoftext|>, используется как «конец ответа»);
• labels — 30 раз -100, затем те же 10 токенов ответа и токен конца.

PyTorch в cross_entropy пропускает позиции с меткой -100, поэтому модель учится только на ответе, а не на повторении подсказки. Это то самое маскирование подсказки из урока 6.1.2.

Две мелочи: строка <s> в начале — не служебный токен Qwen (наследство шаблонов LLaMA), она просто кодируется как обычный текст; вреда нет, но и смысла тоже. А пустой блок <think>\n\n</think> учит модель отвечать без размышления — как в режиме enable_thinking=False.

Chat Template (шаблон диалога) у Qwen3 такой.

Поскольку Qwen3 — гибридная модель рассуждений, режим размышления можно включать вручную.

Без thinking mode:

messages = [
    {"role": "system", "content": "===system_message_test==="},
    {"role": "user", "content": "===user_message_test==="},
    {"role": "assistant", "content": "===assistant_message_test==="},
]

text = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True,
    enable_thinking=False
)
print(text)

<|im_start|>system
===system_message_test===<|im_end|>
<|im_start|>user
===user_message_test===<|im_end|>
<|im_start|>assistant
<think>

</think>

===assistant_message_test===<|im_end|>
<|im_start|>assistant
<think>

</think>

С thinking mode:

messages = [
    {"role": "system", "content": "===system_message_test==="},
    {"role": "user", "content": "===user_message_test==="},
    {"role": "assistant", "content": "===assistant_message_test==="},
]

text = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True,
    enable_thinking=True
)
print(text)

<|im_start|>system
===system_message_test===<|im_end|>
<|im_start|>user
===user_message_test===<|im_end|>
<|im_start|>assistant
<think>

</think>

===assistant_message_test===<|im_end|>
<|im_start|>assistant

Примечание переводчика: как читать эти два вывода

Разница — только в самом конце: в режиме без размышления шаблон после «приглашения ассистента» сразу вставляет пустой <think></think>, а в режиме с размышлением оставляет место, чтобы модель начала свой <think> сама. Пустой блок у прошлой реплики ассистента шаблон Qwen3 добавляет в обоих режимах (старые размышления в историю диалога не попадают). Функция process_func выше вручную воспроизводит именно вариант без размышления.

Примечание переводчика: загрузка датасета (из ноутбука)

В тексте рецепта пропущено, как из JSON получается tokenized_id. В ноутбуке это так:

from datasets import Dataset
import pandas as pd

df = pd.read_json('./huanhuan.json')  # не забудьте поправить путь
ds = Dataset.from_pandas(df)
tokenized_id = ds.map(process_func, remove_columns=ds.column_names)

Загрузка модели и токенизатора

tokenizer = AutoTokenizer.from_pretrained('ПОМЕНЯЙ_МЕНЯ/Qwen/Qwen3-8B')  # ваш путь к модели

model = AutoModelForCausalLM.from_pretrained('ПОМЕНЯЙ_МЕНЯ/Qwen/Qwen3-8B', device_map="auto", torch_dtype=torch.bfloat16)

LoRA Config

В классе LoraConfig много параметров, самые важные:

• task_type: тип модели; сейчас почти все модели decoder_only — каузальные языковые модели, CAUSAL_LM;
• target_modules: имена слоёв модели, которые нужно обучать, — в основном слои части attention; у разных моделей слои называются по-разному;
• r: ранг LoRA — размерность низкоранговых матриц; меньший r — меньше параметров;
• lora_alpha: параметр масштаба; вместе с r определяет силу обновления LoRA. Фактический множитель — lora_alpha/r, в нашем примере 32 / 8 = 4 раза;
• lora_dropout: доля dropout в слоях LoRA, защищает от переобучения.

config = LoraConfig(
    task_type=TaskType.CAUSAL_LM,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj"],
    inference_mode=False, # режим обучения
    r=8, # ранг LoRA
    lora_alpha=32, # alpha LoRA
    lora_dropout=0.1 # доля Dropout
)

Примечание переводчика: что это значит в числах

LoRA заменяет обновление матрицы $W$ размера $d_{out} \times d_{in}$ произведением $BA$, где $B$ — $d_{out} \times r$, $A$ — $r \times d_{in}$, а результат умножается на $\alpha / r$:

$$W' = W + \frac{\alpha}{r}\,BA .$$

Для q_proj у Qwen3-8B ($4096 \to 4096$) при $r = 8$ это $8 \cdot (4096 + 4096) = 65\,536$ обучаемых чисел вместо 16,8 млн. По нашей оценке (36 слоёв, hidden_size 4096, intermediate_size 12288, 8 голов K/V по 128), всего обучается около 22 млн параметров — примерно 0,27 % модели. Точное число покажет model.print_trainable_parameters(). Хотя в описании сказано «в основном слои attention», в target_modules перечислены и слои MLP (gate_proj, up_proj, down_proj) — так LoRA работает заметно лучше. Подробнее — урок 6.2.1.

Примечание переводчика: две строки из ноутбука

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

model.enable_input_require_grads()  # нужно при включённом gradient checkpointing
model = get_peft_model(model, config)  # оборачиваем модель: обучаться будут только LoRA-матрицы
model.print_trainable_parameters()

Без get_peft_model Trainer попытается обучать все 8 млрд параметров и упадёт по памяти.

Training Arguments

• output_dir: куда сохранять модель;
• per_device_train_batch_size: batch_size на одну карту;
• gradient_accumulation_steps: накопление градиента;
• num_train_epochs: как видно из названия, число epoch.

args = TrainingArguments(
    output_dir="./output/Qwen3_8B_LoRA", # не забудьте поправить
    per_device_train_batch_size=4,
    gradient_accumulation_steps=4,
    logging_steps=10,
    num_train_epochs=3,
    save_steps=100,
    learning_rate=1e-4,
    save_on_each_node=True,
    gradient_checkpointing=True,
    report_to="none",
)

Знакомство со SwanLab

Рисунок в оригинале (images/05-2.png): логотип и интерфейс SwanLab.

SwanLab — открытый инструмент для записи обучения моделей, рассчитанный на исследователей ИИ: визуализация обучения, автоматическое логирование, запись гиперпараметров, сравнение экспериментов, совместная работа. В SwanLab исследователь по наглядным графикам находит проблемы обучения, сравнивает эксперименты в поисках идей и, делясь онлайн-ссылками и обучая модели в рамках организации, ломает барьеры в общении команды.

Зачем записывать обучение

По сравнению с разработкой программ обучение моделей больше похоже на экспериментальную науку. За каждой хорошей моделью — тысячи экспериментов. Исследователь постоянно пробует, записывает, сравнивает и копит опыт, чтобы найти лучшую архитектуру, гиперпараметры и пропорции данных. Насколько эффективно ведётся запись и сравнение — от этого сильно зависит скорость исследований.

Создаём SwanLabCallback

Советуем сначала зарегистрироваться на сайте SwanLab, а при инициализации обучения выбрать (2) Use an existing SwanLab account и войти с личным (private) API Key.

import swanlab
from swanlab.integration.transformers import SwanLabCallback

# Создаём SwanLabCallback
swanlab_callback = SwanLabCallback(
    project="Qwen3-Lora",  # не забудьте поправить
    experiment_name="Qwen3-8B-LoRA-experiment"  # не забудьте поправить
)

Примечание переводчика

SwanLab — китайский аналог Weights & Biases. Если не хотите регистрироваться, у него есть локальный режим без облака (см. документацию SwanLab), а можно вообще обойтись встроенным TensorBoard: report_to="tensorboard" в TrainingArguments вместо колбэка. Важно не чем смотреть, а что смотреть: как читать кривые лосса — урок 6.2.2.

Обучение через Trainer

trainer = Trainer(
    model=model,
    args=args,
    train_dataset=tokenized_id,
    data_collator=DataCollatorForSeq2Seq(tokenizer=tokenizer, padding=True),
    callbacks=[swanlab_callback] # передаём созданный выше swanlab_callback
)
trainer.train()

TrainOutput(global_step=699, training_loss=2.6425710331557988, metrics={'train_runtime': 879.9696, 'train_samples_per_second': 12.713, 'train_steps_per_second': 0.794, 'total_flos': 5.190619083415757e+16, 'train_loss': 2.6425710331557988, 'epoch': 2.990353697749196})

Примечание переводчика: проверим числа

Батч на шаг — 4 × 4 = 16 примеров. 3729 примеров / 16 ≈ 233 шага на эпоху, × 3 эпохи = 699 шагов — ровно global_step. Обучение заняло 880 секунд (~15 минут; на какой видеокарте — в рецепте не сказано). DataCollatorForSeq2Seq дополняет labels значением -100, так что паддинг тоже не попадает в loss.

После обучения откройте SwanLab — там видны записанные параметры и график лосса во время обучения:

Рисунок в оригинале (images/05-1.png): кривая train/loss в SwanLab.

Публичная ссылка на запись обучения из примера, для справки:

Графики — Qwen3-Lora/Qwen3-8B-LoRA-shufan.jiang

Инференс с LoRA-весами

Получив любую контрольную точку (checkpoint), загружаем веса lora для инференса:

from transformers import AutoModelForCausalLM, AutoTokenizer
import torch
from peft import PeftModel

mode_path = 'ПОМЕНЯЙ_МЕНЯ/Qwen/Qwen3-8B'  # не забудьте поправить
lora_path = './output/Qwen3_8B_lora/checkpoint-699' # не забудьте поправить

# Загружаем токенизатор
tokenizer = AutoTokenizer.from_pretrained(mode_path)

# Загружаем базовую модель Qwen3
model = AutoModelForCausalLM.from_pretrained(mode_path, device_map="auto",torch_dtype=torch.bfloat16, trust_remote_code=True)

# Загружаем веса LoRA
model = PeftModel.from_pretrained(model, model_id=lora_path)

prompt = "Кто ты?"
inputs = tokenizer.apply_chat_template(
                                    [{"role": "user", "content": "Представь, что ты женщина при императоре — Чжэнь Хуань."},{"role": "user", "content": prompt}],
                                    add_generation_prompt=True,
                                    tokenize=True,
                                    return_tensors="pt",
                                    return_dict=True,
                                    enable_thinking=False
                                )

# Параметры генерации
gen_kwargs = {"max_length": 2500, "do_sample": True, "top_k": 1}
with torch.no_grad():
    outputs = model.generate(**inputs, **gen_kwargs)
    outputs = outputs[:, inputs['input_ids'].shape[1]:]
    print(tokenizer.decode(outputs[0], skip_special_tokens=True))

Я Чжэнь Хуань, мой отец — Чжэнь Юаньдао, заместитель главы Далисы.

(Ответ переведён: модель, обученная на оригинальном датасете, отвечает по-китайски.)

Примечание переводчика: мелкие нестыковки в коде

• Папка вывода при обучении названа Qwen3_8B_LoRA, а при загрузке — Qwen3_8B_lora: на Linux регистр важен, так что выберите одно написание.
• inputs создаются на CPU, а модель — на GPU; с device_map="auto" generate обычно сам переносит тензоры, но надёжнее написать inputs = inputs.to(model.device).
• do_sample=True вместе с top_k=1 — это по сути жадный выбор: из одного кандидата выбирать нечего.
• При обучении системная подсказка шла как роль system, а при проверке роль задана сообщением user. Модель всё равно отвечает «в образе», но честнее проверять в том же формате, что и при обучении.

От переводчика: как запустить на своей машине

🖥 На вашей машине (4×GPU)

• Qwen3-8B в bfloat16 (~16 ГБ) + LoRA + gradient_checkpointing с батчем 4 и длиной до 1024 токенов должна поместиться на одну RTX 4080 32 ГБ. Чтобы device_map="auto" не размазал модель по всем четырём картам (это медленно), запускайте CUDA_VISIBLE_DEVICES=0 python train.py.
• Хотите быстрее — возьмите Qwen3-1.7B или Qwen3-4B: тот же код, обучение за минуты. Хотите все 4 карты — запустите тот же скрипт через torchrun --nproc_per_node 4 train.py (DDP, урок 5.7.4), предварительно убрав device_map="auto" из from_pretrained (иначе каждый процесс попытается занять все карты): каждая карта держит свою копию модели, а эффективный батч вырастет в 4 раза.
• Готовый адаптер можно подать в vLLM без слияния с базовой моделью: vllm serve ~/models/Qwen3-8B --enable-lora --lora-modules huanhuan=./output/Qwen3_8B_LoRA/checkpoint-699 — и обращаться к модели по имени huanhuan.

Что сделать руками:

1. Повторите рецепт на Qwen3-1.7B. Сравните ответы базовой и дообученной модели на 5 вопросах в стиле датасета.
2. Поменяйте r (4, 8, 32) и lora_alpha, сравните кривые лосса в SwanLab или TensorBoard — урок 6.2.2.
3. Соберите свой маленький датасет в том же формате (например, 200 вопросов и ответов по курсу на русском) и дообучите модель на нём. Проверьте, не «забыла» ли модель общие знания после дообучения.

Словарик

Русский	Пояснение
обучение с учителем, SFT	дообучение на парах «указание — ответ»
низкоранговая адаптация (LoRA)	обучаем маленькие матрицы $A$, $B$
ранг (rank, r)	внутренняя размерность $A$ и $B$
масштаб (lora_alpha)	множитель $\alpha / r$
накопление градиента	несколько микробатчей на шаг
пересчёт активаций	экономия памяти ценой времени
контрольная точка (checkpoint)	сохранённые веса адаптера
гибридная модель рассуждений	умеет отвечать с размышлением и без
запись и визуализация обучения	SwanLab, W&B, TensorBoard
отыгрыш роли (role-play)	модель говорит «в образе»