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.

Patch sentence_transformers when it is first imported instead of importing it with unsloth (#17267)

Daniel Han082595c6fa5e
diff --git a/tests/test_sentence_transformers_lazy_patch.py b/tests/test_sentence_transformers_lazy_patch.py
new file mode 100644
index 00000000000..14ab47e25cd
--- /dev/null
+++ b/tests/test_sentence_transformers_lazy_patch.py
@@ -0,0 +1,112 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2023-present Daniel Han-Chen & the Unsloth team. All rights reserved.
+
+"""unsloth does not import sentence_transformers itself; it patches the package when (or if) it is imported,
+with the same result in either import order."""
+
+import importlib.util
+import json
+import os
+import pathlib
+import subprocess
+import sys
+import textwrap
+
+import pytest
+
+_ROOT = pathlib.Path(__file__).resolve().parents[1]
+
+_CHILD = textwrap.dedent(
+ """
+ import json, sys
+ sys.path.insert(0, {root!r})
+ if {st_first}:
+ import sentence_transformers
+ try:
+ import unsloth.models.sentence_transformer as module
+ except Exception as error:
+ print("UNSLOTH_IMPORT_FAILED", repr(error))
+ raise SystemExit(0)
+ assert module.__file__.startswith({root!r}), module.__file__
+ loaded = "sentence_transformers" in sys.modules
+ from sentence_transformers import SentenceTransformerTrainer
+ from sentence_transformers.models import Dense, Pooling
+ import sentence_transformers
+ print(json.dumps({{
+ "loaded_by_unsloth": loaded,
+ "flags": [
+ getattr(SentenceTransformerTrainer, "_unsloth_auto_compile_patched", False),
+ getattr(SentenceTransformerTrainer, "_unsloth_load_from_checkpoint_patched", False),
+ getattr(Pooling, "_unsloth_float16_pooling", False),
+ getattr(Dense, "_unsloth_input_dtype", False),
+ ],
+ "loader": type(sentence_transformers.__spec__.loader).__name__,
+ }}))
+ """
+)
+
+
+def _run(st_first):
+ code = _CHILD.format(root = str(_ROOT), st_first = st_first)
+ # The suite's conftest refuses the CPU fallback; this child only needs the import to work.
+ env = {k: v for k, v in os.environ.items() if k != "UNSLOTH_DISABLE_CPU_FALLBACK"}
+ out = subprocess.run(
+ [sys.executable, "-c", code], capture_output = True, text = True, timeout = 900, env = env
+ )
+ assert out.returncode == 0, out.stderr[-4000:]
+ if "UNSLOTH_IMPORT_FAILED" in out.stdout:
+ pytest.skip(out.stdout.strip().splitlines()[-1])
+ return json.loads(out.stdout.strip().splitlines()[-1])
+
+
+ importlib.util.find_spec("sentence_transformers") is None, reason = "no sentence_transformers"
+)
+def test_unsloth_does_not_import_sentence_transformers_and_patches_it_on_import():
+ late = _run(st_first = False)
+ assert late["loaded_by_unsloth"] is False
+ assert late["flags"] == [True, True, True, True]
+ assert late["loader"] != "_PatchAfterImportLoader"
+ early = _run(st_first = True)
+ assert early["flags"] == [True, True, True, True]
+
+
+_RELOAD_CHILD = textwrap.dedent(
+ """
+ import copy, importlib, importlib.util, json, sys
+ sys.path.insert(0, {root!r})
+ try:
+ import unsloth.models.sentence_transformer as module
+ except Exception as error:
+ print("UNSLOTH_IMPORT_FAILED", repr(error))
+ raise SystemExit(0)
+ importlib.reload(module)
+ copy.copy(importlib.util.find_spec("sentence_transformers").loader)
+ import sentence_transformers
+ from sentence_transformers.models import Pooling
+ print(json.dumps({{
+ "flags": [getattr(Pooling, "_unsloth_float16_pooling", False)],
+ "loader": type(sentence_transformers.__spec__.loader).__name__,
+ }}))
+ """
+)
+
+
+ importlib.util.find_spec("sentence_transformers") is None, reason = "no sentence_transformers"
+)
+def test_reloading_the_module_does_not_recurse_on_import():
+ env = {k: v for k, v in os.environ.items() if k != "UNSLOTH_DISABLE_CPU_FALLBACK"}
+ out = subprocess.run(
+ [sys.executable, "-c", _RELOAD_CHILD.format(root = str(_ROOT))],
+ capture_output = True,
+ text = True,
+ timeout = 900,
+ env = env,
+ )
+ assert out.returncode == 0, out.stderr[-4000:]
+ if "UNSLOTH_IMPORT_FAILED" in out.stdout:
+ pytest.skip(out.stdout.strip().splitlines()[-1])
+ result = json.loads(out.stdout.strip().splitlines()[-1])
+ assert result["flags"] == [True]
+ assert result["loader"] != "_PatchAfterImportLoader"
diff --git a/unsloth/models/sentence_transformer.py b/unsloth/models/sentence_transformer.py
index 66491fba605..f19bbe8d723 100644
--- a/unsloth/models/sentence_transformer.py
+++ b/unsloth/models/sentence_transformer.py
@@ -34,6 +34,8 @@ import inspect
import json
import os
import posixpath
+import importlib.abc
+import sys
import threading
import types
from huggingface_hub import hf_hub_download
@@ -3634,7 +3636,80 @@ def _patch_dense_input_dtype():
Dense._unsloth_input_dtype = True
-_patch_sentence_transformer_trainer()
-_patch_st_trainer_load_from_checkpoint()
-_patch_pooling_float16_accumulation()
-_patch_dense_input_dtype()
+def _apply_sentence_transformers_patches():
+ _patch_sentence_transformer_trainer()
+ _patch_st_trainer_load_from_checkpoint()
+ _patch_pooling_float16_accumulation()
+ _patch_dense_input_dtype()
+
+
+class _PatchAfterImportLoader(importlib.abc.Loader):
+ def __init__(self, loader):
+ self._loader = loader
+
+ def __getattr__(self, name):
+ # Resource / is_package lookups made while the package's __init__ runs.
+ if name == "_loader": # copy / pickle build the object without __init__
+ raise AttributeError(name)
+ return getattr(self._loader, name)
+
+ def create_module(self, spec):
+ return self._loader.create_module(spec)
+
+ def exec_module(self, module):
+ self._loader.exec_module(module)
+ # Hand the module back its own loader, then patch the fully imported package.
+ module.__loader__ = self._loader
+ if getattr(module, "__spec__", None) is not None:
+ module.__spec__.loader = self._loader
+ try:
+ _apply_sentence_transformers_patches()
+ except Exception as error:
+ # A failed patch must not make `import sentence_transformers` itself fail.
+ logging.getLogger(__name__).warning(
+ f"Unsloth: could not patch sentence_transformers: {error}"
+ )
+
+
+class _SentenceTransformersFinder(importlib.abc.MetaPathFinder):
+ # Found by marker, not isinstance: a re-executed module defines a new class.
+ _unsloth_st_finder = True
+
+ def __init__(self):
+ self._busy = threading.local()
+
+ def find_spec(
+ self,
+ fullname,
+ path,
+ target = None,
+ ):
+ if fullname != "sentence_transformers" or fullname in sys.modules:
+ return None
+ # Another finder that also walks sys.meta_path would otherwise call back into this one forever.
+ if getattr(self._busy, "active", False):
+ return None
+ self._busy.active = True
+ try:
+ for finder in sys.meta_path:
+ if finder is self or not hasattr(finder, "find_spec"):
+ continue
+ try:
+ spec = finder.find_spec(fullname, path, target)
+ except Exception:
+ continue
+ if spec is None:
+ continue
+ if spec.loader is not None and hasattr(spec.loader, "exec_module"):
+ spec.loader = _PatchAfterImportLoader(spec.loader)
+ return spec
+ return None
+ finally:
+ self._busy.active = False
+
+
+# sentence_transformers is heavy and only embedding fine-tuning needs it: patch on first import.
+if "sentence_transformers" in sys.modules:
+ _apply_sentence_transformers_patches()
+elif not any(getattr(f, "_unsloth_st_finder", False) for f in sys.meta_path):
+ sys.meta_path.insert(0, _SentenceTransformersFinder())