Formatos de modelo

Os modelos de difusão são geralmente armazenados no formato Diffusers ou no formato de arquivo único. Os arquivos de modelo podem ser armazenados em vários tipos de arquivo, como safetensors ou ckpt.

Formato refere-se a se os pesos são armazenados em uma estrutura de diretórios. Tipo de arquivo refere-se a como esses pesos são serializados, como safetensors ou ckpt.

Diffusers format                    Single-file format
model/                              model.safetensors   (or .ckpt)
├─ model_index.json                 └─ all components in one file
├─ unet/  (or transformer/)
├─ text_encoder/
├─ vae/
└─ scheduler/

Este guia mostrará como carregar pipelines e modelos a partir desses formatos e arquivos.

Formato Diffusers

O formato Diffusers armazena cada modelo (UNet, transformer, text encoder) em uma subpasta separada. Há vários benefícios em armazenar os modelos separadamente.

Inicialização mais rápida do pipeline geral, pois você pode carregar o modelo individual de que precisa ou carregá-los todos em paralelo.
Menor uso de memória, pois você não precisa carregar todos os componentes do pipeline se precisar de apenas um modelo. Reutilize um modelo que é compartilhado entre vários pipelines.
Menores requisitos de armazenamento, pois os modelos comuns compartilhados entre vários pipelines são baixados apenas uma vez.
Flexibilidade para usar modelos novos ou aprimorados em um pipeline.

Formato de arquivo único

O formato de arquivo único armazena todos os pesos do modelo (UNet, transformer, text encoder) em um único arquivo. Os benefícios dos formatos de arquivo único incluem:

Maior compatibilidade com ComfyUI ou Automatic1111.
Mais fácil de baixar e compartilhar um único arquivo.

Use from_single_file() para carregar um arquivo único.

import torch
from diffusers import StableDiffusionXLPipeline

pipeline = StableDiffusionXLPipeline.from_single_file(
    "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0.safetensors",
    dtype=torch.float16,
    device_map="cuda"  # or "mps", "xpu", "cpu"
)

O método from_single_file() também suporta a passagem de novos modelos ou agendadores.

import torch
from diffusers import FluxPipeline, FluxTransformer2DModel

transformer = FluxTransformer2DModel.from_single_file(
    "https://huggingface.co/Kijai/flux-fp8/blob/main/flux1-dev-fp8.safetensors", dtype=torch.bfloat16
)
pipeline = FluxPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev",
    transformer=transformer,
    dtype=torch.bfloat16,
    device_map="cuda"  # or "mps", "xpu", "cpu"
)

Opções de configuração

Os modelos no formato Diffusers possuem um arquivo config.json em seus repositórios com atributos importantes, como o número de camadas e cabeças de atenção. O método from_single_file() determina automaticamente a configuração adequada a ser usada a partir do config.json. No entanto, isso pode falhar em alguns casos raros, nos quais você deve usar o argumento config.

Você também deve usar o argumento config se os modelos em um pipeline forem diferentes da implementação original ou se ele não tiver os metadados necessários para determinar a configuração correta.

from diffusers import StableDiffusionXLPipeline

ckpt_path = "https://huggingface.co/segmind/SSD-1B/blob/main/SSD-1B.safetensors"

pipeline = StableDiffusionXLPipeline.from_single_file(ckpt_path, config="segmind/SSD-1B")

Ao passar original_config com local_files_only=True, o Diffusers infere os componentes do pipeline a partir da assinatura da classe do pipeline. Ele não baixa arquivos de configuração do Hub, o que evita mudanças que quebram a compatibilidade quando você está offline. Esse caminho é menos confiável do que fornecer a config um caminho local para o modelo e pode resultar em erro. Execute uma vez com local_files_only=False para que as configurações fiquem no cache local, caso você precise delas offline mais tarde.

Substitua as configurações padrão passando os argumentos diretamente para from_single_file(). Os exemplos abaixo demonstram como substituir as configurações em um pipeline ou modelo.

pipeline

model

Arquivos locais

O método from_single_file() tenta configurar um pipeline ou modelo inferindo o tipo de modelo a partir das chaves no arquivo de checkpoint. Por exemplo, qualquer checkpoint de arquivo único baseado no modelo base Stable Diffusion XL é configurado a partir de stabilityai/stable-diffusion-xl-base-1.0.

Se você estiver trabalhando com arquivos locais, baixe os arquivos de configuração com o método snapshot_download e o checkpoint do modelo com hf_hub_download. Esses arquivos são baixados para o seu diretório de cache, mas você pode baixá-los para um diretório específico com o argumento local_dir.

from huggingface_hub import hf_hub_download, snapshot_download
from diffusers import StableDiffusionXLPipeline

my_local_checkpoint_path = hf_hub_download(
    repo_id="segmind/SSD-1B",
    filename="SSD-1B.safetensors"
)

my_local_config_path = snapshot_download(
    repo_id="segmind/SSD-1B",
    allow_patterns=["*.json", "**/*.json", "*.txt", "**/*.txt"]
)

pipeline = StableDiffusionXLPipeline.from_single_file(
    my_local_checkpoint_path, config=my_local_config_path, local_files_only=True
)

Symlink

Se você estiver trabalhando com um sistema de arquivos que não suporta links simbólicos, baixe primeiro o arquivo de checkpoint para um diretório local usando o parâmetro local_dir. O uso do parâmetro local_dir desativa automaticamente os links simbólicos.

from huggingface_hub import hf_hub_download, snapshot_download
from diffusers import StableDiffusionXLPipeline

