Hanyuyuan6/remote-gpu-trainer

remote-gpu-trainer — el ciclo de vida de experimentos de DL

Descripción general

Una habilidad para todo el arco de un experimento de DL: EJECUTAR → VERIFICAR → ENTREGAR.

• EJECUTAR — conseguir que un trabajo largo de GPU comience, sobreviva, termine y luego obtener el resultado de la máquina. En una máquina que posees no hay medidor; en una máquina alquilada la idea central es que eres un inquilino a corto plazo en la máquina de otra persona — por lo que el trabajo es separar el trabajo, hacer que el resultado sobreviva a la instancia y detener el medidor de forma segura, no aprovisionar un clúster. Específico de la plataforma en los bordes (un profiles/<platform>.md posee cada ruta, proxy, verbo de facturación y regla de spot), invariante en el núcleo.
• VERIFICAR — ¿es este número un error, un efecto real o ruido? Un resultado sorprendente es una hipótesis, no un hecho para informar. Agnóstico de la plataforma.
• ENTREGAR — organiza el resultado para que cada número/figura/tabla enviada sea una función determinista de una capa de evidencia inmutable; la procedencia y la consistencia entre documentos están aseguradas por el mecanismo, no por un humano que recuerde actualizar tres documentos. Agnóstico de la plataforma.

Dos posturas recorren VERIFICAR y ENTREGAR: soberanía del usuario (la ciencia — conteo de semillas, qué muestras, si existe un canal aux — es decisión del usuario; la habilidad organiza y divulga un trade-off una vez, luego deja de insistir) y auditar → divulgar, no imponer (la habilidad es una auditora honesta, no una guardiana — un problema de integridad debe surgir con la conclusión que afecta, pero la habilidad nunca bloquea al usuario para enviar). Lema: "divúlguelo, o no lo afirme."

Enrutar primero

1. EJECUTAR — ¿posees la máquina o la alquilas?
   • Local (una estación de trabajo/portátil que posees, sin medidor) → references/run-local/ y profiles/local.md.
   • Alquilado / remoto (cualquier máquina medida o compartida que no posees) → references/run-remote/, y elige tu profiles/<platform>.md PRIMERO (posee cada ruta/verbo/proxy al que delegan las fases).
2. Luego SIEMPRE → VERIFICAR el resultado (references/verifying/) → ENTREGARLO (references/delivering/). Estos dos son agnósticos de la plataforma; se ejecutan igual ya sea que el trabajo se haya entrenado localmente o en un alquiler. No omitas nada aquí solo porque la ejecución fue exitosa — una ejecución verde no es un número real, y un número real aún no es un entregable limpio.

¿Ya estás depurando un modelo que no converge / OOM / se cuelga / NaN, sin importar dónde se ejecute? Salta directamente a references/training/ (la capa de depuración de 8 archivos), luego vuelve a VERIFICAR antes de informar.

Principios operativos (la columna vertebral)

Los invariantes de carga. Una línea cada uno; el conjunto completo multiplataforma (10 invariantes para el ciclo de vida remoto) está en references/run-remote/principles.md — léelo antes de la Fase 0 de una ejecución remota.

• Checkpoint-durable + reanudación idempotente es la columna vertebral universal. Checkpoint a archivos en una ubicación durable + carga incondicional de la última versión al inicio es el único mecanismo que sobrevive a una caída de SSH, una muerte por walltime de Slurm, un reesquema de K8s, una preferencia spot, una desconexión de Colab. La primitiva de separación (tmux / sbatch / Job) es el enchufe intercambiable; este es el invariante.
• Confía en el artefacto que cargaste, no en una línea de registro que afirma éxito. "sincronizado / guardado / hecho" miente bajo una escritura que falló silenciosamente; el propio estado de un observador también es una afirmación — concílialo con el proceso / artefacto / píxeles / bytes reales.
• Verificaciones baratas antes del cómputo costoso. Una prueba de humo de CPU de 1–2 lotes (registro apagado) elimina errores de importación/configuración/forma/escala por ~gratis, antes de que facturen horas de GPU.
• El costo y las acciones destructivas son decisión del usuario. Nunca liberes/termines automáticamente, nunca elimines archivos durables sin confirmación; si la limpieza no puede liberar espacio, pide expandir el disco, no reduzcas silenciosamente el experimento.
• Auditar → divulgar, no imponer. Lo que es obligatorio es la divulgación, no la solución. Un hallazgo de integridad (sin validación disjunta, fuga, prueba tocada durante la selección, un número que no puedes rederivar) debe viajar con la conclusión — pero la habilidad divulga, no bloquea.

EJECUTAR — local (una máquina que posees)

Sin medidor, sin reloj de desmontaje — los riesgos se mueven de dinero a contención de recursos y estabilidad de tu máquina. La disciplina que no se relaja: higiene del entorno, conciencia de recursos, cuidado de artefactos/checkpoints y "declarar la semilla". Comienza en profiles/local.md, luego el documento correspondiente:

• Higiene del entorno — nunca entrenes/instales en conda base en una máquina persistente; la compuerta de 4 pasos (enumerar → elegir el entorno del proyecto → confirmar sys.executable → ejecutar) → references/run-local/env-hygiene.md.
• Inicio y separación — nohup/tmux, registro + sonda de actividad, no bloquees en primer plano → references/run-local/launch.md.
• Múltiples GPU de un solo nodo — contrato de entorno torchrun/accelerate DDP, conceptos básicos de rango/colgado en primera ejecución → references/run-local/multi-gpu.md (múltiples nodos → references/run-remote/multinode.md).
• OOM local — la escalera para solucionarlo en hardware que no puedes alquilar más grande → references/run-local/local-oom.md.

EJECUTAR — remoto (una máquina que alquilas)

Elige tu perfil PRIMERO — une cada ruta/proxy/credencial/verbo de facturación/regla spot concreta a la que delegan las fases. Modelo verbal mental (una API para todas las plataformas; el perfil une cada verbo a comandos reales): up (alquilar+alcanzar) → push (código/datos dentro) → run (separado + checkpointing) → watch (monitor durable) → pull (resultados fuera + verificar) → down (detener el medidor).

Estás en…	Perfil	Verbo para detener el medidor (la trampa)
AutoDL (más profundo, probado en batalla)	profiles/autodl.md	Apagar detiene el medidor, mantiene el disco (la excepción de AutoDL)
RunPod	profiles/runpod.md	terminate (stop aún factura 2×; destruye el volumen del disco)
vast.ai	profiles/vastai.md	destroy (stop factura el disco para siempre)
Lambda	profiles/lambda.md	terminate (sin estado de stop)
Paperspace	profiles/paperspace.md	destroy + liberar IP + eliminar almacenamiento
恒源云 / 矩池云 / Featurize / 揽睿星舟	profiles/china.md	por plataforma (el disco de datos a menudo factura mientras está detenido)
SSH puro / Slurm / K8s / Colab	profiles/generic-ssh.md	manual (una máquina olvidada factura 24/7)

El ciclo de vida de 6 fases (lista de verificación completa por plataforma → references/run-remote/lifecycle_checklist.md): 0 auditoría del entorno (df -i no solo df -h, cgroup memory.max, presupuesto de disco para checkpoints) · 1 SSH + credenciales (la imagen preconstruida es el entorno — no hagas conda create en un alquiler; secretos vía stdin) · 2 envoltorio + compuerta de humo de CPU antes de alquilar · 3 inicio separado (sondear, luego devolver el control — nunca un sleep bloqueante) · 4 monitoreo durable (la arquitectura de cuatro capas → references/run-remote/monitoring_patterns.md; un observador vinculado a la sesión muere con la sesión) · 5 agregar + verificar + desmontar.

Ley de hierro — compuerta de desmontaje: NO release / terminate / destroy / eliminación de archivos hasta que los checkpoints estén descargados a local Y verificados mediante carga (scripts/verify_local.py), y el usuario haya aprobado explícitamente la acción que afecta el costo. "Parecía hecho en el registro" no es evidencia. En la mayoría de las plataformas, la acción de detener el medidor es irreversible (elimina el disco) — la confirmación importa más, no menos.

Otras referencias remotas: ssh_transport.md (rsync/scp reanudable, secretos-vía-stdin, CRLF) · spot-resilience.md (gracia de preferencia, cadencia Young/Daly, reanudación de escritura atómica) · china-network.md (mirrors + HF_ENDPOINT + la trampa no_proxy) · parallel_ablation.md (independencia de abanico + reconciliación) · multinode.md (NCCL/fabric, avanzado) · gotchas_universal.md (el catálogo completo U1–U43 con un índice grep).

Cuando el entrenamiento en sí mismo se rompe (el modelo, no la plataforma)

Una vez que la máquina se ejecuta, el entrenamiento se rompe a su manera — local o remoto, la misma capa de depuración (references/training/, 8 archivos; cada entrada síntoma → causa raíz → solución con documentos citados). Enruta por síntoma:

• OOM / no cabe (CUDA-VRAM o host-RAM, OOM-en-un-paso, la escalera para solucionarlo) → oom-memory.md.
• Inicio de múltiples GPU / SE CUELGA (contrato de entorno torchrun/accelerate/deepspeed, DDP/FSDP/ZeRO) → distributed-launch.md.
• NaN / Inf / picos de pérdida (fp16/bf16/tf32, AMP/GradScaler, divergencia de LLM) → precision-stability.md.
• Demasiado lento (limitado por GPU vs datos vs comunicaciones, perillas del dataloader, trampas de torch.compile) → throughput-profiling.md.
• Errores de reanudación (guardado/reanudación de estado completo + fragmentado; reinicio de época, reorganización, scaler/EMA eliminados) → checkpoint-resume.md.
• Errores por dominio (LLM, visión det/seg, difusión, RL, multimodal/VLM) → by-domain.md.
• Se ejecuta pero no aprende (sobreajustar-un-lote, parámetros-no-actualizándose, LR/programación, errores comunes de función de pérdida, congelamiento) → convergence-debugging.md.
• Corrección del dataloader (duplicación de aumento de worker-RNG, fragmentación de IterableDataset, RGB-vs-BGR / ÷255 / set_epoch) → data-pipeline.md.

VERIFICAR — ¿es real el número?

Antes de confiar o informar cualquier métrica, delta de ablación o "ahora funciona": clasifícalo como error / efecto / ruido, mantén una comparación con exactamente una variable cambiada y sondear fugas / comparación justa / varianza / dirección de la métrica. Un número que no puedes rederivar del artefacto guardado no es un resultado todavía. Postura: auditar → divulgar — saca a la superficie un problema de integridad con la conclusión, nunca pases en silencio ni bloquees por completo.

• Metodología completa (la escalera de sonda de 14 secciones + los 6 invariantes) → references/verifying/methodology.md.
• Salida constante / degenerada, real == shuffle, modelo-ignora-entrada → references/verifying/representation-collapse.md.
• Un humo verde que oculta subentrenamiento vs un error real; pérdida-baja-pero-muestras-malas → references/verifying/smoke-hidden-failures.md.

Declara la dirección de la métrica al comparar (PSNR/SSIM/mAP ↑ mejor; LPIPS/NMSE/pérdida ↓ mejor) — nunca asumas. Análisis forense de trackers / poda de ejecuciones duplicadas → scripts/wandb_forensics.py.

ENTREGAR — organizar → fuente única → figuras

Haz que el entregable sea una función determinista de una capa de evidencia inmutable y versionada; asegura la procedencia y la consistencia entre documentos por mecanismo, no a mano. Ocho principios, en niveles (references/delivering/principles.md):

