diffusers/v0.43.0/pt/quicktour.md

Início rápido

Diffusers é uma biblioteca para desenvolvedores e pesquisadores que fornece uma API de inferência simples para gerar imagens, vídeos e áudio, além dos blocos de construção para implementar novos fluxos de trabalho.

O Diffusers oferece muitas otimizações nativas que permitem carregar e executar modelos grandes em configurações com memória limitada ou acelerar a inferência.

Este Quickstart fornecerá uma visão geral do Diffusers e permitirá que você comece a gerar rapidamente.

Antes de começar, verifique se você tem uma conta do Hugging Face para usar modelos com acesso restrito, como o Flux. Prefere construir um pipeline personalizado? Consulte o Modular Diffusers quickstart e a overview.

Siga o guia de Instalação para instalar o Diffusers, caso ainda não esteja instalado.

Prompt do agente

Cole isso no seu agente de codificação para configurar o Diffusers para inferência.

Help me get set up with Hugging Face Diffusers for inference.

1. Install Diffusers for my environment with `uv pip install "diffusers[torch]"`.
2. If I need gated Hub models, help me authenticate to the Hugging Face Hub.
3. Install Diffusers coding agent skills with `diffusers-cli skills add diffusers-cli`. Pass `--cursor`, `--claude`, or `--codex` if auto-detect fails. Optionally pass `--all` to install every skill in the registry.
4. Run a first text-to-image with DiffusionPipeline or `diffusers-cli run`, using a small or current Quickstart model and the right `device_map` for my machine.
5. Ask what I want next and point me at the matching docs.

DiffusionPipeline

DiffusionPipeline agrupa os componentes de um modelo de difusão (codificador de texto, agendador, UNet ou DiT e VAE) em uma única classe para inferência. Carregue com from_pretrained() e, em seguida, chame o pipeline.

Argumentos em __call__() como num_inference_steps alteram a qualidade e a velocidade. Para detalhes de carregamento e componentes combinados, consulte Carregar pipelines. Para trocar o agendador, consulte Agendadores.

Os exemplos abaixo usam os valores padrão dos argumentos.

Use .images[0] para acessar a imagem gerada.

import torch
from diffusers import DiffusionPipeline

pipeline = DiffusionPipeline.from_pretrained(
  "Qwen/Qwen-Image", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)

prompt = """
cinematic film still of a cat sipping a margarita in a pool in Palm Springs, California
highly detailed, high budget hollywood movie, cinemascope, moody, epic, gorgeous, film grain
"""
pipeline(prompt).images[0]

Use .frames[0] para acessar o vídeo gerado e export_to_video() para salvar o vídeo.

import torch
from diffusers import AutoencoderKLWan, DiffusionPipeline
from diffusers.utils import export_to_video

vae = AutoencoderKLWan.from_pretrained(
  "Wan-AI/Wan2.2-T2V-A14B-Diffusers",
  subfolder="vae",
  dtype=torch.float32
)
pipeline = DiffusionPipeline.from_pretrained(
  "Wan-AI/Wan2.2-T2V-A14B-Diffusers",
  vae=vae,
  dtype=torch.bfloat16,
  device_map="cuda"  # or "mps", "xpu", "cpu"
)

prompt = """
Cinematic video of a sleek cat lounging on a colorful inflatable in a crystal-clear turquoise pool in Palm Springs, 
sipping a salt-rimmed margarita through a straw. Golden-hour sunlight glows over mid-century modern homes and swaying palms. 
Shot in rich Sony a7S III: with moody, glamorous color grading, subtle lens flares, and soft vintage film grain. 
Ripples shimmer as a warm desert breeze stirs the water, blending luxury and playful charm in an epic, gorgeously composed frame.
"""
video = pipeline(prompt=prompt, num_frames=81, num_inference_steps=40).frames[0]
export_to_video(video, "output.mp4", fps=16)

LoRA

Os adaptadores LoRA adicionam um checkpoint de estilo ou assunto pequeno sobre um pipeline base. Carregue um com load_lora_weights(). Alguns LoRAs precisam de uma frase gatilho. Verifique o cartão de modelo do LoRA.

import torch
from diffusers import DiffusionPipeline

pipeline = DiffusionPipeline.from_pretrained(
  "Qwen/Qwen-Image", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
pipeline.load_lora_weights(
  "threecrowco/VolkClipartQwen",
  weight_name="pytorch_lora_weights.safetensors",
)

prompt = """
Volk clipart style drawing of a cat sipping a margarita in a pool in Palm Springs, California, flat colors, bold outlines, simple shapes
"""
pipeline(prompt).images[0]

Quantização e otimizações

Modelos grandes geralmente precisam de menos memória ou mais velocidade. Use quantização para reduzir os pesos na memória e compile_repeated_blocks() para acelerar gerações posteriores. Para offloading de modelos e outras opções, consulte Otimizar e escalar.

Para usar menos memória, carregue em 4 bits com bitsandbytes.

import torch
from diffusers import DiffusionPipeline
from diffusers.quantizers import PipelineQuantizationConfig

quant_config = PipelineQuantizationConfig(
  quant_backend="bitsandbytes_4bit",
  quant_kwargs={"load_in_4bit": True, "bnb_4bit_quant_type": "nf4", "bnb_4bit_compute_dtype": torch.bfloat16},
  components_to_quantize=["transformer", "text_encoder"],
)
pipeline = DiffusionPipeline.from_pretrained(
  "Qwen/Qwen-Image",
  dtype=torch.bfloat16,
  quantization_config=quant_config,
  device_map="cuda"  # or "mps", "xpu", "cpu"
)

prompt = """
cinematic film still of a cat sipping a margarita in a pool in Palm Springs, California
highly detailed, high budget hollywood movie, cinemascope, moody, epic, gorgeous, film grain
"""
pipeline(prompt).images[0]

Para acelerar execuções posteriores, compile blocos repetidos no transformer. O primeiro generate após o compile é um cold start e é lento. Os generates subsequentes são mais rápidos.

import torch
from diffusers import DiffusionPipeline

pipeline = DiffusionPipeline.from_pretrained(
  "Qwen/Qwen-Image", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
pipeline.transformer.compile_repeated_blocks(fullgraph=True)

prompt = """
cinematic film still of a cat sipping a margarita in a pool in Palm Springs, California
highly detailed, high budget hollywood movie, cinemascope, moody, epic, gorgeous, film grain
"""
pipeline(prompt).images[0]

Próximas etapas

• Inferência — pipelines, prompting e adaptadores
• Otimizar e escalar — memória, velocidade, quantização e serviço
• Modular Diffusers — blocos componíveis e pipelines personalizados
• Treinar e ajustar — scripts de treinamento e adaptadores
• CLI — gerar a partir da linha de comando