Интеграции с хранилищами

Storage Buckets можно читать и записывать из многих библиотек Python для работы с данными, используя пути hf://buckets/, которые поддерживаются файловым интерфейсом huggingface_hub.

За механизмами доступа — монтированием, монтированием томов и fsspec — см. Схемы доступа.

pandas

import pandas as pd

df = pd.read_parquet("hf://buckets/username/my-bucket/data.parquet")
df.to_parquet("hf://buckets/username/my-bucket/output.parquet")

Dask

Dask выполняет чтение и запись лениво, по одной партиции на файл, поэтому вы можете обрабатывать наборы данных, превышающие объём памяти, непосредственно из хранилища:

import dask.dataframe as dd

df = dd.read_parquet("hf://buckets/username/my-bucket/data/")
df.to_parquet("hf://buckets/username/my-bucket/output/")

Подробнее см. в Dask on the Hub.

Daft

Daft нативно поддерживает пути hf://buckets/, при этом ускоренное чтение Xet включено по умолчанию:

import daft
from daft.io import IOConfig, HuggingFaceConfig
from huggingface_hub import get_token

io_config = IOConfig(hf=HuggingFaceConfig(token=get_token()))
df = daft.read_parquet("hf://buckets/username/my-bucket/data.parquet", io_config=io_config)

PyArrow

import pyarrow.parquet as pq

table = pq.read_table("hf://buckets/username/my-bucket/data.parquet")

PySpark

При установленном pyspark_huggingface:

df = (
    spark.read.format("huggingface")
    .option("data_files", '["data.parquet"]')
    .load("buckets/username/my-bucket")
)

Подробнее см. в PySpark на Hub.

🤗 Datasets

from datasets import load_dataset

ds = load_dataset("buckets/username/my-bucket", data_files=["data.parquet"])

Inspect AI

Inspect AI может записывать журналы оценки напрямую в бакет — укажите для каталога журналов путь hf://buckets/ (требуется huggingface_hub>=1.6.0). Сначала создайте бакет и выполните аутентификацию (Inspect не создаст его за вас):

hf auth login
hf buckets create username/my-bucket --private

export INSPECT_LOG_DIR=hf://buckets/username/my-bucket/eval-logs
inspect eval popularity.py --model openai/gpt-4
inspect view

Подробнее см. в руководстве по журналам оценки Inspect.

SkyPilot

SkyPilot выполняет AI-задачи более чем на 20 облачных платформах, в Kubernetes и в локальных средах и может использовать хранилище Hugging Face в качестве бэкенда — так что одно хранилище доступно для чтения из любого облака без создания отдельных копий для каждого облака. Укажите store: hf в записи file_mounts, чтобы смонтировать хранилище в режиме чтения и записи или репозиторий в режиме только чтения:

# qwen-sft.yaml — launch anywhere: sky launch qwen-sft.yaml --infra aws|gcp|...
resources:
  accelerators: H100:1

file_mounts:
  /base-model:
    source: hf://Qwen/Qwen2.5-3B           # model repo, read-only
    store: hf
    mode: MOUNT
  /data:
    source: hf://datasets/username/my-data@v1.0   # dataset repo, pinned to a tag, read-only
    store: hf
    mode: MOUNT
  /checkpoints:
    source: hf://buckets/username/qwen-sft   # bucket, read-write — checkpoints sync back
    store: hf
    mode: MOUNT

run: |
  python train.py --model /base-model --output_dir /checkpoints

Авторизуйтесь один раз — hf auth login (или export HF_TOKEN=<your-token>) — этого достаточно для SkyPilot. Он передаёт ваш локальный токен Hugging Face в каждое облако, поэтому монтирование бакетов и репозиториев выполняется с автоматической аутентификацией:

pip install "skypilot[huggingface]"
hf auth login                              # or: export HF_TOKEN=<your-token>
sky launch qwen-sft.yaml

Если ваш собственный код run использует репозитории с ограниченным доступом, добавьте --secret HF_TOKEN к команде запуска, чтобы также передать токен в качестве переменной окружения.

MOUNT и MOUNT_CACHED для hf работают идентично и используют FUSE-бэкенд hf-mount, который требует базового образа с glibc ≥ 2.34 и /dev/fuse. Облачные провайдеры с «голыми» ВМ обеспечивают наличие обоих. Образ Kubernetes по умолчанию в SkyPilot содержит более старую версию glibc, поэтому задайте более новый image_id (например, docker:mirror.gcr.io/ubuntu:22.04). Актуальные требования к окружению описаны в документации SkyPilot по хранилищу.

См. статью в блоге SkyPilot + Hugging Face о хранилище с бенчмарками и подробным описанием.

Операции файловой системы

Для прямых операций с файлами huggingface_hub предоставляет предварительно созданный объект файловой системы hffs:

from huggingface_hub import hffs

with hffs.open("buckets/username/my-bucket/hello.txt", "w") as f:
    f.write("Hello world!")

hffs.cp("buckets/username/my-bucket/hello.txt", "buckets/username/my-bucket/hello2.txt")
hffs.rm("buckets/username/my-bucket/hello2.txt")
files = hffs.ls("buckets/username/my-bucket")
text_files = hffs.glob("buckets/username/my-bucket/*.txt")

DuckDB

DuckDB 2.0 и более поздние версии читают пути hf://buckets/ нативно через расширение httpfs (а для записи — с расширением hf), как из CLI, так и из любого клиента:

SELECT * FROM 'hf://buckets/username/my-bucket/data/**/*.parquet' LIMIT 10;
COPY tbl TO 'hf://buckets/username/my-bucket/out.parquet';

См. Запрос с DuckDB для частных бакетов и более старых версий DuckDB.

Другие языки

OpenDAL предоставляет аналогичный файловый интерфейс для Rust, Java, Go, JavaScript и других языков.

Скоро

Поддержка нативных URL hf:// в разработке для других библиотек — включая Polars и WebDataset. Тем временем все они уже работают через S3-совместимый API.