remote-gpu-trainer

remote-gpu-trainer — o Ciclo de Vida de Experimentos de DL

Visão Geral

Uma habilidade para todo o arco de um experimento de DL: EXECUTAR → VERIFICAR → ENTREGAR.

• EXECUTAR — fazer um trabalho longo de GPU iniciar, sobreviver e terminar, e então obter o resultado da máquina. Em uma máquina que você possui não há medidor; em uma máquina alugada, a percepção central é que você é um inquilino de curto prazo na máquina de outra pessoa — então o trabalho é desanexar o trabalho, fazer o resultado sobreviver à instância e parar o medidor com segurança, não provisionar um cluster. Específico da plataforma nas bordas (um profiles/<platform>.md é dono de cada caminho, proxy, verbo de faturamento e regra de spot), invariante no núcleo.
• VERIFICAR — esse número é um bug, um efeito real ou ruído? Um resultado surpreendente é uma hipótese, não um fato a ser relatado. Agnóstico de plataforma.
• ENTREGAR — organizar o resultado para que cada número/figura/tabela enviada seja uma função determinística de uma camada de evidência imutável; proveniência e consistência entre documentos são garantidas por mecanismo, não por um humano lembrar de atualizar três documentos. Agnóstico de plataforma.

Duas posturas permeiam VERIFICAR e ENTREGAR: soberania do usuário (a ciência — contagem de sementes, quais amostras, se um canal aux existe — é decisão do usuário; a habilidade organiza e divulga um tradeoff uma vez, então para de importunar) e auditar → divulgar, não impor (a habilidade é um auditor honesto, não um porteiro — um problema de integridade deve vir com a conclusão que afeta, mas a habilidade nunca bloqueia o usuário de enviar). Mantra: "divulgue, ou não reivindique."

Roteiro primeiro

1. EXECUTAR — máquina própria ou alugada?
   • Local (um workstation/laptop que você possui, sem medidor) → references/run-local/ e profiles/local.md.
   • Alugado/remoto (qualquer máquina medida ou compartilhada que você não possui) → references/run-remote/, e escolha seu profiles/<platform>.md PRIMEIRO (ele é dono de cada caminho/verbo/proxy para o qual as fases delegam).
2. Então SEMPRE → VERIFICAR o resultado (references/verifying/) → ENTREGÁ-LO (references/delivering/). Essas duas são agnósticas de plataforma; funcionam da mesma forma quer o trabalho tenha treinado localmente ou em um aluguel. Não pule nada aqui só porque a execução foi bem-sucedida — uma execução verde não é um número real, e um número real não é ainda um entregável limpo.

Já está depurando um modelo que não converge / OOM / trava / NaN, independentemente de onde executa? Vá direto para references/training/ (a camada de depuração de 8 arquivos), depois volte para VERIFICAR antes de relatar.

Princípios operacionais (a espinha dorsal)

As invariantes estruturais. Uma linha cada; o conjunto completo multiplataforma (10 invariantes para o ciclo de vida remoto) está em references/run-remote/principles.md — leia antes da Fase 0 de uma execução remota.

• Checkpoint durável + retomada idempotente é a espinha dorsal universal. Fazer checkpoint de arquivo para o local durável + carregar incondicionalmente o último na inicialização é o único mecanismo que sobrevive a uma queda de SSH, um kill de walltime do Slurm, um reagendamento do K8s, uma preempção spot, uma desconexão do Colab. O primitivo de desanexação (tmux / sbatch / Job) é o plugue intercambiável; esta é a invariante.
• Confie no artefato que você carregou, não em uma linha de log que afirma sucesso. "sincronizado / salvo / pronto" mente sob uma gravação que falhou silenciosamente; o próprio estado de um observador também é uma afirmação — reconcilie-o contra o processo / artefato / pixels / bytes reais.
• Verificações baratas antes de computação cara. Um smoke de CPU de 1–2 lotes (logger desligado) mata bugs de import/config/forma/escala de graça, antes que eles custem horas de GPU.
• Custo e ações destrutivas são decisão do usuário. Nunca libere/termine automaticamente, nunca exclua arquivos duráveis sem confirmação; se a limpeza não puder liberar espaço, peça para expandir o disco, não encolha silenciosamente o experimento.
• Auditar → divulgar, não impor. O que é obrigatório é a divulgação, não a correção. Uma descoberta de integridade (sem validação disjunta, vazamento, teste tocado durante a seleção, um número que você não pode rederivar) deve vir com a conclusão — mas a habilidade divulga, não bloqueia.

