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.

Gate the sentence-transformers module types on the routes that delegate the load (#12446)

Daniel Han2af60e60ccf6
diff --git a/tests/test_st_modules_json_trust_gate.py b/tests/test_st_modules_json_trust_gate.py
index 6357cf27ff6..5f1be01215d 100644
--- a/tests/test_st_modules_json_trust_gate.py
+++ b/tests/test_st_modules_json_trust_gate.py
@@ -272,6 +272,1001 @@ def test_a_real_dense_config_is_untouched_by_that_check(tmp_path):
)
+def test_the_delegating_routes_gate_the_module_types_too(model_dir):
+ """These routes never reach _load_modules, and below 6.0 sentence-transformers has no gate."""
+ model, witness = model_dir
+
+ with pytest.raises(ValueError, match = "not part of Sentence Transformers"):
+ FastSentenceTransformer._check_modules_json_types(str(model), None, False)
+
+ assert not witness.exists()
+
+
+def test_that_validation_passes_a_stock_module_list_untouched(tmp_path):
+ """A no-op for a normal repo: it runs on every delegated load."""
+ model = tmp_path / "model"
+ model.mkdir()
+ (model / "modules.json").write_text(
+ json.dumps(
+ [
+ {
+ "idx": 0,
+ "name": "0",
+ "path": "",
+ "type": "sentence_transformers.models.Transformer",
+ },
+ {
+ "idx": 1,
+ "name": "1",
+ "path": "1_Pooling",
+ "type": "sentence_transformers.models.Pooling",
+ },
+ {
+ "idx": 2,
+ "name": "2",
+ "path": "2_Normalize",
+ "type": "sentence_transformers.models.Normalize",
+ },
+ ]
+ ),
+ encoding = "utf-8",
+ )
+
+ FastSentenceTransformer._check_modules_json_types(str(model), None, False)
+
+
+def test_that_validation_is_silent_when_there_is_no_modules_json(tmp_path):
+ """A transformers-native encoder has no modules.json."""
+ model = tmp_path / "model"
+ model.mkdir()
+
+ FastSentenceTransformer._check_modules_json_types(str(model), None, False)
+
+
+def test_validation_reads_the_sentence_transformers_cache(tmp_path, monkeypatch):
+ """The delegated loads honour SENTENCE_TRANSFORMERS_HOME while hf_hub_download does not, so a
+ model cached only there must still be read rather than becoming a silent pass."""
+ st_home = tmp_path / "st_home"
+ snapshot = st_home / "models--acme--embedder" / "snapshots" / "deadbeef"
+ snapshot.mkdir(parents = True)
+ (snapshot / "modules.json").write_text(
+ json.dumps([{"idx": 0, "name": "0", "path": "0_Sub", "type": f"{MARKER}.Thing"}]),
+ encoding = "utf-8",
+ )
+ monkeypatch.setenv("SENTENCE_TRANSFORMERS_HOME", str(st_home))
+
+ seen = {}
+
+ def fake_module_path(
+ model_name,
+ token = None,
+ cache_dir = None,
+ revision = None,
+ ):
+ seen["cache_dir"] = cache_dir
+ return str(snapshot / "modules.json") if cache_dir == str(st_home) else None
+
+ monkeypatch.setattr(FastSentenceTransformer, "_module_path", staticmethod(fake_module_path))
+
+ with pytest.raises(ValueError, match = "not part of Sentence Transformers"):
+ FastSentenceTransformer._check_modules_json_types("acme/embedder", None, False)
+
+ assert seen["cache_dir"] == str(st_home)
+
+
+def test_consent_skips_validation_so_a_repo_local_class_still_loads(model_dir, monkeypatch):
+ """Below 6 the delegated loader fetches a repo-local class with get_class_from_dynamic_module,
+ which this helper cannot, so validating a consented load would break it."""
+ model, witness = model_dir
+
+ called = []
+ monkeypatch.setattr(
+ FastSentenceTransformer,
+ "_module_path",
+ staticmethod(lambda *a, **k: called.append(1) or None),
+ )
+
+ FastSentenceTransformer._check_modules_json_types(str(model), None, True)
+
+ assert not called, "a consented load must not be validated or resolved here"
+ assert not witness.exists()
+
+
+def test_an_unverifiable_modules_json_fails_closed_where_upstream_would_not_gate(monkeypatch):
+ """_module_path turns every failure into absent, so a transient failure would read as
+ "nothing to check" while the load that follows could still import the type."""
+ import sentence_transformers
+
+ monkeypatch.setattr(FastSentenceTransformer, "_module_path", staticmethod(lambda *a, **k: None))
+ monkeypatch.setattr(
+ FastSentenceTransformer,
+ "_modules_json_for_gating",
+ staticmethod(lambda *a, **k: (_ for _ in ()).throw(ValueError("Unsloth: Could not read"))),
+ )
+
+ with pytest.raises(ValueError, match = "Could not read"):
+ FastSentenceTransformer._check_modules_json_types("acme/embedder", None, False)
+
+
+def test_a_local_directory_without_modules_json_is_a_confirmed_absence(tmp_path):
+ """A transformers-native encoder has no modules.json and must not be refused for it."""
+ model = tmp_path / "model"
+ model.mkdir()
+
+ assert FastSentenceTransformer._modules_json_for_gating(str(model), None) is None
+
+
+def test_unreachable_is_not_read_as_absent(tmp_path, monkeypatch):
+ """LocalEntryNotFoundError subclasses EntryNotFoundError, so catching the latter first turned
+ "could not reach it" into "the repo has no modules.json", which is the opposite answer."""
+ import sentence_transformers
+ from huggingface_hub.errors import LocalEntryNotFoundError
+
+ monkeypatch.setattr(FastSentenceTransformer, "_module_path", staticmethod(lambda *a, **k: None))
+ _patch_download(
+ monkeypatch,
+ lambda *a, **k: (_ for _ in ()).throw(LocalEntryNotFoundError("offline")),
+ )
+ monkeypatch.setattr(sentence_transformers, "__version__", "5.2.0", raising = False)
+
+ with pytest.raises(ValueError, match = "Could not read modules.json"):
+ FastSentenceTransformer._modules_json_for_gating("acme/embedder", None)
+
+
+def test_unreachable_is_tolerated_where_upstream_gates_it_anyway(tmp_path, monkeypatch):
+ """From 6.0 sentence-transformers refuses the type itself, so an unreachable check there must
+ not turn a working load into a failure."""
+ import sentence_transformers
+ from huggingface_hub.errors import LocalEntryNotFoundError
+
+ monkeypatch.setattr(FastSentenceTransformer, "_module_path", staticmethod(lambda *a, **k: None))
+ _patch_download(
+ monkeypatch,
+ lambda *a, **k: (_ for _ in ()).throw(LocalEntryNotFoundError("offline")),
+ )
+ monkeypatch.setattr(sentence_transformers, "__version__", "6.1.0", raising = False)
+
+ assert FastSentenceTransformer._modules_json_for_gating("acme/embedder", None) is None
+
+
+def _patch_download(monkeypatch, replacement):
+ """Replace hf_hub_download in the namespace the method under test actually reads.
+
+ Not by dotted string, and not on whatever sys.modules currently holds. Both of those
+ resolve the module afresh, and tests/vllm_compat/test_extended_module_imports.py pops
+ unsloth.models.sentence_transformer out of sys.modules and re-imports it, so by the
+ time these tests run the name points at a second module object with its own globals
+ dict. The class imported at the top of this file still closes over the first one.
+ Patching the later object left the real hf_hub_download in place, and three tests
+ reached out to the Hub and asserted against a 404 instead of against the fake.
+
+ __globals__ is that first dict by definition, whatever else has been re-imported.
+ """
+ namespace = FastSentenceTransformer._check_delegated_module_config.__globals__
+ monkeypatch.setitem(namespace, "hf_hub_download", replacement)
+
+
+def _simulate_pre_six(monkeypatch):
+ """Report sentence-transformers 5.x. The version is the whole simulation.
+
+ This used to delete util.import_module_class as well, because the config check keyed
+ off that attribute. #12444 replaced it with a version test, for the reason the
+ attribute was never a good one: 5.5 exports the helper while its Dense and Router
+ loaders still resolve config class references ungated. Deleting it here meant these
+ tests passed for a reason production did not have, and hid that exact gap. Setting
+ only the version is what makes them exercise the real condition.
+ """
+ import sentence_transformers
+ monkeypatch.setattr(sentence_transformers, "__version__", "5.2.0", raising = False)
+
+
+def _delegated_model(tmp_path, activation_function):
+ """A local model whose Dense module config names a class, as the Hub form would."""
+ model = tmp_path / "model"
+ (model / "1_Dense").mkdir(parents = True)
+ (model / "modules.json").write_text(
+ json.dumps(
+ [
+ {
+ "idx": 0,
+ "name": "0",
+ "path": "1_Dense",
+ "type": "sentence_transformers.models.Dense",
+ }
+ ]
+ ),
+ encoding = "utf-8",
+ )
+ (model / "1_Dense" / "config.json").write_text(
+ json.dumps(
+ {"in_features": 8, "out_features": 8, "activation_function": activation_function}
+ ),
+ encoding = "utf-8",
+ )
+ return model
+
+
+def test_a_delegated_route_also_checks_the_module_config_class_ref(tmp_path, monkeypatch):
+ """An allowed type is not the whole check.
+
+ Dense is a permitted sentence_transformers class, and below 6.0 its loader resolves and
+ calls whatever activation_function the config names. _load_modules checks this from the
+ files it downloaded; the delegated routes hand the load straight to
+ sentence-transformers, so without this they validated the type and nothing else.
+
+ Hiding import_module_class simulates sentence-transformers < 6, which is where the
+ ungated loader lives; on this branch the config check still keys off that attribute,
+ and #12444 removes the fork so it runs on every version.
+ """
+ _simulate_pre_six(monkeypatch)
+
+ model = _delegated_model(tmp_path, f"{MARKER}.Thing")
+
+ with pytest.raises(ValueError, match = "executes third-party code"):
+ FastSentenceTransformer._check_modules_json_types(str(model), None, False)
+
+
+def test_a_delegated_route_leaves_a_real_dense_config_alone(tmp_path, monkeypatch):
+ """embeddinggemma-300m's Dense modules name torch.nn.modules.linear.Identity."""
+ _simulate_pre_six(monkeypatch)
+
+ model = _delegated_model(tmp_path, "torch.nn.modules.linear.Identity")
+
+ FastSentenceTransformer._check_modules_json_types(str(model), None, False)
+
+
+def test_an_ordinary_embedder_fetches_no_module_configs(tmp_path, monkeypatch):
+ """The cost rule: Transformer, Pooling and Normalize read no class ref out of their
+ configs, so gating them must not add a request per module to every load."""
+ model = tmp_path / "model"
+ model.mkdir()
+ (model / "modules.json").write_text(
+ json.dumps(
+ [
+ {
+ "idx": 0,
+ "name": "0",
+ "path": "",
+ "type": "sentence_transformers.models.Transformer",
+ },
+ {
+ "idx": 1,
+ "name": "1",
+ "path": "1_Pooling",
+ "type": "sentence_transformers.models.Pooling",
+ },
+ {
+ "idx": 2,
+ "name": "2",
+ "path": "2_Normalize",
+ "type": "sentence_transformers.models.Normalize",
+ },
+ ]
+ ),
+ encoding = "utf-8",
+ )
+
+ requested = []
+
+ def fake_download(repo_id, filename, **kwargs):
+ requested.append(filename)
+ raise AssertionError(f"unexpected fetch of {filename}")
+
+ _patch_download(monkeypatch, fake_download)
+
+ FastSentenceTransformer._check_modules_json_types(str(model), None, False)
+
+ assert requested == []
+
+
+def test_a_recorded_absence_pins_the_commit_the_cache_holds(tmp_path, monkeypatch):
+ """Unreachable, with a recorded absence: pin to the snapshot that absence belongs to.
+
+ "The load can only use the cache too" was the reasoning for returning success with no
+ pin, and it is wrong: this request failed, not every request, so the delegated load
+ can recover and fetch the current branch, which may have gained a module type since
+ the cached answer. The commit is recovered from a file in the same snapshot, so the
+ load matches what was checked, and offline it is what would have been served anyway.
+
+ The lookup also has to read the cache hf_hub_download reads: HUGGINGFACE_HUB_CACHE is
+ the legacy constant and does not follow HF_HUB_CACHE, so naming one of our own
+ searched a different cache and a recorded absence there was missed.
+ """
+ from huggingface_hub.errors import LocalEntryNotFoundError
+
+ commit = "e" * 40
+ snapshot = tmp_path / "active" / "models--acme--embedder" / "snapshots" / commit
+ snapshot.mkdir(parents = True)
+ (snapshot / "config.json").write_text("{}", encoding = "utf8")
+
+ monkeypatch.setenv("HF_HUB_CACHE", str(tmp_path / "active"))
+ monkeypatch.delenv("SENTENCE_TRANSFORMERS_HOME", raising = False)
+ monkeypatch.setattr(FastSentenceTransformer, "_module_path", staticmethod(lambda *a, **k: None))
+ _simulate_pre_six(monkeypatch)
+ _patch_download(
+ monkeypatch,
+ lambda *a, **k: (_ for _ in ()).throw(LocalEntryNotFoundError("offline")),
+ )
+
+ seen = []
+
+ def fake_try_to_load_from_cache(
+ repo_id,
+ filename,
+ cache_dir = None,
+ revision = None,
+ ):
+ seen.append((filename, cache_dir))
+ if filename == "config.json":
+ return str(snapshot / "config.json")
+ # The sentinel the hub returns when it has recorded that the file does not exist.
+ return object()
+
+ monkeypatch.setattr("huggingface_hub.try_to_load_from_cache", fake_try_to_load_from_cache)
+
+ assert FastSentenceTransformer._check_modules_json_types("acme/embedder", None, False) == commit
+ assert all(
+ cache_dir is None for _, cache_dir in seen
+ ), "a cache of our own choosing is not the cache hf_hub_download reads"
+
+
+def test_a_recorded_absence_with_no_recoverable_commit_refuses(tmp_path, monkeypatch):
+ """No commit to pin to means no way to make the load match what was checked.
+
+ Fail closed below 6.0, the same rule as every other branch that could not establish an
+ answer.
+ """
+ from huggingface_hub.errors import LocalEntryNotFoundError
+
+ monkeypatch.setattr(FastSentenceTransformer, "_module_path", staticmethod(lambda *a, **k: None))
+ _simulate_pre_six(monkeypatch)
+ _patch_download(
+ monkeypatch,
+ lambda *a, **k: (_ for _ in ()).throw(LocalEntryNotFoundError("offline")),
+ )
+ monkeypatch.setattr(
+ "huggingface_hub.try_to_load_from_cache",
+ lambda *a, **k: object(),
+ )
+
+ with pytest.raises(ValueError, match = "names no commit"):
+ FastSentenceTransformer._check_modules_json_types("acme/embedder", None, False)
+
+
+def test_a_recorded_absence_is_tolerated_where_upstream_gates_it(tmp_path, monkeypatch):
+ """From 6.0 upstream refuses the type itself, so refusing here would only break a load
+ that is already safe."""
+ import sentence_transformers
+ from huggingface_hub.errors import LocalEntryNotFoundError
+
+ monkeypatch.setattr(sentence_transformers, "__version__", "6.1.0", raising = False)
+ monkeypatch.setattr(FastSentenceTransformer, "_module_path", staticmethod(lambda *a, **k: None))
+ _patch_download(
+ monkeypatch,
+ lambda *a, **k: (_ for _ in ()).throw(LocalEntryNotFoundError("offline")),
+ )
+ monkeypatch.setattr(
+ "huggingface_hub.try_to_load_from_cache",
+ lambda *a, **k: object(),
+ )
+
+ assert FastSentenceTransformer._check_modules_json_types("acme/embedder", None, False) == ""
+
+
+def test_a_module_at_the_repository_root_is_checked_too(tmp_path, monkeypatch):
+ """ "path": "" is the repository root, which sentence-transformers accepts.
+
+ Skipping an empty path left the whole module-config check bypassable by declaring
+ Dense at the root and putting the class ref in the root config.json.
+ """
+ _simulate_pre_six(monkeypatch)
+
+ model = tmp_path / "model"
+ model.mkdir()
+ (model / "modules.json").write_text(
+ json.dumps(
+ [{"idx": 0, "name": "0", "path": "", "type": "sentence_transformers.models.Dense"}]
+ ),
+ encoding = "utf-8",
+ )
+ (model / "config.json").write_text(
+ json.dumps({"in_features": 8, "out_features": 8, "activation_function": f"{MARKER}.Thing"}),
+ encoding = "utf-8",
+ )
+
+ with pytest.raises(ValueError, match = "executes third-party code"):
+ FastSentenceTransformer._check_modules_json_types(str(model), None, False)
+
+
+def test_an_unreadable_module_config_refuses_rather_than_passing(tmp_path, monkeypatch):
+ """A fetch that fails is not a module without a config.
+
+ Swallowing the error meant the gate recorded "nothing to check" while the load that
+ follows makes its own request, which can succeed and resolve the unchecked name.
+ """
+ _simulate_pre_six(monkeypatch)
+ monkeypatch.setattr(
+ FastSentenceTransformer,
+ "_modules_json_for_gating",
+ staticmethod(lambda *a, **k: str(tmp_path / "modules.json")),
+ )
+ (tmp_path / "modules.json").write_text(
+ json.dumps(
+ [
+ {
+ "idx": 0,
+ "name": "0",
+ "path": "1_Dense",
+ "type": "sentence_transformers.models.Dense",
+ }
+ ]
+ ),
+ encoding = "utf-8",
+ )
+
+ def unreachable(*args, **kwargs):
+ raise OSError("hub unreachable")
+
+ _patch_download(monkeypatch, unreachable)
+
+ with pytest.raises(ValueError, match = "refuses rather than loading unchecked"):
+ FastSentenceTransformer._check_modules_json_types("acme/embedder", None, False)
+
+
+def test_a_module_that_ships_no_config_is_not_a_refusal(tmp_path, monkeypatch):
+ """A genuine 404 means there is no class ref to check, which is not an error."""
+ from huggingface_hub.errors import EntryNotFoundError
+
+ _simulate_pre_six(monkeypatch)
+ monkeypatch.setattr(
+ FastSentenceTransformer,
+ "_modules_json_for_gating",
+ staticmethod(lambda *a, **k: str(tmp_path / "modules.json")),
+ )
+ (tmp_path / "modules.json").write_text(
+ json.dumps(
+ [
+ {
+ "idx": 0,
+ "name": "0",
+ "path": "1_Dense",
+ "type": "sentence_transformers.models.Dense",
+ }
+ ]
+ ),
+ encoding = "utf-8",
+ )
+
+ def absent(*args, **kwargs):
+ raise EntryNotFoundError("no such file")
+
+ _patch_download(monkeypatch, absent)
+
+ FastSentenceTransformer._check_modules_json_types("acme/embedder", None, False)
+
+
+def test_the_module_config_check_is_skipped_where_upstream_gates_it(tmp_path, monkeypatch):
+ """On 6.0 and later there is nothing to add, so it must not spend a request."""
+ model = tmp_path / "model"
+ (model / "1_Dense").mkdir(parents = True)
+ (model / "modules.json").write_text(
+ json.dumps(
+ [
+ {
+ "idx": 0,
+ "name": "0",
+ "path": "1_Dense",
+ "type": "sentence_transformers.models.Dense",
+ }
+ ]
+ ),
+ encoding = "utf-8",
+ )
+ (model / "1_Dense" / "config.json").write_text(
+ json.dumps({"activation_function": f"{MARKER}.Thing"}), encoding = "utf-8"
+ )
+
+ def refuse(*args, **kwargs):
+ raise AssertionError("no fetch expected where upstream gates the name")
+
+ _patch_download(monkeypatch, refuse)
+
+ import sentence_transformers
+
+ monkeypatch.setattr(sentence_transformers, "__version__", "6.1.0", raising = False)
+ FastSentenceTransformer._check_modules_json_types(str(model), None, False)
+
+
+def test_only_the_config_the_loader_reads_is_requested(tmp_path, monkeypatch):
+ """WordEmbeddings.load never opens config.json, so asking for it is a liability.
+
+ With the fetch failing closed, an unnecessary request against a cache that has no
+ recorded 404 for the unused name turned a model the delegated loader could load
+ entirely from cache into a refusal.
+ """
+ _simulate_pre_six(monkeypatch)
+ monkeypatch.setattr(
+ FastSentenceTransformer,
+ "_modules_json_for_gating",
+ staticmethod(lambda *a, **k: str(tmp_path / "modules.json")),
+ )
+ (tmp_path / "modules.json").write_text(
+ json.dumps(
+ [
+ {
+ "idx": 0,
+ "name": "0",
+ "path": "0_WordEmbeddings",
+ "type": "sentence_transformers.models.WordEmbeddings",
+ }
+ ]
+ ),
+ encoding = "utf-8",
+ )
+
+ requested = []
+ config_dir = tmp_path / "cached" / "0_WordEmbeddings"
+ config_dir.mkdir(parents = True)
+ (config_dir / "wordembedding_config.json").write_text(
+ json.dumps(
+ {"tokenizer_class": "sentence_transformers.models.tokenizer.WhitespaceTokenizer"}
+ ),
+ encoding = "utf-8",
+ )
+
+ def fake_download(repo_id, filename, **kwargs):
+ requested.append(filename)
+ name = filename.rsplit("/", 1)[-1]
+ target = config_dir / name
+ if not target.is_file():
+ raise OSError("not cached, and the loader would never ask for this one")
+ return str(target)
+
+ _patch_download(monkeypatch, fake_download)
+
+ FastSentenceTransformer._check_modules_json_types("acme/embedder", None, False)
+
+ assert requested == ["0_WordEmbeddings/wordembedding_config.json"]
+
+
+def test_router_still_falls_back_to_config_json(tmp_path, monkeypatch):
+ """Router is the one class that does read config.json when its own file is absent."""
+ from huggingface_hub.errors import EntryNotFoundError
+ from sentence_transformers import models as st_models
+
+ if getattr(st_models, "Router", None) is None:
+ pytest.skip("installed sentence-transformers has no Router")
+
+ _simulate_pre_six(monkeypatch)
+ monkeypatch.setattr(
+ FastSentenceTransformer,
+ "_modules_json_for_gating",
+ staticmethod(lambda *a, **k: str(tmp_path / "modules.json")),
+ )
+ (tmp_path / "modules.json").write_text(
+ json.dumps(
+ [
+ {
+ "idx": 0,
+ "name": "0",
+ "path": "1_Router",
+ "type": "sentence_transformers.models.Router",
+ }
+ ]
+ ),
+ encoding = "utf-8",
+ )
+
+ config_dir = tmp_path / "cached" / "1_Router"
+ config_dir.mkdir(parents = True)
+ (config_dir / "config.json").write_text(
+ json.dumps({"types": {"query": f"{MARKER}.Thing"}}), encoding = "utf-8"
+ )
+
+ requested = []
+
+ def fake_download(repo_id, filename, **kwargs):
+ requested.append(filename)
+ name = filename.rsplit("/", 1)[-1]
+ target = config_dir / name
+ if not target.is_file():
+ raise EntryNotFoundError("absent")
+ return str(target)
+
+ _patch_download(monkeypatch, fake_download)
+
+ with pytest.raises(ValueError, match = "executes third-party code"):
+ FastSentenceTransformer._check_modules_json_types("acme/embedder", None, False)
+
+ assert requested[-1] == "1_Router/config.json"
+
+
+def test_an_empty_router_config_still_checks_the_fallback(tmp_path, monkeypatch):
+ """Router.load falls back on falsey content, not only on a missing file.
+
+ sentence-transformers 5.x Router.load reads its own file and then does
+ `if not config: config = cls.load_config(config_filename = "config.json")`, so an
+ existing but empty router_config.json sends it to config.json and it resolves the
+ `types` it finds there. Stopping at the first file that downloaded meant the gate
+ validated the empty file, never fetched the fallback, and passed on a repository whose
+ config.json names an arbitrary class.
+ """
+ import sentence_transformers
+
+ st_models = pytest.importorskip("sentence_transformers.models")
+ if getattr(st_models, "Router", None) is None:
+ pytest.skip("this sentence-transformers has no Router")
+
+ _simulate_pre_six(monkeypatch)
+
+ # Two directories on purpose. On a delegated route nothing is local, and the only
+ # files on disk are the ones this gate downloaded, so the cache has to start empty:
+ # writing both into one folder lets the reader find the fallback on disk and refuse
+ # for a reason that has nothing to do with whether it was ever fetched.
+ remote = tmp_path / "remote"
+ remote.mkdir()
+ (remote / "router_config.json").write_text("{}", encoding = "utf8")
+ (remote / "config.json").write_text(
+ json.dumps({"types": {"query": "evil_pkg.Thing"}}),
+ encoding = "utf8",
+ )
+ cache = tmp_path / "cache" / "1_Router"
+ cache.mkdir(parents = True)
+
+ requested = []
+
+ def fake_download(repo, filename, **kwargs):
+ requested.append(os.path.basename(filename))
+ name = os.path.basename(filename)
+ source = remote / name
+ if not source.exists():
+ from huggingface_hub.errors import EntryNotFoundError
+ raise EntryNotFoundError(filename)
+ target = cache / name
+ target.write_text(source.read_text(encoding = "utf8"), encoding = "utf8")
+ return str(target)
+
+ _patch_download(monkeypatch, fake_download)
+
+ with pytest.raises(ValueError, match = "evil_pkg.Thing"):
+ FastSentenceTransformer._check_delegated_module_config(
+ "acme/embedder",
+ {
+ "idx": 0,
+ "name": "0",
+ "path": "1_Router",
+ "type": "sentence_transformers.models.Router",
+ },
+ "sentence_transformers.models.Router",
+ st_models.Router,
+ )
+ # Both files, because the first one was empty.
+ assert requested == ["router_config.json", "config.json"]
+
+
+def test_a_non_empty_config_asks_for_nothing_extra(tmp_path, monkeypatch):
+ """The fallback costs a request only where upstream would take it.
+
+ A real Router config is a non-empty dict, upstream never reaches `if not config`, and
+ the check must not start fetching a second file on every ordinary load.
+ """
+ st_models = pytest.importorskip("sentence_transformers.models")
+ if getattr(st_models, "Router", None) is None:
+ pytest.skip("this sentence-transformers has no Router")
+
+ _simulate_pre_six(monkeypatch)
+
+ folder = tmp_path / "1_Router"
+ folder.mkdir()
+ (folder / "router_config.json").write_text(
+ json.dumps({"types": {"query": "sentence_transformers.models.Transformer"}}),
+ encoding = "utf8",
+ )
+ (folder / "config.json").write_text(
+ json.dumps({"types": {"query": "evil_pkg.Thing"}}),
+ encoding = "utf8",
+ )
+
+ requested = []
+
+ def fake_download(repo, filename, **kwargs):
+ requested.append(os.path.basename(filename))
+ return str(folder / os.path.basename(filename))
+
+ _patch_download(monkeypatch, fake_download)
+
+ FastSentenceTransformer._check_delegated_module_config(
+ "acme/embedder",
+ {"idx": 0, "name": "0", "path": "1_Router", "type": "sentence_transformers.models.Router"},
+ "sentence_transformers.models.Router",
+ st_models.Router,
+ )
+ assert requested == ["router_config.json"]
+
+
+def test_the_validated_commit_is_reported(tmp_path, monkeypatch):
+ """The gate hands back the commit it read, so the load can be pinned to it.
+
+ Validation and the load resolve the branch separately, so a repository that advances
+ between the two is checked on one snapshot and loaded from another.
+ """
+ snapshot = tmp_path / "models--acme--embedder" / "snapshots" / ("a" * 40)
+ snapshot.mkdir(parents = True)
+ (snapshot / "modules.json").write_text(
+ json.dumps(
+ [
+ {
+ "idx": 0,
+ "name": "0",
+ "path": "",
+ "type": "sentence_transformers.models.Transformer",
+ }
+ ]
+ ),
+ encoding = "utf8",
+ )
+ monkeypatch.setattr(FastSentenceTransformer, "_module_path", staticmethod(lambda *a, **k: None))
+ _patch_download(monkeypatch, lambda *a, **k: str(snapshot / "modules.json"))
+
+ assert (
+ FastSentenceTransformer._check_modules_json_types("acme/embedder", None, False) == "a" * 40
+ )
+
+
+def test_the_commit_comes_from_the_resolution_that_already_happened(tmp_path, monkeypatch):
+ """_module_path resolves through hf_hub_download, so its snapshot is the live one.
+
+ That is the branch an ordinary load takes, and taking the commit from the path it
+ returns is what makes the pin cost nothing: no second request, and no separate
+ resolution to disagree with.
+ """
+ snapshot = tmp_path / "models--acme--embedder" / "snapshots" / ("b" * 40)
+ snapshot.mkdir(parents = True)
+ (snapshot / "modules.json").write_text(
+ json.dumps(
+ [
+ {
+ "idx": 0,
+ "name": "0",
+ "path": "",
+ "type": "sentence_transformers.models.Transformer",
+ }
+ ]
+ ),
+ encoding = "utf8",
+ )
+ monkeypatch.setattr(
+ FastSentenceTransformer,
+ "_module_path",
+ staticmethod(lambda *a, **k: str(snapshot / "modules.json")),
+ )
+ _patch_download(
+ monkeypatch,
+ lambda *a, **k: pytest.fail("_module_path already resolved it; nothing else should fetch"),
+ )
+
+ assert (
+ FastSentenceTransformer._check_modules_json_types("acme/embedder", None, False) == "b" * 40
+ )
+
+
+def test_a_local_directory_has_no_commit_to_pin(tmp_path, monkeypatch):
+ """A folder on disk is not a snapshot, so the load must be left exactly as it was."""
+ local = tmp_path / "my-embedder"
+ local.mkdir()
+ (local / "modules.json").write_text(
+ json.dumps(
+ [
+ {
+ "idx": 0,
+ "name": "0",
+ "path": "",
+ "type": "sentence_transformers.models.Transformer",
+ }
+ ]
+ ),
+ encoding = "utf8",
+ )
+ assert FastSentenceTransformer._check_modules_json_types(str(local), None, False) == ""
+
+
+def test_consent_reports_no_commit(monkeypatch):
+ """With trust_remote_code there is nothing to gate, so there is nothing to pin."""
+ assert FastSentenceTransformer._check_modules_json_types("acme/embedder", None, True) == ""
+
+
+ "path, expected",
+ [
+ (f"/c/models--a--b/snapshots/{'c' * 40}/modules.json", "c" * 40),
+ (f"/c/models--a--b/snapshots/{'C' * 40}/modules.json", "c" * 40),
+ ("/c/models--a--b/snapshots/main/modules.json", ""),
+ ("/home/me/my-model/modules.json", ""),
+ (None, ""),
+ ],
+)
+def test_only_an_immutable_snapshot_is_a_commit(path, expected):
+ """A branch name in the snapshot slot is not something to pin to."""
+ assert FastSentenceTransformer._snapshot_revision(path) == expected
+
+
+def test_the_module_configs_are_read_from_the_validated_snapshot(tmp_path, monkeypatch):
+ """Every config read has to come from the commit modules.json came out of.
+
+ Passing the caller's revision through meant modules.json could resolve commit A while
+ each module config resolved commit B. The caller then pins the load to A, so a clean
+ config in B was validated while A's unchecked value was the one that ran. That inverts
+ the race rather than closing it.
+ """
+ _simulate_pre_six(monkeypatch)
+
+ commit = "c" * 40
+ snapshot = tmp_path / "models--acme--embedder" / "snapshots" / commit
+ snapshot.mkdir(parents = True)
+ (snapshot / "modules.json").write_text(
+ json.dumps(
+ [
+ {
+ "idx": 0,
+ "name": "0",
+ "path": "1_Dense",
+ "type": "sentence_transformers.models.Dense",
+ }
+ ]
+ ),
+ encoding = "utf8",
+ )
+ dense = snapshot / "1_Dense"
+ dense.mkdir()
+ (dense / "config.json").write_text(
+ json.dumps({"activation_function": "torch.nn.Tanh"}),
+ encoding = "utf8",
+ )
+
+ revisions = []
+
+ def fake_download(repo, filename, **kwargs):
+ revisions.append((os.path.basename(filename), kwargs.get("revision")))
+ return str(snapshot / filename)
+
+ _patch_download(monkeypatch, fake_download)
+
+ assert (
+ FastSentenceTransformer._check_modules_json_types(
+ "acme/embedder", None, False, revision = "main"
+ )
+ == commit
+ )
+
+ # modules.json is fetched on the caller's revision, because that is what resolves the
+ # commit. Everything after it is fetched on the commit that resolution produced.
+ assert revisions[0] == ("modules.json", "main")
+ assert [r for name, r in revisions[1:]] == [commit] * len(revisions[1:])
+ assert len(revisions) > 1
+
+
+def test_a_named_branch_still_resolves_to_a_commit(tmp_path, monkeypatch):
+ """The gate reports a commit even when the caller named a branch.
+
+ That is the input the pin needs, and it held on the previous head too: the bug was the
+ condition at the call site, which discarded this value whenever a revision was given
+ and so left `revision = "main"` racing exactly as a missing revision did. That half is
+ not unit-testable without a full load, and is covered by a traced base-against-head
+ run instead, where base passes "main" to SentenceTransformer and head passes the
+ resolved commit. This test guards the contract the call site depends on.
+ """
+ commit = "d" * 40
+ snapshot = tmp_path / "models--acme--embedder" / "snapshots" / commit
+ snapshot.mkdir(parents = True)
+ (snapshot / "modules.json").write_text(
+ json.dumps(
+ [
+ {
+ "idx": 0,
+ "name": "0",
+ "path": "",
+ "type": "sentence_transformers.models.Transformer",
+ }
+ ]
+ ),
+ encoding = "utf8",
+ )
+ monkeypatch.setattr(FastSentenceTransformer, "_module_path", staticmethod(lambda *a, **k: None))
+ _patch_download(monkeypatch, lambda *a, **k: str(snapshot / "modules.json"))
+
+ assert (
+ FastSentenceTransformer._check_modules_json_types(
+ "acme/embedder", None, False, revision = "main"
+ )
+ == commit
+ )
+
+
+def test_an_immutable_revision_resolves_to_itself(tmp_path, monkeypatch):
+ """A caller who already named a commit gets a pin that changes nothing."""
+ commit = "e" * 40
+ snapshot = tmp_path / "models--acme--embedder" / "snapshots" / commit
+ snapshot.mkdir(parents = True)
+ (snapshot / "modules.json").write_text(
+ json.dumps(
+ [
+ {
+ "idx": 0,
+ "name": "0",
+ "path": "",
+ "type": "sentence_transformers.models.Transformer",
+ }
+ ]
+ ),
+ encoding = "utf8",
+ )
+ monkeypatch.setattr(FastSentenceTransformer, "_module_path", staticmethod(lambda *a, **k: None))
+ _patch_download(monkeypatch, lambda *a, **k: str(snapshot / "modules.json"))
+
+ assert (
+ FastSentenceTransformer._check_modules_json_types(
+ "acme/embedder", None, False, revision = commit
+ )
+ == commit
+ )
+
+
+def test_a_confirmed_absent_modules_json_still_pins_the_load(tmp_path, monkeypatch):
+ """Absence is the thing being validated, so it has to be pinned like a presence.
+
+ And pinned to the commit that answered the 404, read off that response, not from a
+ second resolution of the branch. A second lookup can return a newer commit than the
+ one whose answer was "no modules.json", which pins the load to a snapshot nothing
+ checked: the same inversion as validating one commit and loading another, moved one
+ step along. The hub sends x-repo-commit on the 404, so the exact commit is already in
+ hand and costs no request.
+ """
+ from huggingface_hub.errors import EntryNotFoundError
+
+ commit = "f" * 40
+ monkeypatch.setattr(FastSentenceTransformer, "_module_path", staticmethod(lambda *a, **k: None))
+
+ class Response:
+ headers = {"x-repo-commit": commit}
+
+ def absent(*args, **kwargs):
+ error = EntryNotFoundError("no modules.json")
+ error.response = Response()
+ raise error
+
+ _patch_download(monkeypatch, absent)
+
+ def unexpected(*args, **kwargs):
+ pytest.fail("the 404 already named the commit; nothing should resolve it again")
+
+ monkeypatch.setattr("huggingface_hub.HfApi", unexpected)
+
+ assert (
+ FastSentenceTransformer._check_modules_json_types(
+ "acme/embedder", None, False, revision = "main"
+ )
+ == commit
+ )
+
+
+def test_a_404_without_a_commit_header_is_tolerated_where_upstream_gates_it(tmp_path, monkeypatch):
+ """From 6.0 upstream refuses the type itself, so an unpinnable absence is not fatal.
+
+ Below 6.0 it is: see the refusal test beside this one. A proxy that strips
+ x-repo-commit, or an older hub whose error carries no response at all, leaves nothing
+ to pin to, and on a version where nothing else checks the type that has to refuse.
+ """
+ from huggingface_hub.errors import EntryNotFoundError
+
+ monkeypatch.setattr(FastSentenceTransformer, "_module_path", staticmethod(lambda *a, **k: None))
+ _patch_download(
+ monkeypatch,
+ lambda *a, **k: (_ for _ in ()).throw(EntryNotFoundError("no modules.json")),
+ )
+
+ assert FastSentenceTransformer._check_modules_json_types("acme/embedder", None, False) == ""
+
+
@pytest.mark.parametrize("helper", ["present", "absent", "none"])
def test_the_check_does_not_key_off_the_import_module_class_attribute(
helper, tmp_path, monkeypatch
@@ -458,3 +1453,212 @@ def test_every_config_driven_import_in_sentence_transformers_has_a_rule():
if klass is None:
continue
assert FastSentenceTransformer._class_ref_rules(klass), name
+
+
+def test_the_delegated_check_fetches_the_legacy_config_filename(tmp_path, monkeypatch):
+ """A 3.x/4.x WordEmbeddings has no config_file_name, and its loader still reads
+ wordembedding_config.json.
+
+ Asking only for config.json got a 404, left `folders` empty, and passed, after which
+ the delegated loader read the legacy file and imported its tokenizer_class with
+ trust_remote_code=False. The local checker already consults
+ _LEGACY_MODULE_CONFIG_FILES; the delegated one did not.
+ """
+ _simulate_pre_six(monkeypatch)
+
+ class LegacyWordEmbeddings:
+ """No config_file_name, which is what 3.x and 4.x look like."""
+
+ __name__ = "WordEmbeddings"
+
+ LegacyWordEmbeddings.__name__ = "WordEmbeddings"
+
+ remote = tmp_path / "remote"
+ remote.mkdir()
+ (remote / "wordembedding_config.json").write_text(
+ json.dumps({"tokenizer_class": "evil_pkg.Tok"}), encoding = "utf8"
+ )
+ cache = tmp_path / "cache" / "0_WordEmbeddings"
+ cache.mkdir(parents = True)
+
+ requested = []
+
+ def fake_download(repo, filename, **kwargs):
+ name = os.path.basename(filename)
+ requested.append(name)
+ source = remote / name
+ if not source.exists():
+ from huggingface_hub.errors import EntryNotFoundError
+ raise EntryNotFoundError(filename)
+ target = cache / name
+ target.write_text(source.read_text(encoding = "utf8"), encoding = "utf8")
+ return str(target)
+
+ _patch_download(monkeypatch, fake_download)
+
+ with pytest.raises(ValueError, match = "evil_pkg.Tok"):
+ FastSentenceTransformer._check_delegated_module_config(
+ "acme/embedder",
+ {
+ "idx": 0,
+ "name": "0",
+ "path": "0_WordEmbeddings",
+ "type": "sentence_transformers.models.WordEmbeddings",
+ },
+ "sentence_transformers.models.WordEmbeddings",
+ LegacyWordEmbeddings,
+ )
+ assert "wordembedding_config.json" in requested
+
+
+def test_an_unparseable_manifest_refuses_rather_than_passing(tmp_path, monkeypatch):
+ """The file is in hand and still unreadable, which is not "nothing to check".
+
+ The delegated loader opens the very same path straight afterwards, so a transient read
+ error here followed by a retry that succeeds there would import a type nothing ever
+ looked at. Below 6.0 nothing else checks it, so this refuses.
+ """
+ _simulate_pre_six(monkeypatch)
+
+ broken = tmp_path / "models--acme--embedder" / "snapshots" / ("a" * 40)
+ broken.mkdir(parents = True)
+ (broken / "modules.json").write_text("{not json", encoding = "utf8")
+ monkeypatch.setattr(
+ FastSentenceTransformer,
+ "_module_path",
+ staticmethod(lambda *a, **k: str(broken / "modules.json")),
+ )
+
+ with pytest.raises(ValueError, match = "Could not read the modules.json"):
+ FastSentenceTransformer._check_modules_json_types("acme/embedder", None, False)
+
+
+def test_an_unparseable_manifest_is_tolerated_where_upstream_gates_it(tmp_path, monkeypatch):
+ """From 6.0 upstream refuses the type itself, so refusing here would only break a
+ load that is already safe."""
+ import sentence_transformers
+
+ monkeypatch.setattr(sentence_transformers, "__version__", "6.1.0", raising = False)
+
+ broken = tmp_path / "models--acme--embedder" / "snapshots" / ("b" * 40)
+ broken.mkdir(parents = True)
+ (broken / "modules.json").write_text("{not json", encoding = "utf8")
+ monkeypatch.setattr(
+ FastSentenceTransformer,
+ "_module_path",
+ staticmethod(lambda *a, **k: str(broken / "modules.json")),
+ )
+
+ assert (
+ FastSentenceTransformer._check_modules_json_types("acme/embedder", None, False) == "b" * 40
+ )
+
+
+def test_a_manifest_that_is_not_a_list_is_not_a_refusal(tmp_path, monkeypatch):
+ """A modules.json that is not a list names no modules, and the loader iterates it too,
+ so it cannot build a module from this either. Refusing would only break a load that
+ upstream fails on its own."""
+ _simulate_pre_six(monkeypatch)
+
+ odd = tmp_path / "models--acme--embedder" / "snapshots" / ("c" * 40)
+ odd.mkdir(parents = True)
+ (odd / "modules.json").write_text(json.dumps({"not": "a list"}), encoding = "utf8")
+ monkeypatch.setattr(
+ FastSentenceTransformer,
+ "_module_path",
+ staticmethod(lambda *a, **k: str(odd / "modules.json")),
+ )
+
+ assert (
+ FastSentenceTransformer._check_modules_json_types("acme/embedder", None, False) == "c" * 40
+ )
+
+
+def test_a_404_without_a_commit_header_refuses_below_six(tmp_path, monkeypatch):
+ """No commit from the response and none from the caller means no pin is possible.
+
+ The delegated request resolves the branch again and can get one that has since gained
+ a modules.json, so accepting the absence unpinned let that through.
+ """
+ from huggingface_hub.errors import EntryNotFoundError
+
+ _simulate_pre_six(monkeypatch)
+ monkeypatch.setattr(FastSentenceTransformer, "_module_path", staticmethod(lambda *a, **k: None))
+ _patch_download(
+ monkeypatch,
+ lambda *a, **k: (_ for _ in ()).throw(EntryNotFoundError("no modules.json")),
+ )
+
+ with pytest.raises(ValueError, match = "named no commit"):
+ FastSentenceTransformer._check_modules_json_types(
+ "acme/embedder", None, False, revision = "main"
+ )
+
+
+def test_an_explicit_commit_needs_no_commit_header(tmp_path, monkeypatch):
+ """A caller who named a commit has already answered the question the header answers.
+
+ The 404 was answered at that commit and there is nothing for a second resolution to
+ disagree with, so this must not refuse for want of a header.
+ """
+ from huggingface_hub.errors import EntryNotFoundError
+
+ commit = "a" * 40
+ _simulate_pre_six(monkeypatch)
+ monkeypatch.setattr(FastSentenceTransformer, "_module_path", staticmethod(lambda *a, **k: None))
+ _patch_download(
+ monkeypatch,
+ lambda *a, **k: (_ for _ in ()).throw(EntryNotFoundError("no modules.json")),
+ )
+
+ assert (
+ FastSentenceTransformer._check_modules_json_types(
+ "acme/embedder", None, False, revision = commit
+ )
+ == commit
+ )
+
+
+def test_an_unreadable_module_config_refuses_rather_than_skipping(tmp_path, monkeypatch):
+ """A config that is present and unreadable is unverifiable, not absent.
+
+ The loader opens this same path next and its read may succeed, so skipping meant a
+ Dense activation could be imported with nothing having checked it. The refusal the
+ fetch path promised was only ever about the fetch; this is the read.
+ """
+ st_models = pytest.importorskip("sentence_transformers.models")
+ _simulate_pre_six(monkeypatch)
+
+ folder = tmp_path / "2_Dense"
+ folder.mkdir()
+ (folder / "config.json").write_text("{not json", encoding = "utf8")
+
+ with pytest.raises(ValueError, match = "Could not read"):
+ FastSentenceTransformer._check_module_config_class_refs(
+ str(folder),
+ "sentence_transformers.models.Dense",
+ "acme/embedder",
+ False,
+ st_models.Dense,
+ )
+
+
+def test_an_unreadable_module_config_is_tolerated_where_upstream_gates_it(tmp_path, monkeypatch):
+ """From 6.0 upstream resolves these through its own gate, so refusing would only break
+ a load that is already safe."""
+ import sentence_transformers
+
+ st_models = pytest.importorskip("sentence_transformers.models")
+ monkeypatch.setattr(sentence_transformers, "__version__", "6.1.0", raising = False)
+
+ folder = tmp_path / "2_Dense"
+ folder.mkdir()
+ (folder / "config.json").write_text("{not json", encoding = "utf8")
+
+ FastSentenceTransformer._check_module_config_class_refs(
+ str(folder),
+ "sentence_transformers.models.Dense",
+ "acme/embedder",
+ False,
+ st_models.Dense,
+ )
diff --git a/unsloth/models/sentence_transformer.py b/unsloth/models/sentence_transformer.py
index 69b360e86db..f382a5ab343 100644
--- a/unsloth/models/sentence_transformer.py
+++ b/unsloth/models/sentence_transformer.py
@@ -1296,13 +1296,15 @@ class FastSentenceTransformer(FastModel):
"sentence_transformers.base.modules.transformer.Transformer",
}
- # Dense imports AND CALLS config["activation_function"], WordEmbeddings imports
- # config["tokenizer_class"], Router/Asym import every config["types"] value, all ungated on
- # some versions, so an allowed in-namespace "type" reaches them. Prefixes are upstream's own
- # rules, applied unconditionally: util.import_module_class is not a version test, since 5.5
- # exports it while its WordEmbeddings.load still calls import_from_string on tokenizer_class.
# Which config key each loader resolves as a dotted import path, keyed by the class
- # that resolves it. By class and not by key name: SpladePooling lists
+ # that resolves it. Dense imports AND CALLS config["activation_function"],
+ # WordEmbeddings imports config["tokenizer_class"], Router and Asym import every
+ # config["types"] value, all ungated on some versions, so an allowed in-namespace
+ # "type" reaches them. The prefixes are upstream's own rules and are applied on every
+ # version: util.import_module_class is not a version test, since 5.5 exports it while
+ # its WordEmbeddings.load still calls import_from_string on tokenizer_class.
+ #
+ # By class and not by key name: SpladePooling lists
# activation_function in its own config_keys too, but the value there is the literal
# "relu" or "log1p_relu" and it is compared, never imported (SpladePooling.py:
# `if self.activation_function == "log1p_relu"`). Matching on the key name alone
@@ -1380,6 +1382,25 @@ class FastSentenceTransformer(FastModel):
with open(config_path, encoding = "utf8") as f:
config = json.load(f)
except (OSError, ValueError) as exception:
+ # The file is there and cannot be read, which is not the same as not being
+ # there: the loader opens this same path next and its read may succeed, so
+ # skipping here meant a Dense activation, a WordEmbeddings tokenizer or a
+ # Router type could be imported with nothing having checked it. The
+ # refusal the caller's message promised was only ever about the fetch;
+ # this is the read.
+ import sentence_transformers
+
+ if Version(sentence_transformers.__version__).major < 6:
+ raise ValueError(
+ f"Unsloth: Could not read {config_path} to check the class the "
+ f"module {class_ref} of {model_name} names "
+ f"({type(exception).__name__}: {exception}). The installed "
+ f"sentence-transformers "
+ f"({getattr(sentence_transformers, '__version__', 'unknown')}) "
+ f"resolves that name without checking it, so this refuses rather "
+ f"than loading unchecked. Retry, or pass the argument "
+ f"`trust_remote_code=True` to allow custom code to be run."
+ ) from exception
logging.debug(
"Unsloth: Could not read module config %s: %s", config_path, exception
)
@@ -1400,6 +1421,14 @@ class FastSentenceTransformer(FastModel):
elif isinstance(config.get(key), str):
refs.append((key, config[key], prefix))
+ # Upstream reads its own file and only falls back when the parsed content is
+ # falsey (Router.py: `if not config:`), so once a real config has been read
+ # there is no second file the loader will look at. Reading both and taking the
+ # union refused a repository whose router_config.json is clean because an
+ # unrelated config.json sat beside it, which is a load upstream completes.
+ if config:
+ break
+
for key, value, prefix in refs:
if not value.startswith(prefix):
raise ValueError(
@@ -1409,6 +1438,510 @@ class FastSentenceTransformer(FastModel):
f"be run."
)
+ @staticmethod
+ def _is_commit(revision):
+ """Is this revision already an immutable commit, rather than a branch or tag."""
+ if not isinstance(revision, str) or len(revision) != 40:
+ return False
+ return all(c in "0123456789abcdef" for c in revision.lower())
+
+ @staticmethod
+ def _commit_of_response(exception):
+ """The commit a hub error's own response was answered at, or "".
+
+ hf_hub_download's 404 carries x-repo-commit, so the commit that established an
+ absence is already in hand. Only the remote variants of the error carry a
+ response, and the header can be absent through a proxy, so this returns "" and the
+ caller leaves the load unpinned rather than guessing.
+ """
+ response = getattr(exception, "response", None)
+ headers = getattr(response, "headers", None)
+ if headers is None:
+ return ""
+ try:
+ sha = headers.get("x-repo-commit") or headers.get("X-Repo-Commit") or ""
+ except Exception:
+ return ""
+ if isinstance(sha, str) and len(sha) == 40:
+ lowered = sha.lower()
+ if all(c in "0123456789abcdef" for c in lowered):
+ return lowered
+ return ""
+
+ @staticmethod
+ def _snapshot_revision(path):
+ """The commit a hub cache path belongs to, or "" when it is not one.
+
+ hf_hub_download returns <cache>/models--org--name/snapshots/<sha>/<file>, so the
+ commit the gate just read is already in hand and costs no request to recover.
+ Anything that is not a 40-hex snapshot component (a local directory, a layout this
+ does not recognise) returns "", which means "do not pin".
+ """
+ if not isinstance(path, str):
+ return ""
+ parts = path.replace("\\", "/").split("/")
+ for index in range(len(parts) - 2, -1, -1):
+ if parts[index] != "snapshots":
+ continue
+ candidate = parts[index + 1]
+ if len(candidate) == 40 and all(c in "0123456789abcdef" for c in candidate.lower()):
+ return candidate.lower()
+ return ""
+ return ""
+
+ @staticmethod
+ def _modules_json_for_gating(
+ model_name,
+ token,
+ cache_dir = None,
+ revision = None,
+ resolved = None,
+ ):
+ """Return the modules.json path, or None when the repo confirmedly has none.
+
+ Raise when neither can be established: _module_path turns every failure into "absent", and
+ a guard must not read "could not check" as "nothing to check". Only worth refusing over
+ where sentence-transformers would not gate the type itself, which it does from 6.0.
+ """
+ path = FastSentenceTransformer._module_path(
+ model_name, token, cache_dir = cache_dir, revision = revision
+ )
+ if path:
+ if resolved is not None:
+ # _module_path resolves through hf_hub_download, so online this is the
+ # commit the branch points at right now and offline it is the cached
+ # snapshot, which is the only thing the load could use either. Both are
+ # the snapshot the load would reach on its own, so recording it here
+ # pins the load to what was checked without asking the hub again.
+ resolved["revision"] = FastSentenceTransformer._snapshot_revision(path)
+ return path
+
+ try:
+ if os.path.isdir(model_name):
+ return None
+ except (OSError, TypeError, ValueError):
+ pass
+
+ from huggingface_hub import try_to_load_from_cache
+ from huggingface_hub.errors import EntryNotFoundError, LocalEntryNotFoundError
+
+ def _cached_answer():
+ """What the local cache already knows, or None if it knows nothing."""
+ try:
+ # No default of our own: HUGGINGFACE_HUB_CACHE is the legacy constant and
+ # does not follow HF_HUB_CACHE, so naming it searched a different cache
+ # from the one hf_hub_download writes, and a recorded absence there was
+ # missed. Passing None lets the hub apply the same default it applies to
+ # the download below.
+ return try_to_load_from_cache(
+ model_name,
+ "modules.json",
+ cache_dir = cache_dir,
+ revision = revision,
+ )
+ except Exception:
+ return None
+
+ # Deliberately not consulted before the download. A recorded absence is keyed to
+ # whatever commit the local refs file points at, which for a branch is a stale
+ # pointer, so answering "this repo has no modules.json" from it decided a security
+ # question against a snapshot nobody had checked was current, and reported no
+ # commit, which left the load unpinned. A branch that gains a modules.json between
+ # the two then loads an unchecked module type. The cache is still the answer when
+ # the hub cannot be reached, which is what the LocalEntryNotFoundError handler
+ # below uses it for, so an offline load behaves as it did.
+ try:
+ downloaded = hf_hub_download(
+ model_name,
+ "modules.json",
+ token = token,
+ cache_dir = cache_dir,
+ revision = revision,
+ )
+ if resolved is not None:
+ resolved["revision"] = FastSentenceTransformer._snapshot_revision(downloaded)
+ return downloaded
+ except LocalEntryNotFoundError as exception:
+ # Checked before EntryNotFoundError, which it subclasses: not reachable is not the same
+ # answer as not present, and catching it there read one as the other.
+ cached = _cached_answer()
+ if isinstance(cached, str):
+ if resolved is not None:
+ resolved["revision"] = FastSentenceTransformer._snapshot_revision(cached)
+ return cached
+ if cached is not None:
+ # Unreachable, and the cache already recorded that this repo has no
+ # modules.json. "The load can only use the cache too" was the reasoning
+ # here and it is wrong: this request failed, not every request, so the
+ # delegated load can recover and fetch the current branch, which may have
+ # gained a module type since the cached answer. Returning success with no
+ # pin let exactly that through.
+ #
+ # So the load is pinned to the commit the cache holds for this revision,
+ # recovered from a file that lives in the same snapshot. That is the
+ # snapshot whose absence was recorded, which makes the load consistent
+ # with what was checked, and offline it is what would have been served
+ # anyway.
+ snapshot_commit = ""
+ for probe in (
+ "config.json",
+ "config_sentence_transformers.json",
+ "tokenizer_config.json",
+ "README.md",
+ ):
+ try:
+ hit = try_to_load_from_cache(
+ model_name,
+ probe,
+ cache_dir = cache_dir,
+ revision = revision,
+ )
+ except Exception:
+ continue
+ if isinstance(hit, str):
+ snapshot_commit = FastSentenceTransformer._snapshot_revision(hit)
+ if snapshot_commit:
+ break
+ if snapshot_commit:
+ if resolved is not None:
+ resolved["revision"] = snapshot_commit
+ return None
+ # No commit to pin to, so there is no way to make the load match what was
+ # checked. Fail closed below 6.0, the same rule as every other branch that
+ # could not establish an answer.
+ import sentence_transformers
+
+ if Version(sentence_transformers.__version__).major >= 6:
+ logging.debug(
+ "Unsloth: %s is unreachable and its cached absence names no "
+ "commit; sentence-transformers gates the module class itself on "
+ "this version.",
+ model_name,
+ )
+ return None
+ raise ValueError(
+ f"Unsloth: Could not reach {model_name} to check its module classes, "
+ f"and the cached answer names no commit to load instead "
+ f"({type(exception).__name__}: {exception}). The installed "
+ f"sentence-transformers "
+ f"({getattr(sentence_transformers, '__version__', 'unknown')}) imports "
+ f"a module class named in modules.json without checking it, so this "
+ f"refuses rather than loading whatever the retry returns. Retry, or "
+ f"pass the argument `trust_remote_code=True` to allow custom code to "
+ f"be run."
+ ) from exception
+ unverifiable = exception
+ except EntryNotFoundError as exception:
+ # The repo really has no modules.json at this revision. Pin anyway: absence is
+ # the thing being validated, and a branch that gains one before the load would
+ # otherwise bring in an unchecked module type.
+ #
+ # The commit comes off the 404 itself, not from a second lookup. Resolving the
+ # branch again could answer with a newer commit than the one that established
+ # the absence, which would pin the load to a snapshot nothing had checked: the
+ # same inversion as validating one commit and loading another, moved one step
+ # along. The hub returns x-repo-commit on the 404, so the response names
+ # exactly the commit whose answer was "no modules.json", and it costs nothing.
+ if resolved is not None:
+ sha = FastSentenceTransformer._commit_of_response(exception)
+ if not sha and FastSentenceTransformer._is_commit(revision):
+ # The caller already named an immutable commit, so the 404 was
+ # answered at it and there is nothing for a second resolution to
+ # disagree with. No header needed.
+ sha = revision.lower()
+ if sha:
+ resolved["revision"] = sha
+ else:
+ # No commit from the response and none from the caller, so there is no
+ # way to make the load match the absence that was just established:
+ # the delegated request resolves the branch again and can get one that
+ # has since gained a modules.json. Fail closed below 6.0, the same
+ # rule as every other branch that cannot establish an answer.
+ import sentence_transformers
+ if Version(sentence_transformers.__version__).major < 6:
+ raise ValueError(
+ f"Unsloth: {model_name} reports no modules.json at "
+ f"{revision or 'the default revision'}, and the response named "
+ f"no commit, so the load cannot be pinned to the revision that "
+ f"was checked. The installed sentence-transformers "
+ f"({getattr(sentence_transformers, '__version__', 'unknown')}) "
+ f"imports a module class named in modules.json without checking "
+ f"it, so this refuses rather than loading whatever the next "
+ f"request returns. Pass an explicit `revision` naming a commit, "
+ f"or pass the argument `trust_remote_code=True` to allow custom "
+ f"code to be run."
+ ) from exception
+ logging.debug(
+ "Unsloth: the 404 for %s carried no commit; sentence-transformers "
+ "gates the module class itself on this version.",
+ model_name,
+ )
+ return None
+ except Exception as exception:
+ unverifiable = exception
+
+ import sentence_transformers
+
+ if Version(sentence_transformers.__version__).major >= 6:
+ logging.debug(
+ "Unsloth: Could not read modules.json of %s (%s); sentence-transformers gates the "
+ "module class itself on this version.",
+ model_name,
+ unverifiable,
+ )
+ return None
+ raise ValueError(
+ f"Unsloth: Could not read modules.json of {model_name} to check its module classes "
+ f"({type(unverifiable).__name__}: {unverifiable}). The installed sentence-transformers "
+ f"({getattr(sentence_transformers, '__version__', 'unknown')}) imports a module class "
+ f"named there without checking it, so this refuses rather than loading unchecked. "
+ f"Retry, or pass the argument `trust_remote_code=True` to allow custom code to be run."
+ ) from unverifiable
+
+ @staticmethod
+ def _check_modules_json_types(
+ model_name,
+ token,
+ trust_remote_code,
+ cache_dir = None,
+ revision = None,
+ ):
+ """Validate only, and report the commit that was validated.
+
+ for_inference and the fast encoder route return a stock SentenceTransformer without
+ reaching _load_modules, and below 6.0 it has no gate.
+
+ The return value is the resolved commit, or "" when there is none to report. The
+ validation and the load that follows it resolve the repository separately, so a
+ branch that advances between the two means the gate passed on one snapshot while
+ another one loaded. Handing the caller the commit this read lets the load be pinned
+ to the snapshot that was actually checked, at no extra request: the fetch here
+ already resolved it. It is "" for a local directory, for a revision that is not an
+ immutable commit, and whenever there was no modules.json to read, and the caller
+ then loads exactly as it did before.
+ """
+ # Consent means the code may run, so there is nothing to gate and nothing to import here.
+ # Resolving anyway would also break a repo-local class: below 6 the delegated loader fetches
+ # it with get_class_from_dynamic_module, where this helper's fallback cannot.
+ if trust_remote_code:
+ return ""
+
+ # The delegated loads honour SENTENCE_TRANSFORMERS_HOME, and hf_hub_download does not, so
+ # resolve it here too: otherwise _module_path looks in the wrong cache, swallows the miss,
+ # and the gate passes on a modules.json it never read.
+ cache_dir = cache_dir or os.environ.get("SENTENCE_TRANSFORMERS_HOME")
+ resolved = {}
+ modules_json_path = FastSentenceTransformer._modules_json_for_gating(
+ model_name, token, cache_dir = cache_dir, revision = revision, resolved = resolved
+ )
+ validated = resolved.get("revision", "")
+ # Everything below this point reads from the snapshot modules.json came out of, not
+ # from the caller's revision. Passing the original through meant modules.json could
+ # resolve commit A while each module config resolved commit B, and since the caller
+ # pins the load to A, a clean config in B was validated while A's unchecked value
+ # was the one that ran. That inverts the race rather than closing it.
+ config_revision = validated or revision
+ if not modules_json_path:
+ return validated
+ try:
+ with open(modules_json_path, encoding = "utf8") as f:
+ modules_config = json.load(f)
+ except (OSError, ValueError) as exception:
+ # Fail closed, for the same reason the fetch error does. The file is in hand
+ # and still unreadable, and the delegated loader opens the very same path
+ # straight afterwards: a transient read error or a retry that succeeds there
+ # would import a type nothing ever looked at. "Could not check" is not
+ # "nothing to check". Only worth refusing over below 6.0, where
+ # sentence-transformers does not gate the type itself.
+ import sentence_transformers
+ if Version(sentence_transformers.__version__).major >= 6:
+ logging.debug(
+ "Unsloth: Could not read %s to gate its module types (%s); "
+ "sentence-transformers gates the module class itself on this version.",
+ modules_json_path,
+ exception,
+ )
+ return validated
+ raise ValueError(
+ f"Unsloth: Could not read the modules.json of {model_name} that was just "
+ f"fetched, to check its module classes ({type(exception).__name__}: "
+ f"{exception}). The installed sentence-transformers "
+ f"({getattr(sentence_transformers, '__version__', 'unknown')}) imports a "
+ f"module class named there without checking it, so this refuses rather "
+ f"than loading unchecked. Retry, or pass the argument "
+ f"`trust_remote_code=True` to allow custom code to be run."
+ ) from exception
+ if not isinstance(modules_config, list):
+ # Not a refusal: a modules.json that is not a list names no modules at all,
+ # and the loader iterates it, so it cannot build a module from this either.
+ return validated
+
+ for module_config in modules_config:
+ if not isinstance(module_config, dict):
+ continue
+ class_ref = module_config.get("type")
+ if FastSentenceTransformer._is_transformer_module_ref(class_ref):
+ continue
+ module_class = FastSentenceTransformer._resolve_module_class(
+ class_ref,
+ model_name,
+ trust_remote_code,
+ token = token,
+ cache_dir = cache_dir,
+ revision = config_revision,
+ )
+ FastSentenceTransformer._check_delegated_module_config(
+ model_name,
+ module_config,
+ class_ref,
+ module_class,
+ token = token,
+ cache_dir = cache_dir,
+ revision = config_revision,
+ )
+
+ return validated
+
+ # The module classes whose own loader resolves a dotted path out of their config: Dense
+ # reads activation_function, WordEmbeddings reads tokenizer_class, Router and Asym read
+ # types. Every other shipped class reads plain values only, so an ordinary embedder
+ # (Transformer, Pooling, Normalize) costs no extra request below.
+ _CONFIG_REF_MODULE_CLASSES = frozenset({"Asym", "Dense", "Router", "WordEmbeddings"})
+
+ @staticmethod
+ def _check_delegated_module_config(
+ model_name,
+ module_config,
+ class_ref,
+ module_class,
+ token = None,
+ cache_dir = None,
+ revision = None,
+ ):
+ """Check a module's own config on a delegated route, where nothing is local yet.
+
+ An allowed type is not enough: sentence-transformers below 6 lets Dense name any
+ activation_function and Router any types entry, and resolves that dotted path itself.
+ _load_modules checks this already, from files it has just downloaded; the delegated
+ routes hand the whole load to sentence-transformers and so never reached it.
+
+ Scoped to the classes that actually read a class ref, so the usual load adds no
+ request, and skipped entirely where sentence-transformers gates the name itself,
+ so no version that does not need this pays for it.
+ """
+ if getattr(module_class, "__name__", "") not in (
+ FastSentenceTransformer._CONFIG_REF_MODULE_CLASSES
+ ):
+ return
+
+ import sentence_transformers
+
+ if Version(sentence_transformers.__version__).major >= 6:
+ # Upstream resolves these through its own gate from 6.0, so there is nothing
+ # to add and no reason to spend a request. Deliberately the version and not
+ # hasattr(import_module_class): 5.5 exports that helper while its module
+ # loaders still resolve the name ungated.
+ return
+
+ folder = module_config.get("path")
+ if not isinstance(folder, str):
+ return
+ # An empty path is the repository root, which sentence-transformers accepts and
+ # loads the root config.json from. Skipping it left the whole check bypassable by
+ # declaring Dense with "path": "".
+ folder = folder.strip("/")
+
+ config_names = []
+ config_file_name = getattr(module_class, "config_file_name", None)
+ if isinstance(config_file_name, str):
+ config_names.append(config_file_name)
+ else:
+ # config_file_name only exists from 5, so on 3.x and 4.x a WordEmbeddings has
+ # no such attribute while its loader still opens wordembedding_config.json.
+ # Asking only for config.json got a 404, left nothing to check, and passed,
+ # after which the loader read the legacy file and imported its tokenizer_class
+ # ungated. The local checker already consults this table; so does this now.
+ legacy = FastSentenceTransformer._LEGACY_MODULE_CONFIG_FILES.get(
+ getattr(module_class, "__name__", "")
+ )
+ if legacy is not None:
+ config_names.append(legacy)
+ config_names.append("config.json")
+ # Only Router and Asym fall back to config.json when their own file is absent.
+ # The others open exactly one file, and requesting a second one the loader never
+ # reads can fail on a cache that is complete for the load but carries no recorded
+ # 404 for the unused name, turning a loadable offline model into a refusal.
+ if (
+ getattr(module_class, "__name__", "") in ("Asym", "Router")
+ and "config.json" not in config_names
+ ):
+ config_names.append("config.json")
+
+ try:
+ is_local = os.path.isdir(model_name)
+ except (OSError, TypeError, ValueError):
+ is_local = False
+
+ folders = []
+ if is_local:
+ folders.append(os.path.join(model_name, *folder.split("/")) if folder else model_name)
+ else:
+ from huggingface_hub.errors import EntryNotFoundError, LocalEntryNotFoundError
+ for config_name in dict.fromkeys(config_names):
+ try:
+ downloaded = hf_hub_download(
+ model_name,
+ f"{folder}/{config_name}" if folder else config_name,
+ token = token,
+ cache_dir = cache_dir,
+ revision = revision,
+ )
+ except LocalEntryNotFoundError as exception:
+ # Checked first: it subclasses EntryNotFoundError, so catching the parent
+ # above it would read "could not reach" as "not present".
+ raise ValueError(
+ f"Unsloth: Could not read {config_name} of the module {class_ref} in "
+ f"{model_name} to check the class it names "
+ f"({type(exception).__name__}: {exception}). Loading would resolve that "
+ f"name on this sentence-transformers, so this refuses rather than "
+ f"loading unchecked. Retry, or pass the argument "
+ f"`trust_remote_code=True` to allow custom code to be run."
+ ) from exception
+ except EntryNotFoundError:
+ # A genuine 404: this module ships no such config, so there is no class
+ # ref in it to check.
+ continue
+ except Exception as exception:
+ raise ValueError(
+ f"Unsloth: Could not read {config_name} of the module {class_ref} in "
+ f"{model_name} to check the class it names "
+ f"({type(exception).__name__}: {exception}). Loading would resolve that "
+ f"name on this sentence-transformers, so this refuses rather than "
+ f"loading unchecked. Retry, or pass the argument "
+ f"`trust_remote_code=True` to allow custom code to be run."
+ ) from exception
+ folders.append(os.path.dirname(downloaded))
+ # Router.load falls back to config.json when the parsed content is falsey,
+ # not merely when its own file is absent (Router.py: `if not config:`).
+ # Stopping at the first file that downloaded therefore validated an empty
+ # router_config.json and never fetched the fallback, so the `types` the
+ # loader does resolve went unchecked. A real config is a non-empty dict and
+ # still stops here, so a working model asks for nothing extra.
+ try:
+ with open(downloaded, encoding = "utf8") as handle:
+ content = json.load(handle)
+ except (OSError, ValueError):
+ # Unreadable is not "checked": let the fallback be fetched too, and
+ # leave the refusal to the reader below, which sees both files.
+ content = None
+ if content:
+ break
+
+ for load_path in dict.fromkeys(folders):
+ FastSentenceTransformer._check_module_config_class_refs(
+ load_path, class_ref, model_name, False, module_class
+ )
+
@staticmethod
def _load_modules(
model_name,
@@ -1777,6 +2310,24 @@ class FastSentenceTransformer(FastModel):
if _st_cache is not None:
st_kwargs["cache_folder"] = _st_cache
+ _validated = FastSentenceTransformer._check_modules_json_types(
+ model_name,
+ token,
+ trust_remote_code,
+ cache_dir = st_kwargs.get("cache_folder"),
+ revision = revision,
+ )
+ # Load the snapshot that was checked. Without this the gate reads one commit of
+ # a branch and the load resolves the branch again, so a repository that advances
+ # in between is validated on the old files and loaded from the new ones.
+ #
+ # Whenever the gate resolved a commit, including when the caller named a
+ # revision. Restricting it to a falsey revision left `revision = "main"` racing
+ # exactly as before, and it does not override anyone's choice: _validated IS
+ # what the caller's own revision resolved to, so pinning only removes the second
+ # resolution. An explicit commit resolves to itself and the pin is a no-op.
+ if _validated:
+ st_kwargs["revision"] = _validated
st_model = SentenceTransformer(model_name, **st_kwargs)
if _ensure_sentence_attention_masks(
getattr(st_model[0], "auto_model", None)
@@ -1873,12 +2424,20 @@ class FastSentenceTransformer(FastModel):
FastSentenceTransformer._patch_mpnet_v5()
# ST takes cache_folder, not cache_dir: map cache_dir onto it so this load hits the warm cache (None lets ST honor SENTENCE_TRANSFORMERS_HOME, matching the prefetch).
+ _validated = FastSentenceTransformer._check_modules_json_types(
+ model_name,
+ token,
+ trust_remote_code,
+ cache_dir = kwargs.get("cache_dir") or kwargs.get("cache_folder"),
+ revision = revision,
+ )
+ # Same race as the delegated route above, same pin.
st_model = SentenceTransformer(
model_name,
device = st_device,
trust_remote_code = trust_remote_code,
token = token,
- revision = revision,
+ revision = _validated or revision,
model_kwargs = model_kwargs,
cache_folder = kwargs.get("cache_dir") or kwargs.get("cache_folder"),
)