feat(cpu): add Qwen3.5 4B multimodal support

[Aharrypotter]

What this PR does

Extends the existing Qwen3.5-4B text runtime to the image, ordered multi-image,
and bounded short-video CPU path already supported by Qwen3.5-0.8B:

• accepts the official 24-layer, hidden-size-1024 Qwen3.5-4B vision tower
• adds a separate 4B multimodal runtime config and W4A32 KAI conversion recipe
• generalizes checkpoint/model-file validation without weakening the 0.8B contract
• documents 4B single-image, repeated --image_path, and optional local MP4 use

End-to-end demos

Single image

Prompt

Describe this image in exactly one sentence. Output only that sentence, with no preamble or reasoning.

Qwen3.5-4B Multimodal on OnePlus 13T

Two tabby cats are lying on a pink blanket, one with its head resting on a remote control and the other with its head on a white object.

Ordered multi-image

First image	Second image

Prompt

Describe the first and second images in exactly one sentence. Output only that sentence, with no preamble or reasoning.

Qwen3.5-4B Multimodal on OnePlus 13T

Two tabby cats are sleeping on a pink blanket next to two remote controls.
The image displays a diagram illustrating various algorithms, frameworks, compilers, and accelerators related to AI inference.

Bounded short video

Prompt

What direction does the red square move in the video? Output only one short sentence, with no frame-by-frame description or reasoning.

Qwen3.5-4B Multimodal on OnePlus 13T

The red square moves to the right.

The auxiliary Pixel 9 Pro XL produced byte-identical token-ID records for all
three cases.

Review guide

Area	Main files	What to review
Runtime contract	configuration_qwen3_5.hpp	4B text/vision geometry and model/config checks
Conversion validation	validate_checkpoint.py, test_validators.py	size-specific vision contracts and descriptor coverage
Recipes	config_4B_multimodal_w4a32_kai.json, quant_cfg_4B_multimodal_w4a32_kai.json	official geometry, KAI shapes, V2 multimodal conversion
Tests/docs	Qwen35ConfigTest.cpp, README.md	0.8B regression protection and 4B user workflow

Current-head validation

Candidate HEAD: 55e59c30dbecb524467ae42514a24b8bdc2f232a
Validated local commit: 3439b8bd8e0a3f96b314ad92fd71c7003a42da82
Identical source tree: 1d8e8e93064724f22f82579073b5abd54809ecc0
Merged-main base: b9b46ae416514ec7b516f36b44be7d8e28b79ceb

Gate	Result
Source/static	git diff --check, clang-format dry-run, and both runtime/quant JSON parses passed
macOS arm64 exact source tree	config 7/7, multimodal 25/25, Python validators 11/11
GitHub Actions	pending for this Draft PR
Pinned Transformers BF16 oracle	single, ordered multi-image, and video passed with no-think template parity
Pre-merge H20 Linux evidence	focused suites passed; full conversion descriptor audit passed
Pre-merge Android cross-build evidence	NDK r28b/API 28 arm64-v8a; ELF/dependency audit passed
Pre-merge OnePlus 13T primary evidence	focused suites, MP4 smoke, full model SHA, and all three product demos passed
Pre-merge Pixel 9 Pro XL auxiliary evidence	same gates passed; all three token-ID records match OnePlus

Full validation details

Evidence	Result
Official checkpoint	Qwen/Qwen3.5-4B@851bf6e8...
Converted V2 model	5,126,262,484 bytes; 2b38d8bb...
Descriptor audit	626 total: 347 KAI, 279 float32, 199 visual
Conversion resources	54.639 s; peak RSS 32,365,592 KiB
Oracle source	Transformers fd12552d...; explicit enable_thinking=false
Oracle grids	single [1,14,20]; multi [1,14,20] + [1,22,46]; video [4,8,12]
Android video	selection [0,2,4,6,9,11,13,15]; patches [384,1536]
Prompt tokens	single 103; multi 361; video 168 on oracle, OnePlus, and Pixel
Device identity	model, runner, tokenizer, config, loaded RT/CPU-backend libraries all hash-bound
Device RSS	OnePlus 3.22/3.40/3.25 GiB; Pixel 3.26/3.44/3.30 GiB observed for the three correctness runs
Evidence boundary	integration/correctness only; printed time and RSS are not performance acceptance

The H20, Android, and phone rows are retained from the sealed pre-merge 4B
candidate. They validate the exact 4B model/config/conversion contract and the
three product workloads, but are not described as exact-head closure after the
#697 squash/refactor. Exact-head device replay remains a Draft-PR follow-up.

How to convert and run

python -m pymllm.mobile.utils.mllm_convertor \
  --input_path /path/to/Qwen3.5-4B \
  --output_path /path/to/qwen3.5-4b-multimodal-w4a32-kai.mllm \
  --model_name Qwen3.5-4B-Multimodal \
  --cfg_path examples/qwen3_5/quant_cfg_4B_multimodal_w4a32_kai.json \
  --pipeline w4a32_kai_pipeline \
  --include_prefix model.language_model. \
  --include_prefix model.visual. \
  --format v2

Use config_4B_multimodal_w4a32_kai.json with the existing Qwen3.5 runner.
Repeat --image_path for ordered images, or use --video_path in a
decoder-enabled build.

Known limits

