Carregando modelos

O Transformers oferece muitos modelos pré-treinados que estão prontos para uso com uma única linha de código. É necessário uma classe de modelo e o método from_pretrained().

Chame from_pretrained() para baixar e carregar os pesos e a configuração de um modelo armazenados no Hub do Hugging Face.

O método from_pretrained() carrega os pesos armazenados no formato de arquivo safetensors, caso estejam disponíveis. Tradicionalmente, os pesos de modelos do PyTorch são serializados com a utilidade pickle, que é conhecida por ser insegura. Os arquivos Safetensor são mais seguros e mais rápidos para carregar.

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-2-7b-hf", device_map="auto")

Este guia explica como os modelos são carregados, as diferentes maneiras de carregar um modelo, como superar problemas de memória para modelos muito grandes e como carregar modelos personalizados.

Modelos e configurações

Todos os modelos possuem um arquivo configuration.py com atributos específicos, como o número de camadas ocultas, o tamanho do vocabulário, a função de ativação e outros. Você também encontrará um arquivo modeling.py que define as camadas e as operações matemáticas realizadas dentro de cada camada. O arquivo modeling.py utiliza os atributos do modelo em configuration.py e constrói o modelo de acordo. Neste ponto, você tem um modelo com pesos aleatórios que precisa ser treinado para produzir resultados significativos.

Uma arquitetura se refere ao esqueleto do modelo e um checkpoint se refere aos pesos do modelo para uma determinada arquitetura. Por exemplo, BERT é uma arquitetura, enquanto google-bert/bert-base-uncased é um checkpoint. Você verá o termo modelo usado de forma intercambiável com arquitetura e checkpoint.

Existem dois tipos gerais de modelos que você pode carregar:

1. Um modelo básico, como AutoModel ou LlamaModel, que produz estados ocultos.
2. Um modelo com um head específico acoplado, como AutoModelForCausalLM ou LlamaForCausalLM, para executar tarefas específicas.

Classes de modelo

Para obter um modelo pré-treinado, é necessário carregar os pesos no modelo. Isso é feito chamando from_pretrained(), que aceita pesos do Hugging Face Hub ou de um diretório local.

Há duas classes de modelo: a classe AutoModel e uma classe específica do modelo.

from transformers import AutoModelForCausalLM, AutoModelForSequenceClassification, AutoModelForQuestionAnswering

# use the same API for 3 different tasks
model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-2-7b-hf")
model = AutoModelForSequenceClassification.from_pretrained("meta-llama/Llama-2-7b-hf")
model = AutoModelForQuestionAnswering.from_pretrained("meta-llama/Llama-2-7b-hf")

from transformers import AutoModelForCausalLM

# use the same API to load 3 different models
model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-2-7b-hf")
model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-v0.1")
model = AutoModelForCausalLM.from_pretrained("google/gemma-7b")

from transformers import LlamaModel, LlamaForCausalLM

model = LlamaForCausalLM.from_pretrained("meta-llama/Llama-2-7b-hf")

Modelos grandes

Modelos pré-treinados de grande porte exigem muita memória para serem carregados. O processo de carregamento envolve:

1. criando um modelo com pesos aleatórios
2. carregando os pesos pré-treinados
3. colocando os pesos pré-treinados no modelo

Você precisa de memória suficiente para armazenar duas cópias dos pesos do modelo (aleatórios e pré-treinados), o que pode não ser possível dependendo do seu hardware. Em ambientes de treinamento distribuído, isso é ainda mais desafiador, pois cada processo carrega um modelo pré-treinado.

O Transformers reduz alguns desses desafios relacionados à memória com inicialização rápida, checkpoints particionados, o recurso Big Model Inference do Accelerate e o suporte a tipos de dados de bits mais baixos.

Pontos de verificação fragmentados

save_pretrained() faz o particionamento automático de checkpoints maiores que 50GB. Isso mantém o número de shards baixo para modelos grandes e simplifica o gerenciamento de arquivos.

Os parâmetros são carregados em paralelo e a memória de pico depende apenas do tamanho do modelo. Use max_shard_size em save_pretrained() para definir o tamanho máximo do checkpoint antes da divisão em shards.

O uso de memória para modelos que exigem conversão dinâmica de pesos depende do tamanho do modelo e do tamanho dos maiores parâmetros em uma única conversão. Isso geralmente se aplica a modelos de mistura de especialistas (MoE), em que o uso de memória é o tamanho do modelo mais o número de especialistas em uma camada. Consulte o guia do dynamic weight loader para saber mais sobre como os modelos são carregados.

save_pretrained() também cria um arquivo de índice que mapeia os nomes dos parâmetros para seus arquivos de fragmento. O índice contém duas chaves, metadata e weight_map.

import json
import os
import tempfile

with tempfile.TemporaryDirectory() as tmp_dir:
    model.save_pretrained(tmp_dir, max_shard_size="50GB")
    with open(os.path.join(tmp_dir, "model.safetensors.index.json"), "r") as f:
        index = json.load(f)

print(index.keys())

metadata armazena o tamanho total do modelo.

index["metadata"]
{'total_size': 28966928384}

weight_map mapeia cada parâmetro para seu arquivo de shard.

index["weight_map"]
{'lm_head.weight': 'model-00006-of-00006.safetensors',
 'model.embed_tokens.weight': 'model-00001-of-00006.safetensors',
 'model.layers.0.input_layernorm.weight': 'model-00001-of-00006.safetensors',
 'model.layers.0.mlp.down_proj.weight': 'model-00001-of-00006.safetensors',
 ...
}

