From 9257d3bfb2392f570fa6866780ae332c33ebd374 Mon Sep 17 00:00:00 2001 From: Chad Voegele Date: Wed, 8 Jul 2026 13:48:59 -0500 Subject: [PATCH 1/2] fix(skills): address day-0 June 5 trial findings Signed-off-by: Chad Voegele --- .agents/skills/compare-results/SKILL.md | 30 ++++++++++-- .agents/skills/day0-release/SKILL.md | 45 ++++++++++------- .agents/skills/evaluation/SKILL.md | 2 +- .../evaluation/recipes/tasks/aa/scicode.md | 9 ++-- .../evaluation/references/run-validation.md | 49 +++++++++++++++++++ .agents/skills/ptq/SKILL.md | 40 ++++++++++++--- .../ptq/references/checkpoint-validation.md | 10 +++- .agents/skills/quant-recipe-search/SKILL.md | 26 ++++++++-- .../references/recipe_iteration.md | 29 +++++++++++ 9 files changed, 200 insertions(+), 40 deletions(-) diff --git a/.agents/skills/compare-results/SKILL.md b/.agents/skills/compare-results/SKILL.md index dd908d4910c..d6fee539e78 100644 --- a/.agents/skills/compare-results/SKILL.md +++ b/.agents/skills/compare-results/SKILL.md @@ -32,11 +32,19 @@ change is being measured, typically a further quantized version of the baseline. 5. For each task, use the canonical score field from the matching `.agents/skills/evaluation/recipes/tasks/.md` Score Extraction section. -6. Compute exact deltas outside the chat context when there are multiple tasks +6. Read and perform `.agents/skills/evaluation/references/run-validation.md` + **External Baseline Sanity Check**. Record each source URL, protocol + difference, and task status before applying the candidate-delta gate. A + failed baseline blocks a success verdict; correct and rerun it first. If no + credible comparable reference exists, label the baseline externally + unverified rather than claiming the check passed, then continue using the + validated measured baseline. +7. Compute exact deltas outside the chat context when there are multiple tasks or repeated runs. -7. Report comparability and quantized-feasibility verdicts before interpreting - the delta as model quality. If the user did not provide an acceptance - threshold, report feasibility as inconclusive instead of inventing one. +8. Report comparability, external baseline sanity, and quantized-feasibility + verdicts before interpreting the delta as model quality. If the user did not + provide an acceptance threshold, report feasibility as inconclusive instead + of inventing one. ## Comparability Checklist @@ -64,9 +72,17 @@ the validated runs are comparable: precision the baseline is**, and apply the gate relative to that baseline rather than to an assumed BF16. +For SciCode, keep `num_repeats: 1` to limit sandbox workload. If variance is a +concern, run multiple independent matched baseline/candidate pairs instead of +increasing repeats within one run. + If any item differs, either rerun with matched settings or label the result as not an apples-to-apples quantization comparison. +These checks compare the baseline and candidate to each other. The external +baseline check in `evaluation/references/run-validation.md` separately tests +whether the baseline's absolute score is credible; both guards must be reported. + ## Report Format Include: @@ -74,7 +90,13 @@ Include: - Baseline and candidate identifiers. - Per-task metric path, baseline score, candidate score, delta, and stderr if available. +- Per-task external reference score, source URL, known protocol differences, + percentage-point difference, and sanity status (`verified`, `failed`, or + `externally unverified`). - Comparability status for prompt/template, generation settings, sample counts, reasoning handling, judge/simulator setup, and score field. - Comparability verdict: comparable, not comparable, or inconclusive. - Quantization feasibility verdict: acceptable, not acceptable, or inconclusive. + Never report `acceptable` when external baseline sanity failed. An externally + unverified baseline does not block `acceptable`; apply the candidate-delta + gate and report the missing external corroboration. diff --git a/.agents/skills/day0-release/SKILL.md b/.agents/skills/day0-release/SKILL.md index 5fb2e2714db..0fc3c67cef4 100644 --- a/.agents/skills/day0-release/SKILL.md +++ b/.agents/skills/day0-release/SKILL.md @@ -52,9 +52,9 @@ progress: - [ ] Step 0: Resolve inputs; confirm threshold and eval set - [ ] Step 1: Setup gate — creds present, cluster reachable - [ ] Step 2: PTQ (ptq skill) → gate_ptq.py -- [ ] Step 3: Baseline eval (evaluation skill, deploys source) → gate_run.py [skip if cached, see below] +- [ ] Step 3: Baseline eval (evaluation skill, deploys source) → gate_run.py - [ ] Step 4: Quantized eval (evaluation skill, deploys candidate) → gate_run.py -- [ ] Step 5: Compare (compare-results skill) → gate_compare.py → decision +- [ ] Step 5: Compare (compare-results skill) → external sanity → gate_compare.py → decision - [ ] Step 6: Closeout — report + publish recommendation ``` @@ -83,10 +83,8 @@ unvalidated checkpoint. ### Step 3 — Baseline eval The baseline is the **source** (pre-quantization) model on the same task set and -sampling params. **Look it up first** — if a matching baseline run already -exists in MLflow (same model, task set, sampling params), reuse it and skip this -stage. Otherwise run it via the **evaluation** skill (which deploys the source -model itself). Gate with `gate_run.py`. +sampling params. Always run a fresh baseline via the **evaluation** skill, +which deploys the source model itself. Gate with `gate_run.py`. ### Step 4 — Quantized eval @@ -110,7 +108,14 @@ dropped samples) — do **not** compare scores from it. ### Step 5 — Compare -Invoke the **compare-results** skill to produce per-task deltas, then gate: +Invoke the **compare-results** skill. It must perform the shared external +baseline sanity check before the candidate-delta gate. A failed check is +`ANOMALOUS` with failure class `EXTERNAL_BASELINE_MISMATCH`: investigate and +rerun the baseline. If no credible comparable external score exists, record the +baseline as externally unverified and continue using the validated measured +baseline. + +After recording the external status, produce per-task deltas and run: ```bash python .agents/skills/day0-release/scripts/gate_compare.py \ @@ -125,22 +130,25 @@ normalizes the drop accordingly, so `--threshold 0.01` means "≤1 pt on a 0-100 task / ≤0.01 on a 0-1 task" uniformly. Pass `--scales '{"task": max}'` to override inference if a task's scores happen to fall in an ambiguous range. -Decision from `gate_compare.py`: +`gate_compare.py` checks only the candidate delta; it cannot override a failed +external baseline check. Combined decision: -- **ACCEPT** — every task within threshold → go to Step 6. +- **ACCEPT** — no external check failed and every task is within the candidate + threshold → go to Step 6. A missing comparable external score is not a + failure; report it as externally unverified. - **REGRESSION** — one or more tasks exceed threshold. **v1 stops here and reports** which tasks regressed by how much. (Picking the next recipe and re-running is deferred — see Scope.) -- **ANOMALOUS** — scores present but implausible (e.g. baseline lower than - candidate by a large margin, or a task score outside its valid range) → - surface to the user. +- **ANOMALOUS** — external baseline sanity failed, or scores are otherwise + implausible (e.g. baseline lower than candidate by a large margin, or a task + score is outside its valid range) → correct the baseline or surface it. ### Step 6 — Closeout Report the decision with: source vs output size + ratio, per-task baseline / -candidate / delta / within-threshold, MLflow run IDs, and a publish -recommendation (publish / do-not-publish / needs-human). Archive artifacts to -the workspace. +candidate / delta / within-threshold, external source and sanity status, MLflow +run IDs, and a publish recommendation (publish / do-not-publish). +Archive artifacts to the workspace. ## Triage (gate failure → decision) @@ -154,8 +162,9 @@ Map a gate's `failure_class` to the next action: | `DEPLOYMENT_HEALTH_FAILED` | Drop to the **deployment** skill: reproduce serving standalone (`/health` + one generation), debug flags / image / TP / env, then carry the working command into NEL's `deployment.command` and retry the eval. If it can't serve, `POINT_INFEASIBLE`. | | `EVAL_JUDGE_FAILED` | Usually transient (auth / rate limit) — wait and retry. | | `SAMPLE_ACCOUNTING_FAILED` | Investigate dropped/failed samples before trusting scores. | -| `USER_CONFIG_ERROR` | Stop and ask the user. | -| `UNKNOWN` | Stop and surface to the user (`NEEDS_HUMAN`). | +| `EXTERNAL_BASELINE_MISMATCH` | Investigate baseline configuration, correct it, rerun the baseline, and repeat external sanity before comparison. | +| `USER_CONFIG_ERROR` | Correct it from the request, workspace, or model/config metadata and retry; if irrecoverable, return `ANOMALOUS` with evidence. | +| `UNKNOWN` | Investigate with the owning domain skill; if unresolved, return `ANOMALOUS` with the evidence and next automated retry or patch action. | `SYSTEMIC` (cluster down, dataset unavailable) aborts the whole run. `POINT_INFEASIBLE` means this (model, recipe) can't work as configured. @@ -166,7 +175,7 @@ Return a decision, not a raw artifact: - `ACCEPT` + report + publish recommendation - `REGRESSION` + which tasks failed the threshold and by how much -- `ANOMALOUS` / `INFEASIBLE` / `NEEDS_HUMAN` + reason +- `ANOMALOUS` / `INFEASIBLE` + reason and next automated action - Always: workspace path + MLflow run IDs for traceability ## Scope (v1) diff --git a/.agents/skills/evaluation/SKILL.md b/.agents/skills/evaluation/SKILL.md index c84df3882a7..6776315949d 100644 --- a/.agents/skills/evaluation/SKILL.md +++ b/.agents/skills/evaluation/SKILL.md @@ -409,7 +409,7 @@ Remove `limit_samples` overrides; keep canary-validated parallelism. If the cana ### Step 9 — Verify completed run -Before pulling/reporting scores, validate the run. Read `references/run-validation.md` for NEL timeout/resume behavior, completed-run validation, diagnostics, score harvesting, and the handoff to `compare-results` for baseline-vs-candidate deltas. +Before pulling/reporting scores, validate the run. Read `references/run-validation.md` for NEL timeout/resume behavior, completed-run validation, diagnostics, and score harvesting. For a baseline that will be compared with a candidate, also perform its **External Baseline Sanity Check** before a success verdict, then hand the validated runs to `compare-results` for baseline-vs-candidate deltas. --- diff --git a/.agents/skills/evaluation/recipes/tasks/aa/scicode.md b/.agents/skills/evaluation/recipes/tasks/aa/scicode.md index f961e592234..09b797589b6 100644 --- a/.agents/skills/evaluation/recipes/tasks/aa/scicode.md +++ b/.agents/skills/evaluation/recipes/tasks/aa/scicode.md @@ -17,6 +17,8 @@ harvesting requirements beyond the task YAML fragment. multi-step prompts can exceed 32K). The example template's default of `--max-model-len 131072` satisfies this and is preferred — do not lower it unless you have a memory reason to. +- **Parallelism:** set task-level `parallelism: 8` exactly. Use the same value + for baseline and candidate. ## YAML Fragment @@ -28,13 +30,12 @@ Use this inside the top-level `evaluation.tasks` list: nemo_evaluator_config: config: params: + parallelism: 8 extra: args: ++prompt_config=eval/scicode/default ++with_background=true - num_repeats: 8 + num_repeats: 1 ``` ## Score Extraction from mlflow -Result (0-100): `scicode_pass_at_1_avg-of-N_subtask_accuracy` - -N is the repeat count. If the repeat count is unknown, use the highest available `avg-of-N`. +Result (0-100): `scicode_pass_at_1_avg-of-1_subtask_accuracy` diff --git a/.agents/skills/evaluation/references/run-validation.md b/.agents/skills/evaluation/references/run-validation.md index 6669c607a6b..43dbd8116a5 100644 --- a/.agents/skills/evaluation/references/run-validation.md +++ b/.agents/skills/evaluation/references/run-validation.md @@ -35,6 +35,55 @@ accounting, reasoning/answer parsing status, and any errors or warnings found. If any validation item fails, either rerun/fix it or label the result as incomplete or invalid. +## External Baseline Sanity Check + +For a baseline-vs-candidate comparison, perform this check after run validation +and before applying the candidate-delta gate or issuing a success verdict. This +is additional to, not a replacement for, the apples-to-apples and baseline +precision checks in `compare-results`. + +For each baseline task: + +1. Search for a published score for the exact model in its Hugging Face model + card and on Artificial Analysis (); use + either credible source. A score for a sibling size, release, or precision is + not an exact-model reference. +2. Match model variant, benchmark and version, metric, reasoning/thinking mode, + prompt and chat template, sampling and token budget, sample count, and + evaluation protocol as closely as possible. Record the external score, + source URL, and every known protocol difference. Do not treat a mismatched + result as directly comparable; find a closer source or mark the task + externally unverified. +3. Put both scores on a 0-100 scale, then calculate, for higher-is-better + metrics: + + ```text + difference (pp) = abs(measured baseline - external) + ``` + + Treat a credible comparable result as verified only when the absolute + difference is approximately 5 percentage points or less. A difference + greater than approximately 5 points fails the check even if the candidate is + within its normal delta gate (for example, `<1pp`). For an external score of + 60, the approximate range is 55-65; a baseline of 54 is 6 points away and + fails. + +Report each task as `verified`, `failed`, or `externally unverified`. A large +upward difference also does not establish a clean match; investigate protocol +differences before marking it verified. If no credible comparable score exists, +state `externally unverified` and do not invent a reference or claim the sanity +check passed. This status does not block comparison or publication: use the +validated measured baseline, apply the candidate-delta gate, and report that no +external corroboration was available. Only a `failed` external check blocks the +comparison. + +If any task fails, do not report the quantized evaluation as successful and do +not apply the candidate-delta gate to that baseline. Investigate disabled +reasoning/thinking, reasoning parser or adapter handling, prompt/chat-template +differences, sampling or token-budget differences, benchmark version or metric, +incomplete samples, and serving failures. Rerun a corrected baseline, validate +it, and repeat this check before comparing the candidate. + For score harvesting, use the `Score Extraction` section from the matching task reference in `recipes/tasks/.md`. Do not rely on ad hoc `results.yml` greps when a task reference defines the canonical score and stderr fields. diff --git a/.agents/skills/ptq/SKILL.md b/.agents/skills/ptq/SKILL.md index fd66f947900..000d0f3c30b 100644 --- a/.agents/skills/ptq/SKILL.md +++ b/.agents/skills/ptq/SKILL.md @@ -1,12 +1,21 @@ --- name: ptq -description: This skill should be used when the user asks to "quantize a model", "run PTQ", "post-training quantization", "NVFP4 quantization", "FP8 quantization", "INT8 quantization", "INT4 AWQ", "quantize LLM", "quantize MoE", "quantize VLM", or needs to produce a quantized HuggingFace or TensorRT-LLM checkpoint from a pretrained model using ModelOpt. +description: >- + Use when the user asks to "quantize a model", "run PTQ", "post-training + quantization", "NVFP4 quantization", "FP8 quantization", "INT8 + quantization", "INT4 AWQ", "quantize LLM", "quantize MoE", "quantize VLM", + or needs to produce a quantized HuggingFace or TensorRT-LLM checkpoint from a + pretrained model using ModelOpt. Do NOT use for multi-candidate recipe + exploration or optimization (use quant-recipe-search). --- # ModelOpt Post-Training Quantization Produce a quantized checkpoint from a pretrained model. **Read `examples/hf_ptq/README.md` first** — it has the support matrix, CLI flags, and accuracy guidance. +Use `quant-recipe-search` for multi-candidate recipe exploration or +optimization. Use this skill for each selected recipe's PTQ run. + ## Step 1 — Environment Read `skills/common/environment-setup.md` and `skills/common/workspace-management.md`. After completing them you should know: @@ -75,6 +84,24 @@ If the source checkpoint is already quantized and the requested recipe/config re For **listed models** (4A/4B): run full calibration directly (`--calib_size 512`). For **unlisted models** (4C): run a smoke test first (`--calib_size 4`), wait for success, then full calibration. +### Recommended calibration datasets + +- **Text-only LLM PTQ:** Prefer the representative `nemotron-post-training-v3` blend. `modelopt/torch/utils/dataset_utils.py` expands it to seven registered Nemotron SFT domains. Configure Hugging Face credentials where required. + + ```bash + python examples/hf_ptq/hf_ptq.py ... \ + --dataset nemotron-post-training-v3 + ``` + +- **VLM PTQ:** Include image-text calibration with `--calib_with_images`. This path uses `nemotron_vlm_dataset_v2` with the current default subsets `sparsetables`, `plotqa_cot`, and `wiki_en`; `examples/hf_ptq/hf_ptq.py` and `modelopt/torch/utils/vlm_dataset_utils.py` are the source of truth. + + ```bash + python examples/hf_ptq/hf_ptq.py ... \ + --calib_with_images + ``` + +`--dataset` selects text-only calibration and cannot substitute for multimodal examples. Use `--dataset cnn_dailymail` only as a fallback when representative data is unavailable, such as without gated-data access or with only a local public cache. + ### Which path? ```text @@ -138,17 +165,16 @@ Report the path and size to the user. ### Post-quantization validation -This is a required gate before any deployment or evaluation submission. Do not submit an eval, start a serving job, or hand off the checkpoint as ready until the gate has passed. +This is a required gate before any deployment or evaluation submission. Do not submit an eval, start a production serving job, or hand off the checkpoint as ready until the gate, including its serving canary, has passed. -Read `references/checkpoint-validation.md` and perform all three validation groups on the exact checkpoint path that will be deployed/evaluated: +Read `references/checkpoint-validation.md` and perform all four validation groups on the exact checkpoint path that will be deployed/evaluated: 1. Check output size and estimated bits per weight against the baseline/source checkpoint. 2. Check quantized-weight coverage against the requested qformat/recipe/config. 3. Check metadata consistency against the baseline/source model. +4. Complete the required downstream handoff and serving-readiness validation. -Report the gate result before moving on. The report must include source size, output size, output/source size ratio, layer precision counts (for example NVFP4, FP8, INT4, BF16/unquantized excluded, unexpected unquantized, declaration mismatches), and metadata diffs. If the output/source ratio is >= 1.0 for a compression recipe, if any intended layer group is missing quantization, or if metadata changed unexpectedly, stop and fix the checkpoint or ask the user before proceeding. - -**Next steps**: If the user wants to deploy or evaluate the quantized checkpoint, use the **deployment** or **evaluation** skill. The checkpoint workspace carries over. If the model required patches during PTQ (e.g., transformers upgrade), the same fixes will likely be needed at deployment and evaluation time. +Report the gate result before moving on. Follow the canonical report format and all blocking conditions in `references/checkpoint-validation.md`; do not hand off a checkpoint unless every required check passes. ## Key API Rules @@ -163,7 +189,7 @@ Report the gate result before moving on. The report must include source size, ou - **Model-specific dependencies**: Models with `trust_remote_code` may import packages not in the container (e.g., `mamba-ssm` for hybrid Mamba models). See Step 2.5. Use `EXTRA_PIP_DEPS` env var with the launcher, or install manually before running `hf_ptq.py` - **Transformers version**: New models may need a newer version of transformers than what's installed. Check `config.json` for `transformers_version`. In containers, beware of `PIP_CONSTRAINT` blocking upgrades — see `references/slurm-setup-ptq.md` for workarounds -- **Gated datasets**: Some calibration datasets require HF authentication. Ensure `HF_TOKEN` is set in the job environment, or use `--dataset cnn_dailymail` as a non-gated alternative +- **Gated datasets**: Some calibration datasets require HF authentication. Set `HF_TOKEN` in the job environment. Use `--dataset cnn_dailymail` only as the constrained-environment fallback described in Step 4, not as the preferred calibration set - **NFS root_squash + Docker**: See `skills/common/slurm-setup.md` section 5 ## References diff --git a/.agents/skills/ptq/references/checkpoint-validation.md b/.agents/skills/ptq/references/checkpoint-validation.md index fd5d7a766d5..27c763a8d89 100644 --- a/.agents/skills/ptq/references/checkpoint-validation.md +++ b/.agents/skills/ptq/references/checkpoint-validation.md @@ -1,12 +1,13 @@ # Post-Quantization Checkpoint Validation -Before treating an exported checkpoint as ready for deployment/evaluation, verify checkpoint size/bits, quantized-weight coverage, and metadata consistency. This is a gate, not a guideline: do not submit evals, start serving jobs, or mark the checkpoint ready until all required checks pass and the validation report is recorded. +Before treating an exported checkpoint as ready for deployment/evaluation, verify checkpoint size/bits, quantized-weight coverage, metadata consistency, and serving readiness. This is a gate, not a guideline: do not submit evals, start a production serving job, or mark the checkpoint ready until all required checks, including the serving canary, pass and the validation report is recorded. ## Required checks 1. The quantized checkpoint is smaller on disk than the baseline/source checkpoint and has lower estimated bits per weight. Record source size, output size, and output/source ratio. A partial-quantization recipe may not shrink every tensor, but it should still match the intended quantization coverage. If the size reduction is small or missing, explain why before proceeding. 2. The weights that were actually quantized match what the requested qformat/recipe/config targeted. Record layer precision counts grouped by actual/declarative precision, such as NVFP4, FP8, INT4, BF16/unquantized excluded, unexpected unquantized, and declaration mismatches. Quantization config patterns may silently miss layers if the model uses non-standard naming — this only surfaces later as deployment failures when the serving framework tries to load unquantized weights as quantized. 3. Metadata that should not change still matches the baseline/source model. Compare generation settings, tokenizer files, chat template, model architecture fields, max positions/context length, and special tokens; quantization should affect weights and quantization metadata, not silently change prompting or generation behavior. Record every diff and classify it as expected or blocking. +4. The checkpoint is ready for downstream deployment and evaluation. Record the exact checkpoint workspace and path that both downstream skills must inherit. Inventory every model-compatibility change made during PTQ that may be required to load or serve the checkpoint: dependency upgrades, source patches, custom code, environment variables, and launcher or container changes. Record each category separately and write `none` for every category with no changes. Then invoke the **deployment** skill and use that same workspace, checkpoint path, and compatibility inventory to serve the checkpoint in the intended deployment environment. Run a canary query such as `What is the capital of France?` and require a valid response (for this example, one that identifies Paris). Record the target environment, serving framework and launch configuration, canary query, and response. Stop the canary service after validation unless the user asked to keep it running. ## Gate report @@ -17,6 +18,9 @@ Before moving to deployment/evaluation, report a table in this shape: | Size vs source | ` GB / GB = x`; PASS only if the ratio matches the recipe's compression intent | | Layer precision counts | ` NVFP4 / FP8 / INT4 / BF16-or-excluded / unexpected / declaration mismatches` | | Metadata | `no unexpected diffs` or list exact diffs | +| Checkpoint workspace/path | `` / ``; these exact locations must be inherited by deployment and evaluation | +| PTQ compatibility requirements | `dependency upgrades: ...; source patches: ...; custom code: ...; environment variables: ...; launcher/container changes: ...`; use `none` for each category with no changes | +| Serving canary | `; ; -> `; PASS only if the deployment skill starts the service from the recorded workspace/path with all recorded compatibility requirements and returns a valid response | Stop instead of proceeding if: @@ -24,6 +28,10 @@ Stop instead of proceeding if: - Any layer group intended to be quantized has zero or unexpectedly low coverage. - Any layer has quantization metadata inconsistent with its declared precision. - Prompting, tokenizer, generation, architecture, context-length, or special-token metadata changed unexpectedly. +- The exact checkpoint workspace or path is missing or is not preserved for deployment and evaluation. +- Any PTQ compatibility category is omitted instead of recording its requirements or `none`. +- The **deployment** skill cannot start the checkpoint in the intended deployment environment from the recorded workspace/path with the recorded compatibility requirements. +- The serving canary does not return a valid response. - **VLM only:** any vision-tower weight (`model.visual.*`/`vision_tower.*`/`vision_model.*`) carries quantization scales (unless quantizing the ViT is intended). Generic `*mlp*`/`*experts*` recipes silently match the ViT MLPs → garbage image embeddings (~0% on MMMU-Pro) while text looks fine; the precision script above counts them as valid NVFP4, so run the VLM check below. ## VLM check — vision tower must stay unquantized diff --git a/.agents/skills/quant-recipe-search/SKILL.md b/.agents/skills/quant-recipe-search/SKILL.md index ad33cb9d9ee..f9cec267bdc 100644 --- a/.agents/skills/quant-recipe-search/SKILL.md +++ b/.agents/skills/quant-recipe-search/SKILL.md @@ -69,6 +69,9 @@ Keep the search space explicit. A candidate recipe is a tuple across these axes: recipes, AutoQuant selection, or a hybrid of AutoQuant plus manual overrides. - **Module family:** attention, MLP, MoE experts, routers/gates, embeddings, `lm_head`, adapters, vision encoders, and model-specific modules. +- **Layer position:** first/last transformer-layer counts or explicit ordinal + ranges to keep in BF16. First 3-4 and last 1-2 layers are common starting + candidate ranges, not defaults. - **Runtime fusion constraints:** modules fused by the inference library must use compatible quantization. Examples: vLLM Qwen `linear_attn.in_proj_qkvz` and fused MoE expert projections such as gate/up (`w1`/`w3`). @@ -103,18 +106,29 @@ Do not collapse the search to one dimension such as numeric format only. Read - Add at least one manual or sensitivity-guided candidate so AutoQuant can be compared against controlled ablations and there is a fallback if AutoQuant misses the best frontier or hits runtime constraints. + - When sensitivity or model behavior implicates boundary layers, add a + controlled first-layer, last-layer, or combined BF16 exclusion candidate. + Do not preserve boundary layers without testing the trade-off. 4. **Generate candidates** - Delegate checkpoint generation and PTQ validation to `ptq`. - Change one major axis at a time: format, calibration algorithm, module - selection, granularity, exclusions, or calibration data. + family, layer position, granularity, or calibration data. - Use AutoQuant for broad candidate generation and sensitivity reports; use manual recipes for controlled module-family ablations and overrides. + - Resolve positional ordinals against the model's transformer block sequence. + For manual recipes, add those blocks to the recipe exclusions. For + AutoQuant or hybrid candidates, pass positional exclusions into the + selected implementation when supported; otherwise apply a manual override + to its result and record the limitation. 5. **Gate before scaling** - Validate checkpoint coverage and metadata. - Reject or rewrite recipes that mix quantization algorithms inside a fused runtime group. + - Ensure positional exclusions preserve complete fused runtime groups, then + evaluate the candidate against the same BF16 baseline and acceptance + criteria as every other recipe. - If the checkpoint is valid but serving fails due to runtime support, do not reject the recipe immediately. Delegate to `deployment` / `debug` for small patches or flags, then rerun a pipe-clean check. @@ -126,7 +140,8 @@ Do not collapse the search to one dimension such as numeric format only. Read 3. Rerun noisy or near-threshold results before labeling a regression. 4. Decide the next candidate: - Accuracy drop: protect or ablate sensitive module families, try MSE/GPTQ, - or use AutoQuant sensitivity to choose overrides. + use AutoQuant sensitivity to choose overrides, or test first/last-layer + BF16 exclusions when evidence points to boundary sensitivity. - Poor performance/cost: quantize the next high-cost active family, adjust active-cost objective, or try a more aggressive format. - AutoQuant underperforms manual recipes: inspect sensitivity reports, @@ -136,12 +151,13 @@ Do not collapse the search to one dimension such as numeric format only. Read support from checkpoint quality. - Repeated AutoQuant recipes: inspect achieved bits and recipe hashes, then adjust constraints before launching a larger sweep. -5. Promote only when `compare-results` shows the candidate is comparable to the - baseline and satisfies the user-defined goal. +5. Promote only when `compare-results` shows no failed external sanity check, + the candidate is comparable to the validated measured baseline, and the + user-defined goal is met. An externally unverified baseline is non-blocking. Maintain a recipe portfolio table with recipe name, objective, active-cost estimate, calibration notes, checkpoint path, eval/log references, accuracy, -verbosity, and decision. +verbosity, positional exclusions, and decision. ## References diff --git a/.agents/skills/quant-recipe-search/references/recipe_iteration.md b/.agents/skills/quant-recipe-search/references/recipe_iteration.md index 288a0a1c761..0f95d84c98a 100644 --- a/.agents/skills/quant-recipe-search/references/recipe_iteration.md +++ b/.agents/skills/quant-recipe-search/references/recipe_iteration.md @@ -27,6 +27,7 @@ axes, not just a numeric format. | Calibration/search algorithm | Max, MSE, GPTQ, AWQ, AutoQuant scoring, calibration data variants | Algorithm choice is independent from numeric format. | | Selection method | Manual/heuristic, sensitivity-guided manual, AutoQuant, hybrid | Record how each candidate was selected. | | Module family | Attention, MLP, MoE experts, routers/gates, embeddings, `lm_head`, adapters, vision encoders | Change one major family at a time for ablations. | +| Layer position | First/last transformer-layer counts or explicit ordinal ranges kept in BF16 | Treat as a controlled ablation, not a default. Start with first 3-4 and last 1-2 layers when evidence supports it. | | Runtime constraints | Fused attention groups, fused MoE expert projections, backend-supported formats | Do not mix incompatible quantization inside a fused runtime group. | | Calibration budget | Dataset mix, sample count, sequence length, batch size | Vary deliberately and record the budget. | @@ -88,6 +89,26 @@ Choose which modules get which format by one of these methods: - Hybrid: start from AutoQuant, then override known runtime constraints or known-sensitive fused groups manually. +### Layer Position Axis + +Use positional exclusions when sensitivity results or model behavior suggest +that boundary transformer layers are unusually sensitive. Do not assume every +model benefits from them. + +- Resolve ordinal positions from the model's transformer block sequence rather + than assuming a model-specific module path. +- Start with controlled candidates that keep the first 3 or 4 layers, the last + 1 or 2 layers, or both ranges in BF16. Include zero exclusion as the control. +- Change one boundary or count at a time when identifying the useful range. +- For manual candidates, exclude the resolved block paths in the recipe. For + AutoQuant or hybrid candidates, pass the positional exclusions into the + selected implementation when supported; otherwise apply them as a manual + override after selection and record that constraint. +- Keep fused runtime groups internally compatible. Expand an exclusion to the + complete fused group when the backend cannot mix precisions within it. +- Compare each excluded-layer candidate with the same BF16 baseline, benchmarks, + and acceptance threshold used for the rest of the search. + ## Design Workflow 1. Recover existing evidence: @@ -115,6 +136,8 @@ Choose which modules get which format by one of these methods: - Add at least one manual or sensitivity-guided candidate for comparison and as a fallback if AutoQuant misses the benchmark frontier or produces a runtime-incompatible recipe. + - Add positional BF16 exclusion candidates only when sensitivity or observed + behavior warrants the ablation. 5. Generate and validate: - Delegate checkpoint generation and validation to `ptq`. @@ -136,6 +159,9 @@ Search by module family, but respect modules fused by the target runtime. - Fused MoE kernels can couple expert projections such as gate/up (`w1`/`w3`, or equivalent names); treat each fused expert group as one recipe unit unless deployment confirms mixed formats are supported. +- Positional exclusions must preserve these grouping rules. If one boundary + layer intersects a fused group, keep the whole group at a compatible + precision or choose another boundary. - If a checkpoint is valid but deployment fails due to missing support, classify it as checkpoint-quality, recipe/runtime compatibility, or deployment implementation. For deployment implementation, try small patches or flags via @@ -152,6 +178,8 @@ Use this loop after each candidate: - Protect sensitive module families. - Try MSE, GPTQ, or AWQ variants. - Use AutoQuant sensitivity to choose manual overrides. + - Test first-layer, last-layer, or combined BF16 exclusion candidates when + sensitivity or model behavior points to boundary layers. 4. If performance or active cost is insufficient: - Quantize the next high-cost active family. - Try a more aggressive format. @@ -219,6 +247,7 @@ For every candidate, record: - Objective and acceptance threshold. - Numeric formats and module-family coverage. +- First/last BF16 exclusion counts or ordinal ranges. - Calibration/search algorithm and calibration data budget. - Selection method: manual, sensitivity-guided, AutoQuant, or hybrid. - Whether the candidate came from AutoQuant, manual ablation, or a hybrid From c6d92838f75574d01fe556b6ebffaeeaa79ce401 Mon Sep 17 00:00:00 2001 From: Chad Voegele Date: Wed, 8 Jul 2026 16:56:47 -0500 Subject: [PATCH 2/2] docs(skills): clarify PTQ checkpoint output Signed-off-by: Chad Voegele --- .agents/skills/ptq/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.agents/skills/ptq/SKILL.md b/.agents/skills/ptq/SKILL.md index 000d0f3c30b..f1bdf518b6e 100644 --- a/.agents/skills/ptq/SKILL.md +++ b/.agents/skills/ptq/SKILL.md @@ -4,8 +4,8 @@ description: >- Use when the user asks to "quantize a model", "run PTQ", "post-training quantization", "NVFP4 quantization", "FP8 quantization", "INT8 quantization", "INT4 AWQ", "quantize LLM", "quantize MoE", "quantize VLM", - or needs to produce a quantized HuggingFace or TensorRT-LLM checkpoint from a - pretrained model using ModelOpt. Do NOT use for multi-candidate recipe + or needs to produce a quantized HuggingFace checkpoint from a pretrained + model using ModelOpt. Do NOT use for multi-candidate recipe exploration or optimization (use quant-recipe-search). ---