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: 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.py
index 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_ocr
from 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 a
turn 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.py
index 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.py
index 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 Image
diff --git a/studio/backend/core/inference/worker.py b/studio/backend/core/inference/worker.py
index 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) -> Non
def _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 = None
image_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.txt
index 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 extras
jiwer==4.0.0 # WER/CER metrics for vision OCR save-merge benchmarks
omegaconf==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.13
einx<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.py
new file mode 100644
index 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_size
diff --git a/studio/backend/utils/hardware/hardware.py b/studio/backend/utils/hardware/hardware.py
index 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] = Non
except Exception:
pass
if 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.py
index 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) -> boo
return 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 exact
tier 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.py
new file mode 100644
index 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}"