Giao diện dòng lệnh

diffusers-cli là một client dòng lệnh để chạy, kiểm tra và đóng gói các pipeline của Diffusers.

Các lệnh khả dụng

Trang này không cung cấp chi tiết cho tất cả các tùy chọn dưới mỗi lệnh con. Để xem danh sách đầy đủ và luôn cập nhật các tùy chọn cho bất kỳ lệnh con nào, hãy chạy diffusers-cli <command> --help (diffusers-cli run --help).

env

In ra phiên bản của Python, PyTorch, Diffusers, thông tin CUDA và các thư viện tùy chọn đã cài đặt. Hãy sử dụng lệnh này khi mở một issue để các nhà phát triển có thể tái tạo lại môi trường của bạn.

diffusers-cli env

schema

Trả về các đầu vào được chấp nhận của pipeline mà không tải trọng số. Sử dụng khi xây dựng --pipeline-kwargs cho run.

Chỉ tệp chỉ mục được tải về. Các pipeline chuẩn đọc model_index.json. Các pipeline modular đọc modular_model_index.json. Các kho chứa khối tùy chỉnh đọc modular_config.json và cần --trust-remote-code, vì việc tải chúng sẽ thực thi mã từ 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

chạy

Chạy pipeline từ đầu đến cuối. CLI tự động phát hiện kho chuẩn hay kho modular. Nó tự động nạp các đầu vào media từ URL hoặc đường dẫn cục bộ, lưu các đầu ra dựa trên kiểu trả về của pipeline, và có thể chạy từ xa trên Hugging Face Sandbox thông qua --remote.

Ví dụ tối giản:

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

Truyền các đối số pipeline

--pipeline-kwargs nhận một đối tượng JSON được chuyển tiếp đến pipeline(**kwargs). Các giá trị chuỗi tại các khóa đầu vào phương tiện đã biết sẽ được tự động tải:

• Hình ảnh (image, last_image, mask_image, control_image, ip_adapter_image, image_2) → PIL.Image thông qua load_image.
• Video (video, control_video) → list[PIL.Image] thông qua load_video.
• Âm thanh (initial_audio_waveforms, reference_audio, src_audio) → torch.Tensor thông qua 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}'

Cả media keys và text keys đều nhận một mảng JSON để chạy một lô (batch) qua một lần gọi pipeline duy nhất. Mỗi mục trong danh sách media được tải riêng lẻ (URL, đường dẫn cục bộ, hoặc đường dẫn bucket-mount), và Diffusers xử lý toàn bộ danh sách trong một lần forward pass trên 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"
        ]
    }'

Đang tải

Cấu hình cách CLI nạp trọng số mô hình và mã pipeline tùy chỉnh.

• --dtype {auto, bfloat16, bf16, float16, fp16, float32, fp32} — dtype của trọng số.

• --device-map <value> — vị trí đặt các thành phần. Chấp nhận chuỗi thiết bị torch (cuda, cuda:0, cpu, mps), balanced (tự động chia các thành phần trên các GPU hiển thị), hoặc một dict JSON để đặt vị trí rõ ràng cho từng thành phần. Nếu bị bỏ qua, hệ thống sẽ tự động phát hiện. Xem device_map để biết thêm chi tiết.

• --variant fp16 — chọn một biến thể trọng số.

• --revision <sha> — cố định một phiên bản mô hình cụ thể.

• --trust-remote-code — cho phép mã tùy chỉnh từ Hub (bắt buộc đối với các kho chứa các lớp pipeline tùy chỉnh hoặc các khối modular). Xem Các pipeline của cộng đồng để biết về các pipeline tùy chỉnh tiêu chuẩn và Modular Diffusers.

