ad-accuracy-debug

name	ad-accuracy-debug
description	Debug AutoDeploy accuracy regressions vs a reference score (PyTorch backend or published baseline). Use when an AutoDeploy model's eval score is significantly below the reference and the root cause is unknown.
license	Apache-2.0
tags	["tensorrt-llm","autodeploy","accuracy","debugging","evaluation"]
metadata	{"author":"NVIDIA Corporation"}

AutoDeploy Accuracy Debugging

Where this skill applies

This file is part of trtllm-agent-toolkit. Paths such as tensorrt_llm/, tests/, and examples/auto_deploy/ are relative to a TensorRT-LLM source checkout on the user's machine, not the plugin repository.

Related skills in this plugin

• trtllm-agent-toolkit:ad-graph-dump — inspect per-transform FX graph snapshots when Phase 2 suggests a transform was applied incorrectly or is corrupting activations.
• trtllm-agent-toolkit:ad-conf-check — verify that precision or config settings (FP8, sharding, chunked prefill, etc.) were actually applied at runtime before attributing an accuracy gap to a kernel or weight bug.

Input: model name, failing accuracy score, reference score, eval task (e.g. MMLU, GSM8K). Output: identified root cause, minimal reproducer, and a code fix.

Situation Assessment

Before debugging, confirm:

1. What is the reference score? Is it from the PyTorch backend test, a published leaderboard, or set manually?
2. How large is the gap? A 1-2% gap may be within statistical noise; a 5%+ gap is a real bug.
3. Is the eval framework itself suspect? Run the same eval on the PyTorch backend to validate the harness before blaming AutoDeploy.

Abbreviations

• AD — AutoDeploy, TRT-LLM with _autodeploy backend
• PT — PyTorch, TRT-LLM with pytorch backend (manual deployment)

Phase 0 — Validate the Test Harness

Run the equivalent PyTorch backend test on the same model and same eval task. If PT also fails or scores lower than expected, the issue is in the eval framework (prompt format, chat template, sampling params), not AD-specific.

Key things to verify in the eval harness:

• Prompt format / apply_chat_template: does the evaluator send raw prompts or apply a chat template? The relationship is two-sided for reasoning/chat models:
  • Applying apply_chat_template to a concatenated few-shot prompt (without fewshot_as_multiturn) collapses the examples into a malformed single turn and can produce 0% accuracy.
  • Omitting apply_chat_template for a chat-first model can be equally wrong. For chat models on few-shot benchmarks, consider whether apply_chat_template=True paired with fewshot_as_multiturn=True is appropriate — the latter turns each few-shot example into an explicit user/assistant exchange before the template is applied. (Reference: Qwen3.5-MoE accuracy fix in test_llm_api_autodeploy.py.)
• max_output_len for generation tasks: for benchmarks where the model must generate a full reasoning chain before the answer (e.g. GSM8K with a reasoning model), the default MAX_OUTPUT_LEN may truncate the response before the final answer is reached. Consider patching it up (e.g. 512) if outputs appear cut off. This is distinct from capping max_tokens for classification tasks like MMLU where you want to prevent long generations.
• max_tokens for classification tasks: must be capped (e.g. 2 for MMLU) to prevent the model generating a full reasoning chain.
• Dataset path: confirm LLM_MODELS_ROOT is set correctly and the dataset directory exists.

If PT passes: the harness is fine. Proceed to Phase 1.

Phase 1 — Quick Diagnostic with a Small Sample

Write a standalone diagnostic script that:

1. Loads the AD model directly via from tensorrt_llm._torch.auto_deploy import LLM as AutoDeployLLM
2. Reproduces the exact prompt format the evaluator uses (not a simplified variant), including few-shot examples if any
3. Runs ~50-100 samples
4. Prints per-sample (ref, output, correct) and overall accuracy

Critical: reproduce the evaluator's exact prompt format. Deviating — for example, using a 0-shot prompt when the evaluator uses 5-shot — can cause thinking models to produce "Okay" or other meta-responses instead of the expected answer, making results uninterpretable. Verify the first printed prompt matches what the evaluator sends.

Typical evaluator sources:

