Интерфейс командной строки

diffusers-cli — это клиент командной строки для запуска, проверки и упаковки пайплайнов Diffusers.

Доступные команды

На этой странице не приводятся подробности по всем параметрам каждого подкоманды. Чтобы получить полный и актуальный список параметров для любого подкоманды, выполните diffusers-cli <command> --help (diffusers-cli run --help).

env

Выводит версии Python, PyTorch, Diffusers, информацию о CUDA и установленные необязательные зависимости. Используйте эту команду при создании issue, чтобы разработчики могли воспроизвести вашу конфигурацию.

diffusers-cli env

schema

Возвращает допустимые входные данные конвейера без загрузки весов. Используйте его при формировании --pipeline-kwargs для run.

Загружается только файл индекса. Стандартные конвейеры читают model_index.json. Модульные конвейеры читают modular_model_index.json. Репозитории с кастомными блоками читают modular_config.json и требуют --trust-remote-code, так как при их загрузке выполняется код с Hub.

diffusers-cli --format json schema --model black-forest-labs/FLUX.1-dev
diffusers-cli schema --model my-org/my-custom-blocks --trust-remote-code

run

Запустите конвейер от начала до конца. CLI автоматически определяет, является ли репозиторий стандартным или модульным. Он автоматически загружает медиа-входные данные из URL или локальных путей, сохраняет выходные данные в соответствии с типом возвращаемого значения конвейера и может выполняться удалённо в Hugging Face Sandbox с помощью --remote.

Минимальный пример:

diffusers-cli run \
    --model black-forest-labs/FLUX.1-dev \
    --dtype bf16 \
    --pipeline-kwargs '{"prompt": "an astronaut riding a horse"}'

Передача аргументов конвейера

--pipeline-kwargs принимает JSON-объект, который передаётся в pipeline(**kwargs). Строковые значения для известных ключей медиа-входа загружаются автоматически:

• Изображения (image, last_image, mask_image, control_image, ip_adapter_image, image_2) → PIL.Image через load_image.
• Видео (video, control_video) → list[PIL.Image] через load_video.
• Аудио (initial_audio_waveforms, reference_audio, src_audio) → torch.Tensor через torchaudio.load.

diffusers-cli run \
    --model black-forest-labs/FLUX.2-klein-9B --dtype bf16 \
    --pipeline-kwargs '{"prompt": "make the fur grey", "image": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/cat.png", "strength": 0.6}'

Оба типа ключей — media и text — принимают JSON-массив для обработки пачки данных за один вызов конвейера. Каждый элемент списка media загружается отдельно (URL, локальный путь или путь к смонтированному бакету), а Diffusers обрабатывает весь список за один прямой проход на GPU:

diffusers-cli run \
    --model black-forest-labs/FLUX.1-Kontext-dev --dtype bf16 \
    --pipeline-kwargs '{
        "prompt": ["make it grey", "make it pink", "make it blue"],
        "image": [
            "https://.../cat1.png",
            "https://.../cat2.png",
            "https://.../cat3.png"
        ]
    }'

Загрузка

Настройте способ загрузки весов модели и пользовательского кода конвейера в CLI.

• --dtype {auto, bfloat16, bf16, float16, fp16, float32, fp32} — тип данных весов.

• --device-map <value> — размещение компонентов. Принимает строку устройства torch (cuda, cuda:0, cpu, mps), balanced (автоматически распределяет компоненты между видимыми GPU) или JSON-словарь для явного размещения каждого компонента. Если параметр не указан, определяется автоматически. Подробнее см. device_map.

• --variant fp16 — выбрать вариант весов.

• --revision <sha> — зафиксировать конкретную ревизию модели.

• --trust-remote-code — разрешает использование пользовательского кода из Hub (необходимо для репозиториев, содержащих пользовательские классы pipeline или модульные блоки). См. Community pipelines для стандартных пользовательских pipeline и Modular Diffusers.

