Паттерны доступа

Помимо CLI и Python SDK, существует несколько способов получить доступ к данным в бакете из ваших существующих инструментов и рабочих процессов.

Выбор метода доступа

Для инструментов, использующих бакеты в качестве бэкенда (SkyPilot, Inspect, …), см. Интеграции. Чтобы синхронизировать клиент с бакетом без опроса, см. Отслеживание изменений.

Подключение как локальной файловой системы

hf-mount позволяет монтировать бакеты (и репозитории) как локальные файловые системы через NFS (рекомендуется) или FUSE. Файлы загружаются лениво — в сеть отправляются только те байты, которые читает ваш код.

Установите с помощью Homebrew:

brew install hf-mount

Подключить бакет:

hf-mount start bucket username/my-bucket /mnt/data

После монтирования любые инструменты, читающие или записывающие файлы, работают с вашим bucket — pandas, DuckDB, vLLM, скрипты обучения, команды shell и т. д.

Бакеты монтируются с правами на чтение и запись; репозитории — только для чтения. Полную документацию, включая варианты бэкендов, кэширование и режимы записи, см. в репозитории hf-mount.

Точки монтирования томов в Jobs и Spaces

Точки монтирования томов в Jobs и Spaces реализуют ту же идею, что и hf-mount, но управляются платформой — дополнительная настройка не требуется. По умолчанию бакеты монтируются с правами на чтение и запись.

hf jobs run -v hf://buckets/username/my-bucket:/data python:3.12 python script.py

Задачи также могут принимать локальный каталог в качестве источника тома (-v ./training-data:/data): каталог синхронизируется с вашим приватным бакетом jobs-artifacts и монтируется оттуда, поэтому инкрементальная повторная синхронизация и получение результатов выполняются автоматически.

Синтаксис монтирования полного тома и Python API описаны в документации по конфигурации Jobs и в руководстве по монтированию томов в Spaces.

Запрос с помощью DuckDB

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

INSTALL httpfs;
LOAD httpfs;

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

Glob-шаблоны работают так же, как и для наборов данных, например 'hf://buckets/username/my-bucket/data/**/*.parquet'. Бакеты не версионируются, поэтому синтаксис @revision неприменим к путям в бакетах. httpfs поддерживает только чтение; чтобы записать результаты запроса в бакет, загрузите расширение hf (см. ниже).

Закрытые хранилища: сначала создайте секрет Hugging Face. Он подхватывает токен из hf auth login или переменной окружения HF_TOKEN:

CREATE SECRET hf (TYPE huggingface, PROVIDER credential_chain);

Запись в Hugging Face требует расширения hf extension:

SET allow_extension_repositories = 'allowed';
CREATE OR REPLACE EXTENSION REPOSITORY hf_repo WITH PREFIX 'https://hf.co/buckets/duckdb-extensions/builds/resolve';
INSTALL hf FROM hf_repo;
LOAD hf FROM hf_repo;

COPY tbl TO 'hf://buckets/username/my-bucket/out.parquet';

В DuckDB 1.x httpfs не распознаёт пути hf://buckets/. Вместо этого зарегистрируйте HfFileSystem из Python или используйте S3-совместимый API из CLI и других клиентов.

Инструменты для работы с данными на Python

HfFileSystem обеспечивает доступ к бакетам, совместимый с fsspec, с использованием путей hf://buckets/. Любая библиотека Python, поддерживающая 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")

Подробнее о путях hf:// и поддерживаемых операциях см. в руководстве по HfFileSystem и руководстве по Buckets на Python.