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.

Pin the DeepSeek OCR module fetch and import it from that fetch (#12454)

Daniel Han9a3ee8777cd7
diff --git a/studio/backend/core/training/trainer.py b/studio/backend/core/training/trainer.py
index 5e6eb888f92..61d87006184 100644
--- a/studio/backend/core/training/trainer.py
+++ b/studio/backend/core/training/trainer.py
@@ -4050,11 +4050,12 @@ class UnslothTrainer:
if is_deepseek_ocr:
logger.info("Detected DeepSeek OCR model\n")
if not _ensure_deepseek_ocr_installed():
+ # No manual snapshot_download instruction: it told the user to create
+ # a deepseek_ocr directory in the working directory, which is exactly
+ # the directory the loader must not pick up over the pinned source.
error_msg = (
- "Failed to install DeepSeek OCR module. "
- "Please install manually: "
- "from huggingface_hub import snapshot_download; "
- "snapshot_download('unsloth/DeepSeek-OCR', local_dir='deepseek_ocr')"
+ "Could not prepare the DeepSeek OCR module. "
+ "Check network access to huggingface.co and try again."
)
logger.error(error_msg)
self._update_progress(error = error_msg, is_training = False)
@@ -4670,37 +4671,26 @@ class UnslothTrainer:
def _ensure_deepseek_ocr_installed():
- """Auto-install the DeepSeek OCR module from HF hub if missing. Returns True if available
- (already installed or just installed)."""
- try:
- from deepseek_ocr.modeling_deepseekocr import format_messages
- logger.info("DeepSeek OCR module already available")
- return True
- except ImportError:
- pass
+ """Install the pinned DeepSeek OCR module if needed. Returns True if available.
+ Routed through the pinned-source machinery the other Hub-published sources use, so
+ the fetch is at a fixed revision and the import is checked to have come from it.
+ The old version decided "already available" with a bare
+ `from deepseek_ocr... import`, which any `deepseek_ocr` directory anywhere on
+ `sys.path` satisfied: that directory got imported and the real download was skipped.
+ """
try:
- logger.info("DeepSeek OCR module not found. Auto-installing from HuggingFace...")
- logger.info("\n Downloading DeepSeek OCR module from HuggingFace...\n")
-
- from huggingface_hub import snapshot_download
- import sys
- import os
+ logger.info("Preparing the DeepSeek OCR module...")
- script_dir = os.path.dirname(os.path.abspath(__file__))
- parent_dir = os.path.dirname(script_dir)
-
- local_dir = os.path.join(parent_dir, "deepseek_ocr")
-
- snapshot_download("unsloth/DeepSeek-OCR", local_dir = local_dir, local_dir_use_symlinks = False)
-
- if parent_dir not in sys.path:
- sys.path.insert(0, parent_dir)
+ from utils.third_party_source import (
+ ensure_deepseek_ocr_source,
+ import_deepseek_ocr_module,
+ )
- from deepseek_ocr.modeling_deepseekocr import format_messages
+ source = ensure_deepseek_ocr_source()
+ import_deepseek_ocr_module("deepseek_ocr.modeling_deepseekocr", source)
- logger.info("DeepSeek OCR module installed successfully")
- logger.info("DeepSeek OCR module installed successfully!\n")
+ logger.info("DeepSeek OCR module ready")
return True
except Exception as e:
diff --git a/studio/backend/tests/test_deepseek_ocr_pinned_source.py b/studio/backend/tests/test_deepseek_ocr_pinned_source.py
new file mode 100644
index 00000000000..c3604059b6a
--- /dev/null
+++ b/studio/backend/tests/test_deepseek_ocr_pinned_source.py
@@ -0,0 +1,376 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""The DeepSeek OCR modelling code is fetched from the Hub, so it must be pinned.
+
+Three properties, none of which the previous version of this path had:
+
+- the fetch names a revision, so the code that runs is the code that was reviewed
+ rather than whatever the branch points at when a user starts a training run,
+- the bytes are checked against committed digests before they are imported, so the
+ revision pin is not undone by a cached file edited in place,
+- the import comes from that fetch. The old code decided "already available" with a
+ bare `from deepseek_ocr.modeling_deepseekocr import ...`, which any directory named
+ `deepseek_ocr` anywhere on `sys.path` satisfied. That directory was imported, which
+ runs its code, and the real download was then skipped.
+
+No network: the fetch is stubbed and the pinned source is a local fixture, with the
+digest map pointed at the fixture's own bytes. What is exercised for real is which
+directory the import resolves to and what the install predicate accepts.
+"""
+
+import hashlib
+import re
+import sys
+from pathlib import Path
+
+import pytest
+
+from utils import third_party_source
+from utils.third_party_source import (
+ _DEEPSEEK_OCR_MODULES,
+ _DEEPSEEK_OCR_PACKAGE,
+ _DEEPSEEK_OCR_REPOSITORY,
+ _DEEPSEEK_OCR_REVISION,
+ _deepseek_ocr_installed,
+ ensure_deepseek_ocr_source,
+ import_deepseek_ocr_module,
+)
+
+
+BODY = "VALUE = 'pinned'\n"
+
+
[email protected](autouse = True)
+def _studio_home(tmp_path, monkeypatch):
+ """Point cache_root() at a temp dir so a test never touches a real install."""
+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "studio-home"))
+ yield
+ for name in [m for m in sys.modules if m.split(".")[0] == _DEEPSEEK_OCR_PACKAGE]:
+ del sys.modules[name]
+
+
+def pinned_digests(monkeypatch):
+ """Point the committed digest map at the fixture bodies these tests write."""
+ digest = hashlib.sha256(BODY.encode("utf-8")).hexdigest()
+ monkeypatch.setattr(
+ third_party_source,
+ "_DEEPSEEK_OCR_DIGESTS",
+ {name: digest for name in _DEEPSEEK_OCR_MODULES},
+ )
+
+
+def _write_package(root):
+ """A complete pinned package, as a successful install would leave it."""
+ package = Path(root) / _DEEPSEEK_OCR_PACKAGE
+ package.mkdir(parents = True, exist_ok = True)
+ (package / "__init__.py").write_text("", encoding = "utf-8")
+ for name in _DEEPSEEK_OCR_MODULES:
+ (package / name).write_text(BODY, encoding = "utf-8")
+ return package
+
+
+def _fake_download(
+ repo_id = None,
+ *args,
+ **kwargs,
+):
+ package = Path(kwargs["local_dir"])
+ package.mkdir(parents = True, exist_ok = True)
+ for name in _DEEPSEEK_OCR_MODULES:
+ (package / name).write_text(BODY, encoding = "utf-8")
+ return str(package)
+
+
+def test_the_pinned_revision_is_a_full_commit_sha():
+ """ "main" here would silently restore the unpinned behaviour."""
+ assert re.fullmatch(r"[0-9a-f]{40}", _DEEPSEEK_OCR_REVISION)
+
+
+def test_every_pinned_module_has_a_digest():
+ """A module without one would be fetched and imported unverified."""
+ assert set(third_party_source._DEEPSEEK_OCR_DIGESTS) == set(_DEEPSEEK_OCR_MODULES)
+ for digest in third_party_source._DEEPSEEK_OCR_DIGESTS.values():
+ assert re.fullmatch(r"[0-9a-f]{64}", digest)
+
+
+def test_the_fetch_names_the_revision_and_only_python(tmp_path, monkeypatch, pinned_digests):
+ calls = []
+
+ def recording_download(
+ repo_id = None,
+ *args,
+ **kwargs,
+ ):
+ calls.append((repo_id, kwargs))
+ return _fake_download(repo_id, *args, **kwargs)
+
+ monkeypatch.setattr("huggingface_hub.snapshot_download", recording_download)
+
+ source = ensure_deepseek_ocr_source()
+
+ assert len(calls) == 1
+ repo_id, kwargs = calls[0]
+ assert repo_id == _DEEPSEEK_OCR_REPOSITORY
+ assert kwargs["revision"] == _DEEPSEEK_OCR_REVISION
+ assert kwargs["allow_patterns"] == ["*.py"]
+ # Not inside the backend source tree: installing this must not put the backend's own
+ # directories on the import path as a side effect.
+ assert str(source).startswith(str(tmp_path))
+ assert _DEEPSEEK_OCR_REVISION in str(source)
+
+
+def test_a_complete_install_is_reused_without_fetching(monkeypatch, pinned_digests):
+ """Idempotent, and the second run is free."""
+
+ def refuse(*args, **kwargs):
+ raise AssertionError("a complete install must not fetch again")
+
+ monkeypatch.setattr("huggingface_hub.snapshot_download", _fake_download)
+ first_source = ensure_deepseek_ocr_source()
+
+ monkeypatch.setattr("huggingface_hub.snapshot_download", refuse)
+ assert ensure_deepseek_ocr_source() == first_source
+
+
+def test_a_partial_install_is_rebuilt(monkeypatch, pinned_digests):
+ """A half-written tree is not a valid install, so it is replaced, not imported."""
+ fetched = []
+
+ def counting_download(
+ repo_id = None,
+ *args,
+ **kwargs,
+ ):
+ fetched.append(repo_id)
+ return _fake_download(repo_id, *args, **kwargs)
+
+ monkeypatch.setattr("huggingface_hub.snapshot_download", counting_download)
+ source = ensure_deepseek_ocr_source()
+ (source / _DEEPSEEK_OCR_PACKAGE / _DEEPSEEK_OCR_MODULES[0]).unlink()
+
+ ensure_deepseek_ocr_source()
+
+ assert len(fetched) == 2
+
+
+def test_a_cached_module_edited_in_place_is_rebuilt(monkeypatch, pinned_digests):
+ """The case names and file types cannot see.
+
+ An edited file keeps its name, so presence alone would accept it, skip the download
+ and import the altered bytes, which is the revision pin defeated at the last step.
+ """
+ fetched = []
+
+ def counting_download(
+ repo_id = None,
+ *args,
+ **kwargs,
+ ):
+ fetched.append(repo_id)
+ return _fake_download(repo_id, *args, **kwargs)
+
+ monkeypatch.setattr("huggingface_hub.snapshot_download", counting_download)
+ source = ensure_deepseek_ocr_source()
+
+ tampered = source / _DEEPSEEK_OCR_PACKAGE / _DEEPSEEK_OCR_MODULES[0]
+ tampered.write_text(BODY + "import os\nos.environ['X'] = '1'\n", encoding = "utf-8")
+
+ assert _deepseek_ocr_installed(source) is False
+ ensure_deepseek_ocr_source()
+ assert len(fetched) == 2
+ assert tampered.read_text(encoding = "utf-8") == BODY
+
+
+def test_a_fetch_that_does_not_match_the_digests_is_not_installed(monkeypatch, pinned_digests):
+ """A wrong fetch raises instead of being published for a later call to accept."""
+
+ def wrong_download(
+ repo_id = None,
+ *args,
+ **kwargs,
+ ):
+ package = Path(kwargs["local_dir"])
+ package.mkdir(parents = True, exist_ok = True)
+ for name in _DEEPSEEK_OCR_MODULES:
+ (package / name).write_text("VALUE = 'not what was pinned'\n", encoding = "utf-8")
+ return str(package)
+
+ monkeypatch.setattr("huggingface_hub.snapshot_download", wrong_download)
+
+ with pytest.raises(RuntimeError, match = "does not match the pinned digests"):
+ ensure_deepseek_ocr_source()
+
+ assert not _deepseek_ocr_installed(third_party_source._deepseek_ocr_runtime())
+
+
+def test_a_foreign_package_on_sys_path_is_not_what_gets_imported(tmp_path, monkeypatch):
+ """The defect: a `deepseek_ocr` directory on sys.path used to be imported instead.
+
+ The witness file is how this observes execution. A bare
+ `from deepseek_ocr.modeling_deepseekocr import ...` runs the foreign package's
+ module body, so the witness exists before any check can be made about where the
+ code came from.
+ """
+ witness = tmp_path / "witness.txt"
+ foreign = tmp_path / "foreign" / _DEEPSEEK_OCR_PACKAGE
+ foreign.mkdir(parents = True)
+ (foreign / "__init__.py").write_text(
+ f"open({str(witness)!r}, 'a').write('imported\\n')\n", encoding = "utf-8"
+ )
+ (foreign / "modeling_deepseekocr.py").write_text(
+ f"open({str(witness)!r}, 'a').write('imported\\n')\n"
+ "def format_messages(*args, **kwargs):\n return None\n",
+ encoding = "utf-8",
+ )
+ monkeypatch.syspath_prepend(str(tmp_path / "foreign"))
+
+ pinned = tmp_path / "pinned"
+ _write_package(pinned)
+
+ module = import_deepseek_ocr_module("deepseek_ocr.modeling_deepseekocr", pinned)
+
+ assert not witness.exists(), "the foreign deepseek_ocr package was executed"
+ assert module.VALUE == "pinned"
+ assert str(pinned.resolve()) in module.__file__
+
+
+def test_the_trainer_entry_point_reports_success_from_the_pinned_source(tmp_path, monkeypatch):
+ """`_ensure_deepseek_ocr_installed` keeps its True/False contract.
+
+ The training flow checks the return value and surfaces an error to the user on
+ False, so the contract is what keeps the UX identical.
+ """
+ pinned = tmp_path / "pinned"
+ _write_package(pinned)
+ monkeypatch.setattr(third_party_source, "ensure_deepseek_ocr_source", lambda *a, **k: pinned)
+
+ from core.training import trainer
+
+ assert trainer._ensure_deepseek_ocr_installed() is True
+
+
+def test_the_trainer_entry_point_returns_false_when_the_source_is_unavailable(monkeypatch):
+ def unavailable(*args, **kwargs):
+ raise RuntimeError("offline")
+
+ monkeypatch.setattr(third_party_source, "ensure_deepseek_ocr_source", unavailable)
+
+ from core.training import trainer
+
+ assert trainer._ensure_deepseek_ocr_installed() is False
+
+
+def test_an_added_shadowing_package_is_rebuilt(monkeypatch, pinned_digests):
+ """Digests on the listed files cannot see an ADDED file that wins the import.
+
+ `modeling_deepseekocr/__init__.py` is imported in preference to
+ `modeling_deepseekocr.py`, and an origin check passes it because it does sit inside
+ the pinned root, so the contents have to be exactly what was installed.
+ """
+ fetched = []
+
+ def counting_download(
+ repo_id = None,
+ *args,
+ **kwargs,
+ ):
+ fetched.append(repo_id)
+ return _fake_download(repo_id, *args, **kwargs)
+
+ monkeypatch.setattr("huggingface_hub.snapshot_download", counting_download)
+ source = ensure_deepseek_ocr_source()
+
+ shadow = source / _DEEPSEEK_OCR_PACKAGE / "modeling_deepseekocr"
+ shadow.mkdir()
+ (shadow / "__init__.py").write_text("VALUE = 'shadow'\n", encoding = "utf-8")
+
+ assert _deepseek_ocr_installed(source) is False
+ ensure_deepseek_ocr_source()
+ assert len(fetched) == 2
+ assert not shadow.exists()
+
+
+def test_a_bare_added_directory_is_also_rebuilt(monkeypatch, pinned_digests):
+ """A directory needs no __init__.py to be importable, so presence is enough."""
+ monkeypatch.setattr("huggingface_hub.snapshot_download", _fake_download)
+ source = ensure_deepseek_ocr_source()
+
+ (source / _DEEPSEEK_OCR_PACKAGE / "conversation").mkdir()
+
+ assert _deepseek_ocr_installed(source) is False
+
+
+def test_the_install_leaves_only_the_pinned_files(monkeypatch, pinned_digests):
+ """The hub's own metadata directory is removed, so the exact-contents rule holds."""
+
+ def download_with_metadata(
+ repo_id = None,
+ *args,
+ **kwargs,
+ ):
+ result = _fake_download(repo_id, *args, **kwargs)
+ metadata = Path(kwargs["local_dir"]) / ".cache" / "huggingface"
+ metadata.mkdir(parents = True, exist_ok = True)
+ (metadata / "download").write_text("x", encoding = "utf-8")
+ return result
+
+ monkeypatch.setattr("huggingface_hub.snapshot_download", download_with_metadata)
+
+ source = ensure_deepseek_ocr_source()
+
+ names = {entry.name for entry in (source / _DEEPSEEK_OCR_PACKAGE).iterdir()}
+ assert names == {"__init__.py", *_DEEPSEEK_OCR_MODULES}
+
+
+def test_generated_bytecode_does_not_invalidate_the_install(monkeypatch, pinned_digests):
+ """Python writes __pycache__ on the first import.
+
+ Treating it as an unexpected entry made the predicate go False immediately after a
+ successful import, so every later run re-downloaded and an offline run failed on a
+ source it had already installed and used.
+ """
+ monkeypatch.setattr("huggingface_hub.snapshot_download", _fake_download)
+ source = ensure_deepseek_ocr_source()
+
+ for directory in (source, source / _DEEPSEEK_OCR_PACKAGE):
+ cache = directory / "__pycache__"
+ cache.mkdir()
+ (cache / "modeling_deepseekocr.cpython-313.pyc").write_bytes(b"\x00")
+
+ assert _deepseek_ocr_installed(source) is True
+
+ def refuse(*args, **kwargs):
+ raise AssertionError("bytecode must not trigger a re-download")
+
+ monkeypatch.setattr("huggingface_hub.snapshot_download", refuse)
+ assert ensure_deepseek_ocr_source() == source
+
+
+def test_a_sibling_planted_in_the_import_root_is_rebuilt(monkeypatch, pinned_digests):
+ """The root is on sys.path, and the origin check only looks at deepseek_ocr.*.
+
+ The modelling code imports addict, so a planted addict.py beside the package would
+ be imported by it with nothing objecting.
+ """
+ fetched = []
+
+ def counting_download(
+ repo_id = None,
+ *args,
+ **kwargs,
+ ):
+ fetched.append(repo_id)
+ return _fake_download(repo_id, *args, **kwargs)
+
+ monkeypatch.setattr("huggingface_hub.snapshot_download", counting_download)
+ source = ensure_deepseek_ocr_source()
+
+ planted = source / "addict.py"
+ planted.write_text("VALUE = 'planted'\n", encoding = "utf-8")
+
+ assert _deepseek_ocr_installed(source) is False
+ ensure_deepseek_ocr_source()
+ assert len(fetched) == 2
+ assert not planted.exists()
diff --git a/studio/backend/utils/third_party_source.py b/studio/backend/utils/third_party_source.py
index 6661a2e9cc1..2ed7e9900c8 100644
--- a/studio/backend/utils/third_party_source.py
+++ b/studio/backend/utils/third_party_source.py
@@ -95,6 +95,33 @@ _REVISION_PATTERN = re.compile(r"[0-9a-f]{40}")
_SHA256_PATTERN = re.compile(r"[0-9a-f]{64}")
_IMPORT_LOCK = threading.RLock()
+# Published on the Hub rather than on PyPI, so the modelling code is fetched. Pinned to
+# a revision: without one the import executes whatever the branch points at today.
+_DEEPSEEK_OCR_REPOSITORY = "unsloth/DeepSeek-OCR"
+_DEEPSEEK_OCR_REVISION = "84cced885e9ae0de9f2307915a255ac04fd6e8ec"
+_DEEPSEEK_OCR_PACKAGE = "deepseek_ocr"
+_DEEPSEEK_OCR_MODULES = (
+ "configuration_deepseek_v2.py",
+ "conversation.py",
+ "deepencoder.py",
+ "modeling_deepseekocr.py",
+ "modeling_deepseekv2.py",
+)
+# sha256 of each module at the pinned revision, the same guarantee the git-based sources
+# get from source_tree_digest. The revision alone only fixes what is fetched; these fix
+# what is imported, so a cached file edited in place is rebuilt rather than run. They are
+# constants in this file deliberately: a manifest written beside the install would be
+# writable by whoever could edit the install. 181 KB, 0.6 ms to verify.
+_DEEPSEEK_OCR_DIGESTS = {
+ "configuration_deepseek_v2.py": "6ab21f29a4722e26fa28c8e0d4277591689a598df17cf6c712330e8f62b3fc7c",
+ "conversation.py": "ec7b6ce89bcda643de1f43269ffa66a7b2e65dc3ed30e427958f776546b4ba03",
+ "deepencoder.py": "0ae2fb6d1e5ae8cf100fc32f854830acd08c821a0a1f23a94a76588c222ddcf2",
+ "modeling_deepseekocr.py": "31e3d52972534415cb6507a40ff7cd859a3ddd3419ace6900d659fba0e09321b",
+ "modeling_deepseekv2.py": "bab8c5c67236453f3311ef2c6629a3606e608e6cc818c8a5923e7877ec65db7f",
+}
+# The complete package, so an added entry is a rebuild rather than an import candidate.
+_DEEPSEEK_OCR_CONTENTS = frozenset({"__init__.py", *_DEEPSEEK_OCR_MODULES})
+
_DAC_REPOSITORY = "ibm-research/DAC.speech.v1.0"
SNAC_REPOSITORY = "hubertsiuzdak/snac_24khz"
SPARK_TTS_REPOSITORY = "unsloth/Spark-TTS-0.5B"
@@ -847,6 +874,180 @@ def ensure_outetts_source() -> Path:
)
+def _deepseek_ocr_runtime() -> Path:
+ return (
+ cache_root()
+ / "third-party-sources"
+ / "DeepSeek-OCR"
+ / _DEEPSEEK_OCR_REVISION
+ / "runtime-v1"
+ )
+
+
+def _entry_names(directory: Path) -> set[str]:
+ """Names in a directory, minus generated bytecode, which is not an import candidate."""
+ return {entry.name for entry in directory.iterdir() if entry.name != "__pycache__"}
+
+
+def _deepseek_ocr_installed(runtime: Path) -> bool:
+ """Whether the pinned package is present and is byte for byte what was pinned.
+
+ Names and file types are not enough. A cached module edited in place keeps its name,
+ so a predicate that checked only presence would accept it, skip the download and
+ import the altered bytes, which is the revision pin defeated at the last step. Each
+ module is therefore checked against `_DEEPSEEK_OCR_DIGESTS` and the generated
+ `__init__.py` against being empty.
+
+ Digests on the listed files are not enough either, because an ADDED file can win the
+ import without editing any of them: a `modeling_deepseekocr/` directory holding an
+ `__init__.py` is imported in preference to `modeling_deepseekocr.py`, and an origin
+ check passes it because it does sit inside the pinned root. A bare directory needs no
+ `__init__.py` to be importable at all. So the package contents must be exactly what
+ was installed, and anything else makes this a rebuild.
+
+ The import root itself is checked too, not just the package. `import_pinned_module`
+ leaves the root on `sys.path`, and its origin check looks at `deepseek_ocr.*` only,
+ so a planted sibling such as `addict.py` would be imported by the modelling code
+ with nothing objecting. The modelling code does import `addict`, so that is a real
+ name and not a hypothetical one.
+
+ Generated bytecode is ignored at both levels. Python writes `__pycache__` on the
+ first successful import, and treating that as an unexpected entry would make this
+ return False immediately afterwards: every later run would re-download, and an
+ offline run would fail on a source it had already installed and used.
+ `import_pinned_module` purges bytecode before importing anyway.
+
+ Symlinks are rejected rather than followed, matching the rest of this module: a
+ link is a way to point an "installed" package at bytes outside the verified tree.
+ `local_dir` has written real files since huggingface_hub 0.23 and the floor here is
+ 0.34, so this costs nothing.
+ """
+ package = runtime / _DEEPSEEK_OCR_PACKAGE
+ if package.is_symlink() or not package.is_dir():
+ return False
+ for name in ("__init__.py", *_DEEPSEEK_OCR_MODULES):
+ member = package / name
+ if member.is_symlink() or not member.is_file():
+ return False
+ try:
+ if _entry_names(runtime) != {_DEEPSEEK_OCR_PACKAGE}:
+ return False
+ if _entry_names(package) != _DEEPSEEK_OCR_CONTENTS:
+ return False
+ if (package / "__init__.py").read_bytes() != b"":
+ return False
+ for name, expected in _DEEPSEEK_OCR_DIGESTS.items():
+ digest = hashlib.sha256((package / name).read_bytes()).hexdigest()
+ if digest != expected:
+ return False
+ except OSError:
+ return False
+ return True
+
+
+def ensure_deepseek_ocr_source(hf_token: HfTokenArg = None) -> Path:
+ """Install the pinned DeepSeek-OCR modelling code and return its import root.
+
+ The modelling code for this model is published on the Hub rather than on PyPI, so
+ it has to be fetched to be used. Two things make that safe to import, and both were
+ missing where this used to live:
+
+ - a revision. `snapshot_download(repo)` with no revision resolves to whatever the
+ branch points at when it runs, so the code that executes is not the code that was
+ reviewed. The revision is pinned, which makes the fetch content addressed.
+ - a destination the fetch owns. It lands under `cache_root()`, keyed by revision,
+ not inside the backend source tree, so nothing else is on the import path as a
+ side effect of installing this.
+
+ Only `*.py` is fetched. The previous call pulled the whole repository, weights
+ included, to import five modules; the weights were never read from here because the
+ model itself loads from the user's own model id.
+
+ Idempotent: a complete install returns immediately with no network. A partial or
+ tampered one is rebuilt. Concurrent callers serialise on the same lock the other
+ pinned sources use.
+ """
+ runtime = _deepseek_ocr_runtime()
+ if _deepseek_ocr_installed(runtime):
+ return runtime.resolve()
+
+ parent = runtime.parent
+ parent.mkdir(parents = True, exist_ok = True)
+ try:
+ with FileLock(str(parent / ".install.lock"), timeout = 300):
+ if _deepseek_ocr_installed(runtime):
+ return runtime.resolve()
+
+ from huggingface_hub import snapshot_download
+
+ from utils.hf_cache_settings import active_hf_hub_cache
+ from utils.utils import hf_env_offline
+
+ if hf_env_offline():
+ raise RuntimeError(
+ "The pinned DeepSeek-OCR source is not cached and Unsloth is offline"
+ )
+
+ workspace = Path(tempfile.mkdtemp(prefix = ".install-", dir = parent))
+ try:
+ staging = workspace / runtime.name
+ package = staging / _DEEPSEEK_OCR_PACKAGE
+ package.mkdir(parents = True)
+ snapshot_download(
+ _DEEPSEEK_OCR_REPOSITORY,
+ revision = _DEEPSEEK_OCR_REVISION,
+ allow_patterns = ["*.py"],
+ local_dir = str(package),
+ cache_dir = active_hf_hub_cache(),
+ token = hf_token,
+ )
+ # snapshot_download leaves its own metadata directory inside local_dir.
+ # It is dot-prefixed and so not importable, but removing it keeps the
+ # installed package exactly the pinned files, which is what lets the
+ # predicate above treat any other entry as a reason to rebuild.
+ _remove_owned_path(package / ".cache")
+ # The repo is a model, not a package, so it ships no __init__.py. Same
+ # approach as the `generated_files` entry the git-based sources use.
+ (package / "__init__.py").write_text("", encoding = "utf-8")
+ missing = [name for name in _DEEPSEEK_OCR_MODULES if not (package / name).is_file()]
+ if missing:
+ raise RuntimeError(
+ "The pinned DeepSeek-OCR revision is missing " + ", ".join(sorted(missing))
+ )
+ # Before the install is published, so bytes that do not match what was
+ # pinned are never moved into place for a later call to accept.
+ unexpected = sorted(
+ name
+ for name, expected in _DEEPSEEK_OCR_DIGESTS.items()
+ if hashlib.sha256((package / name).read_bytes()).hexdigest() != expected
+ )
+ if unexpected:
+ raise RuntimeError(
+ "The fetched DeepSeek-OCR source does not match the pinned digests: "
+ + ", ".join(unexpected)
+ )
+ extra = sorted(_entry_names(package) - _DEEPSEEK_OCR_CONTENTS)
+ if extra:
+ raise RuntimeError(
+ "The fetched DeepSeek-OCR source carries unexpected entries: "
+ + ", ".join(extra)
+ )
+ _purge_package_bytecode(package)
+ _replace_owned_directory(staging, runtime)
+ finally:
+ _remove_owned_path(workspace)
+ except Timeout as error:
+ raise RuntimeError("Timed out waiting for another DeepSeek-OCR installation") from error
+
+ if not _deepseek_ocr_installed(runtime):
+ raise RuntimeError("The installed DeepSeek-OCR source failed integrity validation")
+ return runtime.resolve()
+
+
+def import_deepseek_ocr_module(module_name: str, source: Path | str) -> ModuleType:
+ return import_pinned_module(module_name, package = _DEEPSEEK_OCR_PACKAGE, source = source)
+
+
def _artifact_matches(path: Path, *, expected_size: int, expected_sha256: str) -> bool:
try:
if not path.is_file() or path.stat().st_size != expected_size: