PyTorch Lightning

Visão Geral

PyTorch Lightning é um framework de deep learning que organiza o código PyTorch para eliminar o código repetitivo, mantendo total flexibilidade. Automatize fluxos de trabalho de treinamento, orquestração multi-dispositivo e implemente as melhores práticas para treinamento e escalonamento de redes neurais em múltiplas GPUs/TPUs.

Versão revisada: Lightning 2.6.6, incluindo correções de segurança para carregamento de checkpoints. Testes de CPU usam Python 3.11, Torch 2.14.1 e Lightning 2.6.6. Use import lightning as L com a distribuição lightning. A distribuição alternativa pytorch-lightning expõe import pytorch_lightning as pl; não misture namespaces de classes dentro de uma única aplicação. Exemplos de GPU, TPU, multi-nó e loggers online são ilustrações verificadas por código-fonte, não validações de treinamento executadas.

Instalação

uv pip install "lightning==2.6.6"

Extras opcionais:

uv pip install "lightning[extra]==2.6.6"    # loggers, strategies, etc.
uv pip install wandb mlflow        # specific loggers as needed

Quando Usar Esta Habilidade

Esta habilidade deve ser usada quando:

• Construindo, treinando ou implantando redes neurais usando PyTorch Lightning
• Organizando código PyTorch em LightningModules
• Configurando Trainers para treinamento multi-GPU/TPU
• Implementando pipelines de dados com LightningDataModules
• Trabalhando com callbacks, logging e estratégias de treinamento distribuído (DDP, FSDP, DeepSpeed)
• Estruturando projetos de deep learning profissionalmente

Capacidades Principais

1. LightningModule - Definição do Modelo

Organize modelos PyTorch em seis seções lógicas:

1. Inicialização - __init__() e setup()
2. Loop de Treinamento - training_step(batch, batch_idx)
3. Loop de Validação - validation_step(batch, batch_idx)
4. Loop de Teste - test_step(batch, batch_idx)
5. Predição - predict_step(batch, batch_idx)
6. Configuração do Otimizador - configure_optimizers()

Referência rápida de template: Veja scripts/template_lightning_module.py para um boilerplate completo.

Documentação detalhada: Leia references/lightning_module.md para documentação completa de métodos, hooks, propriedades e melhores práticas.

2. Trainer - Automação de Treinamento

O Trainer automatiza o loop de treinamento, gerenciamento de dispositivos, operações de gradiente e callbacks. Principais recursos:

• Suporte multi-GPU/TPU com seleção de estratégia (DDP, FSDP, DeepSpeed)
• Treinamento com precisão mista automática
• Acumulação e clipping de gradiente
• Checkpointing e early stopping
• Barras de progresso e logging

Referência rápida de configuração: Veja scripts/quick_trainer_setup.py para configurações comuns do Trainer.

Documentação detalhada: Leia references/trainer.md para todos os parâmetros, métodos e opções de configuração.

3. LightningDataModule - Organização do Pipeline de Dados

Encapsule todas as etapas de processamento de dados em uma classe reutilizável:

1. prepare_data() - Download/cache no rank zero local por nó por padrão; use rank zero global com armazenamento compartilhado quando configurado
2. setup() - Crie datasets e aplique transformações (por GPU)
3. train_dataloader() - Retorne o DataLoader de treinamento
4. val_dataloader() - Retorne o DataLoader de validação
5. test_dataloader() - Retorne o DataLoader de teste

Referência rápida de template: Veja scripts/template_datamodule.py para um boilerplate completo.

Documentação detalhada: Leia references/data_module.md para detalhes de métodos e padrões de uso.

4. Callbacks - Lógica de Treinamento Extensível

Adicione funcionalidade personalizada em hooks de treinamento específicos sem modificar seu LightningModule. Callbacks integrados incluem:

• ModelCheckpoint - Salva os melhores/últimos modelos
• EarlyStopping - Para quando as métricas atingem um platô
• LearningRateMonitor - Rastreia mudanças no scheduler de LR
• BatchSizeFinder - Determina automaticamente o tamanho ideal do batch

Documentação detalhada: Leia references/callbacks.md para callbacks integrados e criação de callbacks personalizados.

5. Logging - Rastreamento de Experimentos

Integre com múltiplas plataformas de logging:

• CSV localmente; TensorBoard é o padrão apenas quando seu pacote opcional está instalado
• Weights & Biases (WandbLogger)
• MLflow (MLFlowLogger)
• Comet (CometLogger)
• CSV (CSVLogger)

NeptuneLogger foi removido no Lightning 2.6.4; o serviço Neptune foi desativado em 5 de março de 2026. Os helpers empacotados usam logging CSV local; rastreamento na nuvem e upload de artefatos de modelo exigem uma escolha intencional.

…