Melhores Práticas de Deep Learning

Regras para treinamento e implantação reprodutíveis e eficientes em PyTorch. Aplique durante a revisão de código e antes de escalar para multi-GPU.

Como Usar Esta Lista

Regras A-B cobrem configuração e pipelines de dados.
Regras C-D regem treinamento e avaliação.
Regras E-F cobrem exportação e produção.
Revise ao alterar hardware, versão do framework ou arquitetura do modelo.

A - Reprodutibilidade

Defina seeds aleatórias. torch.manual_seed(42), np.random.seed(42) e generator do DataLoader para execuções reprodutíveis.
Fixe as versões do PyTorch e CUDA. Registre torch.__version__ e o driver CUDA nos logs de experimentos.
Salve hiperparâmetros com checkpoints. Inclua LR, tamanho do batch, configuração da arquitetura e versão do dataset.
Use flags determinísticas ao depurar. torch.use_deterministic_algorithms(True) para reprodutibilidade (pode reduzir o desempenho).

B - Pipeline de Dados

Separe transformações de treino e validação. Aumentação aleatória apenas no treino; transformações determinísticas na validação/teste.
Use pin_memory e non_blocking com CUDA. Sobreponha a transferência de dados com a computação da GPU.
Defina num_workers apropriadamente. 4-8 workers em máquinas multi-core; 0 em notebooks.
Valide um único batch antes do treinamento. Imprima shapes, dtypes e faixas de valores para capturar bugs do pipeline precocemente.

C - Treinamento

Chame model.train() e model.eval() corretamente. Dropout e batch norm dependem do modo.
Use zero_grad(set_to_none=True) antes do backward. Evita bugs de acumulação de gradiente.
Corte gradientes para RNNs e redes profundas. clip_grad_norm_(model.parameters(), 1.0).
Use precisão mista em CUDA. torch.amp.autocast + GradScaler para 2x de velocidade.
Salve checkpoints em melhorias de validação. Não mantenha apenas a última época.
Monitore métricas de validação a cada época. A perda de treinamento sozinha esconde o overfitting.

D - Design do Modelo

Comece com pesos pré-treinados quando os dados são limitados. ImageNet para visão, HF hub para NLP.
Use taxas de aprendizado diferenciais para fine-tuning. LR menor para camadas pré-treinadas, maior para a nova cabeça.
Combine a função de perda com a tarefa. CrossEntropyLoss para multi-classe; BCEWithLogitsLoss para multi-label.
Perfilar antes de otimizar. Identifique se o carregamento de dados ou a computação da GPU é o gargalo.

E - Checkpointing & Exportação

Salve state_dict, não objetos de modelo completos. Reconstrua a classe do modelo ao carregar.
Use weights_only=True ao carregar checkpoints. Melhpr prática de segurança do PyTorch 2.6+.
Exporte em modo de avaliação. model.eval() antes do trace TorchScript ou exportação ONNX.
Verifique se a saída do modelo exportado corresponde ao PyTorch. torch.allclose contra a saída do ONNX Runtime.

F - Produção

Versionar artefatos do modelo em um registro. Vincule cada artefato ao hash dos dados de treinamento e às métricas.
Inclua o esquema de entrada no contrato de serviço. Shape de tensor esperado, dtype e normalização.
Teste a latência e a memória de inferência. Perfilar tamanhos de batch esperados em produção.
Planeje o custo da GPU. Use instâncias spot, precisão mista e modelos dimensionados corretamente.

FAQs

Qual é o bug de treinamento mais comum?

Esquecer model.eval() durante a validação.
Dropout randomiza as previsões; batch norm usa estatísticas do batch.
As métricas de validação se tornam sem sentido.

Como tornar o treinamento reprodutível?

torch.manual_seed(42)
torch.cuda.manual_seed_all(42)
generator = torch.Generator().manual_seed(42)
loader = DataLoader(ds, generator=generator, shuffle=True)

A reprodutibilidade completa em GPU pode exigir a flag de algoritmos determinísticos.

Quando devo usar PyTorch Lightning?

Boilerplate de multi-GPU, logging e checkpointing se acumulam.
Lightning vale a pena para projetos em equipe e treinamento de produção.
Aprenda loops manuais primeiro para habilidades de depuração.

Como evitar CUDA OOM?

Reduza o tamanho do batch, habilite precisão mista, use acumulação de gradiente.
torch.cuda.empty_cache() entre experimentos.

