2026-01-04 · Atualizado 2026-07-15

[!NOTE] Tradução automática Este artigo foi traduzido automaticamente a partir da versão original em inglês.

LLM Fine-Tuning Guia: LoRA, QLoRA, DoRA, Unsloth, Axolotl e Implementação

A maioria das falhas fine-tuning ocorre devido a problemas na tomada de decisão. Uma equipa treina primeiro para confirmar que o uso de prompts, recuperação de informação ou constrained decoding não consegue resolver o problema; avalia os resultados na distribuição de dados utilizada para o treino; ou descobre, após o treinamento, que o resultado gerado é difícil de ser utilizado.

Este guia aborda a adaptação como um experimento que dispõe de um ponto de saída operacional definido. Começa pela delimitação da fronteira de decisão e, em seguida, percorre um caminho que inclui o processamento de dados, LoRA ou QLoRA, avaliação específica para cada tarefa, exportação e serving.

TL;DR: Faça o ajuste fino quando uma linha de base medida indicar que alterar o comportamento do modelo justifica uma atualização de pesos. Utilize recuperação de informação para atualizar factos e constrained decoding para tratar da sintaxe. Comece com LoRA quando o modelo base se encaixa confortavelmente nos requisitos; recorra a QLoRA quando a memória com pesos congelados for o limite. Mantenha um conjunto de avaliação separado antes do treinamento, compare os resultados com a linha de base não ajustada e escolha o artefato final de deploy antes de optar por um método específico.

Deve mesmo realizar um ajuste fino?

Antes de dedicar GPU horas, decida se fine-tuning é a ferramenta adequada para resolver o problema que tem em mãos.

Fine-tuning versus RAG

Fine-tuning pode alterar a forma como um modelo utiliza a linguagem de domínio, mas constitui um mecanismo de atualização insuficiente para factos que mudam ou que precisam de ser citados. A recuperação de informação e o fine-tuning abordam partes distintas do problema e, frequentemente, devem fazer parte do mesmo sistema.

Fine-tuning vs prompt engineering

Os modelos modernos LLMs respondem bem a instruções claras prompts e a exemplos concretos. Teste essas opções antes de investir em fine-tuning.

[!DICA] Tente primeiro fazer prompts Comece com um prompt e exemplos representativos. Se apenas a sintaxe de saída for pouco confiável, adicione constrained decoding antes de alterar os pesos.

Fine-tuning versus constrained decoding

Bibliotecas como xgrammar e outlines Restringir a geração a um JSON schema, expressão regular ou gramática. Dependendo da restrição e de backend, é compilado um autômato ou uma gramática que acaba por mascarar os tokens seguintes inválidos. Não é necessária nenhuma atualização de pesos.

Isto garante a utilização da linguagem de saída suportada — não que os valores estejam corretos, completos ou semanticamente adequados. Uma chamada de função sintaticamente válida pode ainda conter um ID de cliente incorreto.

Ordem prática:

1. Comece com prompts e exemplos de few-shot para a formatação básica.
2. Adicione constrained decoding (xgrammar ou outlines) quando a sintaxe é inconsistente.
3. Faça o ajuste fino apenas quando for necessário introduzir alterações de comportamento que um esquema não consegue impor.

Referência rápida: correspondência entre problemas e soluções

Tornar o caso de negócio mensurável

Fine-tuning pode reduzir os tokens de prompt recorrentes ou permitir que um modelo mais pequeno atinja o objetivo desejado, mas nenhuma dessas economias é automática. Calcule o ponto de equilíbrio com base no seu próprio tráfego e nos seus preços:

[ \text{pedidos de ponto de equilíbrio} = \frac{\text{custo de treino + avaliação + implementação}} {\text{custo/benefício de base/pedido} - \text{custo/benefício ajustado/pedido}} ]

Se o denominador for pequeno, negativo ou basear-se numa suposição de qualidade não comprovada, o projeto ainda não possui viabilidade económica.

[!DICA] A configuração híbrida Uma arquitetura comum consiste num modelo mais pequeno adaptado à tarefa, aliado a mecanismos de recuperação de informações para atualizar factos. Trate o modelo maior, ativado por prompts, como referência, mantendo o modelo menor apenas se este cumprir os mesmos limiares de qualidade e segurança específicos da tarefa.

Tipos de fine-tuning

Existem três formas principais que fine-tuning pode assumir. Elas diferem em relação ao tipo de dados de que necessitam e ao que ensinam ao modelo.

1. Pre-treino contínuo (não supervisionado)

Treina-se o modelo base com mais texto bruto, sem etiquetas. Ele continua a realizar a previsão do próximo token, tal como durante a fase inicial de pré-treino.

Quando utilizá-lo:

• O domínio possui vocabulário que o modelo de base nunca viu (médico, jurídico, bases de código internas).
• Você dispõe de grandes quantidades de texto do domínio, mas não de pares rotulados (entrada, saída).
• O modelo de base comete erros ao lidar com terminologia específica do domínio.

Exemplo: treino com milhões de notas clínicas para que o modelo aprenda abreviaturas médicas, nomes de medicamentos e fluxos de trabalho clínicos.

2. Aprendizagem Supervisionada fine-tuning (SFT)

SFT é treinado com pares rotulados (entrada, saída). O utilizador apresenta ao modelo a saída exata desejada para cada entrada.

Quando utilizá-lo:

• Tem uma tarefa específica com um formato de entrada/saída estruturado.
• Disponibiliza dados rotulados de alta qualidade, mesmo que em pequenas quantidades.
• Precisa de um comportamento previsível para formas conhecidas de entrada.

Exemplo: treino com pares de (descrição da consulta SQL, código SQL) para texto-em-SQL.

{
    "input": "Get all users who signed up last month",
    "output": "SELECT * FROM users WHERE signup_date >= DATE_SUB(NOW(), INTERVAL 1 MONTH)"
}

3. Ajuste de instruções

O ajuste por instruções é um caso especial de SFT, concebido para fazer com que os modelos sigam uma grande variedade de instruções em linguagem natural. Os dados de treino consistem em pares (instrução, resposta) provenientes de diversas tarefas diferentes.

Quando utilizá-lo:

• Pretende um assistente de uso geral (como o ChatGPT ou o Claude).
• O modelo precisa de ser capaz de lidar com solicitações variadas e abertas.
• Está a desenvolver uma interface de chat.

Exemplo: treino com milhares de instruções diversas, como “Resumir este artigo”, “Escrever um poema sobre X” e “Explicar Y de forma simples”.

Comparação

[!NOTE] O que as pessoas fazem na prática SFT e o ajuste de instruções utilizam o mesmo objetivo baseado no próximo token; a diferença reside na abrangência e na estruturação do dataset. O treino prévio contínuo é um experimento distinto e deve ser seguido por testes tanto para avaliar os ganhos em determinados domínios como para verificar eventuais regressões nas capacidades gerais.

O processo em 7 fases de fine-tuning pipeline

Fine-tuning é um pipeline, e não uma única instrução. Cada fase possui os seus próprios modos de falha, e ignorar alguma delas costuma resultar num modelo de qualidade inferior mais tarde.

Cada fase baseia‑se na anterior:

1. Preparação de dados — Defina a unidade de avaliação, divida os dados e, em seguida, limpe e formate-os
2. Seleção do modelo — Escolha o modelo base adequado e carregue os seus pesos
3. Configuração do treino — Defina o hardware, os hiperparâmetros e a estratégia de otimização
4. Fine-tuning — Execute SFT, DPO ou o treino ORPO
5. Avaliação — Analise o desempenho Benchmark e valide a qualidade
6. Implantação — Exporte e disponibilize o seu modelo
7. Monitorização — Acompanhe o desempenho, faça a manutenção e realize iterações

[!AVISO] Os dados são a base fundamental O treino reproduz falhas sistemáticas nos exemplos utilizados. Verifique as etiquetas, o vazamento de informações, a cobertura e a conformidade com as políticas antes de dedicar tempo a testes com otimizadores.

Fase 1: Preparação de dados

A maioria dos projetos fine-tuning falha precisamente aqui, e não durante o treinamento. A preparação moderna de dados vai além da simples aplicação de expressões regulares em ficheiros CSV.

O processo de dados em 5 fases pipeline

Ferramentas como a DataTrove e a Distilabel podem ser úteis em larga escala, mas a definição de pipeline deve ser orientada pela taxonomia de falhas e pelo contrato de dados, e não por uma ferramenta preferida.

1. Ingestão e filtragem

• Ação: remover respostas de recusa (“Não consigo responder a isso”), dados com codificação UTF-8 corrompida e idiomas que não sejam o alvo.
• Ferramentas: Trafilatura para extração de informações, FastText para identificação do idioma.

2. Política de dados sensíveis

• Ação: determinar o que o modelo pode aprender e, em seguida, redigir, tokenizar ou excluir campos pessoais e confidenciais conforme necessário.
• Ferramentas: Microsoft Presidio ou scrubadub.
• Porquê: um detetor é apenas uma forma de controle; continuam a ser aplicáveis os requisitos relacionados com a proveniência, consentimento, retenção, acesso e eliminação de dados.

3. Deduplicação (MinHash LSH)

• Ação: eliminar duplicatas quase idênticas para que o modelo não as memorize.
• Ferramentas: O DataTrove lida eficazmente com processamentos em escala de terabytes.

