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

This service can be used to:

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

Configurations

• repo_type: The type of the repository. One of model, dataset, space, or bucket.
• repo_id: The id of the repository.
• revision: The revision of the repository. Only applicable for git-based repo types (model, dataset, space).
• root: Set the work directory for backend.
• token: The token for accessing the repository. Required for write operations.
• endpoint: The Hub base URL. Default is https://huggingface.co. Can also be set via the HF_ENDPOINT environment variable.

Refer to HfBuilder’s public API docs for more information.

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)?.finish();

    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)?.finish();

    Ok(())
}

Via URI

use opendal_core::Operator;
use opendal_core::Result;

#[tokio::main]
async fn main() -> Result<()> {
    // 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 endpoint(self, endpoint: &str) -> HfBuilder

configure the Hub base url. You might want to set this variable if your organization is using a Private Hub https://huggingface.co/enterprise

Default is “https://huggingface.co”

Trait Implementations

impl Builder for HfBuilder

type Config = HfConfig

Associated configuration for this builder.

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

Consume the accessor 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.