Devo usar torch.compile?

Sim para treinamento/inferência repetidos no PyTorch 2.6+.
A primeira iteração é lenta (compilação); faça benchmark antes de se comprometer.

Como revisar um PR de treinamento?

Verifique a troca de modo train/eval, posicionamento do dispositivo e salvamento de checkpoint.
Verifique se as métricas de validação estão sendo registradas.
Execute um equivalente a fast_dev_run (poucos batches) para validar o loop.

O que deve constar em uma configuração de treinamento?

Tamanho do batch, LR, épocas, arquitetura do modelo, caminho do dataset, seed e otimizador.
Use YAML/JSON ou Hydra para configurações de experimentos reprodutíveis.

Como detectar um gargalo no carregamento de dados?

Utilização da GPU abaixo de 50% durante o treinamento (verifique nvidia-smi).
Aumente num_workers e pin_memory.
Pré-carregue dados pré-processados em disco.

Quando o treinamento distribuído vale a pena?

Uma única época leva horas em uma GPU.
Aceleração quase linear com DDP em 2-8 GPUs.
Não vale a pena a complexidade para experimentos rápidos.

Como documentar um modelo treinado?

Arquitetura, dados de treinamento, métricas, limitações e especificação de entrada/saída.
Inclua a versão do PyTorch e o hardware usado para o treinamento.

Quais testes o código de inferência deve ter?

def test_model_output_shape():
    out = model(torch.randn(1, 3, 224, 224))
    assert out.shape == (1, num_classes)

Shape, dtype e um teste de entrada/saída dourada.

Como escolher o tamanho do batch?

O maior que couber na memória da GPU sem OOM.
Escalone o LR com o tamanho do batch (regra de escalonamento linear) ao aumentar.
Use acumulação de gradiente para batches efetivamente maiores.

Relacionados

Loops de Treinamento - implementação do loop
GPUs & Precisão Mista - configuração AMP
Salvamento, Carregamento & Exportação - formato de artefato
Rastreamento de Experimentos - registro de execuções
Treinamento Distribuído - escalonamento

Versões da Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ e uv 0.6+.

Melhores Práticas de Deep Learning

Regras para treinamento e implantação reprodutíveis e eficientes em PyTorch. Aplique durante a revisão de código e antes de escalar para multi-GPU.

Como Usar Esta Lista

Regras A-B cobrem configuração e pipelines de dados.
Regras C-D regem treinamento e avaliação.
Regras E-F cobrem exportação e produção.
Revise ao alterar hardware, versão do framework ou arquitetura do modelo.

A - Reprodutibilidade

Defina seeds aleatórias. torch.manual_seed(42), np.random.seed(42) e generator do DataLoader para execuções reprodutíveis.
Fixe as versões do PyTorch e CUDA. Registre torch.__version__ e o driver CUDA nos logs de experimentos.
Salve hiperparâmetros com checkpoints. Inclua LR, tamanho do batch, configuração da arquitetura e versão do dataset.
Use flags determinísticas ao depurar. torch.use_deterministic_algorithms(True) para reprodutibilidade (pode reduzir o desempenho).

B - Pipeline de Dados

Separe transformações de treino e validação. Aumentação aleatória apenas no treino; transformações determinísticas na validação/teste.
Use pin_memory e non_blocking com CUDA. Sobreponha a transferência de dados com a computação da GPU.
Defina num_workers apropriadamente. 4-8 workers em máquinas multi-core; 0 em notebooks.
Valide um único batch antes do treinamento. Imprima shapes, dtypes e faixas de valores para capturar bugs do pipeline precocemente.

C - Treinamento

Chame model.train() e model.eval() corretamente. Dropout e batch norm dependem do modo.
Use zero_grad(set_to_none=True) antes do backward. Evita bugs de acumulação de gradiente.
Corte gradientes para RNNs e redes profundas. clip_grad_norm_(model.parameters(), 1.0).
Use precisão mista em CUDA. torch.amp.autocast + GradScaler para 2x de velocidade.
Salve checkpoints em melhorias de validação. Não mantenha apenas a última época.
Monitore métricas de validação a cada época. A perda de treinamento sozinha esconde o overfitting.

D - Design do Modelo

Comece com pesos pré-treinados quando os dados são limitados. ImageNet para visão, HF hub para NLP.
Use taxas de aprendizado diferenciais para fine-tuning. LR menor para camadas pré-treinadas, maior para a nova cabeça.
Combine a função de perda com a tarefa. CrossEntropyLoss para multi-classe; BCEWithLogitsLoss para multi-label.
Perfilar antes de otimizar. Identifique se o carregamento de dados ou a computação da GPU é o gargalo.

E - Checkpointing & Exportação

Salve state_dict, não objetos de modelo completos. Reconstrua a classe do modelo ao carregar.
Use weights_only=True ao carregar checkpoints. Melhpr prática de segurança do PyTorch 2.6+.
Exporte em modo de avaliação. model.eval() antes do trace TorchScript ou exportação ONNX.
Verifique se a saída do modelo exportado corresponde ao PyTorch. torch.allclose contra a saída do ONNX Runtime.

F - Produção

Versionar artefatos do modelo em um registro. Vincule cada artefato ao hash dos dados de treinamento e às métricas.
Inclua o esquema de entrada no contrato de serviço. Shape de tensor esperado, dtype e normalização.
Teste a latência e a memória de inferência. Perfilar tamanhos de batch esperados em produção.
Planeje o custo da GPU. Use instâncias spot, precisão mista e modelos dimensionados corretamente.

FAQs

Qual é o bug de treinamento mais comum?

Esquecer model.eval() durante a validação.
Dropout randomiza as previsões; batch norm usa estatísticas do batch.
As métricas de validação se tornam sem sentido.

Como tornar o treinamento reprodutível?

torch.manual_seed(42)
torch.cuda.manual_seed_all(42)
generator = torch.Generator().manual_seed(42)
loader = DataLoader(ds, generator=generator, shuffle=True)

A reprodutibilidade completa em GPU pode exigir a flag de algoritmos determinísticos.

Quando devo usar PyTorch Lightning?

Boilerplate de multi-GPU, logging e checkpointing se acumulam.
Lightning vale a pena para projetos em equipe e treinamento de produção.
Aprenda loops manuais primeiro para habilidades de depuração.

Como evitar CUDA OOM?

Reduza o tamanho do batch, habilite precisão mista, use acumulação de gradiente.
torch.cuda.empty_cache() entre experimentos.

Devo usar torch.compile?

Sim para treinamento/inferência repetidos no PyTorch 2.6+.
A primeira iteração é lenta (compilação); faça benchmark antes de se comprometer.

Como revisar um PR de treinamento?

Verifique a troca de modo train/eval, posicionamento do dispositivo e salvamento de checkpoint.
Verifique se as métricas de validação estão sendo registradas.
Execute um equivalente a fast_dev_run (poucos batches) para validar o loop.

O que deve constar em uma configuração de treinamento?

Tamanho do batch, LR, épocas, arquitetura do modelo, caminho do dataset, seed e otimizador.
Use YAML/JSON ou Hydra para configurações de experimentos reprodutíveis.

Como detectar um gargalo no carregamento de dados?

Utilização da GPU abaixo de 50% durante o treinamento (verifique nvidia-smi).
Aumente num_workers e pin_memory.
Pré-carregue dados pré-processados em disco.

Quando o treinamento distribuído vale a pena?

Uma única época leva horas em uma GPU.
Aceleração quase linear com DDP em 2-8 GPUs.
Não vale a pena a complexidade para experimentos rápidos.

Como documentar um modelo treinado?

Arquitetura, dados de treinamento, métricas, limitações e especificação de entrada/saída.
Inclua a versão do PyTorch e o hardware usado para o treinamento.

Quais testes o código de inferência deve ter?

def test_model_output_shape():
    out = model(torch.randn(1, 3, 224, 224))
    assert out.shape == (1, num_classes)

Shape, dtype e um teste de entrada/saída dourada.

Como escolher o tamanho do batch?

O maior que couber na memória da GPU sem OOM.
Escalone o LR com o tamanho do batch (regra de escalonamento linear) ao aumentar.
Use acumulação de gradiente para batches efetivamente maiores.

Relacionados

Loops de Treinamento - implementação do loop
GPUs & Precisão Mista - configuração AMP
Salvamento, Carregamento & Exportação - formato de artefato
Rastreamento de Experimentos - registro de execuções
Treinamento Distribuído - escalonamento

Versões da Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ e uv 0.6+.

Melhores Práticas de Deep Learning

Buscar na documentação

Melhores Práticas de Deep Learning