• --lora <spec> — подключить адаптер LoRA после загрузки. Каждое значение представляет собой JSON-словарь. Повторяйте флаг, чтобы настроить несколько адаптеров. lora_id обязателен для каждой записи, lora_scale по умолчанию равен 1.0, а adapter_name является необязательным (генерируется автоматически как lora_<i> при наложении адаптеров).

  • Один: --lora '{"lora_id": "alvdansen/flux-koda", "lora_scale": 0.8}'
  • Несколько: --lora '{"lora_id": "alvdansen/flux-koda", "lora_scale": 0.6, "adapter_name": "koda"}' --lora '{"lora_id": "Shakker-Labs/FLUX.1-dev-LoRA-AntiBlur", "lora_scale": 0.4}'

  Все спецификации загружаются с помощью pipeline.load_lora_weights(...), а затем активируются вместе одним вызовом pipeline.set_adapters(names, adapter_weights=scales). Подробнее о стеке адаптеров, планировании масштабов и горячей замене см. в разделе LoRA.

Оптимизации

• --cpu-offload {model, group, auto} — источник цели offload — --device-map (обычная строка устройства, необходимая для offload).
  • model — enable_model_cpu_offload для стандартных пайплайнов. См. Разгрузка модели.
  • group — enable_group_offload(offload_type="leaf_level", use_stream=True) для стандартных конвейеров. См. Групповая разгрузка.
  • auto — модульный режим только с ComponentsManager. Стандартные режимы вызывают исключение для модульных конвейеров. auto вызывает исключение для стандартных конвейеров.
• --offload-margin <size> — объём памяти устройства, оставляемый свободным для активаций при использовании --cpu-offload auto, передаётся в enable_auto_cpu_offload как memory_reserve_margin (по умолчанию 3GB). Увеличьте это значение, если при работе с большим холстом память исчерпывается в середине прямого прохода. Офлоадер удерживает компоненты в памяти, пока они в неё помещаются, поэтому на карте с большим объёмом VRAM стандартный запас может оставить недостаточно места для активаций длинного видео.
• --attention-backend — ядра внимания, размещённые на Hub, автоматически загружаются при первом использовании. Варианты: default и бэкенды Hub, зарегистрированные в Diffusers (например, flash_hub, flash_varlen_hub, flash_4_hub, sage_hub, sage_blackwell_hub). Актуальный список можно получить, выполнив diffusers-cli run --help. Поддерживаются только пайплайны на основе Transformer; для устаревших пайплайнов UNet параметр игнорируется с выводом предупреждения. См. Бэкенды внимания.
• --vae-tiling / --vae-slicing — снижают потребление VRAM при декодировании VAE. См. tiling VAE и slicing VAE.
• --compile [JSON] — компиляция модулей денуайзера с помощью torch.compile. CLI предпочитает региональную компиляцию для модулей с повторяющимися блоками. Сам по себе --compile использует fullgraph=true. JSON-объект передаётся в torch.compile. Не поддерживается в сочетании с --context-parallel.
• --context-parallel — контекстный параллелизм в стиле Ulysses для пайплайнов на базе DiT. Локально требуется torchrun, но при использовании --remote CLI самостоятельно оборачивает torchrun --nproc-per-node=gpu. См. Контекстный параллелизм.

Модульные конвейеры

run автоматически определяет модульный репозиторий — либо по наличию файла modular_model_index.json, либо по тому, что в его model_index.json указан подкласс ModularPipeline — поэтому специальный флаг для подключения не требуется.

Некоторые модульные репозитории определяют несколько workflows, похожих на именованные задачи, которые используют общие компоненты, но различаются по набору выполняемых блоков и входным параметрам. Например, MiniMax-H3 предлагает t2va (генерация видео и аудио из текста), fl2va (первый и/или последний ключевой кадр) и ref2va (упорядоченная смесь ссылок на изображения, видео и аудио). Передайте --workflow, чтобы выбрать один из них:

diffusers-cli run \
    --model MiniMaxAI/MiniMax-H3 --workflow fl2va \
    --pipeline-kwargs '{
        "prompt": "the camera pushes in slowly as rain falls",
        "image": "opening-frame.png",
        "last_image": "closing-frame.png",
        "num_frames": 124
    }' \
    --output-key videos --output-key audio \
    --fps 24 --sampling-rate 32000 \
    --cpu-offload auto --dtype bf16