my_local_checkpoint_path = hf_hub_download(
    repo_id="segmind/SSD-1B",
    filename="SSD-1B.safetensors",
    local_dir="my_local_checkpoints",
)
print("My local checkpoint: ", my_local_checkpoint_path)

my_local_config_path = snapshot_download(
    repo_id="segmind/SSD-1B",
    allow_patterns=["*.json", "**/*.json", "*.txt", "**/*.txt"]
)
print("My local config: ", my_local_config_path)

Passe esses caminhos para from_single_file().

pipeline = StableDiffusionXLPipeline.from_single_file(
    my_local_checkpoint_path, config=my_local_config_path, local_files_only=True
)

Tipos de arquivo

Os modelos podem ser armazenados em vários tipos de arquivo. Safetensors é o tipo de arquivo mais comum, mas você pode encontrar outros tipos de arquivo no Hub ou na comunidade de difusão.

safetensors

Safetensors é um tipo de arquivo seguro e rápido para armazenar e carregar tensors com segurança. Ele restringe o tamanho do cabeçalho para limitar certos tipos de ataques, suporta carregamento preguiçoso (útil para configurações distribuídas) e, em geral, carrega mais rápido.

O Diffusers carrega o arquivo safetensors por padrão (uma dependência obrigatória) se estiverem disponíveis e a biblioteca Safetensors estiver instalada.

Use from_pretrained() or from_single_file() to load safetensor files.

import torch
from diffusers import DiffusionPipeline, StableDiffusionXLPipeline

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

pipeline = StableDiffusionXLPipeline.from_single_file(
    "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0.safetensors",
    dtype=torch.float16,
)

Se você estiver usando um checkpoint treinado com um script de treinamento do Diffusers, metadados, como a configuração do LoRA, são salvos automaticamente. Quando o arquivo é carregado, esses metadados são analisados para que o LoRA seja configurado corretamente. Inspecione os metadados de um arquivo safetensors clicando no ícone ao lado do arquivo no Hub.

Salve os metadados do adaptador LoRA para checkpoints que não foram treinados com Diffusers passando-os para save_lora_weights(). Use transformer_lora_adapter_metadata para o transformer e text_encoder_lora_adapter_metadata para o text encoder. Você também deve passar save_directory e pelo menos um de transformer_lora_layers ou text_encoder_lora_layers. Este caminho é suportado apenas para arquivos safetensors.

import torch
from peft.utils import get_peft_model_state_dict
from diffusers import FluxPipeline

pipeline = FluxPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
pipeline.load_lora_weights("linoyts/yarn_art_Flux_LoRA")

transformer_lora_layers = get_peft_model_state_dict(pipeline.transformer)
pipeline.save_lora_weights(
    save_directory="path/to/lora",
    transformer_lora_layers=transformer_lora_layers,
    transformer_lora_adapter_metadata={"r": 8, "lora_alpha": 8},
)

ckpt

Pesos de modelos mais antigos são comumente salvos com a utilidade pickle do Python em um arquivo ckpt.

Arquivos pickled podem ser inseguros, pois podem ser explorados para executar código malicioso. Recomenda-se o uso de arquivos safetensors ou a conversão dos pesos para arquivos safetensors.

Use from_single_file() para carregar um arquivo ckpt.

from diffusers import StableDiffusionPipeline

pipeline = StableDiffusionPipeline.from_single_file(
    "https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/blob/main/v1-5-pruned.ckpt"
)

GGUF

GGUF armazena pesos pré-quantizados em um único arquivo. Diffusers carrega GGUF através do método from_single_file() do modelo com GGUFQuantizationConfig. O carregamento de GGUF no nível de pipeline não é suportado.

Veja GGUF para as etapas de instalação e exemplos completos.

import torch
from diffusers import FluxTransformer2DModel, GGUFQuantizationConfig

transformer = FluxTransformer2DModel.from_single_file(
    "https://huggingface.co/city96/FLUX.1-dev-gguf/blob/main/flux1-dev-Q2_K.gguf",
    quantization_config=GGUFQuantizationConfig(compute_dtype=torch.bfloat16),
)

Convertendo formatos e arquivos

O Diffusers fornece scripts e métodos para converter formatos e arquivos, permitindo que mais ferramentas no ecossistema de difusão os utilizem.

Dê uma olhada na pasta diffusers/scripts para encontrar um script de conversão. Scripts com "to_diffusers" adicionado ao final convertem um modelo para o formato Diffusers. Cada script tem um conjunto específico de argumentos para configurar a conversão. Certifique-se de verificar quais argumentos estão disponíveis.

O exemplo abaixo converte um modelo armazenado no formato Diffusers para um formato de arquivo único. Forneça o caminho do modelo a ser convertido e o local onde salvar o modelo convertido. Você pode especificar opcionalmente o tipo de arquivo e o tipo de dados para salvar o modelo.

python convert_diffusers_to_original_sdxl.py --model_path path/to/model/to/convert --checkpoint_path path/to/save/model/to --use_safetensors

O método save_pretrained() também salva um modelo no formato Diffusers e cuida da criação de subpastas para cada modelo. Ele salva os arquivos como arquivos safetensor por padrão.

from diffusers import StableDiffusionXLPipeline

pipeline = StableDiffusionXLPipeline.from_single_file(
    "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0.safetensors",
)
pipeline.save_pretrained("path/to/save/model")

Próximas etapas

Saiba mais sobre as decisões de design e por que os arquivos safetensor são preferidos para salvar e carregar pesos de modelos no post do blog Safetensors audited as really safe and becoming the default.

Update on GitHub