otimiza-handoff

Handoff de Otimização (kernel-optimize)

Quando o objetivo é levar um kernel ao limite do hardware (não apenas verificar desempenho superficialmente), este arquivo é a interface entre o Primus-Turbo e o loop de otimização autônomo em ../../kernel-optimize/SKILL.md. Ele fornece as informações pré-requisito que esse loop necessita. Leia o hub ../SKILL.md primeiro.

Processo

1. Verifique o ambiente — pip show primus_turbo; reinstale como editável se não estiver (hub SKILL.md → Build).
2. Leia kernel-optimize/SKILL.md "Informações Pré-requisito" para saber o que o loop precisa.
3. Colete os pré-requisitos para a operação alvo (tabelas abaixo + o mapa de código/comandos no hub SKILL.md).
4. Passe o controle para kernel-optimize/SKILL.md; ele executa DEFINE_TARGET → PREPARE_ENVIRONMENT → BASELINE → (ANALYZE → OPTIMIZE → VALIDATE)* → REPORT.
5. Aceitação — de volta ao projeto: execute a suíte completa pytest tests/pytorch/ -v, revise o relatório, confirme um diff/commit limpo.

Antes do loop iniciar, leia ../../../rules/iteration_rules.mdc: uma hipótese por rodada, verificação de corretude antes de desempenho, linhagem de aceitação/rollback, e todo ganho aceito deve ser transferido para um passo de treinamento real (sem caches de ativação/saída de gradiente chaveados por id(...), sem atalhos de GroupGemm apenas com distribuição uniforme).

Informações pré-requisito (por operação)

Requisito	Onde obter
Caminho do arquivo fonte do kernel	hub SKILL.md → Code Map
Comando de teste focado	hub SKILL.md → Test & Bench; ex: pytest tests/pytorch/ops/test_gemm_fp8.py -v -k "blockwise and TRITON"
Comando de benchmark focado	../verify-performance/SKILL.md; ex: PRIMUS_TURBO_GEMM_BACKEND=TRITON python benchmark/ops/training/bench_gemm_turbo.py --dtype fp8 --granularity blockwise
Formato de saída / métricas do benchmark	../verify-performance/SKILL.md (Forward/Backward TFLOPS, porta Check)
Harness de validação rápida	"Validação rápida" abaixo
Regras de pontuação	"Pontuação de otimização" abaixo
execution_mode + reconstrução	"Ambiente de otimização" abaixo

Ambiente de otimização

Backend / linguagem	execution_mode recomendado	Reconstruir após alteração
Triton (Python)	repo-mode	nenhum (instalação editável)
HIP / CK (C++), alterações pequenas/param	repo-mode	GPU_ARCHS=<arch> pip install --no-build-isolation -e . -v
HIP / CK (C++), novo kernel / pesada tentativa-e-erro	workspace-mode	conforme a pilha mínima em kernel-optimize/SKILL.md

Pontuação de otimização

A coluna Check é uma porta rígida — qualquer forma com FAIL/ERROR rejeita o candidato.

Tipo de campanha	primary_metric (agregado = média geométrica entre formas PASS)
Limitado por computação, apenas forward	Forward TFLOPS
Limitado por computação, forward + backward (treinamento)	Combined Step TFLOPS (forward/backward mantidos como diagnósticos)
Limitado por memória (elementwise, quant)	Forward GB/s / Backward GB/s

A derivação de passo combinado (preferida para operações do tipo GEMM com fwd+bwd) está em ../verify-performance/SKILL.md. Confirme primary_metric com o usuário no DEFINE_TARGET.

Validação rápida

Duas ferramentas, papéis separados — não compare números absolutos entre elas (usam engines de temporização diferentes):

• quick_test_bench.py (esta pasta, copiado para o diretório da campanha) é a fonte autoritativa para a verificação de regressão por forma rodada a rodada. BASELINE (rodada 1) e toda rodada VALIDATE executam ESTE script e comparam sua saída --summary-csv. Ele usa um loop manual time.perf_counter.
• o bench_<op>_turbo.py completo (veja ../verify-performance/SKILL.md, torch.utils.benchmark.Timer) é usado apenas para (i) selecionar representative_shapes do conjunto completo de formas e (ii) fazer a aceitação final após a campanha.

Ambos os níveis de validação rodam via quick_test_bench.py, diferindo apenas em SHAPES:

• validação completa (BASELINE + aceitação final) → SHAPES = todas target_shapes.
• validação rápida (cada rodada VALIDATE) → SHAPES = subconjunto de 3–5 representative_shapes.

representative_shapes: apenas formas com Check=PASS da execução BASELINE, cobrindo escalas pequenas (overhead de lançamento) + grandes (computação/memória), preferindo formas de alta variância. Registre-as em manifest.yaml: representative_shapes.

Harness: o template quick_test_bench.py é a referência canônica. Durante PREPARE_ENVIRONMENT, copie-o para <campaign_dir>/quick_test_bench.py com SHAPES vazio e <target_backend> definido; preencha SHAPES com todas as target_shapes para BASELINE, depois reduza para representative_shapes para as rodadas VALIDATE. Adapte a operação/configuração para seu alvo; mantenha o escritor --summary-csv e o esquema de colunas (veja a nota de escopo do esquema abaixo para operações não-GEMM).

Contrato de consistência de medição: BASELINE (rodada 1) e cada VALIDATE leem o mesmo CSV autoritativo via --summary-csv, analisado de forma idêntica entre rodadas pelo mesmo leitor de CSV — o helper MCP opcional mcp__turbo__parse_bench_csv se estiver configurado, caso contrário um csv.DictReader direto chaveado nas colunas abaixo. O leitor específico não importa; congelar o esquema sim. O esquema DEVE corresponder a estas colunas textualmente (qualquer desvio desativa silenciosamente a porta de regressão 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 são desvios padrão absolutos na unidade da métrica. Registre a invocação em manifest.yaml como quick_command: "python <campaign_dir>/quick_test_bench.py"; BASELINE e cada VALIDATE acrescentam --summary-csv <round_dir>/artifacts/benchmark.csv.

Escopo do esquema: as colunas acima são específicas para classe GEMM (dimensões M,N,K, Forward/Backward TFLOPS, out_snr/da_snr/db_snr). Para uma operação não-GEMM, mantenha label, Check e a convenção *_stddev, mas substitua as colunas exclusivas de GEMM pelas que sua primary_metric necessitar — por exemplo, uma operação limitada por memória (conforme "Pontuação de otimização") usa Forward GB/s / Backward GB/s em vez de TFLOPS, e uma operação de saída única substitui out_snr/da_snr/db_snr por sua própria métrica de corretude. Seja qual for o esquema escolhido, congele-o no BASELINE, mantenha-o idêntico byte a byte em todas as rodadas, e atualize o leitor CSV que você usa (o mapeamento mcp__turbo__parse_bench_csv se configurado, senão seu csv.DictReader direto) para corresponder — a porta de regressão por forma chaveia em nomes de colunas exatos.