4. Aumentação sintética, se necessário

• Ação: utilizar um modelo professor mais potente (GPT-4o, DeepSeek-V3) para reescrever os dados brutos em pares de instrução-resposta limpos.
• Ferramentas: Distilabel.
• Validação: analisar amostras das saídas do modelo professor, compará-las com a mesma avaliação utilizada para etiquetas criadas por humanos, e manter separados, na avaliação, os trechos gerados sinteticamente dos escritos por humanos.

5. Formatação

• Ação: converter para um formato padrão (Alpaca ou ShareGPT).

Exemplos de formatos de dados

Formato Alpaca (cumprimento de instruções):

{
    "instruction": "Summarize the following text.",
    "input": "The text to be summarized...",
    "output": "This is the summary."
}

Formato ShareGPT/ChatML (conversacional):

{
    "conversations": [
        { "from": "user", "value": "Hello, who are you?" },
        { "from": "assistant", "value": "I am a helpful AI assistant." }
    ]
}

O que realmente importa

• Cobertura antes do volume. Adicione exemplos que representem modos de falha distintos, e não repetições do caso mais comum e fácil de resolver.
• Limpeza. Remova texto irrelevante, normalize os espaços em branco e mantenha a formatação consistente.
• Equilíbrio. Preserve os casos raros importantes e apresente o desempenho por cada segmento.
• Separação. Divida os dados por origem, utilizador, documento ou período de tempo, quando a divisão aleatória de linhas possa causar a aparição de duplicatas próximas.
• Proveniência. Registe a origem, a licença ou permissão, o histórico de transformações e o caminho de eliminação para cada versão de dataset.

Fase 2: Seleção do modelo e hardware

A escolha do modelo base e a compreensão do limite mínimo definido pelo GPU determinam quais arquiteturas é possível treinar efetivamente.

Comece com o modelo de base mais pequeno que já passe nos testes de baseline inegociáveis. Confirme:

• termos de licença e redistribuição para o produto pretendido;
• idioma, domínio, utilização de ferramentas e comportamento de segurança antes da adaptação;
• compatibilidade do tokenizador e dos modelos de conversação com o dataset;
• tamanho máximo de contexto e comportamento de truncamento exigidos por exemplos reais;
• suporte tanto no motor de treino framework como no motor alvo serving.

Fine-tuning representa uma etapa de adaptação, e não uma correção para uma base inadequada. Se o modelo perder funcionalidades que o dataset não abrange, escolha outra base antes de continuar a coletar mais épocas.

Defina o tamanho da execução, não o nível de marketing

Não existe uma tabela estável que relacione o “tamanho do modelo → GPU”. O consumo máximo de memória varia em função da precisão dos pesos, do otimizador, do número de parâmetros treináveis, do comprimento da sequência, do tamanho dos micro-lotes, do uso de checkpoints de ativação, da implementação de mecanismos de atenção e dos custos adicionais associados a framework. Comece por fazer uma estimativa do consumo de memória e, em seguida, execute um teste rápido de carga com o comprimento máximo possível, utilizando exatamente a pilha de recursos em questão.

O artigo original QLoRA conseguiu adaptar um modelo LLaMA de 65 B a um GPU de 48 GB na sua configuração específica. Esse resultado representa um limite útil, mas não garante que todas as arquiteturas atuais de 70 B, nem os comprimentos de contexto, kernels ou algoritmos de treino, sejam compatíveis com o mesmo dispositivo.

Matemática de memória

Num modelo com (P) parâmetros, os pesos por si só exigem aproximadamente (2P) bytes em BF16/FP16 ou (0,5P) bytes quando armazenados com quatro bits, antes de se considerarem os metadados de quantização e os buffers de runtime. O treino no estilo Adam completo acrescenta ainda os gradientes, os estados do otimizador e, frequentemente, pesos mestre com maior precisão. O LoRA permite evitar a utilização da maior parte da memória destinada aos estados treináveis; além disso, o QLoRA reduz adicionalmente o espaço ocupado pelos pesos base congelados. Nas sequências longas, as ativações continuam a poder representar uma parte significativa do consumo de memória.

Utilize este fluxo de trabalho:

1. Escolha a sequência mais longa e o tamanho do micro-lote que precisa de suportar.
2. Estime os pesos e o estado treinável, reservando espaço adicional para as ativações e os kernels.
3. Execute uma etapa de avanço/retrocesso com o comprimento máximo.
4. Registe a memória máxima alocada e reservada.
5. Só então ajuste o tamanho do lote, o número de núcleos, o comprimento da sequência ou a contagem de GPU.

Fase 3: Métodos de treino (PEFT e LoRA)

fine-tuning completo vs PEFT

