gemma-skills — скиллы для разработки и обучения с Gemma 4

gemma-skills — это официальный репозиторий Google с агентными скиллами для работы с моделями Gemma. Проект поддерживается через Vercel skills CLI и Context7 skills CLI, поэтому устанавливается в любую среду с поддержкой SKILL.md. Внутри два скилла: gemma-dev для разработки приложений и gemma-trainer для локального обучения и дообучения моделей.

Скиллы заточены под актуальное поколение моделей — Gemma 4, и решают типовую проблему агентов: встроенные знания модели устаревают, а репозиторий как раз кодирует свежие best practices от команды Gemma (около 1 000 звёзд на GitHub). Дальше разберём каждый скилл по отдельности.

gemma-dev: разработка приложений с Gemma

Скилл gemma-dev срабатывает, когда нужно построить приложение на базе Gemma или ответить на вопросы про модели Gemma — их возможности, структуру промптов и деплой.

Главный принцип: приоритет прикладного инструментария

Скилл явно запрещает агентам генерировать «сырой» код на PyTorch, TensorFlow или transformers, если пользователь прямо не попросил обучение, fine-tuning или исследования. Вместо этого всегда выбираются высокоуровневые фреймворки, SDK и инструменты, оптимизированные под разработку приложений. Это избавляет от boilerplate и ошибок низкоуровневой работы с моделями.

Выбор модели

Скилл предупреждает: не стоит вслепую подставлять дефолтную gemma-3-1b-it. Нужно анализировать задачу, ограничения железа и требуемые модальности ввода. Для стандартных случаев дефолтом является поколение Gemma 4.

Все модели Gemma 4 поддерживают Thinking Mode — расширенное рассуждение, которое позволяет обрабатывать сложную логику, математику и многошаговые задачи перед генерацией ответа.

26B A4B использует эффективную Mixture-of-Experts для быстрых тяжёлых рассуждений, а 31B — плотная модель.

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

• RAG / векторный поиск — EmbeddingGemma (google/embeddinggemma-300m): до 2K токенов, выходные размерности от 128 до 768.
• Модерация контента — ShieldGemma 2 (google/shieldgemma-2-4b-it): классификатор, который работает параллельно с основной LLM для проверки безопасности.

Деплой и инференс

Скилл задаёт соответствие целей пользователя инструментам:

• Прототипы и демо — Gradio и Transformers для быстрого интерактивного UI на Python.
• Веб и клиентские приложения — transformers.js, инференс прямо в браузере или на устройстве. Критично: всегда ставить версию Hugging Face (npm i @huggingface/transformers), а не Xenova (npm i @xenova/transformers).
• Корпоративный облачный деплой — Vertex AI, контейнеризированное масштабируемое решение (нужны переменные окружения GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, GOOGLE_CLOUD_ENDPOINT_ID).
• Apple Silicon (MLX) — простой путь через Ollama (например, gemma4:26b), продвинутый — через пакет mlx-lm для точного контроля, кастомизации квантизации и fine-tuning (LoRA/QLoRA через mlx_lm.lora).

Ускорение инференса через MTP

Для более быстрого инференса и низкой задержки скилл рекомендует Multi-Token Prediction (MTP) — встроенную технику спекулятивного декодирования в Gemma 4. Лёгкая модель-drafter предлагает несколько кандидатов-токенов, а основная модель проверяет их за один forward pass. Это даёт значительное ускорение при гарантированном сохранении качества.

Каждой целевой модели соответствует assistant-модель с именем <target-model-id>-assistant, например google/gemma-4-31B-it-assistant.

Квантизация с обучением (QAT)

Для максимальной эффективности с минимальной потерей качества Google предлагает официальные Quantization-Aware Training (QAT) модели. В отличие от пост-обучения (PTQ), QAT встраивает имитацию квантизации прямо в процесс обучения.

Рекомендации по движку деплоя:

• llama.cpp / LM Studio — {model-name}-qat-q4_0-gguf (одиночный GGUF-файл).
• vLLM / SGLang — {model-name}-qat-w4a16-ct для сервера, {model-name}-qat-mobile-ct для мобильных (4-битные веса, 16-битные активации).
• Спекулятивное декодирование — {model-name}-qat-q4_0-unquantized вместе с assistant-моделью.
• Другие форматы — {model-name}-qat-q4_0-unquantized (для конвертации, например в MLX).
• Мобильный деплой (Transformers) — {model-name}-qat-mobile-transformers (2-битные слои декодирования, оптимизированные KV-кэши, статические активации).

Готовые коллекции: collections/google/gemma-4-qat-q4_0 и collections/google/gemma-4-qat-mobile.

Работа с документацией

Если установлен MCP-сервер Google и доступен инструмент search_documentation, скилл предписывает использовать его как единственный источник документации — он всегда актуален и экономит токены. При этом вручную фетчить URL запрещено.