• --lora <spec> — gắn một bộ thích ứng LoRA sau khi tải. Mỗi giá trị là một từ điển JSON. Lặp lại cờ này để xếp chồng nhiều bộ thích ứng. lora_id là bắt buộc cho mỗi mục, lora_scale mặc định là 1.0, và adapter_name là tùy chọn (tự động tạo thành lora_<i> khi xếp chồng).

  • Đơn: --lora '{"lora_id": "alvdansen/flux-koda", "lora_scale": 0.8}'
  • Nhiều: --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}'

  Tất cả các thông số kỹ thuật được nạp bởi pipeline.load_lora_weights(...), sau đó được kích hoạt cùng nhau bằng một lần gọi duy nhất pipeline.set_adapters(names, adapter_weights=scales). Xem LoRA để có hướng dẫn chi tiết hơn về việc xếp chồng adapter, lập lịch tỷ lệ và thay đổi nóng.

Tối ưu hóa

• --cpu-offload {model, group, auto} — mục tiêu onload được lấy từ --device-map (chuỗi thiết bị đơn giản bắt buộc cho offload). model — enable_model_cpu_offload cho các pipeline tiêu chuẩn. Xem Model offloading. group — enable_group_offload(offload_type="leaf_level", use_stream=True) cho các pipeline tiêu chuẩn. Xem Group offloading. auto — chỉ dành cho modular với ComponentsManager. Các chế độ tiêu chuẩn sẽ gây lỗi trên các pipeline modular. auto sẽ gây lỗi trên các pipeline tiêu chuẩn.
  • model — enable_model_cpu_offload cho các pipeline tiêu chuẩn. Xem Offloading mô hình.
  • group — enable_group_offload(offload_type="leaf_level", use_stream=True) cho các pipeline tiêu chuẩn. Xem Group offloading.
  • auto — chỉ dùng cho modular với ComponentsManager. Các chế độ chuẩn sẽ gây lỗi với pipeline modular. auto sẽ gây lỗi với pipeline chuẩn.
• --offload-margin <size> — bộ nhớ thiết bị được giữ trống cho các activation dưới --cpu-offload auto, được truyền vào enable_auto_cpu_offload dưới dạng memory_reserve_margin (mặc định là 3GB). Hãy tăng giá trị này khi một canvas lớn bị hết bộ nhớ giữa chừng quá trình forward. Bộ offloader sẽ giữ các thành phần ở trạng thái resident chừng nào chúng còn vừa, do đó trên card VRAM cao, margin mặc định có thể không chừa đủ chỗ cho các activation của một video dài.
• --attention-backend — Các kernel attention được lưu trữ trên Hub, tự động tải xuống khi sử dụng lần đầu. Các lựa chọn bao gồm default cùng các backend Hub đã đăng ký trong Diffusers (ví dụ flash_hub, flash_varlen_hub, flash_4_hub, sage_hub, sage_blackwell_hub). Chạy diffusers-cli run --help để xem danh sách hiện tại. Tính năng này chỉ hỗ trợ các pipeline dựa trên Transformer và sẽ bị bỏ qua kèm theo cảnh báo trên các pipeline UNet cũ. Xem Các backend Attention.
• --vae-tiling / --vae-slicing — giảm VRAM khi giải mã VAE. Xem VAE tiling và VAE slicing.
• --compile [JSON] — biên dịch các module denoiser bằng torch.compile. CLI ưu tiên biên dịch theo vùng cho các module có các khối lặp lại. --compile đơn thuần sử dụng fullgraph=true. Một đối tượng JSON sẽ được chuyển tiếp đến torch.compile. Không được hỗ trợ cùng với --context-parallel.
• --context-parallel — song song ngữ cảnh theo phong cách Ulysses trên pipeline dựa trên DiT. Cần torchrun cục bộ, nhưng khi dùng --remote, CLI sẽ tự bọc torchrun --nproc-per-node=gpu cho bạn. Xem Song song ngữ cảnh.

Đường ống xử lý dạng module

run tự động phát hiện modular repo — hoặc vì nó có kèm modular_model_index.json, hoặc vì model_index.json của nó chỉ định một lớp con của ModularPipeline — nên không cần cờ nào để bật tính năng này.