A aplicação completa de fine-tuning (FFT) atualiza cada peso individualmente, fazendo com que os gradientes e o estado do otimizador cresçam proporcionalmente a todo o modelo. O valor máximo de consumo de recursos não pode ser estimado apenas a partir do número de parâmetros, mas fica muito acima da memória necessária para carregar os pesos durante a inferência.

O fine-tuning (PEFT) eficiente em termos de parâmetros treina apenas um subconjunto reduzido de parâmetros, deixando o resto congelado. Assim, as equações matemáticas tornam‑se muito mais simples de tratar.

LoRA: o ponto de partida

LoRA (Adaptação de Rank Baixo) consiste em congelar uma matriz pré-treinada e representar a sua atualização adquirida através de duas matrizes menores. O artigo original justifica este método com a hipótese de que as atualizações de adaptação úteis possuem um rank intrínseco baixo.

Para uma matriz congelada (W0 \in \mathbb{R}^{d{out} \times d_{in}}), LoRA aprende:

• (A \in \mathbb{R}^{r \times d_{in}})
• (B \in \mathbb{R}^{d_{out} \times r})

A camada adaptada é:

[ W’ = W_0 + \frac{\alpha}{r}BA ]

O adaptador possui (r(d*{in}+d*{out})) parâmetros treináveis em vez de (d*{in}d*{out}) para essa matriz. No caso de uma matriz quadrada com 4.096 elementos e rank 16, isso representa uma redução de 128 vezes na dimensão da matriz — e não 10.000 vezes, como aconteceria num modelo arbitrário. A afirmação de 10.000 vezes mencionada no artigo LoRA referia‑se especificamente a uma configuração do GPT-3 de 175 bilhões de parâmetros que utilizava adaptações em matrizes selecionadas.

Métodos PEFT comparados

Quando escolher qual

• LoRA: comece por aqui. Rápido, eficiente em termos de memória e com excelente suporte técnico.
• QLoRA: quando o mesmo experimento LoRA não é aplicável devido aos pesos de base congelados.
• DoRA: após uma comparação direta LoRA que revele um ganho significativo.
• fine-tuning completo: somente depois de PEFT é que um gargalo pode ser considerado como tal, e não apenas como uma suposição.

DoRA: LoRA decomposto em pesos

DoRA (Adaptação de Baixo Rank Decomposta por Peso) separa a magnitude de cada vetor de peso da sua direção. É aplicada uma atualização LoRA à componente direcional, ao mesmo tempo que se aprende a magnitude de forma independente.

Como funciona:

Em vez de tratar os pesos como uma única entidade, DoRA divide os pesos pré-treinados em duas componentes:

1. Magnitude — um valor treinável por vetor de pesos.
2. Direção — um vetor normalizado atualizado através de matrizes de baixo rank.

Em notação compacta por colunas:

[ W’ = m \frac{V + BA}{\lVert V + BA \rVert_c} ]

Onde:

• m = magnitude (treinável)
• (V) = a matriz direcional congelada
• (BA) = a atualização direcional de baixo rank aprendida
• (\lVert \cdot \rVert_c) = normalização por colunas

O que obtém com essa estrutura adicional:

• Mais graus de liberdade em comparação com o LoRA padrão, uma vez que a magnitude pode variar de forma independente.
• Resultados superiores aos do LoRA em diversas configurações, conforme relatado no artigo original.
• São necessários parâmetros e cálculos adicionais, portanto o ganho obtido deve ser verificado na sua tarefa específica e no serving correspondente.

Fusão de adaptadores para aprendizagem multi-tarefa

Adaptadores separados permitem que uma base congelada suporte várias tarefas. É possível direcionar solicitações para um adaptador, utilizar vários adaptadores a partir de um único motor quando isso for suportado, ou criar um candidato fundido offline. A fusão pode introduzir interferências, pelo que é necessário avaliar o artefato resultante em vez de assumir que os adaptadores de origem funcionam de forma limpa e independente.

Métodos comuns de fusão:

1. Concatenação — combina os parâmetros dos adaptadores e aumenta o rank efetivo. Rápida e simples.
2. Combinação linear — soma ponderada dos adaptadores. Permite ajustar parâmetros de forma detalhada.
3. SVD — decomposição matricial para fusão. Mais flexível, mas mais lenta.

Um adaptador para resumo e outro para tradução, fundidos num único modelo multitarefa.

Fase 4: Fine-tuning e alinhamento de preferências

SFT aprende com demonstrações. A otimização de preferências, por sua vez, baseia‑se em comparações do tipo “a resposta escolhida A é melhor do que a resposta rejeitada B”. Utilize‑o apenas quando a preferência entre pares for a descrição adequada do erro; a correção factual e o cumprimento das políticas exigem frequentemente avaliadores mais robustos do que uma preferência global.

PPO-baseado em RLHF

A receita original era uma estrutura em três fases pipeline:

1. SFT — aprender a tarefa.
2. Modelo de recompensa — treinar com base nas preferências humanas (escolhidas versus rejeitadas).
3. PPO (Proximal Policy Optimization) — aprendizagem por reforço utilizada para otimizar a política.

O custo operacional provém das partes móveis:

• Complexo de implementar e manter.
• Caro — é necessário treinar vários modelos.
• A amostragem on-policy e a otimização de recompensas exigem verificações rigorosas de estabilidade e deteção de manipulação de recompensas.

DPO

DPO (Otimização Direta de Preferências) elimina o modelo de recompensa explícito e o ciclo de RL. Continua a otimizar o objetivo RLHF (maximização de recompensas com restrição de divergência KL), mas faz isso como um problema de aprendizagem supervisionada reparametrizado, em vez de recorrer ao aprendizado por reforço:

{
    "prompt": "Explain quantum computing",
    "chosen": "Quantum computing uses qubits...",   # Preferred response
    "rejected": "Well, it's complicated..."        # Non-preferred response
}

O que muda em termos operacionais:

• Caminho de código mais simples (sem modelo de recompensa separado, sem ciclo de RL).
• Um objetivo offline baseado em pares de preferências, em vez de aprendizagem por reforço on-policy.
• Uma política de referência ou probabilidades de registo de referência equivalentes na formulação padrão.

É mais fácil prototipar um DPO do que um PPO pipeline completo, mas isso não implica necessariamente uma melhoria automática na qualidade. Os resultados dependem da política de partida, da qualidade dos pares, das configurações de perda, dos efeitos relacionados com o comprimento dos dados e do protocolo de avaliação. Compare-o com um SFT checkpoint utilizando os mesmos conjuntos de preferências e tarefas reservadas para teste.

ORPO

ORPO (Otimização de Preferências por Razão de Probabilidades) combina a perda de verossimilhança logarítmica negativa SFT com uma penalização baseada na razão de probabilidades aplicada às respostas rejeitadas. Este método elimina a necessidade de um modelo de referência distinto e permite integrar o aprendizado de tarefas com a otimização de preferências numa única execução.

Como funciona: O ORPO utiliza uma perda combinada que realiza duas funções ao mesmo tempo:

1. Maximiza a probabilidade da resposta escolhida (aprendizagem da tarefa).
2. Penaliza a resposta rejeitada através de um termo de razão de probabilidades (aprendizagem de preferências).

Hipermétricas que vale a pena conhecer:

from trl import ORPOConfig

config = ORPOConfig(
    learning_rate=8e-6,  # Very low, as recommended by the ORPO paper
    beta=0.1,            # Controls strength of preference penalty
    # ... other params
)

• Taxa de aprendizagem: o artigo utilizou taxas baixas nos seus experimentos; ajuste-a em função do seu modelo, dos lotes e dos dados, em vez de copiar um valor como regra geral.
• Beta: controla o termo de preferência em relação ao termo SFT.

O compromisso:

• Uma fase de treino em vez de duas.
• Sem modelo de recompensa.
• Sem execução de passagem para o modelo de referência.
• Um processo acoplado: se o aprendizado da tarefa ou o comportamento de preferência regredir, não existe nenhum SFT checkpoint intermédio do mesmo pipeline para análise.

Escolha entre os designs de dados e avaliação:

• Utilize DPO quando já dispõe de um SFT checkpoint satisfatório e pretende realizar um experimento de preferências offline mais simples.
• Teste o ORPO quando um objetivo de fase única, sem necessidade de referências externas, se adequar aos seus dados e restrições operacionais.
• Empregue PPO-based RLHF quando a amostragem online com base numa recompensa aprendida de forma explícita faça parte dos requisitos, e quando for possível monitorizar a exploração dessa recompensa.

O valor “Nenhum” não é o padrão em todas as tarefas. Mantenha uma linha de base exclusiva para o SFT e informe tanto as métricas da tarefa como as métricas de preferência.

Fine-tuning frameworks

Frameworks As interseções entre esses componentes ocorrem com frequência e mudam rapidamente. É necessário selecionar o caminho de execução que deve ser suportado, fixar as versões utilizadas e garantir que a configuração de treino seja suficientemente portátil para poder ser reproduzida fora de um ambiente de notebook.

Unsloth — eficiência de velocidade e memória

Unsloth integra-se com Hugging Face trl e transformers e disponibiliza kernels otimizados, funcionalidades de checkpointing e caminhos fine-tuning quantificados para os modelos suportados.

• Núcleos personalizados do Triton GPU para atenção, RoPE e entropia cruzada, que eliminam o overhead associado aos PyTorch.
• Backprop eficiente em termos de memória, que recalcula as ativações durante a passagem reversa em vez de as armazenar na memória.
• Operações fundidas que combinam vários passos (normalização de camada + operação linear, entre outras) em uma única chamada de GPU.
• Quantização de 4 bits integrada diretamente no fluxo de QLoRA, com desquantização otimizada.

[!IMPORTANTE] A ordem de importação é importante Siga a ordem de importação apresentada no exemplo do Unsloth para a versão que está a utilizar. O Unsloth aplica patches durante o processo de importação, pelo que deve importá‑lo primeiro. trl e transformers evita a omissão de otimizações ou erros específicos de versão.

# ✅ Correct order
from unsloth import FastLanguageModel  # Must be first!
from trl import SFTTrainer
from transformers import TrainingArguments

# Avoid this order with Unsloth's patched path
from trl import SFTTrainer
from unsloth import FastLanguageModel

Ideal para: treino GPU único, prototipagem, notebooks do Colab e para quem está atento à fatura do GPU.

Os valores de velocidade e consumo de memória publicados variam consoante o modelo, o comprimento da sequência, o lote de processamento, a precisão e o hardware utilizado. Benchmark tokens por segundo e memória máxima durante a sua própria execução, em vez de tratar uma relação indicativa como um framework propriedade.

Axolotl — treino orientado por configurações

# config.yaml - no code required
base_model: meta-llama/Meta-Llama-3-8B
adapter: qlora
lora_r: 32
lora_alpha: 16
datasets:
    - path: data/my_data.jsonl
      type: alpaca
sample_packing: true

Executar com: accelerate launch -m axolotl.cli.train config.yaml

Ideal para: execuções declarativas e reprodutíveis, bem como opções de lançamento integradas para treino distribuído.

A principal vantagem reside na configuração declarativa, que pode ser revista, versionada e reutilizada em execuções locais e distribuídas.

Framework de comparação

Demonstração prática: fine-tuning com o Unsloth

Um exemplo completo do meu unsloth-finetune-demo repositório. A demonstração realiza um ajuste fino do Nemotron-Nano para function calling.

Início rápido

# Clone and setup
git clone https://github.com/slavadubrov/unsloth-finetune-demo.git
cd unsloth-finetune-demo

# Install with uv (recommended)
uv sync

# Run fine-tuning (quick test)
uv run finetune --max-samples 1000

Configuração

As partes interessantes encontram‑se em config.py:

# Model & Dataset
MODEL_NAME = "nvidia/Llama-3.1-Nemotron-Nano-4B-v1.1"  # 4B params, 128K context
DATASET_NAME = "glaiveai/glaive-function-calling-v2"   # 113K examples

# LoRA Configuration
LORA_R = 16        # Adapter capacity; tune against held-out results
LORA_ALPHA = 32    # Update scaling; alpha/r is the classic LoRA scale
MAX_SEQ_LENGTH = 4096

# Candidate modules for this Llama-family model
LORA_TARGET_MODULES = [
    "q_proj", "k_proj", "v_proj", "o_proj",
    "gate_proj", "up_proj", "down_proj",
]

[!NOTE] A razão alfa para classificação alpha/r escala a atualização clássica de LoRA. alpha = 2r Trata‑se de uma heurística de partida comum em algumas documentações de ferramentas, mas não constitui uma garantia de estabilidade. Apenas após a definição dos dados e da linha de base deve proceder‑se à varredura do rank, do alfa, da taxa de aprendizagem e dos módulos‑alvo.

Código de treino principal

from unsloth import FastLanguageModel
from trl import SFTConfig, SFTTrainer

# Load model with 4-bit quantization
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="nvidia/Llama-3.1-Nemotron-Nano-4B-v1.1",
    max_seq_length=4096,
    load_in_4bit=True,
)

# Add LoRA adapters
model = FastLanguageModel.get_peft_model(
    model,
    r=16,
    lora_alpha=32,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj",
                    "gate_proj", "up_proj", "down_proj"],
    use_gradient_checkpointing="unsloth",  # Lower activation memory; extra compute
)

# The data step creates versioned train_dataset and eval_dataset objects.
# Each row has the chat messages and tool schemas expected by current TRL.

# Train with the current TRL configuration surface.
trainer = SFTTrainer(
    model=model,
    processing_class=tokenizer,
    train_dataset=train_dataset,
    eval_dataset=eval_dataset,
    args=SFTConfig(
        output_dir="outputs/nemotron-function-calling",
        max_length=4096,
        packing=True,
        per_device_train_batch_size=2,
        gradient_accumulation_steps=4,
        learning_rate=2e-4,
        num_train_epochs=3,
        bf16=True,
    ),
)
trainer.train()

Fine-tuning com Axolotl