Без MCP используется fetch_url: сначала индексный URL https://ai.google.dev/gemma/docs/llms.txt для обзора страниц, затем нужные страницы — форматирование промптов Gemma 4, генерация текста, function calling, понимание изображений и аудио, thinking mode, embeddings, MTP и DiffusionGemma.

gemma-trainer: локальное обучение и fine-tuning

Скилл gemma-trainer активируется, когда пользователь хочет обучить, дообучить или адаптировать модели Gemma — SFT, DPO, RLHF, Reward Modeling — на локальном железе.

Принципы локального обучения

• Unsloth как приоритет — для локального обучения на одной GPU всегда рекомендуется Unsloth: нативная поддержка Gemma 4, до 70% меньше памяти и до 2× быстрее стандартного PEFT-обучения от Hugging Face.
• Fallback на TRL — для multi-GPU (DDP/FSDP) или когда Unsloth недоступен, используется Hugging Face TRL (SFTTrainer, DPOTrainer) вместе с PEFT и bitsandbytes (для QLoRA).
• Всегда QLoRA (4-битная квантизация) — критично для размещения моделей вроде Gemma 4 12B/31B в потребительской VRAM.
• Контекст 2048–8192 токенов — несмотря на поддержку 256K, локально лучше тренировать с окном 2–8K, чтобы избежать OOM.

Выбор метода обучения

Подготовка и валидация данных

Проблемы с форматированием — причина №1 неудачных тренировок. Скилл требует валидировать файлы утилитой dataset_prep.py и выдерживать официальный chat-шаблон Gemma:

<|turn>system
Your instruction here<turn|>
<|turn>user
Your query here<turn|>
<|turn>model
Your response here<turn|>

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

Форматы датасетов по методам:

• SFT — список turn'ов с ролями user/model.
• DPO — парные примеры: prompt, chosen (лучший ответ) и rejected (худший).
• Reward Modeling — формат как у DPO; RewardTrainer учится выдавать больший logit-score для chosen, чем для rejected.

Скилл также покрывает дистилляцию датасетов (teacher-student): локально можно обучить лёгкую студенческую модель (например, Gemma 4 E2B) на качественных выходах большой модели-учителя (Gemma 4 31B или 26B A4B). Для генерации датасетов есть утилита distill_dataset.py.

Воркфлоу обучения

SFT запускается через sft_train.py. Рекомендуемые гиперпараметры LoRA:

• Rank (r): 16 или 32 (больше — сложнее поведение, но больше памяти).
• Alpha (lora_alpha): 32 или 64 (правило: lora_alpha = 2 * r).
• Dropout (lora_dropout): 0.05 или 0.1.
• Target modules: дефолтные для Gemma 4 в PEFT, с фокусом на LM-слои.
• Learning rate: 2e-4 для QLoRA, 2e-5 для полного fine-tuning.

DPO — по шаблону dpo_train.py. Правила:

• Перед DPO всегда выполнять SFT базовой модели на вашем инструкционном формате. DPO напрямую на out-of-domain базовой модели обычно проваливается или деградирует форматирование.
• beta (температура DPO) = 0.1; значения от 0.1 до 0.5 контролируют, насколько строго модель следует reference policy.

Reward Modeling — через reward_train.py: модель инициализируется с sequence classification head (AutoModelForSequenceClassification с num_labels=1) и обучается выдавать скалярную оценку для предпочтительных ответов.

Мультимодальный fine-tuning

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

• Vision SFT — модели E2B/E4B/12B/26B/31B, стандартный SFTTrainer с кастомным visual data collator; в сообщениях используется тип image с путями к локальным файлам.
• Audio SFT — модели E2B/E4B/12B; сырые аудио-массивы (16 кГц) прогоняются через процессор модели для получения input_features, в формате сообщений тип image заменяется на audio.

Пост-обработка и деплой

После обучения LoRA модель можно конвертировать в GGUF:

• Нативный экспорт через Unsloth (рекомендовано) — слияние и квантизация обрабатываются автоматически.
• Ручная конвертация через llama.cpp — для моделей, обученных не через Unsloth.

Для on-device деплоя на мобильных, вебе и IoT есть LiteRT-LM (формат .litertlm) — оптимизирован для Gemma 4 E2B/E4B с аппаратным ускорением (CPU, GPU, NPU).

Итог

gemma-skills — полезный пример «официальных» скиллов от вендора моделей: вместо абстрактных промптов они кодируют конкретные best practices, которые Google поддерживает в актуальном состоянии. Для разработчиков, работающих с Gemma, это способ всегда получать от агента свежие рекомендации по выбору модели, деплою и обучению. Установка простая — через Vercel skills CLI или Context7, репозиторий google-gemma/gemma-skills открыт на GitHub.