diffusers/v0.43.0/pt/using-diffusers/schedulers.md

Agendadores

Um scheduler informa ao loop de remoção de ruído a quantidade de ruído a ser removida em cada etapa. Diferentes schedulers equilibram velocidade e qualidade.

Este guia mostra como carregar um scheduler e personalizar seu schedule de timestep, espaçamento e sigmas.

Escolhendo um agendador

Comece do checkpoint padrão. Troque apenas se precisar de um compromisso diferente entre velocidade e qualidade.

• DPM++ 2M SDE Karras é uma opção versátil e robusta para muitos checkpoints de difusão latente.
• TCDScheduler funciona bem para modelos destilados.
• Use FlowMatchEulerDiscreteScheduler ou FlowMatchHeunDiscreteScheduler para modelos FlowMatch (Qwen-Image, Flux e similares).
• EulerDiscreteScheduler ou EulerAncestralDiscreteScheduler costumam funcionar bem para imagens em estilo anime.
• LCMScheduler com um LCM UNet ou LoRA para geração em poucas etapas, quando o checkpoint for compatível.

Carregando agendadores

Modelos de flow-matching, como Qwen-Image e Flux, incluem FlowMatchEulerDiscreteScheduler como padrão. Mantenha esse scheduler, a menos que esteja experimentando intencionalmente. Substitua com from_config() apenas quando a substituição for compatível com o checkpoint.

Schedulers são apenas de configuração e não incluem tensores de pesos. Acesse o atributo .scheduler em um pipeline para inspecionar a configuração carregada.

import torch
from diffusers import DiffusionPipeline

pipeline = DiffusionPipeline.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0", dtype=torch.float16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
pipeline.scheduler

Para trocar os agendadores em um pipeline carregado, use from_config() com a configuração existente do agendador para que num_train_timesteps e os campos relacionados permaneçam alinhados. Para checkpoints de FlowMatch (Qwen-Image, Flux e similares), mantenha FlowMatchEulerDiscreteScheduler a menos que você esteja experimentando intencionalmente com um substituto compatível.

from diffusers import DPMSolverMultistepScheduler

pipeline.scheduler = DPMSolverMultistepScheduler.from_config(pipeline.scheduler.config)

Você também pode carregar uma configuração de agendador do Hub com from_pretrained() e passá-la para from_pretrained() por meio de scheduler.

from diffusers import DiffusionPipeline, DPMSolverMultistepScheduler

dpm = DPMSolverMultistepScheduler.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0", subfolder="scheduler"
)
pipeline = DiffusionPipeline.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0",
    scheduler=dpm,
    dtype=torch.float16,
    device_map="cuda",  # or "mps", "xpu", "cpu"
)
pipeline.scheduler

Agendamentos de passo

O timestep ou o agendamento de ruído determina como o ruído é distribuído ao longo do processo de desruidamento. O agendamento pode ser linear ou mais concentrado no início ou no final. Trata-se de uma sequência pré-computada de níveis de ruído gerada a partir da configuração padrão do agendador, mas pode ser personalizada para usar outros agendamentos.

linear (even steps)                 AYS (denser where it matters)
noise                               noise
  ^                                   ^
  | *                                 | *
  |  *                                |   *
  |   *                               |    **
  |    *                              |     ***
  |     *                             |      **
  |      *                            |        *
  |       *                           |          *
  +-----------------> step            +-----------------> step

timesteps personalizados só funcionam se o set_timesteps daquele scheduler aceitar o argumento (os pipelines verificam a assinatura via retrieve_timesteps e lançam ValueError caso contrário). Verifique a página de API do scheduler ou a assinatura de set_timesteps antes de passá-los.

O exemplo abaixo usa o agendamento Align Your Steps (AYS), que pode gerar uma imagem de alta qualidade em 10 etapas, acelerando significativamente a geração e reduzindo o tempo de computação.

Importe o schedule e passe-o para o argumento timesteps no pipeline.

import torch
from diffusers import DiffusionPipeline, DPMSolverMultistepScheduler
from diffusers.schedulers import AysSchedules

sampling_schedule = AysSchedules["StableDiffusionXLTimesteps"]
print(sampling_schedule)
# [999, 845, 730, 587, 443, 310, 193, 116, 53, 13]

pipeline = DiffusionPipeline.from_pretrained(
    "SG161222/RealVisXL_V4.0",
    dtype=torch.float16,
    device_map="cuda"  # or "mps", "xpu", "cpu"
)
pipeline.scheduler = DPMSolverMultistepScheduler.from_config(
  pipeline.scheduler.config, algorithm_type="sde-dpmsolver++"
)

prompt = "A cinematic shot of a cute little rabbit wearing a jacket and doing a thumbs up"
image = pipeline(
    prompt=prompt,
    negative_prompt="",
    timesteps=sampling_schedule,
).images[0]

Plano de passos de tempo AYS 10 passos



Agendamento de passos de tempo espaçados linearmente 10 passos



Agendamento de passos de tempo espaçados linearmente 25 passos

