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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
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.pyindex 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.pyindex 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 annotationsimport os+import reimport structimport threadingfrom pathlib import Path@@ -631,6 +632,17 @@ def _parse_gguf_bool(path: str, wanted_key: str) -> Optional[bool]:if len(bbyte) < 1:breakreturn 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):breakexcept (struct.error, UnicodeDecodeError):@@ -1025,13 +1037,28 @@ def _weight_url_looks_like_derivative_of_projector(weight_url: str, projector_urreturn _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[Optionareturn 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: