add Qwen3-VL support for DFlash training

[skierat]

What does this PR do?

Type of change: new feature

Adds online DFlash training support for Qwen3-VL–style vision-language models.

Changes include:

• Load VLMs through the Transformers 5 AutoModelForImageTextToText API, while retaining compatibility with the legacy VLM auto-model API.
• Run the base model through its top-level multimodal forward when image/video inputs are present, ensuring vision embeddings are injected before collecting DFlash target hidden states.
• Extend VisionLanguageDataCollator to:
  • propagate answer_only_loss, chat-template, and DFlash label-alignment settings;
  • apply VLM_MIN_PIXELS / VLM_MAX_PIXELS processor limits;
  • derive assistant-only masks from ChatML/Llama chat boundaries when processor generation masks are unavailable;
  • enforce the fixed training_seq_len required by DFlash block training.
• Preserve the existing text-only DFlash path.

Usage

python -m torch.distributed.run \                                      
--nproc_per_node 4 \                                                 
examples/speculative_decoding/main.py \                              
--config modelopt_recipes/general/speculative_decoding/dflash.yaml \
model.model_name_or_path=/path/to/qwen3-vl-model \
model.trust_remote_code=true \
data.data_path=/path/to/train.jsonl \
data.vlm_processor=/path/to/qwen3-vl-model \                        
data.vlm_img_dir=/path/to/image/root \
training.training_seq_len=4096 \
training.answer_only_loss=true \
dflash.dflash_block_size=8 \
dflash.dflash_mask_token_id=151669


### Testing
- git diff --check
- Parsed all modified Python modules successfully.
- Ran iterative multi-node Slurm smoke tests with a Qwen3-VL-family model and mixed multimodal data:
    - validated VLM model loading with Transformers 5;
    - validated distributed initialization, DFlash conversion, and VLM collation paths;
    - identified and addressed processor padding/truncation behavior required by fixed-size DFlash blocks.
This PR remains draft pending a completed end-to-end training smoke test and automated regression coverage.

### Before your PR is "Ready for review"
Make sure you read and follow Contributor guidelines (https://github.com/NVIDIA/Model-Optimizer/blob/main/CONTRIBUTING.md) and your commits are signed (git commit -s -S).
Make sure you read and follow the Security Best Practices (https://github.com/NVIDIA/Model-Optimizer/blob/main/SECURITY.md#security-coding-practices-for-contributors) (e.g. avoiding hardcoded trust_remote_code=True, torch.load(...,
weights_only=False), pickle, etc.).
- Is this change backward compatible?: ✅
- If you copied code from any other sources or added a new PIP dependency, did you follow guidance in CONTRIBUTING.md: N/A
- Did you write any new necessary tests?: ❌ — automated Qwen3-VL/DFlash regression coverage still needs to be added before review.
- Did you update Changelog (https://github.com/NVIDIA/Model-Optimizer/blob/main/CHANGELOG.rst)?: ❌ — evaluate and add an entry before marking ready for review if this is considered user-facing speculative-decoding support.
- Did you get Claude approval on this PR?: N/A
### Additional Information
The PR intentionally excludes local Slurm launch scripts, logs, model paths, datasets, and environment-specific configuration.


<!-- This is an auto-generated comment: release notes by coderabbit.ai -->
## Summary by CodeRabbit

* **New Features**
  * Improved Qwen3-VL video handling for speculative decoding with newer Transformers versions.
  * Added support for reading RoPE configuration from modern model configuration formats.
  * Improved multimodal training, label shifting, answer-only loss, and loss-mask behavior.

* **Bug Fixes**
  * Improved validation and error handling for multimodal inputs.
  * Improved training stability when no valid anchor blocks are available.

* **Tests**
  * Added coverage for RoPE configuration export, Qwen3-VL position IDs, and vision-language training options.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 11691ebe-87df-4f7f-be7f-9f4706cc3289

📥 Commits

Reviewing files that changed from the base of the PR and between f479e78 and 7b7c17b.

📒 Files selected for processing (6)

• examples/speculative_decoding/eagle_utils.py
• modelopt/torch/export/plugins/hf_spec_export.py
• modelopt/torch/speculative/plugins/hf_dflash.py
• tests/unit/torch/export/test_hf_spec_rope_export.py
• tests/unit/torch/speculative/plugins/test_hf_dflash.py
• tests/unit/torch/speculative/plugins/test_hf_speculative_offline.py

---

📝 Walkthrough

Walkthrough

Changes

DFlash and RoPE updates

Layer / File(s)	Summary
RoPE configuration extraction modelopt/torch/export/plugins/hf_spec_export.py, tests/unit/torch/export/test_hf_spec_rope_export.py	RoPE export now reads legacy and nested configuration fields, with coverage for rope_parameters.
Qwen3-VL DFlash training flow modelopt/torch/speculative/plugins/hf_dflash.py, tests/unit/torch/speculative/plugins/test_hf_dflash.py	Qwen3-VL video grids and position ids are validated and expanded; multimodal forward calls, loss masks, and empty-anchor gradients are updated.
Vision-language data wiring examples/speculative_decoding/eagle_utils.py, tests/unit/torch/speculative/plugins/test_hf_speculative_offline.py	The online VLM collator receives answer-only loss, label-shifting, and chat-template settings, with corresponding test coverage.

Estimated code review effort: 4 (Complex) | ~45 minutes

Suggested reviewers: h-guo18, yeyu-nvidia

Sequence Diagram(s)

sequenceDiagram
  participant HFDFlashModel
  participant Qwen3VLModel
  participant get_rope_index
  HFDFlashModel->>Qwen3VLModel: recompute position_ids from multimodal inputs
  Qwen3VLModel->>get_rope_index: pass expanded video_grid_thw and mm_token_type_ids
  get_rope_index-->>HFDFlashModel: return position_ids
  HFDFlashModel->>Qwen3VLModel: forward multimodal inputs
  Qwen3VLModel-->>HFDFlashModel: return hidden_states

Loading

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely matches the main change: adding Qwen3-VL support for DFlash training.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Security Anti-Patterns	✅ Passed	No critical anti-patterns were introduced: the only new torch.load(weights_only=False) has an inline safety comment; no hardcoded trust_remote_code/eval/nosec or unsafe numpy.load additions.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}