EXECUTAR — local (uma máquina que você possui)

Sem medidor, sem relógio de desmontagem — os riscos mudam de dinheiro para concorrência de recursos e estabilidade da sua máquina. A disciplina que não relaxa: higiene de ambiente, consciência de recursos, cuidado com artefato/checkpoint, e "declare a semente." Comece em profiles/local.md, depois o documento correspondente:

• Higiene de ambiente — nunca treine/instale no conda base em uma máquina persistente; o portão de 4 etapas (enumerar → escolher o ambiente do projeto → confirmar sys.executable → executar) → references/run-local/env-hygiene.md.
• Lançar e desanexar — nohup/tmux, log + sonda ativa, não bloqueie em primeiro plano → references/run-local/launch.md.
• Multi-GPU de nó único — contrato de ambiente DDP torchrun/accelerate, noções básicas de rank/trava da primeira execução → references/run-local/multi-gpu.md (multi-nó → references/run-remote/multinode.md).
• OOM local — a escada de ajuste em hardware que você não pode alugar maior → references/run-local/local-oom.md.

EXECUTAR — remoto (uma máquina que você aluga)

Escolha seu perfil PRIMEIRO — ele vincula cada caminho/proxy/credencial/verbo de faturamento/regra spot concreto para o qual as fases delegam. Modelo de verbo mental (uma API entre plataformas; o perfil vincula cada verbo a comandos reais): up (alugar+alcançar) → push (código/dados para) → run (desanexado + checkpointing) → watch (monitor durável) → pull (resultados para fora + verificar) → down (parar o medidor).

Você está em…	Perfil	Verbo de parar o medidor (a armadilha)
AutoDL (mais profundo, testado em batalha)	profiles/autodl.md	关机 para o medidor, mantém o disco (a exceção do AutoDL)
RunPod	profiles/runpod.md	terminate (stop ainda fatura 2×; destrói o volume do disco)
vast.ai	profiles/vastai.md	destroy (stop fatura o disco para sempre)
Lambda	profiles/lambda.md	terminate (sem estado stop)
Paperspace	profiles/paperspace.md	destroy + release IP + delete storage
恒源云 / 矩池云 / Featurize / 揽睿星舟	profiles/china.md	por plataforma (disco de dados frequentemente fatura enquanto parado)
Bare SSH / Slurm / K8s / Colab	profiles/generic-ssh.md	manual (uma máquina esquecida fatura 24/7)

O ciclo de vida de 6 fases (checklist completo por plataforma → references/run-remote/lifecycle_checklist.md): 0 auditoria de ambiente (df -i não apenas df -h, cgroup memory.max, orçamento de disco de checkpoint) · 1 SSH + credenciais (a imagem pré-construída é o ambiente — não faça conda create em um aluguel; segredos via stdin) · 2 wrapper + portão de smoke de CPU antes de alugar · 3 lançamento desanexado (sonda, depois devolva — nunca um sleep bloqueante) · 4 monitoramento durável (a arquitetura de quatro camadas → references/run-remote/monitoring_patterns.md; um observador vinculado à sessão morre com a sessão) · 5 agregar + verificar + desmontar.

