Struct Hf 

pub struct Hf { /* private fields */ }

Available on crate feature services-hf only.

Hugging Face’s API support. This service will visit the Hugging Face API to access the Hugging Face File System.

Hugging Face doesn’t host official HTTP API docs. Detailed HTTP request API information can be found on the huggingface_hub Source Code.

Storage Backends

This service supports two storage backends:

• Git-based repositories (model, dataset, space): Files are versioned in a Git repository. Large files are stored via Xet, Hugging Face’s chunk-deduplicated storage backend; writes create new commits. Supports revision for branch/commit targeting.
• Object store buckets (bucket): Files are stored in a Hugging Face Bucket (not git-backed). No revisions or commits — all reads and writes use the Xet protocol directly.

Capabilities

Depending on its configuration and the backing system, this service can expose:

• create_dir
• stat
• read
• write
• delete
• list
• copy
• rename
• presign

Inspect the effective capability set with opendal_core::Operator::info and opendal_core::OperatorInfo::capability after building an operator.

Configuration

Use crate::HfConfig for serializable configuration and this builder’s methods for direct construction. The field and method documentation defines accepted values, defaults, and environment interaction.

Examples

Via Builder (Git-based dataset)

use opendal_core::Operator;
use opendal_core::Result;
use opendal_service_hf::Hf;

#[tokio::main]
async fn main() -> Result<()> {
    let builder = Hf::default()
        .repo_type("dataset")
        .repo_id("username/my-dataset")
        .revision("main")
        .root("/path/to/dir")
        .token("access_token");

    let op: Operator = Operator::new(builder)?;

    Ok(())
}

Via Builder (Object store bucket)

use opendal_core::Operator;
use opendal_core::Result;
use opendal_service_hf::Hf;

#[tokio::main]
async fn main() -> Result<()> {
    let builder = Hf::default()
        .repo_type("bucket")
        .repo_id("username/my-bucket")
        .token("access_token");

    let op: Operator = Operator::new(builder)?;

    Ok(())
}

Via URI

use opendal_core::{Operator, OperatorRegistry, Result};
use opendal_service_hf::register_hf_service;

#[tokio::main]
async fn main() -> Result<()> {
    register_hf_service(OperatorRegistry::get());

    // Git-based dataset
    let op = Operator::from_uri((
        "hf://datasets/username/my-dataset@main",
        vec![("token", "access_token")],
    ))?;

    // Object store bucket
    let op = Operator::from_uri((
        "hf://buckets/username/my-bucket",
        vec![("token", "access_token")],
    ))?;

    Ok(())
}

Implementations

impl HfBuilder

pub fn repo_type(self, repo_type: &str) -> HfBuilder

Set repo type of this backend. Default is model.

Available values:

• model
• dataset
• datasets (alias for dataset)
• space
• bucket

Reference

pub fn repo_id(self, repo_id: &str) -> HfBuilder

Set repo id of this backend. This is required.

Repo id consists of the account name and the repository name.

For example, model’s repo id looks like:

• meta-llama/Llama-2-7b

Dataset’s repo id looks like:

• databricks/databricks-dolly-15k

pub fn revision(self, revision: &str) -> HfBuilder

Set revision of this backend. Default is main.

Revision can be a branch name or a commit hash.

For example, revision can be:

• main
• 1d0c4eb

pub fn root(self, root: &str) -> HfBuilder

Set root of this backend.

All operations will happen under this root.

pub fn token(self, token: &str) -> HfBuilder

Set the token of this backend.

This is optional.

pub fn download_mode(self, mode: &str) -> HfBuilder

Set the download mode. Either xet (default) or http.

• xet: uses the XET protocol for downloads (default).
• http: plain HTTP download, following the redirect from the server.

When this is not set explicitly, the download mode is resolved from the HF_HUB_DISABLE_XET environment variable (the same variable used by huggingface_hub): if it is set to a non-empty value, the mode is forced to http; otherwise it defaults to xet. An explicit value set here always takes precedence over the environment variable.

See https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhubdisablexet.

pub fn endpoint(self, endpoint: &str) -> HfBuilder

Set the Hub base URL.

Configure this when your organization uses a Private Hub.

The default is https://huggingface.co.

Trait Implementations

impl Builder for HfBuilder

type Config = HfConfig

Associated configuration.

fn build(self) -> Result<impl Service, Error>

Consume the builder to build a service.

impl Debug for HfBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for HfBuilder

fn default() -> HfBuilder

Returns the “default value” for a type.