Một số kho mã module định nghĩa nhiều workflows giống như các tác vụ có tên, chia sẻ các thành phần nhưng khác nhau ở các khối được thực thi và các đầu vào mà chúng nhận. Ví dụ, MiniMax-H3 cung cấp t2va (chuyển văn bản thành video và âm thanh), fl2va (khung hình chính đầu tiên và/hoặc cuối cùng) và ref2va (một hỗn hợp có thứ tự của các tham chiếu hình ảnh, video và âm thanh). Truyền --workflow để chọn một 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

Việc chọn một workflow chỉ giữ lại các khối của tác vụ đó, do đó pipeline chỉ khai báo các thành phần cần thiết và load_components chỉ lấy các thư mục con tương ứng. Bỏ qua --workflow để giữ lại mọi workflow khả dụng và để pipeline tự chọn theo từng lần gọi dựa trên các đầu vào được cung cấp.

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

--workflow chỉ áp dụng cho các pipeline dạng modular. Nó sẽ bị bỏ qua kèm theo cảnh báo trên các pipeline tiêu chuẩn.

Một pipeline dạng module trả về một PipelineState thay vì một đối tượng đầu ra duy nhất, do đó --output-key đặt tên cho giá trị trung gian cần lưu.

Đầu ra

run phát hiện kiểu đầu ra của pipeline:

• PIL.Image/list → <NNNN>.png (chỉ số bù số 0, ví dụ 0000.png)
• Chuỗi hình ảnh → 0000.mp4 (--fps kiểm soát tốc độ khung hình, mặc định là 8)
• Mảng âm thanh → 0000.wav (--sampling-rate kiểm soát tốc độ)
• Bất kỳ thứ gì khác → JSON dump

Định dạng thư mục đầu ra mặc định là ~/.diffusers/cli/run/outputs/diffusers-run-<YYYYMMDDTHHMMSS>-<uuid>/. Mỗi lần chạy sẽ có một thư mục con riêng để các lần gọi liên tiếp không ghi đè lên nhau.

Ghi đè bằng --output <path>. Cách đường dẫn được mở rộng phụ thuộc vào dạng của nó và kích thước lô:

Đầu ra dạng thư mục luôn sử dụng tên đệm bằng số (0000, 0001, …). Đường dẫn tệp rõ ràng sẽ giữ nguyên phần tên gốc bạn chọn và được thêm chỉ số đệm khi lô tạo ra nhiều đầu ra.

Sử dụng --push-to để tải các kết quả lên thùng chứa lưu trữ Hugging Face. Tham số này chấp nhận một

• ID bucket HF (<namespace>/<name>)
• hf://buckets/<namespace>/<name>[/<subpath>] URI HF
• URL trình duyệt

