Crate hf_fetch_model

Expand description

§hf-fetch-model

Fast HuggingFace model downloads for Rust.

An embeddable library for downloading HuggingFace model repositories with maximum throughput. Wraps hf_hub and adds repo-level orchestration.

§Quick Start

let outcome = hf_fetch_model::download("julien-c/dummy-unknown".to_owned()).await?;
println!("Model at: {}", outcome.inner().display());

§Configured Download

use hf_fetch_model::FetchConfig;

let config = FetchConfig::builder()
    .filter("*.safetensors")
    .filter("*.json")
    .on_progress(|e| {
        println!("{}: {:.1}%", e.filename, e.percent);
    })
    .build()?;

let outcome = hf_fetch_model::download_with_config(
    "google/gemma-2-2b".to_owned(),
    &config,
).await?;
// outcome.is_cached() tells you if it came from local cache
let path = outcome.into_inner();

§Inspect Before Downloading

Read tensor metadata from .safetensors headers via HTTP Range requests — no weight data downloaded. See examples/candle_inspect.rs for a runnable example.

let results = hf_fetch_model::inspect::inspect_repo_safetensors(
    "EleutherAI/pythia-1.4b", None, None,
).await?;

for (filename, header, _source) in &results {
    println!("{filename}: {} tensors", header.tensors.len());
}

§`HuggingFace` Cache

Downloaded files are stored in the standard HuggingFace cache directory (~/.cache/huggingface/hub/), ensuring compatibility with Python tooling.

§Authentication

Set the HF_TOKEN environment variable to access private or gated models, or use FetchConfig::builder().token().

Re-exports§

pub use config::compile_glob_patterns;
pub use config::file_matches;
pub use config::has_glob_chars;
pub use config::FetchConfig;
pub use config::FetchConfigBuilder;
pub use config::Filter;
pub use discover::DiscoveredFamily;
pub use discover::GateStatus;
pub use discover::ModelCardMetadata;
pub use discover::SearchResult;
pub use download::DownloadOutcome;
pub use error::FetchError;
pub use error::FileFailure;
pub use inspect::AdapterConfig;
pub use plan::download_plan;
pub use plan::DownloadPlan;
pub use plan::FilePlan;
pub use progress::ProgressEvent;
pub use progress::ProgressReceiver;

Modules§

cache: HuggingFace cache directory resolution, model family scanning, and disk usage.
cache_layout: Centralized hf-hub cache path construction.
checksum: SHA256 checksum verification for downloaded files.
config: Configuration for model downloads.
discover: Model family discovery and search via the HuggingFace Hub API.
download: Download orchestration for HuggingFace model repositories.
error: Error types for hf-fetch-model.
inspect: Safetensors header inspection (local and remote).
plan: Download plan: metadata-only analysis of what needs downloading.
progress: Progress reporting for model downloads.
repo: Repository file listing via the HuggingFace API.

Functions§

build_client: Builds a reqwest::Client with auth token, user-agent, and 30-second TCP connect timeout.
download: Downloads all files from a HuggingFace model repository.
download_blocking: Blocking version of download() for non-async callers.
download_file: Downloads a single file from a HuggingFace model repository.
download_file_blocking: Blocking version of download_file() for non-async callers.
download_files: Downloads all files from a HuggingFace model repository and returns a filename → path map.
download_files_blocking: Blocking version of download_files() for non-async callers.
download_files_with_config: Downloads files from a HuggingFace model repository using the given configuration and returns a filename → path map.
download_files_with_config_blocking: Blocking version of download_files_with_config() for non-async callers.
download_with_config: Downloads files from a HuggingFace model repository using the given configuration.
download_with_config_blocking: Blocking version of download_with_config() for non-async callers.
download_with_plan: Downloads files according to an existing DownloadPlan.
download_with_plan_blocking: Blocking version of download_with_plan() for non-async callers.