• NÚCLEO (conectar desde el primer número real) — P1 capas de evidencia/presentación claramente separadas (cero números escritos a mano en la capa de presentación) · P2 números generados desde results.json, no transcritos (por lo que un número desactualizado es físicamente imposible) · P3 ejecuciones inmutables con direccionamiento de contenido y solo añadido (volver a ejecutar crea un nuevo <id-ejecución>, nunca sobrescribe) · P7 trazabilidad de la cadena de figuras (results.json → source_data.csv → figura + sidecar .provenance) + la compuerta de reapertura de píxeles (una figura que se guardó no es una figura que sea correcta) · P8 entrega = una compuerta de divulgación, no una de bloqueo.
• Avanzado (activar cerca de la presentación — YAGNI también se aplica a la procedencia) — P4 datos/división versionados + hash-pinned (la fuga se vuelve comprobable por máquina) · P5 repro con un solo comando desde un clon limpio (scripts/repro.sh.template).

Mecánica: el árbol en disco → references/delivering/data-architecture.md; los dos esquemas de manifiesto → references/delivering/evidence-manifest-schema.md; la convención de una carpeta por figura + compuerta de píxeles → references/delivering/figures.md; la lista de verificación de divulgación por número → references/delivering/delivery-gate.md.

EVIDENCE.json es la fuente única de verdad a nivel de proyecto — un mapa legible por máquina de afirmaciones↔evidencia (cada afirmación ← el id-exp / métrica / figura de respaldo + un ancla de paper + el archivo:línea del repo). scripts/reconcile.py busca en todo el repo sus valores autorizados para detectar desviaciones entre documentos; scripts/manifest_scaffold.py sella la estructura.

Habilidades complementarias (todas OPCIONALES — esta habilidad es independiente)

Instalaciones separadas recomendadas que profundizan EJECUTAR / VERIFICAR / ENTREGAR; la habilidad no necesita ninguna y funciona completamente independiente. Lista de una línea cada una, qué añade cada una y el plan de contingencia sin complemento → references/companions.md. En resumen: dibujo de figuras (nature-figure / publication-chart / scipilot-figure), verificación de experimentos (el agente experiment-verifier), ablación paralela (superpowers:dispatching-parallel-agents), transporte HF + tracker alojado (huggingface-skills:hf-cli / huggingface-trackio).

Mejorar con el tiempo

La habilidad es estática, pero cada ejecución puede enseñarle un error común — sin corromperla. Protocolo → references/self-improvement.md: solo sedimenta un error común con causa raíz, reproducido y generalizable (una falla aislada es una hipótesis, no un error común); enruta los hechos específicos del usuario/proyecto a la memoria del host y los generalizables a una edición propuesta del catálogo; nunca reescribas silenciosamente un archivo de habilidad — redacta síntoma → causa raíz → solución y permite que el usuario lo apruebe. Los hechos de la plataforma llevan un sello verificado <mes> — vuelve a verificar cualquier hecho de desmontaje/facturación contra la documentación actual antes de apostar dinero o datos (scripts/check_staleness.py).

Recursos incluidos

Carga solo lo que la fase actual necesita (las secciones del cuerpo anterior nombran los archivos individuales).

• references/run-local/ — poseer-una-máquina: higiene-del-entorno · inicio · multi-gpu · oom-local.
• references/run-remote/ — máquina-alquilada: principios · lista-de-verificación-del-ciclo-de-vida · patrones-de-monitoreo · transporte-ssh · resiliencia-spot · red-china · ablación-paralela · multinodo · errores-comunes-universales (U1–U43).
• references/training/ — la capa de depuración de entrenamiento de DL (8 archivos; agnóstico local/remoto) — enrutada arriba.
• references/verifying/ — es-el-número-real: metodología · colapso-de-representación · fallos-ocultos-por-humo.
• references/delivering/ — entregable: principios · arquitectura-de-datos (+EVIDENCE.json) · esquema-de-manifiesto-de-evidencia · figuras · compuerta-de-entrega.
• references/companions.md (habilidades opcionales + planes de contingencia) · references/self-improvement.md (bucle de captura-de-error-común).
• profiles/<platform>.md — sustrato por plataforma (7 perfiles de alquiler + local.md; _schema.md = los campos).
• scripts/ — envoltorios (run_one …