parity-testing

Verify numerical parity between NeMo AutoModel implementations and HuggingFace reference models.

960|316|Updated May 21, 2025
One-click install
npx skills add https://github.com/NVIDIA-NeMo/Automodel --skill parity-testing-nvidia-nemo
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: parity-testing
Source: https://github.com/NVIDIA-NeMo/Automodel/tree/main/.agents/contributor-skills/parity-testing
Command: npx skills add https://github.com/NVIDIA-NeMo/Automodel --skill parity-testing-nvidia-nemo

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires torch, transformers, nemo_automodel.

What problem does it solve? Custom model implementations in NeMo AutoModel (combined projections, backend switching, kernel patches) can silently diverge from HuggingFace reference behavior, causing loss divergence or output mismatches that are hard to localize. ## Core Features & Use Cases - Three-Level Test Strategy: State dict round-trip checks on CPU/float32, isolated component parity tests, and end-to-end forward-pass validation on GPU/bfloat16. - Systematic Debugging Workflow: Step-by-step isolation procedure covering weight loading, backend forcing (SDPA/torch linear), component injection, and gradient parity checks. - Pitfall Catalog: Documents 12 known divergence sources including QKV interleaving, RoPE precision, tied weights, MoE routing non-determinism, and kernel patch interference. - Use Case: After adding a new model to NeMo AutoModel, run the three-level parity suite against its HuggingFace counterpart to confirm exact weight round-trips and logits within tolerance before merging. ## Quick Start Verify that my new NeMo AutoModel implementation of Llama-3.2-1B produces numerically identical outputs to the HuggingFace reference model.

Frequently Asked Questions about parity-testing

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I verify a custom PyTorch model matches its HuggingFace reference?▼

Load both models on CPU with float32, run a state dict round-trip check for exact weight equality, then compare logits from identical seeded inputs with max_diff under 1e-5. Finish with an end-to-end GPU test in bfloat16 using looser tolerances.

How to debug loss divergence between two model implementations?▼

Isolate the failing component by testing attention, MLP, norm, and RoPE separately, then verify weight loading via state dict round-trip. If weights match, force baseline backends like SDPA attention and torch linear, and use injection of reference outputs to pinpoint the diverging component.

Why do parity tests pass on CPU but fail on GPU?▼

GPU execution introduces non-determinism from parallel reductions, kernel launch order, and lower-precision dtypes like bfloat16. MoE models additionally suffer from non-deterministic top-k routing, so MoE parity should be tested on CPU or with fixed routing.

What tolerances should I use for bfloat16 model comparison?▼

For bfloat16 end-to-end tests on GPU, use max_diff below 1e-2 and cosine similarity above 0.9999. For float32 on CPU, require max_diff below 1e-5 at component level and exact equality for state dict round-trips.

Why do tied word embeddings cause parity failures?▼

When tie_word_embeddings is enabled, lm_head.weight and embed_tokens.weight must share the same underlying storage. If checkpoint loading creates independent copies, parameter counts increase and the weights diverge during training; verify aliasing by comparing data pointers.