액세스 패턴

CLI 및 Python SDK 외에도 기존 도구 및 워크플로우에서 버킷 데이터에 액세스하는 여러 가지 방법이 있습니다.

액세스 방법 선택

버킷을 백엔드로 사용하는 도구(SkyPilot, Inspect, …)에 대해서는 Integrations를 참조하세요. 폴링 없이 클라이언트를 버킷과 동기화하는 방법에 대해서는 Tracking Changes를 참조하세요.

로컬 파일 시스템으로 마운트

hf-mount는 NFS(권장) 또는 FUSE를 통해 버킷(및 저장소)을 로컬 파일 시스템으로 마운트할 수 있게 해줍니다. 파일은 지연 방식으로 가져오며, 코드가 실제로 읽는 바이트만 네트워크를 통해 전송됩니다.

Homebrew로 설치:

brew install hf-mount

버킷 마운트:

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

마운트된 후에는 파일을 읽거나 쓰는 모든 도구가 버킷과 함께 작동합니다 — pandas, DuckDB, vLLM, 학습 스크립트, 셸 명령 등.

Buckets는 읽기/쓰기 권한으로 마운트되며, 리포지토리는 읽기 전용입니다. 백엔드 옵션, 캐싱, 쓰기 모드에 대한 전체 문서에는 hf-mount 리포지토리를 참조하세요.

Jobs와 Spaces의 볼륨 마운트

Jobs와 Spaces의 볼륨 마운트는 hf-mount와 동일한 개념이며, 플랫폼이 대신 관리하므로 추가 설정이 필요하지 않습니다. 버킷은 기본적으로 읽기/쓰기 모드로 마운트됩니다.

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

Jobs는 볼륨 소스로 로컬 디렉터리를 사용할 수도 있습니다(-v ./training-data:/data): 해당 디렉터리는 사용자의 비공개 jobs-artifacts 버킷으로 동기화되고 거기서 마운트되므로, 증분 재동기화와 출력 가져오기는 자동으로 제공됩니다.

전체 볼륨 마운트 문법 및 Python API에 대해서는 Jobs 구성 문서와 Spaces 볼륨 마운트 가이드를 참조하세요.

DuckDB로 쿼리

DuckDB 2.0 이상에서는 httpfs 확장(읽기) 또는 hf 확장(읽기/쓰기)을 통해 hf://buckets/ 경로를 네이티브로 지원합니다. DuckDB CLI 또는 기타 클라이언트에서 httpfs를 설치하고 로드한 후 버킷을 쿼리합니다:

INSTALL httpfs;
LOAD httpfs;

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

Glob 패턴은 데이터셋과 동일한 방식으로 작동하며, 예를 들어 'hf://buckets/username/my-bucket/data/**/*.parquet'와 같습니다. Buckets는 버전 관리가 되지 않으므로 @revision 구문은 bucket 경로에 적용되지 않습니다. httpfs는 읽기 전용이며, 쿼리 결과를 bucket에 작성하려면 hf 확장 기능을 로드해야 합니다(아래 참조).

비공개 버킷: 먼저 Hugging Face 시크릿을 생성하세요. 토큰은 hf auth login 또는 HF_TOKEN 환경 변수에서 가져옵니다:

CREATE SECRET hf (TYPE huggingface, PROVIDER credential_chain);

Hugging Face에 작성하려면 hf 확장 프로그램이 필요합니다:

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/ 경로를 인식하지 못합니다. 대신 Python에서 HfFileSystem를 등록하거나, CLI 및 기타 클라이언트에서 S3 호환 API를 사용하세요.

Python 데이터 도구

HfFileSystem는 hf://buckets/ 경로를 사용하여 fsspec 호환 방식으로 버킷에 접근할 수 있습니다. fsspec을 지원하는 모든 Python 라이브러리가 버킷 데이터를 직접 읽고 쓸 수 있습니다.

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 가이드를 참고하세요.