• Qwen3.5-4B, batch size 1, and maximum cache length 2048
• images or one finite local H.264 MP4 per request; image/video mixing is not supported
• no audio, URLs, cameras, streaming, multiple videos, or long-video claim
• optional decoder remains default-off and requires separately supplied pinned dependencies
• no accuracy-benchmark, codec-patent, or performance claim is made

Builds on the bounded Qwen3.5-0.8B video support in #697.

Summary by CodeRabbit

• New Features

  • Added support for Qwen3.5-4B multimodal models with image and bounded-video inputs.
  • Added 4B multimodal conversion, validation, and runner examples.
  • Added model-specific handling for both 0.8B and 4B multimodal configurations.

• Bug Fixes

  • Improved configuration checks to detect mismatched model sizes and vision settings.
  • Expanded multimodal validation coverage across supported model variants.

• Documentation

  • Updated capability tables and inference guidance for text-only and multimodal models.
  • Clarified conversion and validation workflows for Qwen3.5 model sizes.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds Qwen3.5 4B multimodal configuration and quantization files. It extends checkpoint and runtime validation for 0.8B and 4B variants, adds test coverage, and documents 4B multimodal conversion and execution.

Changes

Qwen3.5 4B multimodal support

Layer / File(s)	Summary
4B multimodal configuration and quantization examples/qwen3_5/config_4B_multimodal_w4a32_kai.json, examples/qwen3_5/quant_cfg_4B_multimodal_w4a32_kai.json	Adds text, vision, token, cache, and Kai quantization settings for the 4B multimodal model.
Size-aware checkpoint validation examples/qwen3_5/validate_checkpoint.py	Adds separate 0.8B and 4B vision contracts. Validation resolves the model size and checks matching checkpoint and runtime configurations.
Runtime modality classification mllm/models/qwen3_5/configuration_qwen3_5.hpp	Adds 4B text-only and multimodal predicates, modality-aware model-name resolution, and general multimodal parameter validation.
Validation coverage and usage examples tests/cpu/Qwen35ConfigTest.cpp, examples/qwen3_5/test_validators.py, examples/qwen3_5/README.md	Tests the 4B multimodal configuration, descriptors, tensor metadata, and rejection cases. Documents conversion, validation, and runner commands.

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

Possibly related PRs

• UbiquitousLearning/mllm#690: Adds the earlier Qwen3.5 support extended by this PR.
• UbiquitousLearning/mllm#691: Introduces related Qwen3.5-4B infrastructure and shared files.
• UbiquitousLearning/mllm#697: Covers related Qwen3.5 multimodal and video support.

Suggested reviewers: chenghuawang

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 45.83% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding Qwen3.5 4B multimodal CPU support.
Description check	✅ Passed	The description clearly covers the implementation, validation evidence, usage instructions, known limits, and relation to the existing 0.8B support.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

mllm/models/qwen3_5/configuration_qwen3_5.hpp (1)

313-362: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Document the public multimodal predicate APIs.

Line 330 adds hasOfficialQwen35_4BTextGeometry without an API comment. The predicate comments in this range also omit required parameter and return details. Add consistent Doxygen comments for each public predicate, including its config parameter, boolean return condition, and error behavior.

As per coding guidelines, public APIs, classes, and functions must have clear docstrings or comments explaining purpose, parameters, returns, and errors.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@mllm/models/qwen3_5/configuration_qwen3_5.hpp` around lines 313 - 362, Add
consistent Doxygen documentation to hasOfficialQwen35_4BTextGeometry,
isOfficialQwen35_08BMultimodalRuntimeConfig, isOfficialQwen35_08BRuntimeConfig,
isOfficialQwen35_4BTextRuntimeConfig,
isOfficialQwen35_4BMultimodalRuntimeConfig, isOfficialQwen35_4BRuntimeConfig,
and isOfficialQwen35MultimodalRuntimeConfig. Each comment must state the
predicate’s purpose, describe the config parameter, define when it returns true,
and document that evaluation does not report or throw errors.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@mllm/models/qwen3_5/configuration_qwen3_5.hpp`:
- Around line 313-362: Add consistent Doxygen documentation to
hasOfficialQwen35_4BTextGeometry, isOfficialQwen35_08BMultimodalRuntimeConfig,
isOfficialQwen35_08BRuntimeConfig, isOfficialQwen35_4BTextRuntimeConfig,
isOfficialQwen35_4BMultimodalRuntimeConfig, isOfficialQwen35_4BRuntimeConfig,
and isOfficialQwen35MultimodalRuntimeConfig. Each comment must state the
predicate’s purpose, describe the config parameter, define when it returns true,
and document that evaluation does not report or throw errors.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 7da02a2c-9e92-4828-9778-6ecfb8b01bbf

📥 Commits

Reviewing files that changed from the base of the PR and between b9b46ae and 55e59c3.

📒 Files selected for processing (7)

• examples/qwen3_5/README.md
• examples/qwen3_5/config_4B_multimodal_w4a32_kai.json
• examples/qwen3_5/quant_cfg_4B_multimodal_w4a32_kai.json
• examples/qwen3_5/test_validators.py
• examples/qwen3_5/validate_checkpoint.py
• mllm/models/qwen3_5/configuration_qwen3_5.hpp
• tests/cpu/Qwen35ConfigTest.cpp

[chenghuaWang]

LGTM