Lei de Ferro — portão de desmontagem: NENHUM release / terminate / destroy / exclusão de arquivo até que os checkpoints sejam puxados para o local E verificados por carga (scripts/verify_local.py), e o usuário tenha aprovado explicitamente a ação que afeta o custo. "Parecia pronto no log" não é evidência. Na maioria das plataformas, a ação de parar o medidor é irreversível (exclui o disco) — a confirmação importa mais, não menos.

Outras referências remotas: ssh_transport.md (rsync/scp retomável, segredos-via-stdin, CRLF) · spot-resilience.md (período de graça de preempção, cadência Young/Daly, retomada com gravação atômica) · china-network.md (mirrors + HF_ENDPOINT + a armadilha no_proxy) · parallel_ablation.md (independência de fan-out + reconciliação) · multinode.md (NCCL/fabric, avançado) · gotchas_universal.md (o catálogo completo U1–U43 com um índice grep).

Quando o treinamento em si quebra (o modelo, não a plataforma)

Assim que a máquina executa, o treinamento quebra de suas próprias maneiras — local ou remoto, a mesma camada de depuração (references/training/, 8 arquivos; cada entrada sintoma → causa raiz → correção com documentos citados). Roteie por sintoma:

• OOM / não cabe (CUDA-VRAM ou host-RAM, OOM-em-uma-etapa, a escada de ajuste) → oom-memory.md.
• Multi-GPU lançamento / TRAVAS (torchrun/accelerate/deepspeed contrato de ambiente, DDP/FSDP/ZeRO) → distributed-launch.md.
• NaN / Inf / picos de perda (fp16/bf16/tf32, AMP/GradScaler, divergência de LLM) → precision-stability.md.
• Muito lento (vinculado a GPU vs dados vs comunicações, botões do dataloader, armadilhas do torch.compile) → throughput-profiling.md.
• Bugs de retomada (salvar/retomar estado completo + fragmentado; reinício de época, reembaralhamento, scaler/EMA perdido) → checkpoint-resume.md.
• Pegadinhas por domínio (LLM, visão det/seg, difusão, RL, multimodal/VLM) → by-domain.md.
• Executa mas não aprende (overfit-one-batch, params-not-updating, LR/schedule, armadilhas de função de perda, congelamento) → convergence-debugging.md.
• Correção do dataloader (duplicação de aumento worker-RNG, sharding IterableDataset, RGB-vs-BGR / ÷255 / set_epoch) → data-pipeline.md.

VERIFICAR — o número é real?

Antes de confiar ou relatar qualquer métrica, delta de ablação, ou "agora funciona": classifique-o como bug / efeito / ruído, faça uma comparação com exatamente uma variável alterada, e investigue vazamento / comparação justa / variância / direção da métrica. Um número que você não pode rederivar do artefato salvo não é um resultado ainda. Postura: auditar → divulgar — traga um problema de integridade à tona com a conclusão, nunca passe silenciosamente ou bloqueie rigidamente.

• Metodologia completa (a escada de sondagem de 14 seções + as 6 invariantes) → references/verifying/methodology.md.
• Saída constante / degenerada, real == shuffle, modelo ignora entrada → references/verifying/representation-collapse.md.
• Um smoke verde que esconde subtreinamento vs um bug real; perda-baixa-mas-amostras-ruins → references/verifying/smoke-hidden-failures.md.

Declare a direção da métrica ao comparar (PSNR/SSIM/mAP ↑ melhor; LPIPS/NMSE/perda ↓ melhor) — nunca presuma. Forense de rastreador / poda de execuções duplicadas → scripts/wandb_forensics.py.

ENTREGAR — organizar → fonte única → figuras

Faça do entregável uma função determinística de uma camada de evidência imutável e versionada; trave a proveniência e a consistência entre documentos por mecanismo, não manualmente. Oito princípios, em camadas (references/delivering/principles.md):

