misc

sentence_transformers.util.misc.check_teacher_targets(teacher_probabilities: Tensor, teacher_logits: Tensor, teacher_temperature: float, loss_name: str) → None

Inspect a distillation loss’s teacher target once, on its first forward.

Takes the target the loss itself computed rather than recomputing a softmax, so the two can never disagree. Reading either result off an accelerator costs a device synchronization, hence the once-per-loss contract. That also means only the first batch a loss sees is inspected: with one loss shared across a DatasetDict whose splits carry differently scaled teacher scores, the splits drawn later go unexamined.

Parameters:

• teacher_probabilities – The softmaxed teacher target the loss will use.

• teacher_logits – The raw teacher scores, used to report their spread.

• teacher_temperature – The temperature already applied to teacher_logits.

• loss_name – Loss class name, to open the message with.

Raises:

ValueError – If the teacher scores contain NaN, which would make the loss and every gradient NaN on the first backward.

sentence_transformers.util.misc.disable_datasets_caching()

A context manager that will disable caching in the datasets library.

sentence_transformers.util.misc.disable_logging(highest_level=50)

A context manager that will prevent any logging messages triggered during the body from being processed.

Parameters:

highest_level – the maximum logging level allowed.

sentence_transformers.util.misc.fullname(obj) → str

Gives a full name (package_name.class_name) for a class / object in Python. Will be used to load the correct classes from JSON files

Parameters:

obj – The object for which to get the full name, e.g. an instance of a class or the class itself.

Returns:

The full name of the object.

Return type:

str

Example

>>> from sentence_transformers.sentence_transformer.losses import MultipleNegativesRankingLoss
>>> from sentence_transformers import SentenceTransformer
>>> from sentence_transformers.util import fullname
>>> model = SentenceTransformer('sentence-transformers/all-MiniLM-L6-v2')
>>> loss = MultipleNegativesRankingLoss(model)
>>> fullname(loss)
'sentence_transformers.sentence_transformer.losses.multiple_negatives_ranking.MultipleNegativesRankingLoss'

sentence_transformers.util.misc.import_from_string(dotted_path: str) → type

Import a dotted module path and return the attribute/class designated by the last name in the path. Raise ImportError if the import failed.

Parameters:

dotted_path (str) – The dotted module path.

Returns:

The attribute/class designated by the last name in the path.

Return type:

Any

Raises:

ImportError – If the import failed.

Example

>>> import_from_string('sentence_transformers.sentence_transformer.losses.multiple_negatives_ranking.MultipleNegativesRankingLoss')
<class 'sentence_transformers.sentence_transformer.losses.multiple_negatives_ranking.MultipleNegativesRankingLoss'>

sentence_transformers.util.misc.import_module_class(class_ref: str, model_name_or_path: str | None = None, *, trust_remote_code: bool = False, revision: str | None = None, code_revision: str | None = None, token: bool | str | None = None, cache_folder: str | None = None, local_files_only: bool = False) → type

Resolve a module class reference to a class object.

For class refs in the sentence_transformers.* namespace, this imports directly via import_from_string(). For other class refs (e.g. repository-local custom classes like modeling_my_model.CustomTransformer), it first tries transformers.dynamic_module_utils.get_class_from_dynamic_module() to fetch the modeling file from the model directory, then falls back to import_from_string() if dynamic loading is not applicable or fails.

Importing a class outside the sentence_transformers.* namespace runs code selected by the model’s configuration (repository-hosted modeling code via dynamic loading, or a locally installed package via direct import). Loading such a class requires trust_remote_code=True, for local directories just like for Hugging Face Hub repositories.

Changed in version 6.0: Importing a module class outside the sentence_transformers.* namespace now requires trust_remote_code=True whenever model_name_or_path is set. Previously a local model_name_or_path was implicitly trusted, and untrusted imports emitted a FutureWarning while still importing.

Parameters:

• class_ref – Dotted class path. Either a fully-qualified sentence_transformers.* path or a repository-local reference like modeling_<name>.<ClassName>.

• model_name_or_path – Hub repo id or local directory used to source repository-local modeling files. Required for dynamic loading.

• trust_remote_code – Whether to trust and import code selected by the model configuration. Required to import any non-sentence_transformers.* class when model_name_or_path is set, and permits dynamic loading of repository-hosted modeling files. Any falsy value, an explicit None included, is treated as False.

• revision – Hub revision to fetch the modeling file from.

• code_revision – Optional separate revision pinning for the modeling code (overrides revision when set).

• token – Hugging Face Hub authentication token. Required for fetching modeling files from private repositories.

• cache_folder – Optional override for the Hugging Face Hub cache directory.

• local_files_only – If True, only use cached files and never reach out to the Hub.

Returns:

The resolved class.

Raises:

ValueError – If class_ref is outside the sentence_transformers.* namespace, model_name_or_path is set, and trust_remote_code is not True.

sentence_transformers.util.misc.similarity_fct_name(similarity_fct: Callable) → str

Readable config-dict rendering of a loss’s scoring callable: objects exposing get_config_dict (e.g. configured metric classes) and functools.partial() bindings include their settings.