tarioch/unsloth-lora

Treinamento LoRA com Unsloth

Treine um LoRA em um dataset no formato de chat com Unsloth em uma GPU local e exporte o resultado como GGUF. O dataset é do usuário (produzi-lo é específico do problema); este skill começa de train.jsonl e val.jsonl. Servir o modelo é uma etapa separada: a pasta de execução que este skill gera (GGUF mais run.json) é o que um skill de servir, como ollama-model, utiliza.

Execute cada script através do lançador, com a ferramenta Bash: ${CLAUDE_SKILL_DIR}/scripts/run <script.py> [args]. O skill permite exatamente esse comando, de modo que ele é executado em modo automático; chamar um script de outra forma será recusado. Se um comando do lançador for recusado após uma nova mensagem do usuário, invoque este skill novamente. O lançador executa check_data.py com qualquer Python 3 e preflight.py, train.py e export_gguf.py com o Python do ambiente Unsloth, na pasta pai de sua pasta --out/--run (Unsloth escreve uma pasta unsloth_compiled_cache/ no diretório atual). Forneça todo caminho como caminho absoluto: os comandos não compartilham um diretório de trabalho.

Antes de começar, descubra

• A pasta do dataset e o conjunto de avaliação usado posteriormente para comparar modelos: ele não deve fazer parte do treinamento. Se não houver, proponha separar exemplos antes do treinamento.
• O(s) modelo(s) base, como nomes Unsloth 4-bit (ex.: unsloth/Qwen2.5-Coder-3B-Instruct-bnb-4bit). Vários modelos base significam uma pasta de execução para cada um e os mesmos passos para cada um, um após o outro (references/base-models.md).
• A máquina: o treinamento precisa de uma GPU CUDA e do Python do ambiente Unsloth. Pergunte ao usuário o caminho desse Python se UNSLOTH_PYTHON não estiver definido e ~/.config/llm-finetune/unsloth-python não existir, e escreva o caminho como a primeira linha desse arquivo (com a aprovação do usuário): o lançador o lê de lá.
• A pasta de execuções, onde as pastas de execução serão criadas, fora de qualquer checkout git. <runs> abaixo é seu caminho absoluto.

Passos

1. Verifique os dados

${CLAUDE_SKILL_DIR}/scripts/run check_data.py <data> --eval <eval.jsonl>

Deve imprimir ok. Falha em linhas quebradas, conversas que não terminam com uma resposta do assistente, e prompts de validação ou avaliação que também estão no treinamento, com a mesma resposta ou uma diferente: o modelo já os viu, então eles medem recall. A correção é removê-los da validação ou avaliação (ou corrigir como os dados são divididos), nunca alterar o treinamento para fazer a verificação passar. Também relata como as mensagens de sistema são usadas: nenhuma, uma compartilhada, ou mista (veja references/chat-formats.md).

2. Pré-verifique a máquina

${CLAUDE_SKILL_DIR}/scripts/run preflight.py --params-b <bilhões de parâmetros> --out <runs>/<run>

A memória livre da GPU importa mais que a total: jogos, um navegador com aceleração de GPU, ou um modelo que um servidor local ainda mantém (ollama ps, descarregue com ollama stop <model>) podem deixar muito pouca. Se o preflight listar outros usuários da GPU, informe o usuário e deixe-o decidir, não mate processos. Com --params-b ele estima a necessidade (um modelo 3B em 4-bit atingiu pico de 6,6 GiB com comprimento de sequência 1024 e tamanho de lote 4, um 7B com 8,1 GiB) e, quando a memória livre é menor, imprime o par --batch-size/--grad-accum a ser usado. É uma estimativa de duas execuções: para outros tamanhos ou comprimentos de sequência, passe --need-gib e observe o pico que a execução de teste relata.

Se uma importação falhar, o ambiente está quebrado, veja references/troubleshooting.md antes de reinstalar qualquer coisa.

3. Execução de teste

${CLAUDE_SKILL_DIR}/scripts/run train.py --model <base> --data <data> --out <runs>/<run>-smoke --max-steps 2

Leia a saída, não apenas verifique o código de saída:

• o primeiro exemplo renderizado: a linha de sistema no topo é o que o modelo aprenderá a esperar,
• os tokens que recebem loss: apenas a resposta, não a pergunta,
• comprimentos de tokens: um aviso de truncamento significa aumentar --max-seq-length ou descartar exemplos,
• a rodada de sistema que um servidor deve enviar e os avisos sobre ela. Um template de pensamento (Qwen3, Qwen3.5) coloca um bloco vazio thinking response na frente de cada resposta treinada: informe ao usuário que o aplicativo o receberá nas respostas e deve removê-lo.

4. Execução completa

${CLAUDE_SKILL_DIR}/scripts/run train.py --model <base> --data <data> --out <runs>/<run>

Executa por um tempo (minutos para alguns milhares de exemplos em um modelo 3B, mais para 7B). Inicie-o com a opção de background da ferramenta Bash em vez de manter uma sessão aberta (a ferramenta mantém a saída em um arquivo, esse é o log: não adicione >, ; ou && ao comando, a pré-aprovação cobre exatamente o comando do lançador como mostrado), e verifique com ${CLAUDE_SKILL_DIR}/scripts/run train_status.py <runs>/<run>: step, losses, o step com o menor loss de validação e o tempo restante, a partir do último checkpoint. Após uma falha, use --resume. Relate o loss de treinamento e validação e o pico de memória da GPU. Um loss de validação muito acima do loss de treinamento indica overfitting: menos épocas ou mais dados.

5. Exportação

${CLAUDE_SKILL_DIR}/scripts/run export_gguf.py --run <runs>/<run>

Leva alguns minutos para um modelo 3B e mais de dez para um 7B (mesclando, convertendo, quantizando), que é mais do que a ferramenta Bash permite que um comando em primeiro plano execute: inicie em background como o treinamento e aguarde a conclusão. Escreve o GGUF em <run>/gguf/ e o registra em run.json com seu tamanho e checksum. Remove o modelo mesclado de 16 bits (vários GB, --keep-merged o mantém, e então o GGUF fica em <run>/gguf_gguf/) e o Modelfile que o Unsloth escreve ao lado do GGUF: ele usa o template padrão, não o layout usado no treinamento, portanto não siga a dica do Unsloth de ollama create a partir dele. Espere um aviso [CRITICAL] sobre o conversor do llama.cpp em toda exportação; informe ao usuário o que significa (references/troubleshooting.md), não impede a exportação. A pasta de execução agora está pronta para servir: continue com o skill ollama-model, ou passe a seção chat do run.json para quem servir o modelo (references/run-json.md).

6. Limpeza (pergunte primeiro)

Uma vez que o modelo seja exportado e avaliado, ofereça-se para excluir o que é necessário apenas para retomar ou verificar a configuração: <run>/checkpoints/ (para --resume, vários GB para um modelo 7B) e a pasta <run>-smoke. Informe quanto espaço cada um ocupa e exclua apenas o que o usuário concordar. Mantenha adapter/ e run.json: são pequenos e são o que uma nova exportação e as notas de versão precisam.

Regras

• Nunca altere o dataset para fazer uma avaliação parecer melhor, e nunca avalie com dados de treinamento.
• Não instale ou atualize pacotes no ambiente Unsloth sem perguntar: a combinação torch/CUDA é frágil.
• Pergunte antes de excluir pastas de execução ou checkpoints.