Выбор рабочего процесса оставляет только блоки этой задачи, поэтому конвейер объявляет лишь необходимые компоненты, а load_components загружает только их подпапки. Если опустить --workflow, будут доступны все рабочие процессы, и конвейер будет выбирать их для каждого вызова на основе переданных входных данных.

diffusers-cli --format json schema --model MiniMaxAI/MiniMax-H3 --trust-remote-code

--workflow применяется только к модульным конвейерам. Для стандартных конвейеров он игнорируется с выводом предупреждения.

Модульный конвейер возвращает PipelineState, а не единый объект вывода, поэтому --output-key задаёт имя промежуточного результата для сохранения.

Результаты

run определяет тип вывода конвейера:

• PIL.Image/list → <NNNN>.png (индекс с ведущими нулями, например, 0000.png)
• Последовательность изображений → 0000.mp4 (--fps управляет частотой кадров, по умолчанию 8)
• Массив аудио → 0000.wav (--sampling-rate управляет частотой)
• Всё остальное → дамп JSON

Формат каталога вывода по умолчанию — ~/.diffusers/cli/run/outputs/diffusers-run-<YYYYMMDDTHHMMSS>-<uuid>/. Каждому запуску выделяется собственный подкаталог, чтобы последовательные вызовы не перезаписывали результаты.

Переопределите с помощью --output <path>. Способ расширения пути зависит от его формата и размера батча:

Вывод в каталог всегда использует имена с нулевым дополнением (0000, 0001, …). Явно указанные пути к файлам сохраняют выбранный вами префикс, а при генерации нескольких выводов в одном батче к нему добавляется индекс с нулевым дополнением.

Используйте --push-to для загрузки результатов в хранилище Hugging Face. Он принимает:

• ID HF-бакета (<namespace>/<name>)
• hf://buckets/<namespace>/<name>[/<subpath>] URI HF
• URL в браузере

Подпуть используется как префикс папки. Если бакет отсутствует, он создаётся, а объекты размещаются по пути [<subpath>/]<run_id>/<filename>.

# HF bucket id — files at hf://buckets/alice/edit-outputs/<run_id>/<file>
--push-to alice/edit-outputs

# URI with subpath — files at hf://buckets/alice/edit-outputs/greyscale/2026-07/<run_id>/<file>
--push-to hf://buckets/alice/edit-outputs/greyscale/2026-07

# Browser URL copy-paste from the Hub also works.
--push-to https://huggingface.co/buckets/alice/edit-outputs/tree/greyscale/2026-07

Таблица ниже описывает удалённые запуски. Для локальных запусков --push-to загружает сохранённый локально результат. Он не подавляет создание локальных файлов.

--format определяет метаданные в stdout (пути, время, информация о песочнице). Он не изменяет формат файла самого медиа. Записываемые изображения всегда в формате PNG, видео — MP4, аудио — WAV.

Удаленное выполнение ( --remote )

Вызовите тот же запрос внутри Hugging Face Sandbox — изолированной облачной ВМ, которой CLI управляет по HTTP: он загружает входные данные, запускает конвейер, скачивает выходные данные, а затем завершает работу песочницы. Требуется huggingface_hub>=1.23.

Песочница запускается из diffusers/diffusers-cli-cuda, готового образа, в котором уже установлены torch, CUDA и зависимости CLI, поэтому при холодном запуске сразу начинается генерация, а не установка.

diffusers-cli run \
    --model black-forest-labs/FLUX.1-dev --dtype bf16 \
    --pipeline-kwargs '{"prompt": "an astronaut riding a horse"}' \
    --remote --flavor a100-large

Удалённые флаги:

