Skip to content

Add Qwen3-VL-4B support#4263

Draft
hengtaoguo wants to merge 1 commit into
mainfrom
hengtaoguo-vl
Draft

Add Qwen3-VL-4B support#4263
hengtaoguo wants to merge 1 commit into
mainfrom
hengtaoguo-vl

Conversation

@hengtaoguo

@hengtaoguo hengtaoguo commented Jun 24, 2026

Copy link
Copy Markdown
Collaborator

Description

This PR adds Qwen/Qwen3-VL-4B-Instruct to maxtext:

  • Add Qwen3-VL-4B model config and register Qwen/Qwen3-VL-4B-Instruct.
  • Wire Qwen3-VL into multimodal config validation, prompt/image preprocessing, embedding fusion, and vision bidirectional masking.
  • Add Qwen3-VL vision encoder/projector subclasses reusing the existing Qwen3 Omni vision tower implementation.
  • Extend vision RoPE handling to Qwen3 vision models.
  • Add HF config, HF shape metadata, parameter mappings, and conversion hooks for Qwen3-VL checkpoint conversion.
  • Preserve non-causal-LM HF config architectures during save when no causal LM mapping exists.

Tests

# Checkpoint conversion
python -m maxtext.checkpoint_conversion.to_maxtext src/maxtext/configs/base.yml model_name=qwen3-vl-4b base_output_directory=gs://hengtaoguo-maxtext-logs/checkpoints/qwen3-vl-4b/unscanned/2026-06-24-15-27 scan_layers=false hf_access_token=<your_token> weight_dtype=bfloat16 hardware=cpu skip_jax_distributed_system=True checkpoint_storage_use_ocdbt=False checkpoint_storage_use_zarr3=False --eager_load_method=safetensors --lazy_load_tensors=False

# Decode check
python -m maxtext.inference.decode maxtext/configs/base.yml model_name=qwen3-vl-4b tokenizer_path=Qwen/Qwen3-VL-4B-Instruct tokenizer_type=huggingface load_parameters_path=gs://hengtaoguo-maxtext-logs/checkpoints/qwen3-vl-4b/unscanned/2026-06-24-15-27/0/items per_device_batch_size=1 run_name=ht_test scan_layers=false use_multimodal=true prompt=\'Describe\ this\ image\' image_path=\'tests/assets/test_image.jpg\' max_prefill_predict_length=512 max_target_length=768 ici_tensor_parallelism=4 override_model_config=true attention=\'dot_product\' hf_access_token=<your_token>

# Outputs
Input `<|im_start|>user
<|vision_start|><|image_pad|><|vision_end|>Describe this image<|im_end|>
<|im_start|>assistant
` -> `This image captures a vibrant, sunlit panoramic view of Seattle, Washington, under a clear blue sky. The most iconic landmark, the Space Needle, stands prominently in the center-left of the frame, its distinctive futuristic design rising above the surrounding urban landscape.

Checklist

Before submitting this PR, please make sure (put X in square brackets):

  • I have performed a self-review of my code. For an optional AI review, add the gemini-review label.
  • I have necessary comments in my code, particularly in hard-to-understand areas.
  • I have run end-to-end tests tests and provided workload links above if applicable.
  • I have made or will make corresponding changes to the doc if needed, including adding new documentation pages to the relevant Table of Contents (toctree directive) as explained in our documentation.

@codecov

codecov Bot commented Jun 24, 2026

Copy link
Copy Markdown

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant