Peft Fine Tuning

Эффективная тонкая настройка параметров для LLM с использованием LoRA, QLoRA и 25+ методов. Используйте при тонкой настройке больших моделей (7B-70B) с ограниченной памятью GPU, когда необходимо обучить <1% параметров с минимальной потерей качества или для обслуживания нескольких адаптеров. Официальная библиотека HuggingFace, интегрированная с экосистемой transformers.

Метаданные навыка


Источник	Опционально — установка через `vibeos skills install official/mlops/peft`
Путь	`optional-skills/mlops/peft`
Версия	`1.0.0`
Автор	Orchestra Research
Лицензия	MIT
Зависимости	`peft>=0.13.0`, `transformers>=4.45.0`, `torch>=2.0.0`, `bitsandbytes>=0.43.0`
Платформы	linux, macos, windows
Теги	`Fine-Tuning`, `PEFT`, `LoRA`, `QLoRA`, `Parameter-Efficient`, `Adapters`, `Low-Rank`, `Memory Optimization`, `Multi-Adapter`

Справочник: полный SKILL.md

к сведению

Ниже приведено полное определение навыка, которое VibeOS загружает при активации этого навыка. Это то, что агент видит в качестве инструкций, когда навык активен.

PEFT (Parameter-Efficient Fine-Tuning)

Тонкая настройка LLM путем обучения <1% параметров с использованием LoRA, QLoRA и 25+ методов адаптеров.

Когда использовать PEFT

Используйте PEFT/LoRA когда:

Выполняется тонкая настройка моделей 7B-70B на потребительских GPU (RTX 4090, A100)
Необходимо обучить <1% параметров (адаптеры 6MB против полной модели 14GB)
Требуется быстрая итерация с несколькими адаптерами для конкретных задач
Развертывается несколько вариантов тонкой настройки на основе одной базовой модели

Используйте QLoRA (PEFT + квантизация) когда:

Выполняется тонкая настройка моделей 70B на одном GPU с 24GB
Память является основным ограничением
Можно принять ~5% потерю качества по сравнению с полной тонкой настройкой

Вместо этого используйте полную тонкую настройку когда:

Обучаются маленькие модели (<1B параметров)
Требуется максимальное качество и есть вычислительный бюджет
Значительный сдвиг домена требует обновления всех весов

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

Установка

# Базовая установка
pip install peft

# С поддержкой квантизации (рекомендуется)
pip install peft bitsandbytes

# Полный стек
pip install peft transformers accelerate bitsandbytes datasets

Тонкая настройка LoRA (стандартная)

from transformers import AutoModelForCausalLM, AutoTokenizer, TrainingArguments, Trainer
from peft import get_peft_model, LoraConfig, TaskType
from datasets import load_dataset

# Загрузка базовой модели
model_name = "meta-llama/Llama-3.1-8B"
model = AutoModelForCausalLM.from_pretrained(model_name, torch_dtype="auto", device_map="auto")
tokenizer = AutoTokenizer.from_pretrained(model_name)
tokenizer.pad_token = tokenizer.eos_token

# Конфигурация LoRA
lora_config = LoraConfig(
    task_type=TaskType.CAUSAL_LM,
    r=16,                          # Ранг (8-64, выше = больше емкость)
    lora_alpha=32,                 # Коэффициент масштабирования (обычно 2*r)
    lora_dropout=0.05,             # Dropout для регуляризации
    target_modules=["q_proj", "v_proj", "k_proj", "o_proj"],  # Слои внимания
    bias="none"                    # Не обучать смещения
)

# Применение LoRA
model = get_peft_model(model, lora_config)
model.print_trainable_parameters()
# Вывод: trainable params: 13,631,488 || all params: 8,043,307,008 || trainable%: 0.17%

# Подготовка датасета
dataset = load_dataset("databricks/databricks-dolly-15k", split="train")

def tokenize(example):
    text = f"### Instruction:\n{example['instruction']}\n\n### Response:\n{example['response']}"
    return tokenizer(text, truncation=True, max_length=512, padding="max_length")

tokenized = dataset.map(tokenize, remove_columns=dataset.column_names)

# Обучение
training_args = TrainingArguments(
    output_dir="./lora-llama",
    num_train_epochs=3,
    per_device_train_batch_size=4,
    gradient_accumulation_steps=4,
    learning_rate=2e-4,
    fp16=True,
    logging_steps=10,
    save_strategy="epoch"
)

trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=tokenized,
    data_collator=lambda data: {"input_ids": torch.stack([f["input_ids"] for f in data]),
                                 "attention_mask": torch.stack([f["attention_mask"] for f in data]),
                                 "labels": torch.stack([f["input_ids"] for f in data])}
)

trainer.train()

# Сохранение только адаптера (6MB против 16GB)
model.save_pretrained("./lora-llama-adapter")

Тонкая настройка QLoRA (эффективное использование памяти)

from transformers import AutoModelForCausalLM, BitsAndBytesConfig
from peft import get_peft_model, LoraConfig, prepare_model_for_kbit_training

# Конфигурация 4-битной квантизации
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",           # NormalFloat4 (лучший для LLM)
    bnb_4bit_compute_dtype="bfloat16",   # Вычисления в bf16
    bnb_4bit_use_double_quant=True       # Вложенная квантизация
)

# Загрузка квантизированной модели
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.1-70B",
    quantization_config=bnb_config,
    device_map="auto"
)

# Подготовка к обучению (включает градиентную контрольную точку)
model = prepare_model_for_kbit_training(model)

# Конфигурация LoRA для QLoRA
lora_config = LoraConfig(
    r=64,                              # Более высокий ранг для 70B
    lora_alpha=128,
    lora_dropout=0.1,
    target_modules=["q_proj", "v_proj", "k_proj", "o_proj", "gate_proj", "up_proj", "down_proj"],
    bias="none",
    task_type="CAUSAL_LM"
)

model = get_peft_model(model, lora_config)
# Модель 70B теперь помещается на одном GPU с 24GB!

Выбор параметров LoRA

Ранг (r) — емкость против эффективности

Ранг	Обучаемые параметры	Память	Качество	Случай использования
4	~3M	Минимальная	Ниже	Простые задачи, прототипирование
8	~7M	Низкая	Хорошее	Рекомендуемая отправная точка
16	~14M	Средняя	Лучше	Общая тонкая настройка
32	~27M	Выше	Высокое	Сложные задачи
64	~54M	Высокая	Наивысшее	Адаптация домена, модели 70B

Alpha (lora_alpha) — коэффициент масштабирования

# Эмпирическое правило: alpha = 2 * rank
LoraConfig(r=16, lora_alpha=32)  # Стандартный
LoraConfig(r=16, lora_alpha=16)  # Консервативный (меньший эффект скорости обучения)
LoraConfig(r=16, lora_alpha=64)  # Агрессивный (больший эффект скорости обучения)

Целевые модули по архитектуре

# Llama / Mistral / Qwen
target_modules = ["q_proj", "v_proj", "k_proj", "o_proj", "gate_proj", "up_proj", "down_proj"]

# GPT-2 / GPT-Neo
target_modules = ["c_attn", "c_proj", "c_fc"]

# Falcon
target_modules = ["query_key_value", "dense", "dense_h_to_4h", "dense_4h_to_h"]

# BLOOM
target_modules = ["query_key_value", "dense", "dense_h_to_4h", "dense_4h_to_h"]

# Автоопределение всех линейных слоев
target_modules = "all-linear"  # PEFT 0.6.0+

Загрузка и слияние адаптеров

Загрузка обученного адаптера

from peft import PeftModel, AutoPeftModelForCausalLM
from transformers import AutoModelForCausalLM

# Вариант 1: Загрузка с PeftModel
base_model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.1-8B")
model = PeftModel.from_pretrained(base_model, "./lora-llama-adapter")

# Вариант 2: Прямая загрузка (рекомендуется)
model = AutoPeftModelForCausalLM.from_pretrained(
    "./lora-llama-adapter",
    device_map="auto"
)

Слияние адаптера с базовой моделью

# Слияние для развертывания (без накладных расходов адаптера)
merged_model = model.merge_and_unload()

# Сохранение объединенной модели
merged_model.save_pretrained("./llama-merged")
tokenizer.save_pretrained("./llama-merged")

# Отправка в Hub
merged_model.push_to_hub("username/llama-finetuned")

Обслуживание нескольких адаптеров

from peft import PeftModel

# Загрузка базовой модели с первым адаптером
model = AutoPeftModelForCausalLM.from_pretrained("./adapter-task1")

# Загрузка дополнительных адаптеров
model.load_adapter("./adapter-task2", adapter_name="task2")
model.load_adapter("./adapter-task3", adapter_name="task3")

# Переключение между адаптерами во время выполнения
model.set_adapter("task1")  # Использовать адаптер task1
output1 = model.generate(**inputs)

model.set_adapter("task2")  # Переключиться на task2
output2 = model.generate(**inputs)

# Отключение адаптеров (использовать базовую модель)
with model.disable_adapter():
    base_output = model.generate(**inputs)

Сравнение методов PEFT

Метод	Обучаемый %	Память	Скорость	Лучше всего подходит для
LoRA	0.1-1%	Низкая	Быстро	Общая тонкая настройка
QLoRA	0.1-1%	Очень низкая	Средне	Ограниченная память
AdaLoRA	0.1-1%	Низкая	Средне	Автоматический выбор ранга
IA3	0.01%	Минимальная	Быстрейший	Few-shot адаптация
Prefix Tuning	0.1%	Низкая	Средне	Управление генерацией
Prompt Tuning	0.001%	Минимальная	Быстро	Простая адаптация задач
P-Tuning v2	0.1%	Низкая	Средне	Задачи NLU

IA3 (минимальные параметры)

from peft import IA3Config

ia3_config = IA3Config(
    target_modules=["q_proj", "v_proj", "k_proj", "down_proj"],
    feedforward_modules=["down_proj"]
)
model = get_peft_model(model, ia3_config)
# Обучается только 0.01% параметров!

Prefix Tuning

from peft import PrefixTuningConfig

prefix_config = PrefixTuningConfig(
    task_type="CAUSAL_LM",
    num_virtual_tokens=20,      # Добавляемые токены
    prefix_projection=True       # Использовать проекцию MLP
)
model = get_peft_model(model, prefix_config)

Шаблоны интеграции

С TRL (SFTTrainer)

from trl import SFTTrainer, SFTConfig
from peft import LoraConfig

lora_config = LoraConfig(r=16, lora_alpha=32, target_modules="all-linear")

trainer = SFTTrainer(
    model=model,
    args=SFTConfig(output_dir="./output", max_seq_length=512),
    train_dataset=dataset,
    peft_config=lora_config,  # Передать конфигурацию LoRA напрямую
)
trainer.train()

С Axolotl (YAML конфиг)

# axolotl config.yaml
adapter: lora
lora_r: 16
lora_alpha: 32
lora_dropout: 0.05
lora_target_modules:
  - q_proj
  - v_proj
  - k_proj
  - o_proj
lora_target_linear: true  # Целевые все линейные слои

С vLLM (инференс)

from vllm import LLM
from vllm.lora.request import LoRARequest

# Загрузка базовой модели с поддержкой LoRA
llm = LLM(model="meta-llama/Llama-3.1-8B", enable_lora=True)

# Обслуживание с адаптером
outputs = llm.generate(
    prompts,
    lora_request=LoRARequest("adapter1", 1, "./lora-adapter")
)

Бенчмарки производительности

Использование памяти (Llama 3.1 8B)

Метод	Память GPU	Обучаемые параметры
Полная тонкая настройка	60+ GB	8B (100%)
LoRA r=16	18 GB	14M (0.17%)
QLoRA r=16	6 GB	14M (0.17%)
IA3	16 GB	800K (0.01%)

Скорость обучения (A100 80GB)

Метод	Токенов/сек	vs Полная FT
Полная FT	2,500	1x
LoRA	3,200	1.3x
QLoRA	2,100	0.84x

Качество (бенчмарк MMLU)

Модель	Полная FT	LoRA	QLoRA
Llama 2-7B	45.3	44.8	44.1
Llama 2-13B	54.8	54.2	53.5

Распространенные проблемы

CUDA OOM во время обучения

# Решение 1: Включить градиентную контрольную точку
model.gradient_checkpointing_enable()

# Решение 2: Уменьшить размер батча + увеличить накопление
TrainingArguments(
    per_device_train_batch_size=1,
    gradient_accumulation_steps=16
)

# Решение 3: Использовать QLoRA
from transformers import BitsAndBytesConfig
bnb_config = BitsAndBytesConfig(load_in_4bit=True, bnb_4bit_quant_type="nf4")

Адаптер не применяется

# Проверить, активен ли адаптер
print(model.active_adapters)  # Должно показать имя адаптера

# Проверить обучаемые параметры
model.print_trainable_parameters()

# Убедиться, что модель в режиме обучения
model.train()

Ухудшение качества

# Увеличить ранг
LoraConfig(r=32, lora_alpha=64)

# Целевые больше модулей
target_modules = "all-linear"

# Использовать больше данных и эпох
TrainingArguments(num_train_epochs=5)

# Уменьшить скорость обучения
TrainingArguments(learning_rate=1e-4)

Лучшие практики

Начинайте с r=8-16, увеличивайте, если качество недостаточно
Используйте alpha = 2 * rank в качестве отправной точки
Целевые слои внимания + MLP для лучшего качества/эффективности
Включите градиентную контрольную точку для экономии памяти
Сохраняйте адаптеры часто (маленькие файлы, легкий откат)
Оценивайте на отложенных данных перед слиянием
Используйте QLoRA для моделей 70B+ на потребительском оборудовании

Ссылки

Расширенное использование — DoRA, LoftQ, стабилизация ранга, пользовательские модули
Устранение неполадок — Распространенные ошибки, отладка, оптимизация

Ресурсы

GitHub: https://github.com/huggingface/peft
Документация: https://huggingface.co/docs/peft
Статья LoRA: arXiv:2106.09685
Статья QLoRA: arXiv:2305.14314
Модели: https://huggingface.co/models?library=peft

Метаданные навыка​

Справочник: полный SKILL.md​

PEFT (Parameter-Efficient Fine-Tuning)

Когда использовать PEFT​

Быстрый старт​

Установка​

Тонкая настройка LoRA (стандартная)​

Тонкая настройка QLoRA (эффективное использование памяти)​

Выбор параметров LoRA​

Ранг (r) — емкость против эффективности​

Alpha (lora_alpha) — коэффициент масштабирования​

Целевые модули по архитектуре​

Загрузка и слияние адаптеров​

Загрузка обученного адаптера​

Слияние адаптера с базовой моделью​

Обслуживание нескольких адаптеров​

Сравнение методов PEFT​

IA3 (минимальные параметры)​

Prefix Tuning​

Шаблоны интеграции​

С TRL (SFTTrainer)​

С Axolotl (YAML конфиг)​

С vLLM (инференс)​

Бенчмарки производительности​

Использование памяти (Llama 3.1 8B)​

Скорость обучения (A100 80GB)​

Качество (бенчмарк MMLU)​

Распространенные проблемы​

CUDA OOM во время обучения​

Адаптер не применяется​

Ухудшение качества​

Лучшие практики​

Ссылки​

Ресурсы​