• --flavor <name> — аппаратное обеспечение песочницы (например, a10g-small, h200, rtx-pro-6000).
• --timeout <duration> — максимальное время выполнения команды run внутри песочницы (по умолчанию 10m).
• --dependencies <pkg> — дополнительные зависимости pip (можно указать несколько), устанавливаемые поверх образа. Полезно для фиксации ветки diffusers в виде tarball или добавления дополнительных пакетов, специфичных для конкретного пайплайна.
• --namespace <name> — создать песочницу в другой организации/аккаунте HF.
• --image <ref> — переопределяет образ песочницы. Он должен содержать torch + CUDA, совместимые с драйвером вашего --flavor. Затем CLI устанавливает собственные зависимости поверх него в каждой холодной песочнице, чего позволяет избежать образ по умолчанию.
• --volume <bucket-id>[:<mount-path>] — монтирует HF storage bucket в песочницу как каталог с правами на чтение и запись (можно указать несколько раз). Каталог монтирования по умолчанию — /mnt/buckets/<bucket-id>. Ссылки на смонтированные файлы в --pipeline-kwargs указываются как обычные локальные пути. Параметр применяется только при создании новой песочницы и игнорируется при переподключении через --sandbox-id.

По умолчанию каждый запуск --remote является эфемерным (создание → запуск → загрузка → завершение). Чтобы переиспользовать «тёплый» песочный ящик между запусками — сохраняя зависимости, кэш весов модели и кэш torch.compile на его диске — — держите его в активном состоянии и переподключайтесь:

• --keep-alive — не завершать песочницу после выполнения. Её id выводится.
• --sandbox-id <id> — переподключиться к сохранённому песочному окружению вместо создания нового.
• --idle-timeout <duration> — автоматическое завершение работы после указанного периода бездействия (по умолчанию 10m). Применяется только при создании нового песочного окружения и игнорируется при переподключении через --sandbox-id.

# First run keeps the sandbox alive and prints sandbox_id=<id>.
diffusers-cli run -m black-forest-labs/FLUX.1-dev --dtype bf16 \
    --pipeline-kwargs '{"prompt": "a cat"}' --remote --flavor a100-large --keep-alive

# Reconnect for the next run — the model is already cached, so only inference runs.
diffusers-cli run -m black-forest-labs/FLUX.1-dev --dtype bf16 \
    --pipeline-kwargs '{"prompt": "a dog"}' --remote --flavor a100-large --sandbox-id <id>

# Stop it when done (or let it timeout).
hf sandbox kill <id>

custom_blocks

Упаковывает локальный подкласс ModularPipelineBlocks для загрузки на Hub. Читает Python-файл, сканирует его с помощью AST в поисках классов, наследующихся от ModularPipelineBlocks или одного из его составных подклассов (SequentialPipelineBlocks, AutoPipelineBlocks, ConditionalPipelineBlocks, LoopSequentialPipelineBlocks), инстанцирует выбранный класс и вызывает save_pretrained в текущей рабочей директории.

# Package the first block found in ./block.py
diffusers-cli custom_blocks

# Point at a different file / pick a specific class
diffusers-cli custom_blocks --block_module_name my_block.py --block_class_name MyDenoiseBlock

Класс блока должен быть инициализируемым без аргументов конструктора и задавать значения по умолчанию в __init__ либо читать конфигурацию из state пайплайна во время вызова.

fp16_safetensors

Эта команда устарела и будет удалена в будущей версии.

Преобразование контрольной точки на Hub в формат .safetensors с точностью fp16 и публикация результата. Полезно для уменьшения размера весов в репозитории, чтобы ускорить загрузку. Точный список аргументов см. в diffusers-cli fp16_safetensors --help.

навыки

Установите навыки из репозитория diffusers (.ai/skills/).

# Install a single skill
diffusers-cli skills add "<skill name>"

# Install every skill in the registry
diffusers-cli skills add --all

# List available skills with a one-line summary of each
diffusers-cli skills list

# Preview a skill's SKILL.md without installing
diffusers-cli skills preview diffusers-cli

# Refetch and reinstall every managed skill
diffusers-cli skills update

# Install to the user-level directory instead of the current project
diffusers-cli skills add diffusers-cli --global

# Install for one agent instead of detecting it from the environment
diffusers-cli skills add --all --claude   # or --codex / --cursor

Без целевого флага CLI устанавливает пакет для того агента, который его запустил, или для всех агентов, если определить конкретного не удаётся. Claude Code получает плагин в каталоге .claude/skills/diffusers/ (с пространством имён /diffusers:<skill name>). Codex и Cursor получают .agents/skills/<skill name>/.