Adapter Utilities

A collection of utility methods mainly related to searching and loading adapter modules from Adapter-Hub.

class adapters.utils.AdapterInfo(source: str, adapter_id: str, model_name: Optional[str] = None, task: Optional[str] = None, subtask: Optional[str] = None, username: Optional[str] = None, adapter_config: Optional[dict] = None, sha1_checksum: Optional[str] = None)

Holds information about an adapter publicly available on the Hub. Returned by list_adapters().

Parameters

  • source (str) – The source repository of this adapter. Always ‘hf’ for adapters available on HF Model Hub.

  • adapter_id (str) – The unique identifier of this adapter.

  • model_name (str, optional) – The identifier of the model this adapter was trained for.

  • task (str, optional) – The task this adapter was trained for.

  • subtask (str, optional) – The subtask or dataset this adapter was trained on.

  • username (str, optional) – The username of author(s) of this adapter.

  • adapter_config (dict, optional) – The configuration dictionary of this adapter.

class adapters.utils.AdapterType(value)

Models all currently available model adapter types.

adapters.utils.download_cached(url, checksum=None, checksum_algo='sha1', cache_dir=None, force_extract=False, **kwargs)

This method downloads a file and caches it.

For more information on why this is needed, refer to the explanation in this Pull Request: https://github.com/adapter-hub/adapters/pull/750

adapters.utils.get_adapter_config_hash(config, length=16, ignore_params=[])

Calculates the hash of a given adapter configuration which is used to identify this configuration.

Returns

The resulting hash of the given config dict.

Return type

str

adapters.utils.get_adapter_info(adapter_id: str) → Optional[AdapterInfo]

Retrieves information about a specific adapter.

Parameters

adapter_id (str) – The identifier of the adapter to retrieve.

Returns

The adapter information or None if the adapter was not found.

Return type

AdapterInfo

adapters.utils.get_from_cache(url: str, cache_dir=None, force_download=False, proxies=None, etag_timeout=10, resume_download=False, user_agent: Optional[Union[Dict, str]] = None, use_auth_token: Optional[Union[bool, str]] = None, local_files_only=False) → Optional[str]

Given a URL, look for the corresponding file in the local cache. If it’s not there, download it. Then return the path to the cached file.

Returns

Local path (string) of file or if networking is off, last version of file cached on disk.

Raises

In case of non-recoverable file (non-existent or inaccessible url + no cache on disk). –

adapters.utils.list_adapters(model_name: Optional[str] = None) → List[AdapterInfo]

Retrieves a list of all publicly available adapters on AdapterHub.ml or on huggingface.co.

Parameters

model_name (str, optional) – If specified, only returns adapters trained for the model with this identifier.

adapters.utils.parse_adapter_config_string(config_string: str) → List[Tuple[str, dict]]

Parses an adapter configuration string into a list of tuples. Each tuple constists of an adapter config identifier and dictionary.

adapters.utils.prefix_attention_mask(attention_mask, dim: Union[int, List[int]] = 3, prefix_value: int = 0)

Adds a prefix to an attention mask. The length of the prefix is determined by the prefix_attention_mask_length attribute in the ForwardContext.

Parameters

  • attention_mask – The attention mask to add the prefix to.

  • dim (int) – The dimension along which to concatenate the prefix_attention_mask. Defaults to 3.

  • prefix_value (int) – The value to use for the prefix_attention_mask. Defaults to 0, however some models, e.g. DistilBert, use different values. BERT like models invert their extended_attention_mask, hence they use 0 as value for not masked tokens. This inversion is usually done in the forward method of the model in 2 different ways: 1) by calling self.invert_attention_mask, as BERT does 2) by doing the inversion manually, e.g. ALBERT does: extended_attention_mask = (1.0 - extended_attention_mask) * torch.finfo(self.dtype).min

adapters.utils.pull_from_hub(specifier: str, model_name: str, adapter_config: Optional[Union[dict, str]] = None, version: Optional[str] = None, strict: bool = False, **kwargs) → str

Redirects loading from the archived Hub repository to HuggingFace Model Hub.

Parameters

  • specifier (str) – A string specifying the adapter to be loaded.

  • model_name (str) – The identifier of the pre-trained model for which to load an adapter.

  • adapter_config (Union[dict, str], optional) – The configuration of the adapter to be loaded.

  • version (str, optional) – The version of the adapter to be loaded. Defaults to None.

  • strict (bool, optional) – If set to True, only allow adapters exactly matching the given config to be loaded. Defaults to False.

Returns

The local path to which the adapter has been downloaded.

Return type

str

adapters.utils.resolve_adapter_config(config: Union[dict, str], local_map=None, **kwargs) → dict

Resolves a given adapter configuration specifier to a full configuration dictionary.

Parameters

config (Union[dict, str]) –

The configuration to resolve. Can be either:

  • a dictionary: returned without further action

  • an identifier string available in local_map

  • the path to a file containing a full adapter configuration

Returns

The resolved adapter configuration dictionary.

Return type

dict

adapters.utils.resolve_adapter_path(adapter_name_or_path, model_name: Optional[str] = None, adapter_config: Optional[Union[dict, str]] = None, version: Optional[str] = None, **kwargs) → str

Resolves the path to a pre-trained adapter module. Note: If attempting to resolve an adapter from the Hub, adapter_config and model_name must be present.

Parameters

  • adapter_name_or_path (str) –

    Can be either:

    • the path to a folder in the file system containing the adapter configuration and weights

    • an url pointing to a zip folder containing the adapter configuration and weights

    • a specifier matching a pre-trained adapter uploaded to Adapter-Hub

  • model_name (str, optional) – The identifier of the pre-trained model for which to load an adapter.

  • adapter_config (Union[dict, str], optional) – The configuration of the adapter to be loaded.

  • version (str, optional) – The version of the adapter to be loaded. Defaults to None.

Returns

The local path from where the adapter module can be loaded.

Return type

str

adapters.utils.url_to_filename(url: str, etag: Optional[str] = None) → str

Generate a local filename from a url.

Convert url into a hashed filename in a reproducible way. If etag is specified, append its hash to the url’s, delimited by a period. If the url ends with .h5 (Keras HDF5 weights) adds ‘.h5’ to the name so that TF 2.0 can identify it as a HDF5 file (see https://github.com/tensorflow/tensorflow/blob/00fad90125b18b80fe054de1055770cfb8fe4ba3/tensorflow/python/keras/engine/network.py#L1380)

Parameters

  • url (str) – The address to the file.

  • etag (str, optional) – The ETag of the file.

Returns

The generated filename.