Stable Diffusion и Python: полное руководство по запуску генерации изображений

Ошибка CUDA out of memory при первом запуске Stable Diffusion через Python почти всегда означает, что модель загружена в полной точности float32 на видеокарту с ограниченным объёмом видеопамяти — и это первая вещь, которую стоит проверить перед написанием любого кода. Библиотека diffusers от Hugging Face позволяет запустить генерацию изображений буквально в несколько строк, но без понимания управления памятью и версий зависимостей скрипт легко падает ещё до первой картинки.

В этом материале разберём, как установить окружение, написать минимальный рабочий скрипт генерации, разобраться с типичными ошибками и ускорить работу. Всё описанное относится к локальному запуску на машине с GPU NVIDIA; для AMD и CPU есть свои нюансы, которые тоже затронем.

Что нужно перед установкой

Для комфортной работы потребуется видеокарта NVIDIA с объёмом VRAM от 6–8 ГБ и установленными актуальными драйверами. Точные минимальные требования зависят от конкретной модели: Stable Diffusion 1.5 заметно легче, чем SDXL, поэтому на слабой карте разумно начинать с версии 1.5. Проверить видеокарту и версию драйвера можно командой:

nvidia-smi

Также понадобится Python 3.10 или 3.11 — именно эти версии чаще всего указаны как поддерживаемые в документации diffusers и PyTorch. Перед установкой проверьте версию интерпретатора командой python --version. Если версия слишком старая или слишком новая, часть зависимостей может не собраться.

Установка окружения и библиотек

Создайте виртуальное окружение и активируйте его. Это изолирует зависимости проекта от системного Python:

python -m venv sd_env
sd_env\Scripts\activate

Далее устанавливается PyTorch с поддержкой CUDA — важно брать сборку именно под вашу версию CUDA с официального сайта PyTorch, а не просто pip install torch (последняя команда может поставить CPU-версию, и генерация будет идти мучительно медленно). После этого ставятся основные библиотеки:

pip install diffusers transformers accelerate safetensors

• 🐍 diffusers — основная библиотека с готовыми пайплайнами генерации;
• 🧠 transformers — нужна для текстового энкодера, который обрабатывает промпт;
• ⚡ accelerate — помогает эффективно распределять модель по памяти;
• 💾 safetensors — безопасный формат весов моделей.

Минимальный скрипт генерации

Когда окружение готово, генерация изображения сводится к загрузке пайплайна и одному вызову. Базовый пример с моделью Stable Diffusion 1.5:

import torch
from diffusers import StableDiffusionPipeline

pipe = StableDiffusionPipeline.from_pretrained(
"runwayml/stable-diffusion-v1-5",
torch_dtype=torch.float16
)
pipe = pipe.to("cuda")

image = pipe("a cat astronaut in space, detailed", num_inference_steps=30).images[0]
image.save("result.png")

Обратите внимание на параметр torch_dtype=torch.float16 — именно половинная точность снижает потребление видеопамяти примерно вдвое и является ключевым приёмом для карт с 6–8 ГБ VRAM. При первом запуске веса модели скачаются с Hugging Face, это займёт время и несколько гигабайт трафика; последующие запуски используют локальный кэш.

Если видеопамяти всё равно не хватает, добавьте разгрузку на CPU:

pipe.enable_model_cpu_offload()

⚠️ Внимание: не смешивайте pipe.to("cuda") и enable_model_cpu_offload() в одном скрипте — эти два подхода управления памятью конфликтуют, и вы получите неочевидные ошибки. Выберите один вариант.

Типичные ошибки и их решение

Больше всего вопросов вызывают ошибки, связанные с памятью и версиями. Разберём самые частые сценарии.

• 🔥 CUDA out of memory — снизьте разрешение генерации, включите float16, используйте enable_model_cpu_offload() или enable_attention_slicing();
• 🐢 Генерация идёт на CPU — проверьте torch.cuda.is_available(); если возвращает False, переустановите PyTorch в CUDA-сборке;
• 📦 Ошибки загрузки модели — возможная причина в устаревшей версии diffusers; обновите её командой pip install -U diffusers;
• 🔑 Ошибка доступа к gated-модели — некоторые репозитории на Hugging Face требуют принятия лицензии и авторизации через токен.

