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
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""Hand-added projector lookup for a remote (-hf) load over its HF cache repo (#9286)."""
from __future__ import annotations
import struct
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
from utils.models.model_config import ( # noqa: E402
_hf_cache_repo_dir,
_hf_cached_local_mmproj,
_local_gguf_companion_search_root,
detect_mmproj_file,
)
_GGUF_MAGIC = 0x46554747
def _gguf_with_general(path: Path, fields: dict) -> Path:
body = b""
for k, v in fields.items():
kb = k.encode("utf-8")
vb = v.encode("utf-8")
body += struct.pack("<Q", len(kb)) + kb
body += struct.pack("<I", 8)
body += struct.pack("<Q", len(vb)) + vb
header = struct.pack("<IIQQ", _GGUF_MAGIC, 3, 0, len(fields))
path.parent.mkdir(parents = True, exist_ok = True)
path.write_bytes(header + body)
return path
def _hf_repo(tmp_path: Path, repo_name: str = "models--org--Model-GGUF") -> tuple[Path, Path]:
repo = tmp_path / repo_name
snapshot = repo / "snapshots" / "deadbeef"
snapshot.mkdir(parents = True)
weight = _gguf_with_general(
snapshot / "model-Q4_K_M.gguf",
{"general.name": "Model", "general.basename": "Model", "general.architecture": "qwen3vl"},
)
return repo, weight
def _projector(path: Path, basename: str | None = None) -> Path:
fields = {"general.type": "mmproj", "general.architecture": "qwen3vl"}
if basename is not None:
fields["general.basename"] = basename
return _gguf_with_general(path, fields)
def test_the_repo_dir_is_named_from_a_cached_weight(tmp_path):
repo, weight = _hf_repo(tmp_path)
assert _hf_cache_repo_dir(str(weight)) == str(repo)
def test_a_quant_subdir_still_names_the_repo_dir(tmp_path):
repo, weight = _hf_repo(tmp_path)
quant_dir = weight.parent / "Q4_K_M"
quant_dir.mkdir()
weight = weight.rename(quant_dir / weight.name)
assert _hf_cache_repo_dir(str(weight)) == str(repo)
def test_a_plain_layout_names_no_repo_dir(tmp_path):
model_dir = tmp_path / "MyModel"
model_dir.mkdir()
weight = _gguf_with_general(
model_dir / "model.gguf", {"general.name": "Model", "general.architecture": "qwen3vl"}
)
assert _hf_cache_repo_dir(str(weight)) is None
projector = _projector(model_dir / "mmproj-F16.gguf")
assert _hf_cached_local_mmproj(str(weight)) == str(projector.resolve())
def test_a_projector_beside_the_weight_is_found(tmp_path):
"""Where Studio's own Reveal in Folder lands, so the likeliest placement."""
_repo, weight = _hf_repo(tmp_path)
projector = _projector(weight.parent / "mmproj-kquant.gguf")
assert _hf_cached_local_mmproj(str(weight)) == str(projector.resolve())
def test_a_projector_at_the_repo_root_is_found(tmp_path):
"""Found one or two levels above the snapshot."""
repo, weight = _hf_repo(tmp_path)
projector = _projector(repo / "mmproj-kquant.gguf")
assert _hf_cached_local_mmproj(str(weight)) == str(projector.resolve())
def test_a_projector_in_the_snapshots_container_is_found(tmp_path):
repo, weight = _hf_repo(tmp_path)
projector = _projector(repo / "snapshots" / "mmproj-kquant.gguf")
assert _hf_cached_local_mmproj(str(weight)) == str(projector.resolve())
def test_a_sibling_repo_and_the_cache_root_stay_out_of_reach(tmp_path):
"""Never above models--<repo>: no borrowing another repo's projector."""
_repo, weight = _hf_repo(tmp_path)
sibling, _sibling_weight = _hf_repo(tmp_path, "models--org--Other-GGUF")
_projector(sibling / "mmproj-kquant.gguf")
_projector(tmp_path / "mmproj-kquant.gguf")
assert _hf_cached_local_mmproj(str(weight)) is None
def test_a_projector_for_another_model_is_refused(tmp_path):
"""Widening the walk widens what can be mispaired, so metadata still decides."""
repo, weight = _hf_repo(tmp_path)
_projector(repo / "mmproj-kquant.gguf", basename = "SomeOtherModel")
assert _hf_cached_local_mmproj(str(weight)) is None
def test_the_snapshots_own_projector_wins_when_the_far_one_cannot_pair(tmp_path):
repo, weight = _hf_repo(tmp_path)
_projector(repo / "mmproj-kquant.gguf", basename = "SomeOtherModel")
near = _projector(weight.parent / "mmproj-F16.gguf", basename = "Model")
assert _hf_cached_local_mmproj(str(weight)) == str(near.resolve())
def test_an_empty_projector_is_not_named(tmp_path):
"""An interrupted copy is a file llama-server cannot open."""
repo, weight = _hf_repo(tmp_path)
(repo / "mmproj-kquant.gguf").write_bytes(b"")
assert _hf_cached_local_mmproj(str(weight)) is None
def test_a_local_selection_keeps_the_root_it_always_had(tmp_path):
"""The local-selection search root is unchanged."""
repo, weight = _hf_repo(tmp_path)
_projector(repo / "mmproj-kquant.gguf")
root = _local_gguf_companion_search_root(str(weight.parent), str(weight))
assert root == str(weight.parent)
assert detect_mmproj_file(str(weight), search_root = root) is None
def _resident(weight: Path, **overrides):
from types import SimpleNamespace
from core.inference.llama_cpp import GgufLoadIntent, LlamaCppBackend
state = dict(
_is_vision = False,
_disable_vision = False,
_hf_repo = "org/Model-GGUF",
_gguf_path = str(weight),
_last_load_intent = GgufLoadIntent(model_identifier = "org/Model-GGUF", is_vision = False),
)
state.update(overrides)
backend = SimpleNamespace(**state)
return lambda extras = (): LlamaCppBackend._hand_added_projector_since_launch(
backend, list(extras)
)
def test_a_projector_dropped_after_a_text_only_load_forces_a_reload(tmp_path):
_repo, weight = _hf_repo(tmp_path)
probe = _resident(weight)
assert probe() is False
_projector(weight.parent / "mmproj-F16.gguf")
assert probe() is True
assert probe(["--no-mmproj"]) is False
def test_the_reload_trigger_leaves_other_residents_alone(tmp_path):
from core.inference.llama_cpp import GgufLoadIntent
_repo, weight = _hf_repo(tmp_path)
_projector(weight.parent / "mmproj-F16.gguf")
assert _resident(weight, _is_vision = True)() is False
assert _resident(weight, _disable_vision = True)() is False
assert _resident(weight, _hf_repo = None)() is False
vision_intent = GgufLoadIntent(model_identifier = "org/Model-GGUF", is_vision = True)
assert _resident(weight, _last_load_intent = vision_intent)() is False