Llama Cookbook: путеводитель

Llama Cookbook — официальный репозиторий Meta с рецептами для моделей семейства Llama. Раньше он назывался llama-recipes; после переименования структуру перестроили, а снимок старой версии оставили в ветке archive-main — поэтому старые ссылки из статей и ответов на форумах часто ведут в никуда.

Эта страница — путеводитель. Она построена по README-файлам и ноутбукам репозитория (ветка main, коммит 2f22a9e). Обзор «LLM Fine-Tuning» переведён полностью (тексты репозитория распространяются по лицензии MIT), ноутбук быстрого LoRA-дообучения пересказан по шагам с ключевым кодом.

Что это и для кого

• Для кого. Для тех, кто уже умеет обучать модели на PyTorch (ступень 3) и знает, как устроена языковая модель (ступень 4). Самые полезные части — дообучение (ступень 6) и приложения (ступень 8).
• Что нужно. Веса Llama лежат на Hugging Face в закрытых репозиториях meta-llama/*: их выдают после принятия лицензии на странице модели. Часть рецептов работает через платные облачные API (Llama API, Together, Groq, DeepInfra) — их можно читать как образец, а запускать с локальной моделью через OpenAI-совместимый сервер (урок «OpenAI-совместимые API»).
• Чем отличается от курса. Курс ChinaAI учит на моделях Qwen и DeepSeek; кукбук — на Llama. Идеи и код почти переносимы: меняется имя модели и шаблон чата.

Лицензии: код и веса — разные вещи

Файл LICENSE репозитория — MIT. Но в шапках некоторых ноутбуков написано, что материал распространяется по Llama Community License, а сами веса моделей — всегда по лицензиям Llama (своя для каждой версии: Llama 2, 3, 3.1, 3.2, 3.3, 4) и правилам допустимого использования (Acceptable Use Policy). Если публикуете дообученную модель, прочитайте лицензию той версии, от которой отталкивались.

Карта репозитория

flowchart TB
R["llama-cookbook"] --> G["getting-started/<br/>первые шаги"]
R --> E["end-to-end-use-cases/<br/>сквозные проекты"]
R --> P["3p-integrations/<br/>облака и фреймворки"]
R --> S["src/llama_cookbook/<br/>библиотека: обучение, FSDP, датасеты"]
G --> G1["inference/"]
G --> G2["finetuning/"]
G --> G3["RAG/"]
G --> G4["responsible_ai/"]
G --> G5["distillation/"]

Четыре верхние папки репозитория и главное внутри getting-started

getting-started — начинать здесь

Раздел оригинала	О чём	Урок курса	Важность
build_with_llama_4.ipynb	Возможности Llama 4 Scout: длинный контекст, несколько картинок в запросе, вызов функций	MoE, длинный контекст	★★
build_with_llama_api.ipynb	Знакомство с облачным Llama API	8.1	★
inference/local_inference/	Локальный инференс через Hugging Face, в том числе мультимодальной Llama 3.2 11B Vision и с LoRA-весами	7.2	★★
finetuning/	Дообучение на одной и нескольких GPU, LoRA и QLoRA, FSDP, свой датасет, дообучение Vision-модели	6.2, 5.4	★★★
finetuning/quickstart_peft_finetuning.ipynb	Ноутбук: LoRA-дообучение Llama 3.1 8B на одной GPU (разбор ниже)	6.2	★★★
RAG/hello_llama_cloud.ipynb	Простейшее RAG-приложение	8.2	★
distillation/	Дистилляция Llama 4 в маленькую Llama 3.2 на синтетических данных из Synthetic Data Kit	6.4	★★
responsible_ai/	Инструменты Purple Llama: Llama Guard (фильтр входов и выходов), Prompt Guard (защита от джейлбрейков и промпт-инъекций), Code Shield (небезопасный код)	8.3	★★
llama-tools/	llama-prompt-ops — автоматическая адаптация промптов под Llama	8.4	★

end-to-end-use-cases — сквозные проекты

Раздел	О чём	Урок курса	Важность
agents/Agents_Tutorial/	Tool Calling 101 и 201: вызов функций и агент, который ищет две статьи и сравнивает их	8.3	★★★
RAFT-Chatbot/	RAFT (Retrieval Augmented Fine Tuning): дообучение модели отличать полезные документы от отвлекающих	8.2, 6.1	★★
Contextual-Chunking-RAG/	Ключевые слова для каждого фрагмента, чтобы фрагменты не теряли контекст документа	8.2	★★
Multi-Modal-RAG/	RAG по картинкам и тексту	9.1	★
NotebookLlama/	Открытый аналог NotebookLM: PDF → чистый текст (1B) → сценарий подкаста (70B) → «драматизация» (8B) → синтез речи	8.3	★★
benchmarks/	Замер пропускной способности инференса и оценка качества через lm-evaluation-harness	7.3	★★
long_context/H2O/	Heavy-Hitter Oracle: KV-кэш хранит только «тяжёлые» и последние токены	KV-кэш, 5.5	★★
multilingual/	Как добавить в Llama новый язык (на примере хинди): свой токенизатор, расширение словаря, дообучение в два этапа	токенизаторы	★★
остальные	Бот для WhatsApp, анализ статей и книг на Llama 4, браузерный агент, text2sql, разбор issues на GitHub, суммаризация, извлечение структуры	8.x	★

3p-integrations и src

• 3p-integrations/ — рецепты от партнёров: AWS Bedrock, Azure, GCP, Groq, Together, vLLM, TGI, LangChain/LangGraph, LlamaIndex. Ценны как образцы; самый полезный для нашей машины — vllm/ (урок «vLLM, SGLang и непрерывный батчинг»).
• src/llama_cookbook/ — исходники библиотеки llama-cookbook (её ставят через pip install llama-cookbook): скрипт обучения finetuning.py, конфиги (configs/training.py, peft.py, fsdp.py), датасеты и политики FSDP. В src/docs/ — FAQ по дообучению.

---

Перевод: обзор «LLM Fine-Tuning»

Оригинал: getting-started/finetuning/LLM_finetuning_overview.md, MIT.

Здесь мы обсуждаем дообучение Meta Llama по нескольким разным рецептам. Рассмотрим два сценария.

1. Параметрически эффективное дообучение (PEFT)

Оно делает дообучение доступнее — даже на одной потребительской видеокарте. Эти методы позволяют держать всю модель замороженной и добавлять в неё лишь крошечные обучаемые параметры или слои. Так обучается лишь очень маленькая часть параметров. Самые известные методы этого класса — LoRA, Llama Adapter и Prefix-tuning.

Эти методы решают три задачи:

• Стоимость полного дообучения. Обучается только небольшой набор дополнительных параметров, а не вся модель, — это позволяет запускать обучение на потребительских GPU.
• Стоимость развёртывания. Для каждой дообученной модели под отдельную задачу пришлось бы разворачивать отдельную модель. С этими методами работу делает лишь небольшой набор параметров (несколько мегабайт вместо нескольких гигабайт) поверх предобученной модели. Для каждой задачи мы только добавляем эти дополнительные параметры, поэтому предобученную модель можно считать «хребтом» (backbone), а эти параметры — «головами» модели для разных задач.
• Катастрофическое забывание. Эти методы также помогают против забывания первой задачи, которое может случиться при дообучении.

Библиотека Hugging Face PEFT даёт простой способ пользоваться этими методами, и мы ею пользуемся. Подробнее — в блоге Hugging Face.

2. Полное или частичное дообучение параметров

У полного дообучения параметров свои преимущества. В нём есть несколько стратегий:

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

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

(В оригинале здесь три схемы — feature_based_fn.png, feature_based_fn_2.png, full_param_fn.png в папке src/docs/img: замороженная модель с обучаемой головой, замороженная модель с добавленными слоями и полностью обучаемая модель.)

В этом сценарии, в зависимости от размера модели, вам может понадобиться больше одной GPU — особенно если модель не помещается для обучения в одну видеокарту. Так, Meta Llama 3 на 8 млрд параметров в одну GPU не поместится. Думать об этом нужно так: памяти GPU должно хватить на параметры модели, градиенты и состояния оптимизатора. Каждое из них, в зависимости от точности обучения, может занимать несколько раз «число параметров × размер числа» (fp32 — 4 байта, fp16 — 2 байта, bf16 — 2 байта). Например, оптимизатор AdamW хранит по 2 числа на каждый параметр, и часто они хранятся в fp32. Поэтому, в зависимости от того, сколько слоёв вы обучаете (размораживаете), нужная память может перерасти одну GPU.

FSDP (Fully Sharded Data Parallel)

В PyTorch есть пакет FSDP для обучения моделей, которые не помещаются в одну GPU. FSDP позволяет обучить гораздо более крупную модель на тех же ресурсах. До FSDP был DDP (Distributed Data Parallel): каждая GPU держала полную копию модели, а делились только данные. В конце обратного прохода градиенты синхронизировались.

FSDP развивает эту идею: делятся не только данные, но и параметры модели, градиенты и состояния оптимизатора. Каждая GPU хранит только свой шард (кусок) модели. Это даёт огромную экономию памяти и позволяет уместить гораздо более крупную модель в то же число GPU. Например, с DDP максимум, что помещается в GPU с 16 ГБ памяти, — модель примерно на 700 млн параметров. Даже если у вас 4 GPU, вы всё равно не выйдете за размер модели, которая помещается в одну GPU. А с FSDP в 4 GPU можно уместить модель на 3 млрд параметров — более чем в 4 раза крупнее.

Подробнее о FSDP — в блоге PyTorch, начать работу — с туториала.

Чтобы ускорить дообучение с FSDP, можно использовать ряд возможностей:

• Смешанная точность. В FSDP она гораздо гибче, чем autocast: пользователь сам задаёт точность для параметров модели, буферов и градиентов.
• Чекпоинтинг активаций (activation checkpointing) — способ сэкономить память: промежуточные активации прямого прохода не хранятся, а выбрасываются, и их пересчитывают при обратном проходе. Чекпоинтинг активаций в FSDP учитывает шардирование, поэтому применять его нужно после того, как модель обёрнута в FSDP. В нашем скрипте так и сделано.
• auto_wrap_policy — способ указать, как FSDP разбивает модель. По умолчанию есть политика обёртки для трансформеров: FSDP формирует каждый свой блок (часть модели) по классу трансформерного слоя. Чтобы найти этот класс в модели, ищите слой, который содержит и слой внимания, и MLP. Так у FSDP получаются более мелкие блоки для обмена данными, и затраты на коммуникацию снижаются.

Примечание переводчика: проверим 700 млн на 16 ГБ

При обучении со смешанной точностью и AdamW на каждый параметр уходит около 16 байт: 2 (вес bf16) + 2 (градиент) + 4 (мастер-копия fp32) + 4 + 4 (два момента AdamW). $16 \text{ ГБ} / 16 \text{ байт} = 10^9$ параметров — и это без активаций; с ними реалистичный предел действительно около 0,7 млрд. При FSDP на 4 GPU эти 16 байт на параметр делятся на четыре. Подробный расчёт — в уроках «Смешанная точность» и «Распределённое обучение».

---

Разбор ноутбука: LoRA-дообучение за 7 шагов

Оригинал: getting-started/finetuning/quickstart_peft_finetuning.ipynb. В шапке ноутбука указана Llama 3 Community License, поэтому здесь пересказ с короткими фрагментами кода.

Ноутбук обучает Llama 3.1 8B на одной GPU (авторы ориентируются на A10 с 24 ГБ) с 8-битным квантованием и LoRA. Задача — суммаризация диалогов на наборе samsum: пары «переписка → краткий пересказ». Если памяти меньше 24 ГБ (например, T4 с 16 ГБ), ноутбук сам уменьшает длину контекста; при нехватке памяти (OOM) её советуют уменьшать дальше.

flowchart LR
A["0. Установка и вход<br/>в Hugging Face"] --> B["1. Модель в int8<br/>+ токенизатор"]
B --> C["2. Проверка базовой<br/>модели"]
C --> D["3. Датасет samsum"]
D --> E["4. LoRA-адаптер"]
E --> F["5. Одна эпоха<br/>обучения"]
F --> G["6. Сохранение"]
G --> H["7. Та же проверка"]

Шаги ноутбука quickstart_peft_finetuning

Шаг 0. Установка. Нужен пакет llama-cookbook и вход в Hugging Face (huggingface_hub.login()) под аккаунтом, которому открыт доступ к весам Meta Llama.

Шаг 1. Модель. Настройки обучения берутся из конфига библиотеки и правятся прямо в коде:

train_config = TRAIN_CONFIG()
train_config.model_name = "meta-llama/Meta-Llama-3.1-8B"
train_config.num_epochs = 1
train_config.gradient_accumulation_steps = 4   # накопление градиентов: 4 шага = 1 обновление
train_config.batch_size_training = 1
train_config.lr = 3e-4
train_config.batching_strategy = "packing"     # склеивать короткие примеры в длинные последовательности
train_config.use_peft = True

Модель загружается в 8 битах через BitsAndBytesConfig(load_in_8bit=True) (урок «Квантование весов»), у токенизатора pad_token приравнивается к eos_token — у Llama нет отдельного токена-заполнителя.

Шаг 2. Проверка до обучения. Базовой модели дают переписку о щенке из приюта и строку Summary:. Базовая модель не пересказывает, а просто повторяет диалог — это нормальное поведение модели, которую не учили выполнять инструкции (урок «От базовой модели к ассистенту»).

Шаг 3. Данные. Набор samsum загружается и токенизируется готовыми функциями библиотеки (get_dataloader(tokenizer, samsum_dataset, train_config)).

Шаг 4. LoRA. Адаптер с рангом r = 8 и lora_alpha = 32; перед этим prepare_model_for_kbit_training(model) готовит квантованную модель к обучению, а get_peft_model(model, peft_config) добавляет обучаемые матрицы (урок «LoRA и QLoRA»).

Шаг 5. Обучение. Оптимизатор AdamW, расписание StepLR (после каждой эпохи шаг умножается на gamma), одна эпоха через функцию train из библиотеки.

Шаг 6. Сохранение. model.save_pretrained(...) сохраняет только LoRA-адаптер — несколько мегабайт.

Шаг 7. Проверка после обучения. На том же диалоге модель выдаёт пересказ вместо повтора: в сохранённом выводе ноутбука — короткий текст о том, что A хочет взять щенка для сына и что B и A согласны: растить собаку непросто.

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

Llama 3.1 8B в 8 битах занимает около 9 ГБ — ноутбук идёт на одной видеокарте; оставьте видимой одну GPU: CUDA_VISIBLE_DEVICES=0. Для QLoRA в README папки finetuning советуют --quantization 4bit --quantization_config.quant_type nf4. Если не хотите ждать доступа к весам Llama, тот же сценарий целиком повторяет урок «Практика — LoRA-дообучение Qwen» на открытой модели. Для обучения на всех четырёх картах в finetuning/multigpu_finetuning.md описан запуск через torchrun с флагом --enable_fsdp (урок «Четыре видеокарты: DDP и FSDP на практике»).

Как запускать

1. Установите библиотеку: pip install llama-cookbook (или из исходников репозитория).
2. На Hugging Face примите лицензию нужной модели meta-llama/... и войдите: huggingface-cli login.
3. Однострочный запуск дообучения на одной GPU из singlegpu_finetuning.md:

FSDP_CPU_RAM_EFFICIENT_LOADING=1 python finetuning.py --use_peft --peft_method lora \
  --quantization 8bit --model_name /path_of_model_folder/8B --output_dir Path/to/save/PEFT/model

Все поля из configs/training.py (например, batch_size_training, context_length, lr, num_epochs) можно передать флагами командной строки, не правя файлы. Встроенные датасеты — samsum_dataset, grammar_dataset, alpaca_dataset; свой датасет подключается по инструкции из finetuning/datasets/README.md.

Что читать дальше

• Видеокурсы Meta на DeepLearning.AI: «Building with Llama 4» и «Introducing Multimodal Llama 3.2» (около 1,5 ч каждый).
• Репозитории PurpleLlama (безопасность), synthetic-data-kit (синтетические данные для дообучения) и llama-prompt-ops.
• В курсе: путеводитель по Mistral Cookbook — те же задачи у другой лаборатории.

Словарик

EN	RU
Parameter-Efficient Fine-Tuning (PEFT)	параметрически эффективное дообучение
catastrophic forgetting	катастрофическое забывание
backbone, head	«хребет» (основная модель), «голова»
freeze / unfreeze layers	заморозить / разморозить слои
optimizer states	состояния оптимизатора
shard, sharding	шард, шардирование
activation checkpointing	чекпоинтинг (пересчёт) активаций
packing	упаковка коротких примеров в одну последовательность
guardrails	защитные фильтры