Отдельно стоит сказать про конфликты версий. Если скрипт падал с загадочными ошибками внутри библиотек, проверьте совместимость установленных версий torch и diffusers — иногда помогает откат на предыдущий стабильный релиз, указанный в документации конкретной модели.

Сравнение способов запуска

Python-скрипт — не единственный способ работы со Stable Diffusion. Выбор зависит от ваших задач:

Если цель — встроить генерацию в собственный сервис, бота или скрипт пакетной обработки, вариант с diffusers вне конкуренции: вы полностью контролируете параметры, сиды, schedulers и можете комбинировать модели. Веб-интерфейсы удобнее для ручного подбора промптов, но хуже поддаются автоматизации.

Что такое scheduler и зачем его менять

Scheduler (планировщик) управляет процессом удаления шума при генерации. В diffusers можно заменить его одной строкой, например на DPMSolverMultistepScheduler — часто это позволяет получить сопоставимое качество за меньшее число шагов, то есть быстрее. Конкретный выбор зависит от модели, поэтому экспериментируйте на своих промптах.

Оптимизация скорости и памяти

После того как базовый скрипт заработал, возникает естественное желание ускорить генерацию. Основные безопасные приёмы: уменьшение числа шагов num_inference_steps (для многих моделей 20–30 шагов достаточно), использование float16 и смена scheduler на более быстрый. Эти методы не требуют ничего, кроме правки параметров.

Для карт с малым объёмом VRAM дополнительно помогают enable_attention_slicing() и enable_vae_slicing() — они замедляют работу, но позволяют генерировать там, где иначе была бы ошибка памяти. На современных версиях PyTorch также доступен более эффективный механизм внимания, который diffusers задействует автоматически, если это возможно.

⚠️ Внимание: не скачивайте веса моделей с непроверенных источников и особенно избегайте файлов в формате .ckpt на базе pickle — при загрузке они могут выполнить произвольный код. Предпочитайте формат .safetensors и официальные репозитории на Hugging Face.

Запуск без GPU: CPU и облако

Запуск на CPU технически возможен — достаточно убрать перенос на CUDA и использовать float32, но генерация одного изображения займёт минуты или десятки минут в зависимости от процессора. Такой вариант годится только для проверки работоспособности кода, а не для реальной работы.

Альтернатива — облачные среды с GPU, например Google Colab или аренда сервера. Там тот же самый скрипт на diffusers запускается без изменений, меняется только окружение. Учтите, что у бесплатных тарифов облачных сервисов есть ограничения по времени сессии и доступной памяти, поэтому приёмы экономии VRAM остаются актуальными и там.

Часто задаваемые вопросы

Сколько видеопамяти нужно для Stable Diffusion через Python?

Для Stable Diffusion 1.5 в float16 обычно достаточно 4–6 ГБ VRAM с включёнными оптимизациями памяти. Модели семейства SDXL требовательнее — желательно 8 ГБ и более. Точный расход зависит от разрешения генерации и включённых техник экономии памяти.

Почему torch.cuda.is_available() возвращает False?

Наиболее вероятная причина — установлена CPU-сборка PyTorch. Переустановите его, взяв команду установки под вашу версию CUDA с официального сайта PyTorch. Также проверьте, что драйвер NVIDIA установлен и виден через nvidia-smi.

Можно ли использовать свои дообученные модели и LoRA?

Да. Diffusers поддерживает загрузку собственных чекпоинтов и LoRA-адаптеров через соответствующие методы пайплайна. Веса должны быть в поддерживаемом формате, предпочтительно safetensors. Порядок загрузки описан в документации библиотеки.

Как сгенерировать несколько изображений за один вызов?

Передайте в пайплайн список промптов или параметр num_images_per_prompt — пайплайн вернёт список изображений. Учтите, что потребление VRAM при пакетной генерации растёт, поэтому на слабых картах лучше генерировать картинки по одной в цикле.

Чем diffusers отличается от оригинального репозитория Stable Diffusion?

Diffusers — это библиотека от Hugging Face с унифицированным API, регулярными обновлениями и поддержкой множества моделей. Оригинальный код от CompVis требует больше ручной настройки. Для большинства задач в 2020-х годах именно diffusers считается стандартной точкой входа.