• tensorrt_llm/evaluate/mmlu.py — 5-shot format with dev examples
• tensorrt_llm/evaluate/gsm8k.py — few-shot with CoT references
• tests/integration/defs/accuracy/accuracy_core.py — MAX_INPUT_LEN, MAX_OUTPUT_LEN, NUM_SAMPLES per task

Phase 2 — Classify the Error Pattern

From the diagnostic output, determine what the model is generating:

Output Pattern	Likely Root Cause
Coherent but consistently wrong letter / answer	Numerical accuracy bug (attention, FP8 kernel, weight corruption)
Generates meta-text ("The user wants...", "The answer is...", "Let me think...")	Prompt format issue — model not primed to answer directly
Outputs empty string or EOS immediately	KV cache garbage (uninitialized cache, scale overflow), or end_id matching first token
Completely random tokens / gibberish	Transformation applied incorrectly, load hook missing or applied twice, corrupted weights
Correct on easy subjects, wrong on hard subjects	Subtle numerical precision bug (FP8 kernel mismatch, attention scale wrong)
NaN in logits, especially on prefill	FX graph transform produced a node without shape metadata — enable AD_DUMP_GRAPHS_DIR and look for nodes missing meta["val"]; often caused by an opaque Python closure inside a transform
Passes at world_size=1, fails at world_size>1	Sharding bug — see Phase 4c

Phase 3 — Configuration Isolation

Narrow down which part of the setup is responsible by reducing the environment to its simplest form, then re-enabling components one at a time until the regression reappears.

Step 1 — Strip to a minimal configuration:

Where feasible, reduce complexity along each axis, re-running the Phase 1 diagnostic after each change:

• Remove sharding or reduce to TP=1 / single GPU
• Disable multi-streaming
• Disable non-default transform passes in the YAML config (enabled: false)
• Revert to torch-simple compile_backend: AutoDeploy currently supports two backends — torch-cudagraph (CUDA graphs, the typical production setting) and torch-simple (no CUDA graphs, significantly slower). If the model is configured with torch-cudagraph, revert to torch-simple and check whether the accuracy issue persists. Note the slower throughput will make the validation loop take longer. If accuracy recovers at torch-simple, CUDA graph capture or replay is the suspect.

If the issue disappears when a component is removed, that component is the suspect — note it and proceed to Step 2 targeting it. If the issue persists even at minimal config, the bug is in a core path (weight loading, attention, KV cache) — proceed to Phase 4.

Step 2 — Re-enable one component at a time:

Starting from the stripped-down configuration that still reproduces the issue, re-enable the suspected components individually — one per diagnostic run. Stop as soon as accuracy drops: the last re-enabled component is the offending pass or backend. Carry this finding into Phase 4 to investigate the root cause.

Phase 4 — Root Cause Investigation

This phase contains targeted investigation paths for known root-cause categories. Add model-specific or error-pattern-specific steps here as they are discovered.

4a — Quantized Model Accuracy

If the failing model is quantized (e.g. FP8, NVFP4), first verify whether the issue is in the quantization itself or in the quantized kernel path:

Step 1 — Test an unquantized baseline.

Ask the user for an unquantized (BF16/FP16) version of the same model. Run the Phase 1 diagnostic against it with an identical configuration (same compile_backend, same TP, same eval format).

• If the unquantized model also fails: the bug is not quantization-related — the issue is in a transform pass, attention implementation, or weight loading. Continue with Phase 3 isolation against the unquantized model.
• If the unquantized model passes: the accuracy gap is introduced by quantization or the quantized kernel path. Proceed to Step 2.

Step 2 — Suspect classification.

When quantization is confirmed as the source, the likely causes are (in rough order of severity):

Suspect	Symptom	How to isolate
Missing scale during dequantization	Near-zero or astronomically large logits; catastrophic accuracy loss (≈ random chance or worse)	Log a few raw logits; they will be wildly out of range
Inverted scale (multiplied instead of divided, or vice versa)	Similarly catastrophic; outputs plausible tokens but systematically wrong	Same logit inspection; compare scale values in the checkpoint vs what the kernel receives
Incorrect block-scale computation	Major but not catastrophic degradation; typically 5–20% below unquantized reference	Compare per-block scales against a reference quantizer on a few weight tensors
.to(dtype) used instead of .view(dtype) for packed format reinterpretation	Wrong scale or weight values without an error — .to() converts values numerically while .view() reinterprets the raw bits	Grep the quantization transform for .to( on quantized weight/scale tensors of packed types (FP4, FP8); the intent is bit-level reinterpretation, which requires .view()
Quantized kernel bug (wrong accumulation, wrong cast)	Non-catastrophic; may be input-dependent or shape-dependent	Step 3 below

Step 3 — Isolate quantized kernels via fake quantization.

AutoDeploy's transform pipeline has a built-in fake-quantization path that implements exactly Q→DQ→high-precision-matmul. Understanding the two stages helps:

• Stage 1 (pattern_matcher): Replaces nn.Linear nodes with torch.ops.auto_deploy.torch_fake_quant_fp8_linear / torch_fake_quant_nvfp4_linear etc. These ops quantize the input, immediately dequantize both input and weight back to BF16/FP16, then run a standard torch.matmul. Scales are exercised but all arithmetic is in high precision. Implementation: tensorrt_llm/_torch/auto_deploy/custom_ops/quantization/torch_quant.py, lines 178–286.

• Stage 2 (post_load_fusion): fuse_fp8_linear, fuse_nvfp4_linear, and fuse_finegrained_fp8_linear transforms replace the fake-quant ops with optimized low-precision kernels. This is where a kernel bug would be introduced.

To run inference in fake-quantization mode (bypassing the low-precision kernels), add the following to the YAML config file the test is already using (passed via --config or --extra_llm_api_options):

transforms:
  fuse_fp8_linear:
    enabled: false
  fuse_nvfp4_linear:
    enabled: false
  fuse_finegrained_fp8_linear:
    enabled: false
  # For MoE models also add:
  fuse_fp8_moe:
    enabled: false
  fuse_finegrained_fp8_moe:
    enabled: false
  fuse_nvfp4_moe:
    enabled: false

If there is no existing config file, create one with only the above content and pass it via --extra_llm_api_options /path/to/fake_quant_debug.yaml. The transforms key maps directly to LlmArgs.transforms; any transform not listed inherits its default from tensorrt_llm/_torch/auto_deploy/config/default.yaml.

If accuracy recovers with fake quantization, the quantized kernel (not the scales) is the bug. If accuracy is still wrong, the scales or weight data are the likely culprit.

4b — Kernel Wrapper Hardcoded Assumptions

Symptom: coherent but systematically wrong output on one specific model family (or one model variant within a family), while a structurally similar model is fine.

Root cause pattern: The C++ kernel or its Python wrapper has a constant where it should read from the model config or from the actual tensor. Two common forms:

• Config value hardcoded: a kernel wrapper assumes a default value instead of reading it from the HF config loaded at runtime.
• Tensor stride/shape hardcoded: a C++ kernel assumes a specific memory layout that differs from what AutoDeploy actually passes. The kernel then reads the wrong memory locations silently.

How to investigate:

1. Identify which kernel is dispatched for the failing op (search for the op's Python entry point in tensorrt_llm/_torch/auto_deploy/).
2. Compare every constant or default in the kernel wrapper call against the corresponding field in the model's HF config (config.json). Flag any value that is not read from the config.
3. For stride bugs: print the actual strides of the tensors being passed to the kernel and compare against what the kernel expects (check the C++ kernel source for stride assumptions or parameters).
4. If a mismatch is found, the fix is to pass the config or tensor property as an explicit parameter rather than using a hardcoded constant.

4c — Sharding-Related Accuracy (world_size > 1)

First step: reproduce the issue at world_size=1. If accuracy recovers, the bug is in the sharding path. If it fails at world_size=1 too, sharding is not the cause — return to Phase 3.

To run at world_size=1, set world_size: 1 in the model's YAML config or pass --extra_llm_api_options with world_size: 1.

Known sharding bug patterns (check in order):

Suspect	Symptom	How to isolate
Wrong allreduce strategy	Non-deterministic or rank-dependent outputs; may appear only at TP≥4	Set allreduce_strategy: NCCL in the sharding transform config; the AUTO default has caused correctness issues in the past
Double all_reduce in MoE	MoE output doubled in magnitude; accuracy catastrophic	Inspect the exported graph; there should be exactly one all_reduce after the sum of routed and shared expert outputs, not one per branch
Head reshape with wrong stride after TP	Attention output garbage at TP>1, correct at TP=1	Reshapes that use concrete head counts from torch.export become wrong after TP splits the head dimension; these must use torch.ops.auto_deploy.view with tp_scaled_dim
Sharding a projection that must not be sharded	Dim-1 gating projections or latent projections sharded → wrong results	Check tp_mode on small-output projections (e.g. MoE router, MLA latent q_a/kv_a); they must be "none"
Nested parameter deletion breaking weight loading	Some weights missing after sharding, silently defaulting to zero or random	If sharding deletes parent module params and child params are looked up by the old path, the load hook may silently skip them

Validating a sharding fix:

If model size permits, run it at world_size=1 (baseline), then world_size=2, then the target world_size. If accuracy is correct at TP=1 and TP=2 but wrong at TP=8, the bug is likely a head-count divisibility assumption (head dim must be divisible by the TP degree). If it is wrong at all TP>1, it is a structural sharding bug (missing allreduce, wrong split point, wrong stride).

Phase 5 — Per-Subject / Per-Category Breakdown

When the overall score is lower than expected but not catastrophically wrong, look at per-subject or per-category breakdowns in the eval logs. Patterns to look for:

Pattern	Implication
All subjects uniformly ~N% below reference	Uniform precision loss — suspect FP8 kernel or attention scale
Specific subjects near 25% (random chance for 4-choice MCQ)	Those subjects have a systematic error — suspect subject length or chunked prefill
Easy subjects correct, hard subjects wrong	Near-decision-boundary sensitivity — suspect subtle numerical error
Subject-correlated errors	Prompt-length correlation — verify truncation behavior

For MCQ tasks like MMLU, random chance is 25%. Subjects scoring 25-35% may be genuinely hard for the model even in the PT backend — verify against PT per-subject scores before concluding an AD-specific bug.

Phase 6 — Iterative Ablation

Once a hypothesis is formed, verify it by toggling one change at a time and re-running the diagnostic (50-100 samples is sufficient for 5%+ gaps).

Each ablation should be a separate diagnostic run. Do not batch multiple hypotheses in one run — it makes results ambiguous.

Anti-Patterns

• Do not use 0-shot prompts to diagnose a 5-shot evaluator. Meta-responses ("Okay", "The answer is...") from a 0-shot run are a prompt-format artifact, not an AD inference bug.
• Do not invoke torchrun for AD tests. The AD LLM API spawns MPI workers internally; torchrun adds a second layer of distributed init that deadlocks.
• Do not override LLM_MODELS_ROOT. If it is already set in the environment (CI sets it to /path/to/llm-models), unsetting or overriding it breaks dataset lookups. Check echo $LLM_MODELS_ROOT before assuming it needs to be set.
• Do not lower the reference threshold as a "fix." The reference value must be validated against the PT backend before being accepted. If PT also fails, re-examine the harness, not the threshold.
• Do not apply the same load hook twice. If a hook converts interleaved → NeoX, applying it again corrupts the weights (it is not idempotent). Check the git log for reverts/restores before adding a hook that might already exist elsewhere in the call chain.

Keeping This Skill Up to Date

Whenever this skill is used and the debugging session uncovers a new root cause or error pattern that is not yet described here, update the skill before closing the session.

Where to add new findings:

• Phase 2 — Classify the Error Pattern: add a new row to the table if the session revealed a symptom → root cause mapping that is not already listed. Keep the "Output Pattern" column observable (something visible in diagnostic output), and the "Likely Root Cause" column actionable (points to a concrete next step or Phase 4 subsection).

• Phase 4 — Root Cause Investigation: add the investigation steps under the most fitting existing subsection (4a quantization, 4b kernel wrapper assumptions, 4c sharding). If the finding does not fit any existing subsection, create a new one numbered sequentially (4d, 4e, …). Each subsection should follow the same structure: symptom, root cause pattern, and a numbered investigation procedure.

What is worth capturing:

• A root cause that is not already represented in Phase 4.
• A symptom pattern that allows earlier classification (Phase 2).
• A configuration or environment condition that reproduces or masks the bug (Phase 3).
• A new anti-pattern discovered during the session.

What is not worth capturing:

• Model-specific quirks with no generalization potential.
• Findings that duplicate what is already written.
• Workarounds that paper over a bug rather than identifying it.