Treinar um Modelo Sentence-Transformers

Quando Usar

Use esta habilidade quando precisar treinar ou ajustar modelos sentence-transformers em SentenceTransformer (bi-encoder; modelo de embedding denso ou estático; para recuperação, similaridade, clustering, classificação, mineração de paráfrases, dedup, multimodal), CrossEncoder (reranker; pontuação de pares para recuperação em duas etapas / par...

Este SKILL.md é um roteador, não um manual. Ele informa quais referências e scripts de exemplo carregar para sua tarefa. O conteúdo real — perdas recomendadas, avaliadores, estrutura do script de treinamento, seleção de modelo, configurações de treinamento, solução de problemas — está em references/ e scripts/.

Não crie um script de treinamento apenas com este arquivo. Abra o template de produção por tipo (scripts/train_<type>_example.py) e copie-o como seu ponto de partida. Os templates contêm uma estrutura de suporte essencial (helper de autocast, classe model-card, lista de silenciamento de logger, force=True, seed, TF32, imports compatíveis com versão, tratamento de métricas de avaliador nomeado) que execuções anteriores do agente perderam repetidamente ao criarem seus próprios scripts a partir de um trecho sintetizado.

1. Identifique o tipo de modelo

Critérios de desempate quando a solicitação é ambígua: "modelo de embedding" / "busca por vetor" / "similaridade" → [SentenceTransformer]. "rerank" / "ranker" / "duas etapas" → [CrossEncoder]. "SPLADE" / "esparso" / "índice invertido" → [SparseEncoder]. Se ainda não estiver claro, pergunte.

2. Leitura obrigatória

Leia estes na íntegra antes de escrever qualquer código. Não trie por relevância percebida.

Por tipo — sempre obrigatório

[SentenceTransformer]

• references/losses_sentence_transformer.md — mapeamento de perda para formato de dados; requisito BatchSamplers.NO_DUPLICATES para família MNRL; incompatibilidade Cached* ↔ gradient_checkpointing.
• references/evaluators_sentence_transformer.md — mapeamento de avaliador para tarefa; construção de chave metric_for_best_model (nomeada vs. não nomeada); valores primary_metric por avaliador.
• references/model_architectures.md — pipelines de encoder vs. decoder vs. estático vs. Router; regras de pooling (mean / cls / lasttoken); comportamento de auto-pooling médio para bases MLM de reinício.
• scripts/train_sentence_transformer_example.py — template de produção; copie este como seu ponto de partida.

[CrossEncoder]

• references/losses_cross_encoder.md — pointwise / pairwise / listwise / destilação; derivação pos_weight; activation_fn=Identity() obrigatório para perdas não-BCE (colapso de avaliação-rank silencioso caso contrário).
• references/evaluators_cross_encoder.md — receita CrossEncoderRerankingEvaluator; formato de chave de avaliador nomeado eval_{name}_{primary_metric}.
• scripts/train_cross_encoder_example.py — template de produção; copie este como seu ponto de partida.

[SparseEncoder]

• references/losses_sparse_encoder.md — requisito do wrapper SpladeLoss; pesos do regularizador FLOPS; comportamento de rampa de dimensão ativa de smoke-test.
• references/evaluators_sparse_encoder.md — SparseNanoBEIREvaluator (apenas em inglês) e a alternativa in-domain; formato de chave eval_{name}_{primary_metric}.
• scripts/train_sparse_encoder_example.py — template de produção; copie este como seu ponto de partida.

Transversais — sempre obrigatórios (independentemente da tarefa)

• references/training_args.md — configurações TrainingArguments, regras de precisão (carregar fp32 + autocast bf16/fp16; nunca torch_dtype=bfloat16), warmup_steps (float) vs. warmup_ratio obsoleto, save_steps deve ser um múltiplo de eval_steps para load_best_model_at_end, schedulers, HPO, tracker, resume, variantes de hub-push.
• references/dataset_formats.md — regras de correspondência de colunas (detecção automática de nome de rótulo; ordem da coluna não é nome); receitas de remodelação; opções de mineração de hard-negative.

…