docs: document eager experts_implementation requirement for MoE-quantized inference - #2620
Merged
Merged
Conversation
…for native inference
QuantTensor's 3D fused-expert quantization is storage-only and cannot
represent a transpose without a lossy dequantize/re-quantize round trip.
Some transformers experts_implementation strategies (e.g. grouped_mm,
which may be auto-selected even on CPU) call weight.transpose(-2, -1)
before their matmul kernel, which crashes against a QuantTensor even for
architectures whose checkpoint layout is fully supported for
quantization (is_transposed=False). Document the model.set_experts_implementation("eager")
workaround and link the follow-up issue (#2619) tracking a more general
fix.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: e10674c1-6909-4b09-9f5a-d41b28c89d2d
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates Olive’s quantization documentation to capture a transformers MoE inference-time limitation affecting moe=True-quantized fused-expert weights, and documents the practical workaround needed for native PyTorch inference.
Changes:
- Adds a new documentation section explaining that some
transformersMoE experts implementations (e.g."grouped_mm") may callweight.transpose(-2, -1)and can crash with Olive’s storage-only 3DQuantTensor. - Documents the recommended workaround for native PyTorch inference:
model.set_experts_implementation("eager"). - Links to the tracking follow-up issue (#2619).
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Ti-Tai Wang (titaiwangms)
added
the
documentation
Ti-Tai Wang (titaiwangms)
enabled auto-merge (squash)
August 13, 2026 19:38
Jambay Kinley (jambayk)
approved these changes
Aug 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Describe your changes
Documents a limitation surfaced while validating KQuant/RTN MoE quantization on a real (locally-constructed)
Qwen3MoeForCausalLMmodel:transformersmay auto-select the"grouped_mm"experts implementation at inference time (even on CPU), which internally callsweight.transpose(-2, -1)on the fused-experts weight before its matmul kernel. Olive's 3D fused-expertQuantTensoris storage-only and cannot represent a transpose without a lossy dequantize/re-quantize round trip, so this raises aRuntimeErrorat inference time -- even for architectures whose checkpoint layout (is_transposed=False) is already fully supported for quantization byRtn/Gptq/KQuant.This reproduces identically for both
Rtn(merged, #2616) andKQuant(#2618), confirming it's a sharedQuantTensorlimitation rather than a pass-specific bug.Adds a short doc section next to the existing "
moeand ONNX export" note, documenting the workaround (model.set_experts_implementation("eager")before running inference) and linking the follow-up issue.Follow-up issue: #2619 (tracks whether the deferred "transposed layout" (
is_transposed=True)QuantTensordesign work could also resolve this as a side effect, or whether it needs separate design).Doc-only change, no code/test changes.