Python module
hf_utils
Utilities for interacting with Hugging Face Files/Repos.
HuggingFaceRepo
class max.pipelines.lib.hf_utils.HuggingFaceRepo(repo_id, revision='main', trust_remote_code=False, repo_type=None)
Handle for interacting with a Hugging Face repository (remote or local).
encoding_for_file()
encoding_for_file(file)
Infers the supported encoding for a given weight file path.
file_exists()
file_exists(filename)
Returns whether the given file exists in the repo.
files_for_encoding()
files_for_encoding(encoding, weights_format=None)
Returns paths to weight files for the given encoding (and optionally format).
-
Parameters:
-
- encoding (Literal['float32', 'bfloat16', 'q4_k', 'q4_0', 'q6_k', 'float8_e4m3fn', 'float4_e2m1fnx2', 'gptq'])
- weights_format (WeightsFormat | None)
-
Return type:
-
dict[WeightsFormat, list[Path]]
formats_available
property formats_available: list[WeightsFormat]
Returns the weight formats available in this repo.
info
property info: ModelInfo
Returns Hugging Face model info (online repos only).
repo_id
repo_id: str
The Hugging Face repo id. While it’s called repo_id, it can be a HF remote or local path altogether.
repo_type
repo_type: RepoType | None = None
The type of repo. This is inferred from the repo_id.
revision
revision: str = 'main'
The revision to use for the repo.
size_of()
size_of(filename)
Returns file size in bytes for online repos, or None.
supported_encodings
property supported_encodings: list[Literal['float32', 'bfloat16', 'q4_k', 'q4_0', 'q6_k', 'float8_e4m3fn', 'float4_e2m1fnx2', 'gptq']]
Returns encodings supported by this repo’s weight files.
trust_remote_code
trust_remote_code: bool = False
Whether to trust remote code.
weight_files
property weight_files: dict[WeightsFormat, list[str]]
Returns weight file paths grouped by format (safetensors, gguf).
download_weight_files()
max.pipelines.lib.hf_utils.download_weight_files(huggingface_model_id, filenames, revision=None, force_download=False, max_workers=8)
Downloads weight files for a Hugging Face model and returns local paths.
-
Parameters:
-
- huggingface_model_id (str) – The Hugging Face model identifier, ie. modularai/Llama-3.1-8B-Instruct-GGUF
- filenames (list[str]) – A list of file paths relative to the root of the Hugging Face repo. If files provided are available locally, download is skipped, and the local files are used.
- revision (str | None) – The Hugging Face revision to use. If provided, we check our cache directly without needing to go to Hugging Face directly, saving a network call.
- force_download (bool) – A boolean, indicating whether we should force the files to be redownloaded, even if they are already available in our local cache, or a provided path.
- max_workers (int) – The number of worker threads to concurrently download files.
-
Return type:
-
list[Path]
generate_local_model_path()
max.pipelines.lib.hf_utils.generate_local_model_path(repo_id, revision)
Generate the local filesystem path where a Hugging Face model repo is cached.
This function uses Hugging Face’s official snapshot_download with local_files_only=True to resolve the local cache path for a model repository.
-
Parameters:
-
Returns:
-
The absolute path to the cached model files for the specified revision.
-
Return type:
-
Raises:
-
FileNotFoundError – If the model is not found in the local cache
is_diffusion_pipeline()
max.pipelines.lib.hf_utils.is_diffusion_pipeline(repo)
Check if a Hugging Face repository is a diffusion pipeline.
Diffusion pipelines typically have a model_index.json file that describes the pipeline components.
-
Parameters:
-
repo (HuggingFaceRepo) – The HuggingFaceRepo to check.
-
Returns:
-
True if the repository appears to be a diffusion pipeline, False otherwise.
-
Return type:
try_to_load_from_cache()
max.pipelines.lib.hf_utils.try_to_load_from_cache(repo_id, filename, revision)
Wrapper around huggingface_hub.try_to_load_from_cache; validates repo exists.
validate_hf_repo_access is called first to ensure the repo exists.
validate_hf_repo_access()
max.pipelines.lib.hf_utils.validate_hf_repo_access(repo_id, revision)
Validates repository access and raises clear, user-friendly errors.
Results are cached to avoid redundant Hugging Face API calls when the same repository is validated multiple times within a process.
-
Parameters:
-
Raises:
-
ValueError – With user-friendly error messages for various access issues
-
Return type:
-
None
Was this page helpful?
Thank you! We'll create more content like this.
Thank you for helping us improve!