Buckets:
| # Интерфейс командной строки | |
| `diffusers-cli` — это клиент командной строки для запуска, проверки и упаковки пайплайнов Diffusers. | |
| ## Доступные команды | |
| | Команда | Назначение | | |
| |---|---| | |
| | [`env`](#env) | Вывод информации об окружении для отчётов об ошибках. | | |
| | [`schema`](#schema) | Просмотрите сигнатуру `__call__` конвейера без загрузки весов. | | |
| | [`run`](#run) | Запустите конвейер локально или в Hugging Face Sandbox. | | |
| | [`custom_blocks`](#customblocks) | Упакуйте локальный подкласс `ModularPipelineBlocks` для Hub. | | |
| | [`fp16_safetensors`](#fp16safetensors) | Конвертируйте контрольную точку в `.safetensors` с fp16. | | |
| | [`skills`](#skills) | Установите готовые наборы навыков в вашего ИИ-агента для написания кода. | | |
| > [!TIP] | |
| > На этой странице не приводятся подробности по всем параметрам каждого подкоманды. Чтобы получить полный и актуальный список параметров для любого подкоманды, выполните `diffusers-cli <command> --help` (`diffusers-cli run --help`). | |
| ## env | |
| Выводит версии Python, PyTorch, Diffusers, информацию о CUDA и установленные необязательные зависимости. Используйте эту команду при создании обращения, чтобы разработчики могли воспроизвести вашу конфигурацию. | |
| ```bash | |
| diffusers-cli env | |
| ``` | |
| ## schema | |
| Возвращает допустимые входные данные конвейера без загрузки весов. Используйте его при формировании `--pipeline-kwargs` для [`run`](#run). | |
| Загружается только файл индекса. Стандартные конвейеры читают `model_index.json`. Модульные конвейеры читают `modular_model_index.json`. Репозитории с кастомными блоками читают `modular_config.json` и требуют `--trust-remote-code`, так как при их загрузке выполняется код с Hub. | |
| ```bash | |
| 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`. | |
| Минимальный пример: | |
| ```bash | |
| 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)`. Строковые значения по известным ключам медиа-входа загружаются автоматически: | |
| - Images (`image`, `last_image`, `mask_image`, `control_image`, `ip_adapter_image`, `image_2`) → `PIL.Image` через `load_image`. | |
| - Videos (`video`, `control_video`) → `list[PIL.Image]` через `load_video`. | |
| - Audio (`initial_audio_waveforms`, `reference_audio`, `src_audio`) → `torch.Tensor` через `torchaudio.load`. | |
| ```bash | |
| 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: | |
| ```bash | |
| 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](../optimization/device_map). | |
| - `--variant fp16` — выбрать вариант весов. | |
| - `--revision <sha>` — зафиксировать конкретную ревизию модели. | |
| - `--trust-remote-code` — разрешает использование пользовательского кода из Hub (необходимо для репозиториев, содержащих пользовательские классы pipeline или модульные блоки). См. [Community pipelines](../using-diffusers/custom_pipeline_overview) для стандартных пользовательских pipeline и [Modular Diffusers](../modular_diffusers/overview). | |
| - `--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](../tutorials/using_peft_for_inference). | |
| ### Оптимизации | |
| - `--cpu-offload {model, group, auto}` — целевой объект для загрузки (onload) определяется параметром `--device-map` (для offload требуется обычная строка устройства). | |
| - `model` — `enable_model_cpu_offload` для стандартных пайплайнов. См. [Разгрузка модели](../optimization/memory#model-offloading). | |
| - `group` — `enable_group_offload(offload_type="leaf_level", use_stream=True)` для стандартных конвейеров. См. [Групповая разгрузка](../optimization/memory#group-offloading). | |
| - `auto` — модульный режим только с [`ComponentsManager`](../modular_diffusers/components_manager). Стандартные режимы вызывают исключение для модульных конвейеров. `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 параметр игнорируется с выводом предупреждения. См. [Бэкенды внимания](../optimization/attention_backends). | |
| - `--vae-tiling` / `--vae-slicing` — снижают потребление VRAM при декодировании VAE. См. [tiling VAE](../optimization/memory#vae-tiling) и [slicing VAE](../optimization/memory#vae-slicing). | |
| - `--compile [JSON]` — компиляция модулей денуайзера с помощью [torch.compile](../optimization/fp16#torchcompile). CLI предпочитает [региональную компиляцию](../optimization/fp16#regional-compilation) для модулей с повторяющимися блоками. Сам по себе `--compile` использует `fullgraph=true`. JSON-объект передаётся в `torch.compile`. Не поддерживается вместе с `--context-parallel`. | |
| - `--context-parallel` — контекстный параллелизм в стиле Ulysses для пайплайнов на базе DiT. Локально требуется torchrun, но при использовании `--remote` CLI автоматически оборачивает `torchrun --nproc-per-node=gpu`. См. [Контекстный параллелизм](../optimization/context_parallelism). | |
| ### Модульные конвейеры | |
| `run` автоматически определяет [модульный репозиторий](../modular_diffusers/overview) — либо по наличию файла `modular_model_index.json`, либо по тому, что в его `model_index.json` указан подкласс `ModularPipeline` — поэтому для подключения этого режима не требуется специальный флаг. | |
| Некоторые модульные репозитории определяют несколько *workflows*, похожих на именованные задачи, которые используют общие компоненты, но различаются набором выполняемых блоков и входными параметрами. Например, [MiniMax-H3](../api/pipelines/minimax_h3) предлагает `t2va` (генерация видео и аудио из текста), `fl2va` (первый и/или последний ключевой кадр) и `ref2va` (упорядоченная смесь ссылок на изображения, видео и аудио). Передайте `--workflow`, чтобы выбрать один из них: | |
| ```bash | |
| 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`, будут доступны все рабочие процессы, и конвейер будет выбирать нужный для каждого вызова на основе переданных входных данных. | |
| ```bash | |
| diffusers-cli --format json schema --model MiniMaxAI/MiniMax-H3 --trust-remote-code | |
| ``` | |
| `--workflow` применяется только к модульным конвейерам. Для стандартных конвейеров он игнорируется с выводом предупреждения. | |
| Модульный конвейер возвращает [`PipelineState`](../modular_diffusers/modular_pipeline), а не единый объект вывода, поэтому `--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>`. Способ расширения пути зависит от его формата и размера батча: | |
| | `--output` | 1 выход | N выходов | | |
| |---|---|---| | |
| | _опущено_ | default dir → `0000.png` | каталог по умолчанию → `0000.png`, `0001.png`, `0002.png`, … | | |
| | `./results/` (с завершающим `/` или существующая директория) | `./results/0000.png` | `./results/0000.png`, `./results/0001.png`, … | | |
| | `my-cat.png` (путь к файлу) | `my-cat.png` (используется дословно) | `my-cat-0000.png`, `my-cat-0001.png`, … | | |
| Вывод в каталог всегда использует имена с нулевым дополнением (`0000`, `0001`, …). Явно указанные пути к файлам сохраняют выбранный вами префикс, а при генерации нескольких выводов в одном батче к нему добавляется индекс с нулевым дополнением. | |
| Используйте `--push-to` для загрузки результатов в [хранилище Hugging Face](https://huggingface.co/docs/hub/en/storage-buckets). Он принимает: | |
| - ID HF-бакета (`<namespace>/<name>`) | |
| - `hf://buckets/<namespace>/<name>[/<subpath>]` | |
| [URI HF](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/hf_uris) | |
| - URL в браузере | |
| Подпуть используется как префикс папки. Если бакет отсутствует, он создаётся, а объекты размещаются по пути `[<subpath>/]<run_id>/<filename>`. | |
| ```bash | |
| # 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` загружает сохранённый локально результат. Он не подавляет создание локальных файлов. | |
| | `--push-to` задан? | `--output` задан? | Результат | | |
| |---|---|---| | |
| | нет | нет | загрузить в локальную папку по умолчанию | | |
| | нет | да | загрузить в `--output` | | |
| | да | нет | только bucket, без локальной загрузки | | |
| | да | да | bucket И `--output` | | |
| `--format` определяет метаданные в stdout (пути, время, информация о песочнице). Он не изменяет формат файла самого медиа. Записываемые изображения всегда в формате PNG, видео — MP4, аудио — WAV. | |
| ### Удаленное выполнение (`--remote`) | |
| Вызовите тот же запрос внутри [Hugging Face Sandbox](https://huggingface.co/docs/huggingface_hub/en/guides/sandbox) — изолированной облачной ВМ, которой CLI управляет по HTTP: он загружает входные данные, запускает конвейер, скачивает результаты, а затем завершает работу песочницы. Требуется `huggingface_hub>=1.23`. | |
| Песочница запускается из [`diffusers/diffusers-cli-cuda`](https://hub.docker.com/r/diffusers/diffusers-cli-cuda) — готового образа, в котором уже установлены torch, CUDA и зависимости CLI, поэтому при холодном запуске сразу начинается генерация, а не установка. | |
| ```bash | |
| 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](https://huggingface.co/docs/hub/en/storage-buckets) в песочницу как каталог с правами на чтение и запись (можно указать несколько раз). Каталог монтирования по умолчанию — `/mnt/buckets/<bucket-id>`. Ссылки на смонтированные файлы в `--pipeline-kwargs` указываются как обычные локальные пути. Параметр применяется только при создании новой песочницы и игнорируется при переподключении через `--sandbox-id`. | |
| По умолчанию каждый запуск `--remote` является эфемерным (создание → выполнение → загрузка → завершение). Чтобы переиспользовать «тёплый» песочный ящик между запусками — сохраняя зависимости, кэш весов модели и кэш `torch.compile` на его диске — — держите его в активном состоянии и переподключайтесь: | |
| - `--keep-alive` — не завершать песочницу после выполнения. Её id выводится. | |
| - `--sandbox-id <id>` — переподключиться к сохранённому песочному окружению вместо создания нового. | |
| - `--idle-timeout <duration>` — автоматическое завершение работы после указанного периода бездействия (по умолчанию `10m`). Применяется только при создании нового песочного окружения и игнорируется при переподключении через `--sandbox-id`. | |
| ```bash | |
| # 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` в текущей рабочей директории. | |
| ```bash | |
| # 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` | |
| > [!CAUTION] | |
| > Эта команда устарела и будет удалена в будущей версии. | |
| Преобразование контрольной точки на Hub в формат `.safetensors` с точностью fp16 и публикация результата. Полезно для уменьшения размера весов репозитория и ускорения загрузки. Точные аргументы см. в `diffusers-cli fp16_safetensors --help`. | |
| ## `skills` | |
| Установите навыки из репозитория diffusers ([`.ai/skills/`](https://github.com/huggingface/diffusers/tree/main/.ai/skills)). | |
| ```bash | |
| # 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>/`. | |
Xet Storage Details
- Size:
- 26.9 kB
- Xet hash:
- b72c7a2c0b16405c9128ab2e106a2b2781b1f2793db34b385e22bc1f4d1ab40e
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.