• NÚCLEO (conecte a partir do primeiro número real) — P1 camadas de evidência/apresentação limpa e separadamente (zero números digitados à mão na camada de apresentação) · P2 números gerados a partir de results.json, não transcritos (portanto, um número desatualizado é fisicamente impossível) · P3 execuções imutáveis endereçadas por conteúdo e somente anexação (reexecutar cria um novo <run-id>, nunca sobrescreve) · P7 rastreabilidade da cadeia de figuras (results.json → source_data.csv → figura + sidecar .provenance) + o portão de reabertura de pixels (uma figura que salvou não é uma figura que está correta) · P8 entrega = um portão de divulgação, não um bloqueador.
• Avançado (ative perto da submissão — YAGNI também se aplica à proveniência) — P4 dados/divisão versionados + hash-pinned (vazamento torna-se verificável por máquina) · P5 reprodutibilidade com um comando a partir de um clone limpo (scripts/repro.sh.template).

Mecânica: a árvore no disco → references/delivering/data-architecture.md; os dois esquemas de manifesto → references/delivering/evidence-manifest-schema.md; a convenção de uma pasta por figura + portão de pixels → references/delivering/figures.md; a lista de verificação de divulgação por número → references/delivering/delivery-gate.md.

EVIDENCE.json é a fonte única da verdade em nível de projeto — um mapa legível por máquina de reivindicações↔evidência (cada reivindicação ← o exp-id / métrica / figura de suporte + uma âncora de artigo + o file:line do repositório). scripts/reconcile.py pesquisa em todo o repositório com base em seus valores autoritativos para capturar deriva entre documentos; scripts/manifest_scaffold.py carimba a estrutura.

Habilidades complementares (todas OPCIONAIS — esta habilidade é independente)

Instalações separadas recomendadas que aprofundam EXECUTAR / VERIFICAR / ENTREGAR; a habilidade não precisa de nenhuma delas e funciona totalmente independente. Lista de uma linha cada, o que cada uma adiciona, e o fallback sem complemento → references/companions.md. Em resumo: desenho de figuras (nature-figure / publication-chart / scipilot-figure), verificação de experimento (o agente experiment-verifier), ablação paralela (superpowers:dispatching-parallel-agents), transporte HF + rastreador hospedado (huggingface-skills:hf-cli / huggingface-trackio).

Melhorando ao longo do tempo

A habilidade é estática, mas cada execução pode ensinar uma pegadinha — sem corrompê-la. Protocolo → references/self-improvement.md: apenas sedimente uma pegadinha com causa raiz, reproduzida e generalizável (um problema único é uma hipótese, não uma pegadinha); encaminhe fatos específicos do usuário/projeto para a memória do host e os generalizáveis para uma edição de catálogo proposta; nunca reescreva silenciosamente um arquivo de habilidade — elabore o sintoma → causa raiz → correção e deixe o usuário aprovar. Fatos de plataforma carregam um carimbo verified <mês> — re-verifique qualquer fato de desmontagem/faturamento com a documentação atual antes de apostar dinheiro ou dados (scripts/check_staleness.py).

Recursos agrupados

Carregue apenas o que a fase atual precisa (as seções do corpo acima nomeiam os arquivos individuais).

• references/run-local/ — possua-uma-máquina: env-hygiene · launch · multi-gpu · local-oom.
• references/run-remote/ — máquina-alugada: principles · lifecycle_checklist · monitoring_patterns · ssh_transport · spot-resilience · china-network · parallel_ablation · multinode · gotchas_universal (U1–U43).
• references/training/ — a camada de depuração de treinamento DL (8 arquivos; agnóstico local/remoto) — roteada acima.
• references/verifying/ — o-número-é-real: methodology · representation-collapse · smoke-hidden-failures.
• references/delivering/ — entregável: principles · data-architecture (+EVIDENCE.json) · evidence-manifest-schema · figures · delivery-gate.
• references/companions.md (habilidades opcionais + fallbacks) · references/self-improvement.md (loop de capturar-pegadinha).
• profiles/<platform>.md — substrato por plataforma (7 perfis de aluguel + local.md; _schema.md = os campos).
• scripts/ — wrappers (run_one...)