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: load and run DeepSeek-OCR and DeepSeek-OCR-2 (#13310)
Daniel Handabf5ab66345
diff --git a/studio/backend/core/inference/inference.py b/studio/backend/core/inference/inference.pyindex cdc17ebcf0b..b41c88432e5 100644--- a/studio/backend/core/inference/inference.py+++ b/studio/backend/core/inference/inference.py@@ -35,6 +35,7 @@ from core.inference.runtime_context import (runtime_context_length,)from core.inference.message_content import content_to_text, named_turn+from core.inference.model_ids import is_deepseek_ocrfrom core.inference.chat_eos import (chat_eos_repair,resolve_chat_turn_end_eos_ids_using,@@ -544,6 +545,14 @@ def _prompt_already_has_bos(tokenizer, prompt):return bool(len(ids)) and ids[0] == bos_token_id+_MISSING = object()+++class _OcrNeedsImageError(ValueError):+ public = True+ openai_param = "messages"++def _without_image_parts(messages) -> list[dict]:"""The same conversation with every image placeholder dropped, collapsing aturn back to its text when that is all it held."""@@ -1419,6 +1428,12 @@ class InferenceBackend:tokenizer = getattr(tokenizer, "tokenizer", tokenizer)top_k = self._normalize_top_k(top_k)+ if is_deepseek_ocr(model_info.get("model")):+ yield from self._generate_deepseek_ocr_response(+ messages, image, images, max_new_tokens, cancel_event, _adapter_state, stop+ )+ return+if is_vision and (image or images):# Verify the stored processor can handle images; FastVisionModel may# return a raw tokenizer instead of a ProcessorMixin (e.g. Gemma-3).@@ -1609,6 +1624,77 @@ class InferenceBackend:stop = stop,)+ def _generate_deepseek_ocr_response(+ self,+ messages,+ image,+ images,+ max_new_tokens,+ cancel_event,+ _adapter_state,+ stop = None,+ ) -> Generator[str, None, None]:+ """DeepSeek-OCR ships no processor or chat template: its own infer() tiles the image."""+ import tempfile++ from core.inference.chat_template_helpers import last_user_text++ self.last_generation_stats = None+ picture = image if image is not None else next(iter(images or ()), None)+ if picture is None:+ raise _OcrNeedsImageError(+ "DeepSeek-OCR reads text from an image: attach one to your message."+ )+ model_info = self.models[self.active_model_name]+ tokenizer = model_info.get("tokenizer") or model_info.get("processor")+ prompt = "<image>\n" + (last_user_text(messages) or "Free OCR.")+ infer = model_info["model"].infer+ # infer() hardcodes max_new_tokens=8192 and no stopping criteria: bound the generate() it calls.+ owner = infer.__self__+ previous = owner.__dict__.get("generate", _MISSING)+ generate = owner.generate+ stopping_criteria = self._cancel_stopping_criteria(cancel_event)++ def bounded_generate(*args, **kwargs):+ if max_new_tokens:+ kwargs["max_new_tokens"] = min(+ kwargs.get("max_new_tokens", max_new_tokens), max_new_tokens+ )+ if stopping_criteria is not None:+ kwargs["stopping_criteria"] = stopping_criteria+ return generate(*args, **kwargs)++ with tempfile.TemporaryDirectory() as tmp, self._generation_lock:+ path = str(Path(tmp) / "image.png")+ picture.convert("RGB").save(path)+ self._apply_adapter_state(_adapter_state)+ owner.generate = bounded_generate+ try:+ # Gundam preset from each model card: 640 px tiles for v1, 768 for OCR-2.+ text = infer(+ getattr(tokenizer, "tokenizer", tokenizer),+ prompt = prompt,+ image_file = path,+ output_path = tmp,+ base_size = 1024,+ image_size = 640+ if "DeepseekOCRForCausalLM" in model_info["model"].config.architectures+ else 768,+ crop_mode = True,+ save_results = False,+ eval_mode = True,+ )+ finally:+ if previous is _MISSING:+ del owner.generate+ else:+ owner.generate = previous+ text = text or ""+ for sequence in stop or ():+ if sequence and sequence in text:+ text = text[: text.index(sequence)]+ yield text+def _generate_vision_response(self,messages,diff --git a/studio/backend/core/inference/model_ids.py b/studio/backend/core/inference/model_ids.pyindex 13e03ec56b6..21429233bff 100644--- a/studio/backend/core/inference/model_ids.py+++ b/studio/backend/core/inference/model_ids.py@@ -161,3 +161,14 @@ def mlx_bnb_substitutions(repos: Iterable[str]) -> list[tuple[str, str]]:if base:swaps.append((repo, base))return swaps+++_DEEPSEEK_OCR_ARCHITECTURES = frozenset({"DeepseekOCRForCausalLM", "DeepseekOCR2ForCausalLM"})+# infer() tiles pages itself, so the 800 px chat cap blurs text; still bounded (many images per request).+DEEPSEEK_OCR_MAX_IMAGE_SIDE = 2048+++def is_deepseek_ocr(model) -> bool:+ """A loaded DeepSeek-OCR model, which generates through its own infer()."""+ architectures = getattr(getattr(model, "config", None), "architectures", None) or ()+ return hasattr(model, "infer") and not _DEEPSEEK_OCR_ARCHITECTURES.isdisjoint(architectures)diff --git a/studio/backend/core/inference/orchestrator.py b/studio/backend/core/inference/orchestrator.pyindex 769d1d65064..8bf8c85b8be 100644--- a/studio/backend/core/inference/orchestrator.py+++ b/studio/backend/core/inference/orchestrator.py@@ -408,6 +408,7 @@ def _mirrored_model_entry(model_info: dict, model_name: str) -> dict:"audio_edit": model_info.get("audio_edit"),"audio_music": model_info.get("audio_music"),"audio_cpp_backend": model_info.get("audio_cpp_backend"),+ "max_image_side": model_info.get("max_image_side"),}@@ -4024,6 +4025,8 @@ class InferenceOrchestrator:"""Resize image preserving aspect ratio (runs locally, no ML imports)."""if img is None:return None+ entry = self.models.get(self.active_model_name) or {}+ max_size = max(max_size, entry.get("max_image_side") or 0)if img.size[0] > max_size or img.size[1] > max_size:from PIL import Imagediff --git a/studio/backend/core/inference/worker.py b/studio/backend/core/inference/worker.pyindex 9349cb1963c..5e7fa0a59b1 100644--- a/studio/backend/core/inference/worker.py+++ b/studio/backend/core/inference/worker.py@@ -232,6 +232,17 @@ def _decode_image(image_base64: str):return Image.open(BytesIO(image_data))+def _active_model_is_deepseek_ocr(backend) -> bool:+ from core.inference.model_ids import is_deepseek_ocr++ models = getattr(backend, "models", None)+ if not isinstance(models, dict):+ return False+ return is_deepseek_ocr(+ (models.get(getattr(backend, "active_model_name", None)) or {}).get("model")+ )++def _resize_image(img, max_size: int = 800):"""Resize image while maintaining aspect ratio."""if img is None:@@ -766,6 +777,11 @@ def _handle_load(backend, config: dict, resp_queue: Any) -> None:"has_audio_input": getattr(mc, "has_audio_input", False),"can_batch": _load_can_batch(backend),}+ if _active_model_is_deepseek_ocr(backend):+ from core.inference.model_ids import DEEPSEEK_OCR_MAX_IMAGE_SIDE++ # The route resizes before the IPC hop, so it needs the raised cap too.+ model_info["max_image_side"] = DEEPSEEK_OCR_MAX_IMAGE_SIDE_bm = getattr(backend, "models", {}) or {}_entry = (_bm.get(mc.identifier) or _bm.get(getattr(backend, "active_model_name", None)) or {}@@ -1067,14 +1083,16 @@ def _dispatch_generate(backend, cmd: dict, resp_queue: Any, cancel_event) -> Nondef _generation_kwargs(backend, cmd: dict, cancel_event) -> dict:+ resize = _resize_image+ if _active_model_is_deepseek_ocr(backend):+ from core.inference.model_ids import DEEPSEEK_OCR_MAX_IMAGE_SIDE+ resize = functools.partial(_resize_image, max_size = DEEPSEEK_OCR_MAX_IMAGE_SIDE)image = Noneimage_b64 = cmd.get("image_base64")if image_b64:- image = _resize_image(_decode_image(image_b64))+ image = resize(_decode_image(image_b64))images = [- _resize_image(_decode_image(encoded))- for encoded in cmd.get("images_base64") or ()- if encoded+ resize(_decode_image(encoded)) for encoded in cmd.get("images_base64") or () if encoded]gen_kwargs = {diff --git a/studio/backend/requirements/extras.txt b/studio/backend/requirements/extras.txtindex f047c3c2a95..f41e2f36ce4 100644--- a/studio/backend/requirements/extras.txt+++ b/studio/backend/requirements/extras.txt@@ -14,6 +14,10 @@ scikit-learn==1.8.0; sys_platform == "win32" and platform_machine == "ARM64"# Additional extrasjiwer==4.0.0 # WER/CER metrics for vision OCR save-merge benchmarksomegaconf==2.3.1+# Imported only by Hub remote code (DeepSeek-OCR and DeepSeek-OCR-2 modeling files), so a+# grep of this repo finds no user; without them those models fail to load (#8732).+addict==2.4.0+easydict==1.13einx<0.4.3; sys_platform == "win32"# einx dropped 3.9 in 0.4.0, so the non-Windows pin splits at 3.10.einx==0.4.3; sys_platform != "win32" and python_version >= "3.10"diff --git a/studio/backend/tests/test_deepseek_ocr_inference.py b/studio/backend/tests/test_deepseek_ocr_inference.pynew file mode 100644index 00000000000..d2031db0c68--- /dev/null+++ b/studio/backend/tests/test_deepseek_ocr_inference.py@@ -0,0 +1,246 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""DeepSeek-OCR loads on the transformers 4.57.6 sidecar and generates through its own infer() (#8732)."""++from __future__ import annotations++import base64+import importlib+import importlib.machinery+import io+import json+import sys+import threading+import types+from pathlib import Path+from unittest.mock import MagicMock++import pytest++_BACKEND = Path(__file__).resolve().parent.parent+if str(_BACKEND) not in sys.path:+ sys.path.insert(0, str(_BACKEND))++_STUBBED: list[str] = []+++def _stub_if_missing(+ name,+ attrs = (),+ named_spec = False,+):+ """Same helper as test_chat_prompt_bos.py: core.inference.inference imports unsloth, trl and peft."""+ if name in sys.modules:+ return+ try:+ importlib.import_module(name)+ return+ except Exception: # noqa: BLE001+ pass+ _STUBBED.append(name)+ module = types.ModuleType(name)+ module.__spec__ = importlib.machinery.ModuleSpec(name, None) if named_spec else None+ module.__version__ = "0.0.0"+ module.__getattr__ = lambda _attr: MagicMock()+ for attr in attrs:+ setattr(module, attr, MagicMock())+ sys.modules[name] = module+ parent, _, child = name.rpartition(".")+ if parent and parent in sys.modules:+ setattr(sys.modules[parent], child, module)+++for _torchao in (+ "torchao",+ "torchao.prototype",+ "torchao.prototype.safetensors",+ "torchao.prototype.safetensors.safetensors_support",+ "torchao.prototype.safetensors.safetensors_utils",+ "torchao.quantization",+ "torchao.dtypes",+ "torchao.float8",+ "torchao.utils",+):+ _stub_if_missing(_torchao, named_spec = True)++_stub_if_missing("unsloth", ("FastLanguageModel", "FastVisionModel", "is_bfloat16_supported"))+_stub_if_missing("unsloth.chat_templates", ("get_chat_template",))+_stub_if_missing("unsloth_zoo")+_stub_if_missing("trl", ("SFTTrainer", "SFTConfig"))+_stub_if_missing("peft", ("PeftModel", "PeftModelForCausalLM"))++from core.inference.inference import InferenceBackend # noqa: E402++for _name in reversed(_STUBBED):+ sys.modules.pop(_name, None)++import utils.transformers_version as tv # noqa: E402++_OCR2 = {+ "architectures": ["DeepseekOCR2ForCausalLM"],+ "model_type": "deepseek_vl_v2",+ "auto_map": {"AutoModel": "modeling_deepseekocr2.DeepseekOCR2ForCausalLM"},+}+++def _local_model(tmp_path: Path, config: dict) -> str:+ (tmp_path / "config.json").write_text(json.dumps(config), encoding = "utf-8")+ return str(tmp_path)++[email protected]("architecture", ["DeepseekOCRForCausalLM", "DeepseekOCR2ForCausalLM"])+def test_deepseek_ocr_routes_to_the_457_sidecar(tmp_path, monkeypatch, architecture):+ monkeypatch.setattr(tv.sys, "platform", "linux")+ path = _local_model(tmp_path, {**_OCR2, "architectures": [architecture]})+ assert tv.get_transformers_tier(path, probe = False) == "457"+++def test_deepseek_vl2_shares_the_model_type_but_keeps_its_tier(tmp_path, monkeypatch):+ monkeypatch.setattr(tv.sys, "platform", "linux")+ path = _local_model(tmp_path, {**_OCR2, "architectures": ["DeepseekVLV2ForCausalLM"]})+ assert tv.get_transformers_tier(path, probe = False) != "457"+++def test_macos_keeps_deepseek_ocr_on_mlx(tmp_path, monkeypatch):+ monkeypatch.setattr(tv.sys, "platform", "darwin")+ assert tv.get_transformers_tier(_local_model(tmp_path, _OCR2), probe = False) != "457"+++class _OcrModel:+ config = types.SimpleNamespace(architectures = ["DeepseekOCR2ForCausalLM"])++ def __init__(self):+ self.calls = []+ self.generate_kwargs = None++ def generate(self, **kwargs):+ self.generate_kwargs = kwargs+ return "ids"++ def infer(self, tokenizer, **kwargs):+ self.calls.append((tokenizer, kwargs, Path(kwargs["image_file"]).is_file()))+ self.generate(max_new_tokens = 8192) # what the real infer() hardcodes+ return "UNSLOTH 8732 OCR"+++def _backend(model):+ backend = InferenceBackend.__new__(InferenceBackend)+ backend._generation_lock = threading.Lock()+ backend.active_model_name = "unsloth/DeepSeek-OCR-2"+ backend.models = {+ backend.active_model_name: {"model": model, "tokenizer": "tok", "is_vision": True}+ }+ return backend+++def _generate(+ backend,+ image,+ text = "Free OCR.",+ **kwargs,+):+ return list(+ backend._generate_chat_response_inner(+ messages = [{"role": "user", "content": text}],+ image = image,+ **kwargs,+ )+ )+++def _image():+ return pytest.importorskip("PIL.Image").new("RGB", (32, 32), "white")+++def test_chat_runs_the_models_own_infer_on_the_attached_image():+ model = _OcrModel()++ assert _generate(_backend(model), _image()) == ["UNSLOTH 8732 OCR"]+ tokenizer, kwargs, image_was_written = model.calls[0]+ assert (tokenizer, kwargs["prompt"], kwargs["eval_mode"]) == ("tok", "<image>\nFree OCR.", True)+ assert image_was_written+++def test_the_request_bounds_and_can_cancel_the_generate_infer_runs():+ model = _OcrModel()+ _generate(_backend(model), _image(), max_new_tokens = 300, cancel_event = threading.Event())++ assert model.generate_kwargs["max_new_tokens"] == 300+ assert model.generate_kwargs["stopping_criteria"] is not None+ assert "generate" not in vars(model), "the bound generate must not outlive the request"+++def test_the_requested_adapter_state_is_applied_under_the_generation_lock():+ model = _OcrModel()+ backend = _backend(model)+ applied = []+ backend._apply_adapter_state = lambda state: applied.append(+ (state, backend._generation_lock.locked())+ )+ _generate(backend, _image(), _adapter_state = False)++ assert applied == [(False, True)]+++def test_chat_without_an_image_gets_a_client_visible_error():+ with pytest.raises(ValueError, match = "attach one") as raised:+ _generate(_backend(_OcrModel()), image = None)+ assert (raised.value.public, raised.value.openai_param) == (True, "messages")+++def test_deepseek_ocr_does_not_count_as_a_transformers_5_model(tmp_path, monkeypatch):+ monkeypatch.setattr(tv.sys, "platform", "linux")+ assert tv.needs_transformers_5(_local_model(tmp_path, _OCR2)) is False+++def test_the_request_stop_sequence_ends_the_ocr_text():+ assert _generate(_backend(_OcrModel()), _image(), stop = [" 8732"]) == ["UNSLOTH"]+++def _page_b64():+ Image = pytest.importorskip("PIL.Image")+ buffer = io.BytesIO()+ Image.new("RGB", (1700, 2200), "white").save(buffer, "PNG")+ return base64.b64encode(buffer.getvalue()).decode()+++def test_the_worker_raises_the_image_cap_only_for_deepseek_ocr():+ from core.inference import worker++ cmd = {"messages": [], "image_base64": _page_b64()}+ other = types.SimpleNamespace(+ config = types.SimpleNamespace(architectures = ["Qwen2VLForConditionalGeneration"])+ )++ def longest_side(model):+ return max(worker._generation_kwargs(_backend(model), cmd, None)["image"].size)++ assert longest_side(_OcrModel()) == 2048+ assert longest_side(other) == 800+++def test_the_route_side_resize_uses_the_cap_the_worker_reported():+ Image = pytest.importorskip("PIL.Image")+ from core.inference.orchestrator import InferenceOrchestrator, _mirrored_model_entry++ orchestrator = InferenceOrchestrator.__new__(InferenceOrchestrator)+ orchestrator.active_model_name = "m"+ page = Image.new("RGB", (1700, 2200), "white")++ orchestrator.models = {"m": _mirrored_model_entry({"max_image_side": 2048}, "m")}+ assert max(orchestrator.resize_image(page).size) == 2048+ orchestrator.models = {"m": _mirrored_model_entry({}, "m")}+ assert max(orchestrator.resize_image(page).size) == 800+++ ("architecture", "image_size"),+ [("DeepseekOCRForCausalLM", 640), ("DeepseekOCR2ForCausalLM", 768)],+)+def test_each_model_gets_its_own_gundam_tile_size(architecture, image_size):+ model = _OcrModel()+ model.config = types.SimpleNamespace(architectures = [architecture])+ _generate(_backend(model), _image())++ assert model.calls[0][1]["image_size"] == image_sizediff --git a/studio/backend/utils/hardware/hardware.py b/studio/backend/utils/hardware/hardware.pyindex 168abe0fb5d..b1958397b7b 100644--- a/studio/backend/utils/hardware/hardware.py+++ b/studio/backend/utils/hardware/hardware.py@@ -5387,7 +5387,9 @@ def _load_config_for_gpu_estimate(model_name: str, hf_token: Optional[str] = Nonexcept Exception:passif tier != "default":- _tier_version = {"510": "5.10.x", "530": "5.3.0", "550": "5.5.0"}.get(tier, "5.x")+ _tier_version = {"457": "4.57.6", "510": "5.10.x", "530": "5.3.0", "550": "5.5.0"}.get(+ tier, "5.x"+ )logger.info("Config for '%s' not parseable by the default transformers; ""needs transformers %s and will be loaded with that sidecar in the worker",diff --git a/studio/backend/utils/transformers_version.py b/studio/backend/utils/transformers_version.pyindex b5861511553..239482946a8 100644--- a/studio/backend/utils/transformers_version.py+++ b/studio/backend/utils/transformers_version.py@@ -350,6 +350,12 @@ _TRANSFORMERS_510_MODEL_TYPES: set[str] = {"gemma4_unified_assistant",}+# DeepSeek-OCR remote code subclasses transformers 4.x DeepseekV2 modules (DeepseekV2MoE, removed in 5.x)+# and its config fails 5.x validation (kv_lora_rank: null), so it only loads on 4.57.x (#8732).+_TRANSFORMERS_457_ARCHITECTURES: frozenset[str] = frozenset(+ {"DeepseekOCRForCausalLM", "DeepseekOCR2ForCausalLM"}+)+# Architecture classes / model_type values requiring transformers 5.5.0 (via config.json)._TRANSFORMERS_550_ARCHITECTURES: set[str] = {"DiffusionGemmaForBlockDiffusion",@@ -405,6 +411,7 @@ _config_json_cache: dict[tuple[str, str | None], dict | None] = {}_config_needs_510_cache: dict[tuple[str, str | None], bool] = {}_config_needs_550_cache: dict[tuple[str, str | None], bool] = {}_config_needs_530_cache: dict[tuple[str, str | None], bool] = {}+_config_needs_457_cache: dict[tuple[str, str | None], bool] = {}# Process-lifetime probe cache, keyed by model_name + a local config.json signature (see# _probe_cache_key) so an overwritten checkpoint re-probes. Not keyed by Hub sha, so the@@ -414,6 +421,7 @@ _probe_tier_cache: dict[str, str] = {}TRANSFORMERS_510_VERSION = "5.10.2"TRANSFORMERS_550_VERSION = "5.5.0"TRANSFORMERS_530_VERSION = "5.3.0"+TRANSFORMERS_457_VERSION = "4.57.6"TRANSFORMERS_DEFAULT_VERSION = "5.5.0" if sys.version_info >= (3, 10) else "4.57.6"# Backwards-compat alias for the highest 5.x tier; prefer TRANSFORMERS_510_VERSION /# TRANSFORMERS_550_VERSION / TRANSFORMERS_530_VERSION.@@ -425,6 +433,8 @@ from utils.paths.storage_roots import studio_root as _studio_root # noqa: E402_VENV_T5_530_DIR = str(_studio_root() / ".venv_t5_530")_VENV_T5_550_DIR = str(_studio_root() / ".venv_t5_550")_VENV_T5_510_DIR = str(_studio_root() / ".venv_t5_510")+# Built at runtime on the first DeepSeek-OCR load; not pre-installed by setup.+_VENV_T4_457_DIR = str(_studio_root() / ".venv_t4_457")# Backwards-compat alias_VENV_T5_DIR = _VENV_T5_550_DIR@@ -437,7 +447,7 @@ _VENV_T5_LATEST_DIR = str(_studio_root() / ".venv_t5_latest")_LATEST_PIN_MARKER = ".unsloth_pinned_transformers"# Tier precedence: higher rank wins in _higher_tier. "latest" outranks every fixed tier.-_TIER_RANK = {"default": 0, "530": 1, "550": 2, "510": 3, "latest": 4}+_TIER_RANK = {"default": 0, "457": 0.5, "530": 1, "550": 2, "510": 3, "latest": 4}def _higher_tier(a: str, b: str) -> str:@@ -523,6 +533,21 @@ def activate_transformers_for_subprocess(model_name: str, hf_token: str | None =)_pp = os.environ.get("PYTHONPATH", "")os.environ["PYTHONPATH"] = _VENV_T5_550_DIR + (os.pathsep + _pp if _pp else "")+ elif tier == "457":+ if not _ensure_venv_t4_457_exists():+ raise RuntimeError(+ f"Cannot activate transformers {TRANSFORMERS_457_VERSION}: "+ f".venv_t4_457 missing at {_VENV_T4_457_DIR}"+ )+ if _VENV_T4_457_DIR not in sys.path:+ sys.path.insert(0, _VENV_T4_457_DIR)+ logger.info(+ "Prepended transformers %s venv to sys.path from %s",+ TRANSFORMERS_457_VERSION,+ _VENV_T4_457_DIR,+ )+ _pp = os.environ.get("PYTHONPATH", "")+ os.environ["PYTHONPATH"] = _VENV_T4_457_DIR + (os.pathsep + _pp if _pp else "")elif tier == "530":if not _ensure_venv_t5_530_exists():raise RuntimeError(@@ -1095,6 +1120,13 @@ def _config_needs_510(cfg: dict) -> bool:return _nemotron_h_needs_mlp_support(cfg)+def _config_needs_457(cfg: dict) -> bool:+ # macOS runs these through MLX, which needs the 5.x stack.+ if sys.platform == "darwin":+ return False+ return _config_matches_tier(cfg, _TRANSFORMERS_457_ARCHITECTURES, set())++def _config_needs_530(cfg: dict) -> bool:return _config_matches_tier(cfg,@@ -1151,6 +1183,19 @@ def _check_config_needs_530(model_name: str, hf_token: str | None = None) -> booreturn result+def _check_config_needs_457(model_name: str, hf_token: str | None = None) -> bool:+ """True if ``config.json`` is a DeepSeek-OCR checkpoint (cached like the 5.x checks)."""+ cache_key = _token_cache_key(model_name, hf_token)+ if cache_key in _config_needs_457_cache:+ return _config_needs_457_cache[cache_key]++ cfg = _load_config_json(model_name, hf_token)+ result = bool(cfg) and _config_needs_457(cfg)+ if _config_json_is_definitive(model_name, hf_token):+ _config_needs_457_cache[cache_key] = result+ return result++def _check_config_needs_510(model_name: str, hf_token: str | None = None) -> bool:"""Check ``config.json`` for Gemma 4 Unified / 12B architectures (authenticated with``hf_token``; cached by (model, token) only for a definitive read)."""@@ -1820,6 +1865,11 @@ def get_transformers_tier(if _safe_is_file(local_cfg):cfg = _load_config_json(model_name, hf_token)if cfg is not None:+ if _config_needs_457(cfg):+ logger.info(+ "Transformers tier 457 selected for %s (local config.json check)", model_name+ )+ return "457"if _config_needs_510(cfg):tier = _raise_tier_for_nested(cfg, "510")logger.info(@@ -1937,6 +1987,9 @@ def get_transformers_tier(return tier# --- Slow config fallbacks (network for HF IDs; authenticated with hf_token) --------+ if _check_config_needs_457(model_name, hf_token):+ logger.info("Transformers tier 457 selected for %s (config.json check)", model_name)+ return "457"if _check_config_needs_510(model_name, hf_token):tier = _raise_tier_for_nested(_load_config_json(model_name, hf_token), "510")logger.info("Transformers tier %s selected for %s (config.json check)", tier, model_name)@@ -2009,7 +2062,7 @@ def needs_transformers_5(model_name: str) -> bool:log-only parent caller never spawns sidecar probes (the worker re-resolves the exacttier with ``probe=True`` on the real activation path)."""- return get_transformers_tier(model_name, probe = False) != "default"+ return get_transformers_tier(model_name, probe = False) not in ("default", "457")# --- Version switching (in-process, used only by export) ---@@ -2084,6 +2137,12 @@ _VENV_T5_550_PACKAGES = (# Backwards-compat alias_VENV_T5_PACKAGES = _VENV_T5_550_PACKAGES+# transformers 4.57.6 refuses to import next to huggingface_hub 1.x.+_VENV_T4_457_PACKAGES = (+ f"transformers=={TRANSFORMERS_457_VERSION}",+ "huggingface_hub==0.36.2",+)+# Setup installs tiktoken best-effort, so the runtime must agree or it deletes the sidecar and# retries the same impossible install._OPTIONAL_SIDECAR_PACKAGES = frozenset({"tiktoken"})@@ -3220,6 +3279,14 @@ def _ensure_venv_t5_510_exists() -> bool:)+def _ensure_venv_t4_457_exists() -> bool:+ return _ensure_venv_dir(+ _VENV_T4_457_DIR,+ _VENV_T4_457_PACKAGES,+ f"transformers {TRANSFORMERS_457_VERSION}",+ )++def _ensure_venv_t5_exists() -> bool:"""Backwards-compat: ensure the Gemma 4 5.5 sidecar venv exists."""return _ensure_venv_t5_550_exists()diff --git a/tests/python/test_remote_code_requirements.py b/tests/python/test_remote_code_requirements.pynew file mode 100644index 00000000000..343f09de6eb--- /dev/null+++ b/tests/python/test_remote_code_requirements.py@@ -0,0 +1,34 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.++"""Hub remote code imports these, nothing in this repo does, so an unused-package sweep drops them."""++from __future__ import annotations++import re+from pathlib import Path++EXTRAS_TXT = (+ Path(__file__).resolve().parents[2] / "studio" / "backend" / "requirements" / "extras.txt"+)++REMOTE_CODE_PACKAGES = {+ "addict": ("unsloth/DeepSeek-OCR", "unsloth/DeepSeek-OCR-2"), # #8732+ "easydict": ("unsloth/DeepSeek-OCR",),+}+++def _requirement_names(path: Path) -> set[str]:+ names = set()+ for line in path.read_text(encoding = "utf-8").splitlines():+ line = line.split("#", 1)[0].strip()+ match = re.match(r"[A-Za-z0-9][A-Za-z0-9._-]*", line)+ if match:+ names.add(re.sub(r"[-_.]+", "-", match.group(0)).lower())+ return names+++def test_remote_code_packages_are_installed():+ names = _requirement_names(EXTRAS_TXT)+ missing = {pkg: models for pkg, models in REMOTE_CODE_PACKAGES.items() if pkg not in names}+ assert not missing, f"extras.txt dropped packages that model remote code imports: {missing}"