tao-finetune-huggingface-model

Ajuste fino de GPU NVIDIA local para modelos de HuggingFace, basado en documentación obtenida en tiempo real con referencias curadas como red de seguridad. Un contenedor NGC, unos pocos scripts enfocados, un solo empuje al Hub de HF. Sigue las reglas de este archivo; no improvises.

Orden de autoridad (de mayor a menor):

1. Entrada del usuario — model_id, dataset_id, training_method, anulaciones de config.yaml explícitos.
2. Investigación en vivo — tarjeta del modelo, ejemplo del repositorio de HF, script de ajuste fino del autor, documentos de tareas de HF, artículo; siempre obtenido (Paso 3 + references/research-priorities.md).
3. Referencias curadas (references/*.md) — respaldo cuando la investigación en vivo es silenciosa/ambigua.
4. Memoria de datos de entrenamiento — último recurso; sospechoso, verificar contra (2)/(3).

La resolución de conflictos entre (2) y (3) y la nota de discrepancia de línea de origen están en references/research-priorities.md.

Entradas

Requerido:

• model_id — ID del modelo de HuggingFace, por ejemplo google/vit-base-patch16-224

Credenciales condicionales (leídas desde el entorno de la sesión, exportadas antes de iniciar cuando estén presentes):

• HF_TOKEN — solo cuando el modelo/dataset es gated (lectura) o push_to_hub está activado (escritura); público + público + push_to_hub: false no necesita ninguno. El valor nunca se lee — solo la presencia mediante [ -n "$HF_TOKEN" ].
• WANDB_API_KEY, WANDB_PROJECT — solo cuando WandB está habilitado; WANDB_MODE=disabled opta por no participar.

Dataset — exactamente uno:

• dataset_id — ID del dataset de HuggingFace (fuente: hf)
• local_dataset_path — carpeta o archivo local (fuente: local); local_dataset_format opcional ∈ {auto, imagefolder, coco, voc, jsonl, arrow, parquet, csv} (predeterminado: detección automática).
• (omitir) — el agente recomienda datasets populares (fuente: recommend)

Opcional (con valores predeterminados):

• task_type — detectado automáticamente desde config + tarjeta del modelo
• n_train=10000, n_eval=1000, n_epochs=3, lora_r=16
• output_dir=./output/<model_short_name></model_short_name>
• hf_model_repo — destino de empuje; si no está configurado y HF_TOKEN tiene acceso de escritura, se deriva automáticamente como <whoami>/<model_short_name>-finetuned</model_short_name></whoami>.
• push_to_hub=True — establecer en False para omitir
• skip_baseline=False — omitir evaluación de línea base de cero disparos

Entregables opcionales (desactivados por defecto):

emit_progress_log: false   # output_dir/PROGRESS.md (diario por paso)
emit_report:       false   # reports/report.{pdf,html} con curvas y muestras
emit_unit_tests:   false   # tests/ con pruebas de lotes heterogéneos de datos falsos

Todos los valores residen en output_dir/config.yaml. Nunca codifiques en Python.

Plataforma de ejecución

Esta habilidad orquesta qué ejecutar; las habilidades de plataforma poseen cómo ejecutarlo en un host GPU — léelas primero.

Plataforma predeterminada: local-docker — construir una imagen única (run-<short>:latest</short>) y ejecutarla en el daemon Docker local. Preguntar solo cuando el usuario necesite explícitamente un backend diferente (GPU remota Brev, SLURM/Kubernetes); luego ejecutar la verificación previa de esa plataforma primero y enrutar los comandos docker run de los Pasos 4–5 a través de ella. Las verificaciones previas de tiempo de ejecución GPU y presencia de credenciales (valores nunca leídos), el conjunto canónico de banderas docker run, el comando de selección list_tao_platforms.py y las banderas específicas del flujo de trabajo (--entrypoint /bin/bash -lc, PYTORCH_CUDA_ALLOC_CONF, --name hft_train) están en references/workflow-intake-preflight.md.

Referencias — red de seguridad de respaldo

Consultadas solo cuando la investigación en vivo es silenciosa, ambigua o no disponible; los documentos en vivo siempre ganan para el modelo específico y la API actual. Cada paso vincula las referencias que necesita; catálogo completo en references/detailed-workflow.md.

Siempre activas: core-rules.md, error-playbook.md, compat-workarounds.md, model-discovery.md, dataset-recommendations.md, dataset-sources.md, dataset-patterns.md, hardware-container.md, research-priorities.md, cv-scripts.md, vlm-scripts.md, docker-runs.md, hub-push.md, pipeline-skill-template.md, deliverables.md. Opcionales (cuando su bandera/necesidad aplica): progress-tracking.md, testing.md, reporting.md, workflow-intake-preflight.md, workflow-generate-train.md, workflow-push-rerun.md.

Regla: antes de recurrir al respaldo, registrar la fuente en vivo que se intentó y por qué fue insuficiente (config.yaml notes:, y PROGRESS.md si está habilitado). Los marcadores [FETCH LIVE] en cv-scripts.md / vlm-scripts.md son una lista de verificación de investigación, no código para insertar — volver a obtener la URL listada si un bloque no tiene hallazgo del Paso 3.

Reglas fundamentales

Comportamientos no negociables. Versión corta (enumeración completa — lista de importaciones alucinadas, lista de nunca sin aprobación, tablas completas de recuperación de errores y dimensionamiento de hardware — en references/core-rules.md, consultar antes de cualquier decisión durante el entrenamiento):

• Tu conocimiento de la biblioteca HF está desactualizado. Obtener documentos en vivo (tarjeta del modelo, ejemplo del repositorio de HF, documento de tarea) antes de escribir cualquier código ML — no generar argumentos del entrenador / collator / transformaciones desde la memoria (Paso 3).
• Prueba de humo con datos reales con --max_steps 1 antes de cualquier ejecución completa; no lanzar lotes sin una prueba de humo verificada.
• Nunca sustituir silenciosamente model_id, dataset_id, o training_method — si lo que el usuario pidió no carga, detenerse y preguntar.
• La recuperación de errores es de cambio mínimo. OOM → reducir el lote a la mitad, duplicar grad_accum, habilitar checkpointing de gradientes (sin cambiar a LoRA sin aprobación); NaN → reducir LR 10×; pérdida plana → inspeccionar collator; mismo error 3× → detenerse y preguntar. No bucle.
• Columnas del dataset verificadas ANTES del collator — renombrar en prepare_data.py; reestructuración necesaria → detenerse y preguntar.
• Regla general de dimensionamiento de hardware (bf16): ≤3B → 24 GB, 7–13B → 80 GB, 30B+ → multi-GPU o LoRA en 1× 80 GB, 70B+ → 8× 80 GB o LoRA. El ajuste fino completo no cabrá y no se solicitó LoRA → preguntar antes de cambiar.

Flujo de trabajo — 6 pasos

Un solo pase, secuencial; cada paso tiene un claro umbral antes de que comience el siguiente.

Paso 1 — Inspeccionar y calificar

Objetivo: decidir si proceder. Explorar modelo + dataset, aplicar aceptar/rechazar, registrar correcciones de compatibilidad aplicables, escribir el config.yaml inicial.

Prerrequisitos: MODEL_ID, opcional DATASET_ID / local_dataset_path, opcional HF_TOKEN, OUTPUT_DIR (predeterminado ./output/<model_short_name></model_short_name>). Las exploraciones se ejecutan en un contenedor Docker python:3.12-slim solo de CPU (.probe/scratch montado en enlace) para que el host no necesite virtualenv — Docker debe existir primero. Guardía de presencia de Docker, entorno del contenedor, invocación completa de la exploración y los scripts de exploración del modelo/dataset están en references/workflow-intake-preflight.md, references/model-discovery.md y references/dataset-sources.md.

Requisitos de exploración:

• Modelo: cargar AutoConfig, leer etiquetas de la tarjeta del modelo, detectar tarea desde architectures + etiquetas + ejemplos de la tarjeta (registro de respaldo en model-discovery.md).
• Dataset: para datasets recomendados, presentar primero 3-5 opciones de dataset-recommendations.md; para datos locales, montar enlace de solo lectura y usar detección de formato de dataset-sources.md.
• Rechazar temprano si falla la configuración del modelo, la tarea está fuera de alcance, no existe fuente de receta o el dataset no puede cargar / coincidir con el esquema de la tarea.
• Evaluar compat-workarounds.md contra el modelo/tarea; diferir reglas dependientes del hardware al Paso 2.

Escribir el config.yaml inicial (model_id, task, dataset_id o local_dataset_path, research_sources: [] rellenado en el Paso 3, applicable_workarounds: del Paso 1, notes: [] para respaldos de referencia, push_to_hub: true predeterminado — plantilla anotada en references/workflow-intake-preflight.md). Opcionalmente rm -rf "$OUTPUT_DIR/.probe"una vez cumplido el umbral.

Umbral: config.yaml existe con modelo, dataset, tarea, applicable_workarounds; no proceder si falta algún campo.

Paso 2 — Auditoría de hardware e imagen NGC

Objetivo: verificar Docker + GPU + disco, elegir la imagen PyTorch NGC en vivo, finalizar reglas de compatibilidad dependientes del hardware.

2a. Auditoría (umbral duro) — tres comprobaciones (comandos en references/workflow-intake-preflight.md):

1. Entorno de ejecución del host GPU — setup-nvidia-gpu-host.sh --backend docker --check-only de tao-setup-nvidia-gpu-host; en fallo, pedir aprobación y luego volver a ejecutar con --install --yes.
2. Advertencia suave de disco libre — anular mediante MIN_DISK_GB (predeterminado 100 GB); recomendar ≥ 100 GB para base NGC (~20 GB) + caché HF + checkpoints + datos.
3. Presencia de credenciales condicionales (desde el entorno de la sesión, valores nunca leídos) — HF_TOKEN solo cuando está gated o push_to_hub está activado; WANDB_* solo cuando WandB está activado.

No proceder al Paso 4 en un fallo duro — el docker build del Paso 4 extrae una base NGC de 20+ GB, y un nvidia-container-toolkit faltante solo aparece más tarde como could not select device driver "" with capabilities: [[gpu]]. Registrar gpu_count, gpu_name, driver_major, vram_gb_per_gpu en config.yaml.

2b. Elegir imagen NGC (en vivo): desde la matriz de soporte de NVIDIA Deep Learning Frameworks (https://docs.nvidia.com/deeplearning/frameworks/support-matrix/index.html), sección de contenedor PyTorch NGC, elegir la imagen de mayor versión donde Min driver ≤ detected driver_major y CUDA del contenedor ≤ CUDA Toolkit del host (coincidir estrechamente para que cuDNN / TensorRT se alineen). No rechazar una imagen por una etiqueta PyTorch aN/bN/rcN — NGC valida la imagen completa; elegir la más nueva alineada con CUDA y dejar que compat-workarounds.md maneje problemas por versión. Si la matriz es inaccesible, usar los respaldos en references/hardware-container.md; predeterminado nvcr.io/nvidia/pytorch:24.09-py3 (driver ≥ 545; bug SDPA+GQA — si num_key_value_heads , establecerattn_implementation: "eager").Registrarngc_imageenconfig.yaml.

2c. Re-evaluar reglas de compatibilidad dependientes del hardware: volver a ejecutar el recorrido de compat-workarounds.md para entradas cuyo detect necesita hw; actualizar applicable_workarounds: en el lugar.

2d. Comprobación de ajuste del modelo: estimar param_bytes ≈ 2×param_count (bf16); si

60% de vram_gb_per_gpu × 1e9, recomendar LoRA en el resumen visible para el usuario.

Umbral: config.yaml tiene ngc_image, gpu_count, gpu_name, driver_major, vram_gb_per_gpu; correcciones de compatibilidad dependientes del hardware registradas.

Paso 3 — Investigar la receta

Objetivo: obtener la receta en vivo — el conocimiento de transformers/trl/peft sobre datos de entrenamiento es sospechoso, por lo que el Paso 3 es no negociable. Recorrer references/research-priorities.md en orden de prioridad (Prioridad 1 → 6); detenerse una vez que tengas, para la tarea detectada:

• Clase AutoModel / procesador
• Transformaciones de entrenamiento + evaluación
• Collator
• compute_metrics
• Pistas de hiperparámetros (LR, tamaño de lote, épocas, programador)

Registrar hallazgos en meta/recipe.md, añadir URLs de origen a config.yaml: research_sources:. Un espacio sin hallazgo en vivo recurre al andamiaje coincidente (cv-scripts.md / vlm-scripts.md), registrado como "respaldo a andamiaje — sin fuente en vivo para " bajo notes:. Las reglas de resolución de conflictos están en references/research-priorities.md.

Umbral: cada espacio requerido rellenado, con una URL de origen o nota de respaldo de andamiaje.

Paso 4 — Generar proyecto y prueba de humo

Objetivo: escribir todos los scripts, construir la imagen, preparar datos, ejecutar una prueba de humo de 1 paso en datos reales (un docker build, dos docker runs).

4a. Generar archivos del proyecto en output_dir/: config.yaml, Dockerfile, requirements.txt, prepare_data.py, train.py, run_eval.py, infer.py, opcional merge_lora.py, opcional tests/, .gitignore. La investigación en vivo del Paso 3 es la autoridad; cv-scripts.md / vlm-scripts.md dan solo la forma del andamiaje. Aplicar cada entrada de applicable_workarounds como bloque Dockerfile, pin de requisito, anulación de config o variable de entorno de tiempo de ejecución. Reglas duras: run_eval.py mantiene ese nombre de archivo exacto (evita colisionar con el paquete HF evaluate); cada .py generado comienza con la cabecera de copyright Apache-2.0 de NVIDIA y cualquier emisor falla cuando falta; emit_unit_tests: true genera y ejecuta pruebas según references/testing.md. Cuerpos de scripts, forma del Dockerfile y el contrato del emisor están en references/workflow-generate-train.md.

4b. Construir, preparar, prueba de humo — docker build -t run-<short>:latest .</short>, luego prepare_data y la ejecución --smoke --max_steps 1 (references/docker-runs.md§1-3). Criterios de paso de prueba de humo (en logs/smoke.log):

• Sin excepción
• La pérdida es finita (no 0.0, no NaN)
• grad_norm > 0 en el paso 1

Si emit_unit_tests: true, ejecutar también pytest tests/ en el contenedor. Cualquier fallo → DETENERSE.

4c. Resumen de verificación previa — antes del entrenamiento completo, imprimir y verificar: URL de referencia, columnas del dataset, destino del Hub, destino de monitoreo, imagen NGC, hardware, pérdida/norma de grad de prueba de humo.

Umbral: archivos del proyecto escritos, imagen construida, prueba de humo APROBADA, verificación previa sin campos en blanco.

Paso 5 — Entrenar, evaluar, inferir

Objetivo: evaluación de línea base, entrenamiento completo, evaluación post-entrenamiento, fusión opcional de LoRA, 5 muestras de inferencia (todos los comandos: references/docker-runs.md §4-8).

Multi-GPU: prepend torchrun --nproc_per_node=$gpu_count a python train.py.

Mientras el entrenamiento transmite, observar docker logs -f hft_train: la pérdida debería caer dentro de 10-20 pasos; pérdida plana (bug de collator/máscara de etiquetas), NaN (LR demasiado alto) y OOM detienen la ejecución — recuperación en references/core-rules.md. Si emit_report: true, ejecutar report.py después del Paso 5e según references/reporting.md.

Umbral: todo de:

• checkpoints/final/ (o checkpoints/merged/ para LoRA) existe
• reports/eval_results.json tiene una métrica primaria numérica
• reports/baseline_results.json existe (a menos que se omita)
• reports/inference_samples/ tiene 5 muestras
• URL de wandb muestra pérdida descendente

Paso 6 — Empujar y emitir habilidad de re-ejecución

Objetivo: publicar la ejecución y hacerla reproducible sin volver a investigar.

Empujar según references/hub-push.md (pesos, tarjeta del modelo, JSONs de evaluación/linea base, config.yaml, Dockerfile, requirements.txt, muestras de inferencia, informes cuando se emiten) a menos que push_to_hub: false sea explícito. Emitir <output_dir>/skills/run-<short>/SKILL.md</short></output_dir> desde references/pipeline-skill-template.md — sustituir cada marcador de posición, incluir metadatos YAML completos + comentario HTML de copyright de NVIDIA, y hacer que cualquier emisor falle si faltan estos.

Umbral (Criterios de finalización): todo de:

• Umbral del Paso 5 cumplido
• Repositorio del Hub HF existe en la URL resuelta con pesos + tarjeta + results/ (a menos que push_to_hub: false)
• <output_dir>/skills/run-<short>/SKILL.md</short></output_dir> existe, sin <placeholder></placeholder> restante, con metadatos + comentario HTML de copyright según pipeline-skill-template.md

Mensaje final: URL de wandb, URL del Hub HF, métrica primaria de línea base -> ajuste fino, reports/inference_samples/, y la ruta de la habilidad de re-ejecución.

Juego de errores

En un error de tiempo de ejecución conocido, consultar la tabla síntoma → corrección mínima en references/error-playbook.md (entrypoint NGC, regresiones de PyTorch/Transformers, ABI de numpy, bbox de Albumentations, PEFT/checkpointing, amplitud de destino LoRA, brechas de augmentación CV, OOM en el paso 0) antes de rediseñar cualquier cosa. Cuando una fila se dispara dos veces a través de ejecuciones, elevarla a compat-workarounds.md con una regla detect — aplicada automáticamente en el Paso 1 antes de que el error pueda dispararse.

Estilo de comunicación

• Conciso. Sin relleno, sin repetir la solicitud; respuestas de una palabra cuando sea apropiado.
• Incluir siempre URLs directas del Hub y wandb al referenciar artefactos.
• En error: declarar qué salió mal, por qué, qué cambiaste — sin menús.
• Nunca presentar "Opción A/B/C" para una solicitud con una respuesta clara. Actuar.

Ejemplos de pipelines

• tao-rerun-convnext-cifar10
• tao-rerun-detr-cppe5
• tao-rerun-segformer-foodseg103
• tao-rerun-smolvlm-vqav2