Subpath được dùng làm tiền tố thư mục. Bucket sẽ được tạo nếu chưa tồn tại, và các đối tượng sẽ nằm dưới [<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

Bảng dưới đây mô tả các lần chạy từ xa. Đối với các lần chạy cục bộ, --push-to sẽ tải lên kết quả đã được lưu cục bộ. Nó không ngăn việc tạo tệp cục bộ.

--format định dạng metadata trên stdout (đường dẫn, thời gian, thông tin sandbox). Nó không thay đổi định dạng tệp của chính phương tiện. Ảnh được ghi luôn là PNG, video là MP4, âm thanh là WAV.

Thực thi từ xa ( --remote )

Chạy cùng một lệnh bên trong Hugging Face Sandbox — một VM cloud được cách ly, do CLI điều khiển qua HTTP: nó tải lên các đầu vào, chạy pipeline, tải xuống các đầu ra, sau đó kết thúc sandbox. Yêu cầu huggingface_hub>=1.23.

Sandbox khởi động từ diffusers/diffusers-cli-cuda, một ảnh đã được xây dựng sẵn, bao gồm sẵn torch, CUDA và các phụ thuộc của CLI, do đó một lần chạy lạnh sẽ bắt đầu tạo nội dung ngay thay vì phải cài đặt trước.

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

Các cờ từ xa:

• --flavor <name> — phần cứng sandbox (ví dụ: a10g-small, h200, rtx-pro-6000).
• --timeout <duration> — thời gian thực tối đa cho lệnh chạy bên trong sandbox (mặc định là 10m).
• --dependencies <pkg> — các phụ thuộc pip bổ sung (có thể lặp lại), được cài đặt lên trên image. Hữu ích để cố định (pin) một tarball của nhánh diffusers hoặc thêm các phụ kiện (extras) dành riêng cho pipeline.
• --namespace <name> — tạo sandbox dưới một tổ chức/tài khoản HF khác.
• --image <ref> — ghi đè ảnh sandbox. Ảnh này phải có sẵn torch + CUDA tương thích với driver của --flavor của bạn. Khi đó, CLI sẽ tự cài đặt các phụ thuộc của nó lên trên mỗi sandbox lạnh, điều mà ảnh mặc định giúp tránh được.
• --volume <bucket-id>[:<mount-path>] — gắn một HF storage bucket vào sandbox dưới dạng thư mục đọc-ghi (có thể lặp lại). Đường dẫn gắn mặc định là /mnt/buckets/<bucket-id>. Tham chiếu các tệp đã gắn từ --pipeline-kwargs như bất kỳ đường dẫn cục bộ nào khác. Chỉ được áp dụng khi tạo sandbox mới và bị bỏ qua khi kết nối lại qua --sandbox-id.

Mặc định, mỗi lần chạy --remote là tạm thời (tạo → chạy → tải xuống → hủy bỏ). Để tái sử dụng một sandbox đang chạy giữa các lần chạy — giữ các phụ thuộc, bộ nhớ đệm trọng số mô hình và bộ nhớ đệm torch.compile trên đĩa của nó — hãy giữ nó hoạt động và kết nối lại:

• --keep-alive — không kết thúc sandbox sau khi chạy. id của nó sẽ được in ra.
• --sandbox-id <id> — kết nối lại với một sandbox đang được giữ hoạt động thay vì tạo một sandbox mới.
• --idle-timeout <duration> — tự động tắt sau khoảng thời gian không hoạt động này (mặc định 10m). Chỉ được áp dụng khi tạo sandbox mới và bị bỏ qua khi kết nối lại qua --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

Đóng gói một lớp con ModularPipelineBlocks cục bộ để tải lên Hub. Đọc một tệp Python, quét AST để tìm các lớp kế thừa từ ModularPipelineBlocks hoặc một trong các lớp con tổng hợp của nó (SequentialPipelineBlocks, AutoPipelineBlocks, ConditionalPipelineBlocks, LoopSequentialPipelineBlocks), khởi tạo lớp được chọn và gọi save_pretrained trong thư mục làm việc hiện tại.

# 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

Lớp block phải có thể khởi tạo với số lượng đối số constructor bằng 0 và hardcode các giá trị mặc định trong __init__ hoặc đọc config từ state của pipeline tại thời điểm gọi.

fp16_safetensors

Lệnh này hiện đã bị ngừng hỗ trợ và sẽ bị loại bỏ trong một phiên bản tương lai.

Chuyển đổi checkpoint trên Hub sang .safetensors fp16 và đẩy kết quả. Hữu ích để giảm kích thước trọng số của repo, giúp tải nhanh hơn. Xem diffusers-cli fp16_safetensors --help để biết chính xác các tham số.

kỹ năng

Cài đặt các kỹ năng từ kho 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

Nếu không có cờ đích, CLI sẽ cài đặt cho tác nhân đã khởi chạy nó, hoặc cho mọi tác nhân khi không thể xác định. Claude Code nhận một gói plugin dưới .claude/skills/diffusers/ (được đặt trong không gian tên /diffusers:<skill name>). Codex và Cursor nhận .agents/skills/<skill name>/.