[!NOTE] Demonstração em preparação Estou a trabalhar numa demonstração prática com Axolotl. Até lá, o Guia para Acelerar o Paralelismo n-D O documento fornecido por Hugging Face constitui uma referência útil para estratégias de treino multi-GPU.

Em configurações orientadas para configurações e distribuídas, o Axolotl torna o fluxo de trabalho reprodutível:

# axolotl_config.yaml
base_model: meta-llama/Meta-Llama-3-8B
model_type: LlamaForCausalLM

# QLoRA configuration
load_in_4bit: true
adapter: qlora
lora_r: 32
lora_alpha: 16
lora_dropout: 0.05
lora_target_modules:
    - q_proj
    - k_proj
    - v_proj
    - o_proj
    - gate_proj
    - up_proj
    - down_proj

# Dataset
datasets:
    - path: data/training_data.jsonl
      type: alpaca

# Training settings
sequence_len: 4096
sample_packing: true # Benchmark with your length distribution
micro_batch_size: 2
gradient_accumulation_steps: 4
learning_rate: 0.0002
num_epochs: 3

# Precision and attention path; verify support on the pinned stack
bf16: true
flash_attention: true

Executar o treino:

axolotl train axolotl_config.yaml

Etapa 5: Avaliação

Congele o contrato de avaliação antes da primeira execução. Como mínimo, compare a versão ajustada de checkpoint com a versão básica não ajustada, sob exatamente as mesmas condições de prompt, configurações de decodificação e ambiente de ferramentas. Apresente apenas os resultados globais de qualidade após verificar os casos de falha que o projeto deveria ter corrigido.

Acompanhar quatro grupos:

1. Tarefa-alvo: correspondência exata, sucesso na execução, avaliação por especialista humano ou qualquer outro resultado relacionado com o caso de uso.
2. Regressão: capacidades gerais e subtarefas anteriormente suportadas que podem ser afetadas negativamente pela adaptação.
3. Segurança e políticas: recusas de resposta, vazamento de dados, prompt injection ou restrições específicas do domínio.
4. Operações: latência, taxa de transferência, consumo de memória, tamanho dos artefatos e custos na configuração pretendida de serving.

Automação de benchmarks

Utilize lm-evaluation-harness para tarefas padronizadas relevantes, e não como substituto da avaliação do produto:

lm_eval --model hf \
    --model_args pretrained=./outputs/merged-model \
    --tasks hellaswag,arc_easy,mmlu \
    --batch_size 8

LLM-como-jurado

No que diz respeito à qualidade subjetiva, um modelo mais grande pode ajudar na atribuição de pontuações, mas é necessário calibrá‑lo com exemplos revistos por humanos e manter a identidade do candidato em segredo:

judge_prompt = """
Rate this response from 1-5 on:
- Relevance
- Accuracy
- Formatting

Response: {model_output}
Expected: {ground_truth}
"""

Avaliação específica do domínio

Retenha exemplos reais por fonte, utilizador, documento ou período de tempo de forma a que quase-duplicatas não possam passar de um conjunto para outro após a divisão. No que diz respeito a function calling, valide toda a trajetória: seleção da ferramenta, argumentos, resultado da execução, recuperação e resposta final. Quando a amostra for pequena, apresente intervalos de confiança ou contagens de vitórias/perdas em pares, e analise cuidadosamente cada regressão numa fatia crítica.

Fase 6: Implementação e formatos de saída

Escolha o artefato com base no motor serving e no plano de rollback, e não apenas no tamanho do ficheiro:

1. Adaptador LoRA

uv run finetune  # Saves ~100-500MB adapter

• Tamanho: proporcional aos módulos-alvo, à classificação, às camadas e ao tipo de dado; costuma ser muito menor que o modelo base.
• Ideal para: desenvolvimento, adaptadores de tarefas versionados e motores que suportam diretamente o LoRA.
• Vantagem adicional: é possível substituir os adaptadores sem precisar baixar novamente o modelo base.

2. Modelo fundido

uv run finetune --merge  # Creates a standalone full model

• Tamanho: aproximadamente o tamanho total da base checkpoint, dependendo da precisão de saída selecionada.
• Ideal para: motores ou caminhos de distribuição que não suportam o adaptador de forma separada.
• Compromisso: arquivo resultante maior e implementação mais lenta; carregamento de modelo simples em formato único.

3. Formato GGUF

uv run finetune --gguf q4_k_m  # Creates ~2-4GB quantized model

• Tamanho: depende do modelo; aproximadamente pesos de quatro bits mais metadados para as variantes Q4.
• Ideal para: inferência de CPU, Ollama, llama.cpp, e implementação em dispositivos periféricos.
• Opções: q4_k_m (menor), q5_k_m (maior fidelidade na atribuição de peso) q8_0 (maior tamanho e maior fidelidade). Medir o impacto da tarefa após a conversão.

Etapa 7: Serving e monitorização

Com vLLM

# Serve the base and expose a PEFT adapter as a model name.
vllm serve nvidia/Llama-3.1-Nemotron-Nano-4B-v1.1 \
    --enable-lora \
    --lora-modules function-calling=./outputs/adapter \
    --host 0.0.0.0 \
    --port 8000 \
    --max-model-len 4096

Consulta através do API compatível com a OpenAI:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="dummy")
response = client.chat.completions.create(
    model="function-calling",
    messages=[{"role": "user", "content": "Book a flight to Tokyo"}]
)

Com o Ollama (local)

# Create Modelfile
echo 'FROM ./outputs/unsloth-nemotron-function-calling-gguf/model-q4_k_m.gguf' > Modelfile

# Import to Ollama
ollama create my-function-model -f Modelfile

# Run
ollama run my-function-model

Com llama.cpp (CPU)

./llama-cli -m ./outputs/model-q4_k_m.gguf \
    -p "What's the weather in Tokyo?" \
    --ctx-size 4096

Monitorizar o modelo lançado

O ciclo de vida não termina quando a perda de treino atinge um valor considerado “saudável”. Registe a revisão do modelo base, o tokenizador e o template de conversação, o hash do adaptador, a versão dataset, as configurações de treino e o relatório de avaliação como uma única unidade de lançamento. Em produção, monitore o sucesso das tarefas, os resultados inválidos, as falhas nas regras de comportamento, a latência e as alterações nos dados de entrada utilizando os mesmos critérios utilizados em modo offline. Assegure que os artefatos anteriores permaneçam acessíveis e defina um limiar de rollback antes do lançamento.

Principais conclusões

1. Realize o ajuste fino apenas após uma versão de base não ajustada e uma taxonomia de falhas demonstrarem que a adaptação dos pesos resolve o problema.
2. O mecanismo de recuperação gere as evidências em constante mudança; constrained decoding trata da sintaxe; nenhum deles é substituído por SFT.
3. LoRA reduz o número de estados passíveis de treino. QLoRA comprime adicionalmente os pesos de base congelados. Não atribua os valores de memória de QLoRA a LoRA.
4. A cobertura de dados, a integridade das divisões, a proveniência e o mascaramento de perdas são mais importantes do que simplesmente copiar uma configuração de otimizador na moda.
5. DPO, ORPO e os RLHF baseados em PPO representam diferentes esquemas experimentais, e não uma escala de qualidade com um padrão universal.
6. Avalie o comportamento alvo, as regressões, a segurança e as operações com base no mesmo modelo de base.
7. Escolha o adaptador, a saída fundida ou GGUF a partir dos requisitos de serving e de rollback antes de iniciar o treinamento.

Referências

Artigos e investigação

• LoRA: Adaptação de Baixo Rank de Modelos de Língua Grande
• QLoRA: Ajuste fino eficiente de LLMs quantizados
• DoRA: Adaptação de Baixo Rank Decomposta por Pesos
• DPO: Otimização de Preferências Diretas
• ORPO: Otimização da Preferência de Razão de Probabilidades
• PPO: Algoritmos de Otimização de Política Proximal — OpenAI, 2017

Ferramentas de processamento de dados

• DataTrove — Hugging Face processamento de dados em grande escala Distilabel — Geração de dados sintéticos (Argilla)
• Processamento de fluxo — Extração de texto da web e crawling FastText — Identificação de idioma do Facebook AI (suporta 217 idiomas) Microsoft Presidio — Deteção e anonimização de PII
• scrubadub — Biblioteca em Python para remoção de PII

Constrained decoding

• xgrammar — Constrained decoding com FSMs esboços — Geração estruturada para LLMs

Treino frameworks

• Leoa-moura — Otimizado fine-tuning framework
• axolote — Treino orientado por configurações e lançadores distribuídos
• TRL — Hugging Face SFT e biblioteca de treino de preferências Torchtune — PyTorch-nativa biblioteca fine-tuning

Inferência e deploy

• vLLM LoRA adaptadores — Fornece um ou mais adaptadores em conjunto com o modelo base Ollama — Executador local LLM para Mac/Windows/Linux
• llama.cpp — Inferência CPU/GPU em formato GGUF

Avaliação

• avaliação-de-lm-harness — A EleutherAI padronizou os testes de desempenho LLM.

Guias e recursos

• Repositório de Demonstração — Exemplo prático de fine-tuning LLM Fine-Tuning. Intuição Teórica e Implementação Prática — Caderno de investigação do NotebookLM
• Guia para Acelerar o Paralelismo n-D — Hugging Face estratégias de treino multi-GPU