Inferência de Modelos Grandes

Certifique-se de ter o Accelerate v0.9.0 e o PyTorch v1.9.0 ou posterior instalados para usar este recurso!

from_pretrained() é superpotencializado pelo recurso Big Model Inference do Accelerate.

O Big Model Inference cria um esqueleto do modelo no dispositivo meta do PyTorch. O dispositivo meta não armazena nenhum dado real, apenas os metadados.

Os pesos inicializados aleatoriamente são criados apenas quando os pesos pré-treinados são carregados, a fim de evitar manter duas cópias do modelo na memória ao mesmo tempo. O uso máximo de memória é apenas o tamanho do modelo.

Saiba mais sobre a alocação de dispositivos em Projetando um mapa de dispositivos.

A segunda funcionalidade do Big Model Inference está relacionada à forma como os pesos são carregados e distribuídos no esqueleto do modelo. Os pesos do modelo são distribuídos entre todos os dispositivos disponíveis, começando pelo dispositivo mais rápido (geralmente a GPU) e, em seguida, transferindo os pesos restantes para dispositivos mais lentos (CPU e disco rígido).

A combinação de ambos os recursos reduz o uso de memória e os tempos de carregamento para grandes modelos pré-treinados.

Defina device_map como "auto" para habilitar o Big Model Inference.

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained("google/gemma-7b", device_map="auto")

Você também pode atribuir manualmente camadas a um dispositivo em device_map. Ele deve mapear todos os parâmetros do modelo para um dispositivo, mas você não precisa detalhar para onde cada submódulo de uma camada vai, caso a camada inteira esteja no mesmo dispositivo.

Acesse o atributo hf_device_map para ver como um modelo é distribuído entre os dispositivos.

device_map = {"model.layers.1": 0, "model.layers.14": 1, "model.layers.31": "cpu", "lm_head": "disk"}
model.hf_device_map

Deslocamento para o disco

Quando um modelo é grande demais para a soma das suas GPUs e da RAM da CPU, o Big Model Inference transfere os pesos restantes para o disco. Defina offload_folder para um diretório sempre que qualquer peso for mapeado para "disk", pois é lá que o Transformers armazena os pesos transferidos.

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "google/gemma-7b",
    device_map="auto",
    offload_folder="./offload",
)

Use max_memory para limitar a quantidade de memória que cada dispositivo pode usar. O Transformers preenche os dispositivos em ordem de velocidade e envia para o disco o que não couber. O exemplo abaixo limita a GPU a 10GB e a CPU a 30GB, de modo que os pesos restantes ficam armazenados em offload_folder.

model = AutoModelForCausalLM.from_pretrained(
    "google/gemma-7b",
    device_map="auto",
    max_memory={0: "10GB", "cpu": "30GB"},
    offload_folder="./offload",
)

Defina max_memory={} para especificar que não há memória de gpu ou cpu disponível e forçar o offloading do modelo inteiro para o disco.

model = AutoModelForCausalLM.from_pretrained(
    "google/gemma-7b",
    device_map="auto",
    max_memory={},
    offload_folder="./offload",
)

O offloading para o disco troca memória por velocidade. Ler os pesos do disco a cada passagem de frente é mais lento do que ler da memória da CPU ou da GPU. O offloading totalmente para o disco requer accelerate>1.14.0

Tipo de dados do modelo

O argumento dtype controla o dtype do PyTorch usado para instanciar os pesos do modelo. Por padrão, o Transformers carrega os pesos com o valor de dtype ou do legado torch_dtype de config.json. Se o config.json não incluir nenhum desses valores, o Transformers usa o dtype do primeiro peso de ponto flutuante no checkpoint.

Substitua o padrão passando um dtype específico.

import torch
from transformers import AutoModelForCausalLM

# specific dtype
model = AutoModelForCausalLM.from_pretrained("google/gemma-3-1b-it", dtype=torch.float16)

AutoConfig também aceita dtype para modelos instanciados do zero.

import torch
from transformers import AutoConfig, AutoModel

my_config = AutoConfig.from_pretrained("google/gemma-2b", dtype=torch.float16)
model = AutoModel.from_config(my_config)

Modelos personalizados

Modelos personalizados são construídos com base nas classes de configuração e modelagem do Transformers, dão suporte à API AutoClass e são carregados com from_pretrained(). A diferença é que o código de modelagem não vem do Transformers.

Tenha redobrada cautela ao carregar um modelo personalizado. Embora o Hub inclua varredura de malware em todos os repositórios, você ainda deve ter cuidado para evitar a execução acidental de código malicioso.

Defina trust_remote_code=True em from_pretrained() para carregar um modelo personalizado.

from transformers import AutoModelForImageClassification

model = AutoModelForImageClassification.from_pretrained("sgugger/custom-resnet50d", trust_remote_code=True)

Como uma camada extra de segurança, carregue um modelo personalizado de uma revisão específica para evitar o carregamento de código de modelo que pode ter sido alterado. O hash do commit pode ser copiado do histórico de commits dos modelos.

commit_hash = "ed94a7c6247d8aedce4647f00f20de6875b5b292"
model = AutoModelForImageClassification.from_pretrained(
    "sgugger/custom-resnet50d", trust_remote_code=True, revision=commit_hash
)

Consulte o guia Customize models para obter mais informações.