Para o redimensionamento de v-prediction/zero-SNR em checkpoints mais antigos, consulte Checkpoints legados.

Espaçamento de passo de tempo

O espaçamento de timesteps se refere às etapas específicas t a serem amostradas do agendamento. O Diffusers fornece três tipos de espaçamento, conforme mostrado abaixo.

estratégia de espaçamento	cálculo de espaçamento	passos de tempo de exemplo
leading	passos igualmente espaçados	[900, 800, 700, ..., 100, 0]
linspace	inclua o primeiro e o último passos e divida uniformemente os passos intermediários restantes	[1000, 888.89, 777.78, ..., 111.11, 0]
trailing	inclua a última etapa e divida uniformemente as etapas intermediárias restantes, começando pelo final	[999, 899, 799, 699, 599, 499, 399, 299, 199, 99]

Passe a estratégia de espaçamento para o argumento timestep_spacing no agendador.

A estratégia trailing geralmente produz imagens de maior qualidade, com mais detalhes e em menos etapas, mas a diferença de qualidade não é tão óbvia para valores de etapas mais padrão.

import torch
from diffusers import DiffusionPipeline, DPMSolverMultistepScheduler

pipeline = DiffusionPipeline.from_pretrained(
    "SG161222/RealVisXL_V4.0",
    dtype=torch.float16,
    device_map="cuda"  # or "mps", "xpu", "cpu"
)
pipeline.scheduler = DPMSolverMultistepScheduler.from_config(
  pipeline.scheduler.config, timestep_spacing="trailing"
)

prompt = "A cinematic shot of a cute little black cat sitting on a pumpkin at night"
image = pipeline(
    prompt=prompt,
    negative_prompt="",
    num_inference_steps=5,
).images[0]
image

espaçamento final após 5 etapas



espaçamento à esquerda após 5 etapas

Sigmas

Sigmas é uma medida de quão ruidoso é uma amostra em uma etapa específica, conforme definido pelo agendamento. Ao usar sigmas personalizados, os timesteps são calculados a partir desses valores em vez da configuração padrão do agendador.

step:   0    1    2    3    4
sigma:  σ0 > σ1 > σ2 > σ3 > σ4 ≈ 0
        high noise  --->  clean sample

sigmas personalizados só funcionam se o set_timesteps daquele scheduler aceitar o argumento (os pipelines verificam a assinatura via retrieve_timesteps e lançam ValueError caso contrário). Verifique a página de API do scheduler ou a assinatura de set_timesteps antes de passá-los.

Passe os sigmas personalizados para o argumento sigmas no pipeline. O exemplo abaixo usa os sigmas da agenda AYS de 10 etapas.

import torch
from diffusers import DiffusionPipeline, EulerDiscreteScheduler
from diffusers.schedulers import AysSchedules

pipeline = DiffusionPipeline.from_pretrained(
    "SG161222/RealVisXL_V4.0",
    dtype=torch.float16,
    device_map="cuda",  # or "mps", "xpu", "cpu"
)
pipeline.scheduler = EulerDiscreteScheduler.from_config(pipeline.scheduler.config)

sigmas = AysSchedules["StableDiffusionXLSigmas"]
prompt = "A cinematic shot of a cute little rabbit wearing a jacket and doing a thumbs up"
image = pipeline(
    prompt=prompt,
    negative_prompt="",
    sigmas=sigmas,
).images[0]

Karras sigmas

Karras sigmas reamostra o agendamento de ruído para uma amostragem mais eficiente, agrupando os sigmas de forma mais densa no meio da sequência, onde a reconstrução da estrutura é crítica, enquanto usa menos sigmas no início e no final, onde as mudanças de ruído têm menos impacto. Isso pode aumentar o nível de detalhes em uma imagem gerada.

default σ:  *  *  *  *  *  *  *  *     even-ish
Karras σ:   *   * * * * *   *          denser mid, sparser ends
            |---structure---|

Defina use_karras_sigmas=True no agendador para ativá-lo.

import torch
from diffusers import DiffusionPipeline, DPMSolverMultistepScheduler

pipeline = DiffusionPipeline.from_pretrained(
    "SG161222/RealVisXL_V4.0",
    dtype=torch.float16,
    device_map="cuda"  # or "mps", "xpu", "cpu"
)
pipeline.scheduler = DPMSolverMultistepScheduler.from_config(
  pipeline.scheduler.config,
  algorithm_type="sde-dpmsolver++",
  use_karras_sigmas=True,
)

prompt = "A cinematic shot of a cute little rabbit wearing a jacket and doing a thumbs up"
image = pipeline(
    prompt=prompt,
    negative_prompt="",
    num_inference_steps=20,
).images[0]

Karras sigmas habilitado



Karras sigmas desativados

Consulte a visão geral da API do scheduler para obter a lista de schedulers que suportam Karras sigmas. Ele deve ser usado apenas para modelos treinados com Karras sigmas.

Próximas etapas

• Leia o artigo Common Diffusion Noise Schedules and Sample Steps are Flawed para mais detalhes sobre o reescalonamento do agendamento de ruído para impor SNR zero.