optimize-handoff

Transferencia de Optimización (kernel-optimize)

Cuando el objetivo es llevar un kernel al límite del hardware (no solo comprobar rendimiento puntual), este archivo es la interfaz entre Primus-Turbo y el bucle de optimización autónomo en ../../kernel-optimize/SKILL.md. Proporciona la información previa que ese bucle necesita. Lea primero el hub ../SKILL.md.

Proceso

1. Verificar el entorno — pip show primus_turbo; reinstalar en modo editable si no está (hub SKILL.md → Build).
2. Leer kernel-optimize/SKILL.md "Información Previa" para conocer lo que necesita el bucle.
3. Recopilar los requisitos previos para la operación objetivo (tablas a continuación + el mapa de código / comandos del hub SKILL.md).
4. Transferir a kernel-optimize/SKILL.md; ejecuta DEFINE_TARGET → PREPARE_ENVIRONMENT → BASELINE → (ANALYZE → OPTIMIZE → VALIDATE)* → REPORT.
5. Aceptación — de vuelta en el proyecto: ejecutar la suite completa pytest tests/pytorch/ -v, revisar el informe, confirmar un diff/commit limpio.

Antes de que comience el bucle, lea ../../../rules/iteration_rules.mdc: una hipótesis por ronda, puerta de corrección antes del rendimiento, linaje aceptar/revertir, y cada ganancia aceptada debe transferirse a un paso de entrenamiento real (sin cachés de activación/grad_out con clave id(...), sin atajos de GroupGemm solo con distribución uniforme).

Información previa (por operación)

Requisito	Dónde obtenerlo
Ruta del archivo fuente del kernel	hub SKILL.md → Mapa de Código
Comando de prueba enfocado	hub SKILL.md → Test & Bench; ej. pytest tests/pytorch/ops/test_gemm_fp8.py -v -k "blockwise and TRITON"
Comando de benchmark enfocado	../verify-performance/SKILL.md; ej. PRIMUS_TURBO_GEMM_BACKEND=TRITON python benchmark/ops/training/bench_gemm_turbo.py --dtype fp8 --granularity blockwise
Formato de salida / métricas del benchmark	../verify-performance/SKILL.md (Forward/Backward TFLOPS, puerta Check)
Harness de validación rápida	"Validación rápida" más abajo
Reglas de puntuación	"Puntuación de optimización" más abajo
execution_mode + reconstrucción	"Entorno de optimización" más abajo

Entorno de optimización

Backend / lenguaje	execution_mode recomendado	Reconstruir después del cambio
Triton (Python)	repo-mode	ninguna (instalación editable)
HIP / CK (C++), cambios pequeños/param	repo-mode	GPU_ARCHS=<arch> pip install --no-build-isolation -e . -v
HIP / CK (C++), nuevo kernel / prueba y error intensivo	workspace-mode	según la pila mínima en kernel-optimize/SKILL.md

Puntuación de optimización

La columna Check es una puerta infranqueable — cualquier forma que devuelva FAIL/ERROR rechaza al candidato.

Tipo de campaña	primary_metric (agregación = media geométrica en formas PASS)
Limitado por cómputo, solo forward	Forward TFLOPS
Limitado por cómputo, forward + backward (entrenamiento)	Combined Step TFLOPS (forward/backward se mantienen como diagnóstico)
Limitado por memoria (elementwise, quant)	Forward GB/s / Backward GB/s

La derivación de paso combinado (preferida para operaciones tipo GEMM con fwd+bwd) está en ../verify-performance/SKILL.md. Confirme primary_metric con el usuario en DEFINE_TARGET.

Validación rápida

Dos herramientas, roles separados — no compare números absolutos entre ellas (usan motores de temporización diferentes):

• quick_test_bench.py (esta carpeta, copiada al directorio de la campaña) es la fuente autorizada para la puerta de regresión por forma ronda a ronda. BASELINE (ronda 1) y cada ronda VALIDATE ejecutan ESTE script y comparan su salida --summary-csv. Usa un bucle time.perf_counter artesanal.
• el bench_<op>_turbo.py completo (ver ../verify-performance/SKILL.md, torch.utils.benchmark.Timer) se usa solo para (i) elegir representative_shapes del conjunto completo de formas y (ii) hacer la aceptación final después de la campaña.

Ambos niveles de validación se ejecutan mediante quick_test_bench.py, diferenciándose solo en SHAPES:

• validación completa (BASELINE + aceptación final) → SHAPES = todas las target_shapes.
• validación rápida (cada ronda VALIDATE) → SHAPES = el subconjunto de 3–5 representative_shapes.

representative_shapes: solo formas Check=PASS de la ejecución BASELINE, cubriendo escalas pequeñas (overhead de lanzamiento) + grandes (cómputo/memoria), prefiriendo formas de alta varianza. Regístrelas en manifest.yaml: representative_shapes.

Harness: la plantilla quick_test_bench.py es la referencia canónica. Durante PREPARE_ENVIRONMENT, cópiela en <campaign_dir>/quick_test_bench.py con SHAPES vacío y <target_backend> configurado; llene SHAPES con todas las target_shapes para BASELINE, luego reduzca a representative_shapes para las rondas VALIDATE. Adapte la operación/config para su objetivo; mantenga el escritor --summary-csv y el esquema de columnas (vea la nota de alcance del esquema a continuación para operaciones no GEMM).

Contrato de consistencia de medición: BASELINE (ronda 1) y cada VALIDATE leen el mismo CSV autoritativo mediante --summary-csv, analizado idénticamente entre rondas por el mismo lector de CSV — el helper MCP opcional mcp__turbo__parse_bench_csv si está configurado, de lo contrario un csv.DictReader directo con clave en las columnas a continuación. El lector específico no importa; congelar el esquema sí. El esquema DEBE coincidir con estas columnas textualmente (cualquier desviación desactiva silenciosamente la puerta de regresión por forma):

label,B,M,N,K,Check,Forward TFLOPS,Forward TFLOPS_stddev,Backward TFLOPS,Backward TFLOPS_stddev,Forward Time (ms),Backward Time (ms),out_snr,da_snr,db_snr

Check usa PASS / FAIL; *_stddev son desviaciones estándar absolutas en la unidad de la métrica. Registre la invocación en manifest.yaml como quick_command: "python <campaign_dir>/quick_test_bench.py"; BASELINE y cada VALIDATE añadan --summary-csv <round_dir>/artifacts/benchmark.csv.

Alcance del esquema: las columnas anteriores son específicas para operaciones tipo GEMM (dimensiones M,N,K, Forward/Backward TFLOPS, out_snr/da_snr/db_snr). Para una operación no GEMM, mantenga label, Check y la convención *_stddev, pero reemplace las columnas solo GEMM con las que su primary_metric necesite — por ejemplo, una operación limitada por memoria (según "Puntuación de optimización") usa Forward GB/s / Backward GB/s en lugar de TFLOPS, y una operación de una sola salida reemplaza out_snr/da_snr/db_snr con su propia métrica de corrección. Sea cual sea el esquema que elija, congélelo en BASELINE, manténgalo idéntico byte a byte en todas las rondas, y actualice el lector CSV que use (el mapeo mcp__turbo__parse_bench_csv si está configurado, o su csv.DictReader directo) para que coincida — la puerta de regresión por forma se basa en nombres de columna exactos.