Este guia ensina a ajustar o Gemma em um conjunto de dados de imagens e textos personalizado para uma tarefa de visão (gerar descrições de produtos) usando os Transformers e o TRL do Hugging Face. Você vai aprender a realizar as tarefas a seguir:
- O que é a adaptação quantizada de baixa classificação (QLoRA)
- Configurar o ambiente de desenvolvimento
- Criar e preparar o conjunto de dados de ajuste fino para tarefas de visão
- Ajustar o Gemma usando o TRL e o SFTTrainer
- Teste a inferência de modelo e gere descrições de produtos com base em imagens e texto.
O que é a adaptação quantizada de baixa classificação (QLoRA)
Este guia demonstra o uso da adaptação quantizada de baixa classificação (QLoRA), que surgiu como um método conhecido para ajustar com eficiência os LLMs, já que reduz os requisitos de recursos computacionais e mantém o alto desempenho. Na QloRA, o modelo pré-treinado é quantizado para 4 bits, e os pesos são congelados. Em seguida, as camadas de adaptador treináveis (LoRA, na sigla em inglês) são anexadas, e apenas as camadas de adaptador são treinadas. Depois, os pesos do adaptador podem ser mesclados com o modelo base ou mantidos como um adaptador separado.
Configurar o ambiente de desenvolvimento
A primeira etapa é instalar as bibliotecas do Hugging Face, incluindo o TRL, e os conjuntos de dados para ajustar o modelo aberto.
# Install Pytorch & other libraries
%pip install "torch>=2.4.0" tensorboard torchvision
# Install Gemma release branch from Hugging Face
%pip install "transformers>=4.51.3"
# Install Hugging Face libraries
%pip install --upgrade \
"datasets==3.3.2" \
"accelerate==1.4.0" \
"evaluate==0.4.3" \
"bitsandbytes==0.45.3" \
"trl==0.15.2" \
"peft==0.14.0" \
"pillow==11.1.0" \
protobuf \
sentencepiece
Antes de começar o treinamento, é necessário aceitar os Termos de Uso do Gemma. É possível aceitar a licença no Hugging Face clicando no botão "Concordo e acesse o repositório" na página do modelo em: http://huggingface.co/google/gemma-3-4b-pt (ou a página do modelo adequado para o modelo Gemma com capacidade de visão que você está usando).
Depois de aceitar a licença, você vai precisar de um token do Hugging Face válido para acessar o modelo. Se você estiver executando em um Google Colab, poderá usar seu token do Hugging Face com segurança usando os segredos do Colab. Caso contrário, defina o token diretamente no método login. Verifique se o token também tem acesso de gravação, já que você envia o modelo para o Hub durante o treinamento.
from google.colab import userdata
from huggingface_hub import login
# Login into Hugging Face Hub
hf_token = userdata.get('HF_TOKEN') # If you are running inside a Google Colab
login(hf_token)
Criar e preparar o conjunto de dados de ajuste de detalhes
Ao ajustar os LLMs, é importante conhecer seu caso de uso e a tarefa que você quer resolver. Isso ajuda a criar um conjunto de dados para ajustar seu modelo. Se você ainda não definiu seu caso de uso, talvez seja necessário voltar para a prancheta.
Como exemplo, este guia se concentra no seguinte caso de uso:
- Ajustar um modelo do Gemma para gerar descrições de produtos concisas e otimizadas para SEO para uma plataforma de e-commerce, especificamente adaptada para pesquisas em dispositivos móveis.
Este guia usa o conjunto de dados philschmid/amazon-product-descriptions-vlm, um conjunto de descrições de produtos da Amazon, incluindo imagens e categorias.
O TRL do Hugging Face oferece suporte a conversas multimodais. A parte importante é o papel "image", que informa à classe de processamento que ela precisa carregar a imagem. A estrutura precisa seguir:
{"messages": [{"role": "system", "content": [{"type": "text", "text":"You are..."}]}, {"role": "user", "content": [{"type": "text", "text": "..."}, {"type": "image"}]}, {"role": "assistant", "content": [{"type": "text", "text": "..."}]}]}
{"messages": [{"role": "system", "content": [{"type": "text", "text":"You are..."}]}, {"role": "user", "content": [{"type": "text", "text": "..."}, {"type": "image"}]}, {"role": "assistant", "content": [{"type": "text", "text": "..."}]}]}
{"messages": [{"role": "system", "content": [{"type": "text", "text":"You are..."}]}, {"role": "user", "content": [{"type": "text", "text": "..."}, {"type": "image"}]}, {"role": "assistant", "content": [{"type": "text", "text": "..."}]}]}
Agora você pode usar a biblioteca de conjuntos de dados da Hugging Face para carregar o conjunto de dados e criar um modelo de comando para combinar a imagem, o nome do produto e a categoria e adicionar uma mensagem do sistema. O conjunto de dados inclui imagens como objetos Pil.Image.
from datasets import load_dataset
from PIL import Image
# System message for the assistant
system_message = "You are an expert product description writer for Amazon."
# User prompt that combines the user query and the schema
user_prompt = """Create a Short Product description based on the provided <PRODUCT> and <CATEGORY> and image.
Only return description. The description should be SEO optimized and for a better mobile search experience.
<PRODUCT>
{product}
</PRODUCT>
<CATEGORY>
{category}
</CATEGORY>
"""
# Convert dataset to OAI messages
def format_data(sample):
return {
"messages": [
{
"role": "system",
"content": [{"type": "text", "text": system_message}],
},
{
"role": "user",
"content": [
{
"type": "text",
"text": user_prompt.format(
product=sample["Product Name"],
category=sample["Category"],
),
},
{
"type": "image",
"image": sample["image"],
},
],
},
{
"role": "assistant",
"content": [{"type": "text", "text": sample["description"]}],
},
],
}
def process_vision_info(messages: list[dict]) -> list[Image.Image]:
image_inputs = []
# Iterate through each conversation
for msg in messages:
# Get content (ensure it's a list)
content = msg.get("content", [])
if not isinstance(content, list):
content = [content]
# Check each content element for images
for element in content:
if isinstance(element, dict) and (
"image" in element or element.get("type") == "image"
):
# Get the image and convert to RGB
if "image" in element:
image = element["image"]
else:
image = element
image_inputs.append(image.convert("RGB"))
return image_inputs
# Load dataset from the hub
dataset = load_dataset("philschmid/amazon-product-descriptions-vlm", split="train")
# Convert dataset to OAI messages
# need to use list comprehension to keep Pil.Image type, .mape convert image to bytes
dataset = [format_data(sample) for sample in dataset]
print(dataset[345]["messages"])
Ajustar o Gemma usando o TRL e o SFTTrainer
Agora está tudo pronto para ajustar seu modelo. O TRL SFTTrainer do Hugging Face facilita a supervisão do ajuste fino de LLMs abertos. O SFTTrainer é uma subclasse do Trainer da biblioteca transformers e oferece os mesmos recursos, incluindo registro, avaliação e checkpoint, mas adiciona recursos adicionais, como:
- Formatação de conjuntos de dados, incluindo formatos de conversa e instruções
- Treinamento apenas para conclusões, ignorando instruções
- Empacotar conjuntos de dados para um treinamento mais eficiente
- Suporte a ajustes finos com eficiência de parâmetros (PEFT, na sigla em inglês), incluindo QLoRA
- Preparar o modelo e o tokenizer para o ajuste fino de conversação (como adicionar tokens especiais)
O código abaixo carrega o modelo e o tokenizer do Gemma do Hugging Face e inicializa a configuração de quantização.
import torch
from transformers import AutoProcessor, AutoModelForImageTextToText, BitsAndBytesConfig
# Hugging Face model id
model_id = "google/gemma-3-4b-pt" # or `google/gemma-3-12b-pt`, `google/gemma-3-27-pt`
# Check if GPU benefits from bfloat16
if torch.cuda.get_device_capability()[0] < 8:
raise ValueError("GPU does not support bfloat16, please use a GPU that supports bfloat16.")
# Define model init arguments
model_kwargs = dict(
attn_implementation="eager", # Use "flash_attention_2" when running on Ampere or newer GPU
torch_dtype=torch.bfloat16, # What torch dtype to use, defaults to auto
device_map="auto", # Let torch decide how to load the model
)
# BitsAndBytesConfig int-4 config
model_kwargs["quantization_config"] = BitsAndBytesConfig(
load_in_4bit=True,
bnb_4bit_use_double_quant=True,
bnb_4bit_quant_type="nf4",
bnb_4bit_compute_dtype=model_kwargs["torch_dtype"],
bnb_4bit_quant_storage=model_kwargs["torch_dtype"],
)
# Load model and tokenizer
model = AutoModelForImageTextToText.from_pretrained(model_id, **model_kwargs)
processor = AutoProcessor.from_pretrained("google/gemma-3-4b-it")
O SFTTrainer oferece suporte a uma integração integrada com peft, o que facilita o ajuste eficiente de LLMs usando a QLoRA. Você só precisa criar uma LoraConfig e fornecer ao instrutor.
from peft import LoraConfig
peft_config = LoraConfig(
lora_alpha=16,
lora_dropout=0.05,
r=16,
bias="none",
target_modules="all-linear",
task_type="CAUSAL_LM",
modules_to_save=[
"lm_head",
"embed_tokens",
],
)
Antes de iniciar o treinamento, você precisa definir o hiperparâmetro que quer usar em um SFTConfig e um collate_fn personalizado para processar a visão. O collate_fn converte as mensagens com texto e imagens em um formato que o modelo possa entender.
from trl import SFTConfig
args = SFTConfig(
output_dir="gemma-product-description", # directory to save and repository id
num_train_epochs=1, # number of training epochs
per_device_train_batch_size=1, # batch size per device during training
gradient_accumulation_steps=4, # number of steps before performing a backward/update pass
gradient_checkpointing=True, # use gradient checkpointing to save memory
optim="adamw_torch_fused", # use fused adamw optimizer
logging_steps=5, # log every 5 steps
save_strategy="epoch", # save checkpoint every epoch
learning_rate=2e-4, # learning rate, based on QLoRA paper
bf16=True, # use bfloat16 precision
max_grad_norm=0.3, # max gradient norm based on QLoRA paper
warmup_ratio=0.03, # warmup ratio based on QLoRA paper
lr_scheduler_type="constant", # use constant learning rate scheduler
push_to_hub=True, # push model to hub
report_to="tensorboard", # report metrics to tensorboard
gradient_checkpointing_kwargs={
"use_reentrant": False
}, # use reentrant checkpointing
dataset_text_field="", # need a dummy field for collator
dataset_kwargs={"skip_prepare_dataset": True}, # important for collator
)
args.remove_unused_columns = False # important for collator
# Create a data collator to encode text and image pairs
def collate_fn(examples):
texts = []
images = []
for example in examples:
image_inputs = process_vision_info(example["messages"])
text = processor.apply_chat_template(
example["messages"], add_generation_prompt=False, tokenize=False
)
texts.append(text.strip())
images.append(image_inputs)
# Tokenize the texts and process the images
batch = processor(text=texts, images=images, return_tensors="pt", padding=True)
# The labels are the input_ids, and we mask the padding tokens and image tokens in the loss computation
labels = batch["input_ids"].clone()
# Mask image tokens
image_token_id = [
processor.tokenizer.convert_tokens_to_ids(
processor.tokenizer.special_tokens_map["boi_token"]
)
]
# Mask tokens for not being used in the loss computation
labels[labels == processor.tokenizer.pad_token_id] = -100
labels[labels == image_token_id] = -100
labels[labels == 262144] = -100
batch["labels"] = labels
return batch
Agora você tem todos os elementos básicos necessários para criar o SFTTrainer e iniciar o treinamento do modelo.
from trl import SFTTrainer
trainer = SFTTrainer(
model=model,
args=args,
train_dataset=dataset,
peft_config=peft_config,
processing_class=processor,
data_collator=collate_fn,
)
Inicie o treinamento chamando o método train().
# Start training, the model will be automatically saved to the Hub and the output directory
trainer.train()
# Save the final model again to the Hugging Face Hub
trainer.save_model()
Antes de testar o modelo, libere a memória.
# free the memory again
del model
del trainer
torch.cuda.empty_cache()
Ao usar a QLoRA, você treina apenas os adaptadores, e não o modelo completo. Isso significa que, ao salvar o modelo durante o treinamento, você só salva os pesos do adaptador, e não o modelo completo. Se você quiser salvar o modelo completo, o que facilita o uso com pilhas de veiculação como vLLM ou TGI, mescle os pesos do adaptador nos pesos do modelo usando o método merge_and_unload e salve o modelo com o método save_pretrained. Isso salva um modelo padrão, que pode ser usado para inferência.
from peft import PeftModel
# Load Model base model
model = AutoModelForImageTextToText.from_pretrained(model_id, low_cpu_mem_usage=True)
# Merge LoRA and base model and save
peft_model = PeftModel.from_pretrained(model, args.output_dir)
merged_model = peft_model.merge_and_unload()
merged_model.save_pretrained("merged_model", safe_serialization=True, max_shard_size="2GB")
processor = AutoProcessor.from_pretrained(args.output_dir)
processor.save_pretrained("merged_model")
Testar a inferência de modelo e gerar descrições de produtos
Depois do treinamento, é necessário avaliar e testar o modelo. É possível carregar amostras diferentes do conjunto de dados de teste e avaliar o modelo nessas amostras.
import torch
# Load Model with PEFT adapter
model = AutoModelForImageTextToText.from_pretrained(
args.output_dir,
device_map="auto",
torch_dtype=torch.bfloat16,
attn_implementation="eager",
)
processor = AutoProcessor.from_pretrained(args.output_dir)
Para testar a inferência, informe o nome, a categoria e a imagem do produto. O sample inclui uma figura de ação da Marvel.
import requests
from PIL import Image
# Test sample with Product Name, Category and Image
sample = {
"product_name": "Hasbro Marvel Avengers-Serie Marvel Assemble Titan-Held, Iron Man, 30,5 cm Actionfigur",
"category": "Toys & Games | Toy Figures & Playsets | Action Figures",
"image": Image.open(requests.get("https://m.media-amazon.com/images/I/81+7Up7IWyL._AC_SY300_SX300_.jpg", stream=True).raw).convert("RGB")
}
def generate_description(sample, model, processor):
# Convert sample into messages and then apply the chat template
messages = [
{"role": "system", "content": [{"type": "text", "text": system_message}]},
{"role": "user", "content": [
{"type": "image","image": sample["image"]},
{"type": "text", "text": user_prompt.format(product=sample["product_name"], category=sample["category"])},
]},
]
text = processor.apply_chat_template(
messages, tokenize=False, add_generation_prompt=True
)
# Process the image and text
image_inputs = process_vision_info(messages)
# Tokenize the text and process the images
inputs = processor(
text=[text],
images=image_inputs,
padding=True,
return_tensors="pt",
)
# Move the inputs to the device
inputs = inputs.to(model.device)
# Generate the output
stop_token_ids = [processor.tokenizer.eos_token_id, processor.tokenizer.convert_tokens_to_ids("<end_of_turn>")]
generated_ids = model.generate(**inputs, max_new_tokens=256, top_p=1.0, do_sample=True, temperature=0.8, eos_token_id=stop_token_ids, disable_compile=True)
# Trim the generation and decode the output to text
generated_ids_trimmed = [out_ids[len(in_ids) :] for in_ids, out_ids in zip(inputs.input_ids, generated_ids)]
output_text = processor.batch_decode(
generated_ids_trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False
)
return output_text[0]
# generate the description
description = generate_description(sample, model, processor)
print(description)
Resumo e próximas etapas
Este tutorial abordou como ajustar um modelo Gemma para tarefas de visão usando TRL e QLoRA, especificamente para gerar descrições de produtos. Confira os seguintes documentos:
- Saiba como gerar texto com um modelo Gemma.
- Saiba como ajustar o Gemma para tarefas de texto usando o Hugging Face Transformers.
- Saiba como realizar ajuste fino e inferência distribuídos em um modelo do Gemma.
- Saiba como usar modelos abertos do Gemma com a Vertex AI.
- Aprenda a ajustar o Gemma usando o KerasNLP e implantar na Vertex AI.