Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: pair Qwen3.5 / 3.6 vision projectors from another quantizer (#13288)

Daniel Han93f1dbd6cbc7
diff --git a/studio/backend/tests/test_detect_mmproj_file.py b/studio/backend/tests/test_detect_mmproj_file.py
index fb440c9271d..b4c44bd1ec0 100644
--- a/studio/backend/tests/test_detect_mmproj_file.py
+++ b/studio/backend/tests/test_detect_mmproj_file.py
@@ -27,7 +27,9 @@ def _gguf_with_general(path: Path, fields: dict) -> Path:
for k, v in fields.items():
kb = k.encode("utf-8")
body += struct.pack("<Q", len(kb)) + kb
- if isinstance(v, int):
+ if isinstance(v, list):
+ body += struct.pack("<IIQ", 9, 7, len(v)) + bytes(v)
+ elif isinstance(v, int):
body += struct.pack("<II", 4, v)
else:
vb = v.encode("utf-8")
@@ -491,6 +493,95 @@ def test_gemma4_finetune_pairs_by_functional_metadata(tmp_path, projection_dim,
assert mmproj_matches_model_family(str(model), str(projector)) == (projection_dim == 5376)
[email protected]("arch", ["qwen35", "qwen35moe"])
+ "projection_dim, deepstack, paired",
+ [(2048, [False, False], True), (1024, [False, False], False), (2048, [False, True], False)],
+)
+def test_qwen35_projector_from_another_quantizer_pairs_by_function(
+ tmp_path, arch, projection_dim, deepstack, paired
+):
+ """#6305: an LM Studio Qwen3.6 weight next to Unsloth's projector; Qwen3-VL's deepstack one stays out."""
+ model = _gguf_with_general(
+ tmp_path / "Qwen3.6-35B-A3B-Q4_K_M.gguf",
+ {
+ "general.architecture": arch,
+ "general.basename": "Qwen_Qwen3.6",
+ f"{arch}.embedding_length": 2048,
+ },
+ )
+ projector = _gguf_with_general(
+ tmp_path / "mmproj-F16.gguf",
+ {
+ "general.architecture": "clip",
+ "general.type": "mmproj",
+ "general.basename": "Qwen3.6-35B-A3B",
+ "general.base_model.0.repo_url": "https://huggingface.co/Qwen/Qwen3.6-35B-A3B",
+ "clip.projector_type": "qwen3vl_merger",
+ "clip.vision.projection_dim": projection_dim,
+ "clip.vision.is_deepstack_layers": deepstack,
+ },
+ )
+ assert detect_mmproj_file(str(model)) == (str(projector.resolve()) if paired else None)
+ assert mmproj_matches_model_family(str(model), str(projector)) == paired
+
+
[email protected]("weight_name", ["Qwen_Qwen3.5 35B A3B", "Qwen3.5 Uncensored"])
+def test_qwen35_same_width_projector_of_another_size_is_not_picked(tmp_path, weight_name):
+ """Qwen3.5 2B and 35B-A3B share width 2048, not vision towers; bartowski-style names tie otherwise."""
+ model = _gguf_with_general(
+ tmp_path / "Qwen3.5-35B-A3B-Q4_K_M.gguf",
+ {
+ "general.architecture": "qwen35moe",
+ "general.name": weight_name,
+ "general.basename": "Qwen_Qwen3.5",
+ "qwen35moe.embedding_length": 2048,
+ },
+ )
+ projectors = {}
+ for size in ("2B", "35B-A3B"):
+ projectors[size] = _gguf_with_general(
+ tmp_path / f"mmproj-Qwen_Qwen3.5-{size}-bf16.gguf",
+ {
+ "general.architecture": "clip",
+ "general.type": "mmproj",
+ "general.name": f"Qwen3.5 {size.replace('-', ' ')}",
+ "general.basename": "Qwen3.5",
+ "clip.projector_type": "qwen3vl_merger",
+ "clip.vision.projection_dim": 2048,
+ "clip.vision.is_deepstack_layers": [False, False],
+ },
+ )
+ assert detect_mmproj_file(str(model)) == str(projectors["35B-A3B"].resolve())
+
+
+def test_size_names_do_not_override_an_exact_repo_match(tmp_path):
+ """Converters name MoE sizes differently; the shared base_model URL is authoritative."""
+ url = "https://huggingface.co/Qwen/Qwen3.6-35B-A3B"
+ model = _gguf_with_general(
+ tmp_path / "Qwen3.6-35B-A3B-Q4_K_M.gguf",
+ {
+ "general.architecture": "qwen35moe",
+ "general.name": "Qwen3.6 35B",
+ "general.base_model.0.repo_url": url,
+ "qwen35moe.embedding_length": 2048,
+ },
+ )
+ projector = _gguf_with_general(
+ tmp_path / "mmproj-F16.gguf",
+ {
+ "general.architecture": "clip",
+ "general.type": "mmproj",
+ "general.name": "Qwen3.6 A3B",
+ "general.base_model.0.repo_url": url,
+ "clip.projector_type": "qwen3vl_merger",
+ "clip.vision.projection_dim": 2048,
+ "clip.vision.is_deepstack_layers": [False, False],
+ },
+ )
+ assert detect_mmproj_file(str(model)) == str(projector.resolve())
+
+
def test_mmproj_rejection_names_mismatched_fields(tmp_path, capsys):
model = _gguf_with_general(tmp_path / "model.gguf", {"general.basename": "Foo"})
_gguf_with_general(tmp_path / "mmproj.gguf", {"general.basename": "Bar"})
diff --git a/studio/backend/utils/models/gguf_metadata.py b/studio/backend/utils/models/gguf_metadata.py
index d472d639b6c..d23a935f9e5 100644
--- a/studio/backend/utils/models/gguf_metadata.py
+++ b/studio/backend/utils/models/gguf_metadata.py
@@ -7,6 +7,7 @@ pair weights and projectors via ``general.base_model.0.repo_url``."""
from __future__ import annotations
import os
+import re
import struct
import threading
from pathlib import Path
@@ -631,6 +632,17 @@ def _parse_gguf_bool(path: str, wanted_key: str) -> Optional[bool]:
if len(bbyte) < 1:
break
return bbyte[0] != 0
+ if key == wanted_key and vtype == 9: # BOOL array: whether any is set
+ head = f.read(12)
+ if len(head) < 12:
+ break
+ atype, alen = struct.unpack("<IQ", head)
+ if atype != 7 or alen > 1 << 20:
+ break
+ values = f.read(alen)
+ if len(values) < alen:
+ break
+ return any(values)
if not _skip_gguf_value(f, vtype):
break
except (struct.error, UnicodeDecodeError):
@@ -1025,13 +1037,28 @@ def _weight_url_looks_like_derivative_of_projector(weight_url: str, projector_ur
return _slug_extends_base(weight_slug, projector_slug)
+# Finetunes inherit the vision tower, so these pair by projector type + width, not branding.
+_FUNCTIONAL_PROJECTOR_TYPES = {
+ "gemma4": "gemma4v",
+ "qwen35": "qwen3vl_merger",
+ "qwen35moe": "qwen3vl_merger",
+}
+
+
def mmproj_functional_match(weight_path: str, mmproj_path: str) -> tuple[Optional[bool], str]:
- """Gemma 4 only: pair by projector type + projection dim, not branding. None = unknown."""
- if read_gguf_architecture(weight_path) != "gemma4":
+ """Gemma 4 and Qwen3.5 / 3.6: pair by projector type + projection dim, not branding. None = unknown."""
+ arch = read_gguf_architecture(weight_path)
+ expected_type = _FUNCTIONAL_PROJECTOR_TYPES.get(arch or "")
+ if expected_type is None:
return None, ""
projector_type = read_mmproj_vision_projector_type(mmproj_path)
- if projector_type != "gemma4v":
+ if projector_type != expected_type:
return None, ""
+ if expected_type == "qwen3vl_merger" and _read_gguf_bool(
+ mmproj_path, "clip.vision.is_deepstack_layers"
+ ):
+ # Qwen3-VL shares the type and width, but its deepstack output is wider and llama-server refuses it.
+ return False, "Qwen3-VL deepstack projector"
embedding_length = read_gguf_embedding_length(weight_path)
dims = _parse_gguf_arch_uints(mmproj_path, frozenset({"vision.projection_dim"})) or {}
projection_dim = dims.get("vision.projection_dim")
@@ -1039,12 +1066,32 @@ def mmproj_functional_match(weight_path: str, mmproj_path: str) -> tuple[Optiona
return None, ""
if embedding_length != projection_dim:
return False, (
- f"gemma4.embedding_length {embedding_length} != "
+ f"{arch}.embedding_length {embedding_length} != "
f"clip.vision.projection_dim {projection_dim}"
)
+ # Sizes share widths (Qwen3.5 2B and 35B-A3B are both 2048) but not vision towers, so a
+ # size conflict withholds the rescue and leaves the verdict to the identity metadata.
+ weight_sizes = _model_size_tokens(weight_path)
+ projector_sizes = _model_size_tokens(mmproj_path)
+ if weight_sizes and projector_sizes and weight_sizes.isdisjoint(projector_sizes):
+ return None, ""
return True, ""
+_SIZE_TOKEN_RE = re.compile(r"[ae]?\d+(?:\.\d+)?b", re.IGNORECASE)
+
+
+def _model_size_tokens(path: str) -> frozenset[str]:
+ """Parameter-count tokens (``35b``, ``a3b``, ``e4b``) in the name, basename and filename."""
+ meta = read_gguf_general_metadata(path) or {}
+ text = " ".join(
+ (meta.get("general.name") or "", meta.get("general.basename") or "", Path(path).stem)
+ )
+ return frozenset(
+ token.lower() for token in re.split(r"[\s_\-]+", text) if _SIZE_TOKEN_RE.fullmatch(token)
+ )
+
+
def pairing_score(
weight_meta: Optional[Dict[str, str]], mmproj_meta: Optional[Dict[str, str]]
) -> int: