접근 패턴

접근 패턴 (Access Patterns)

CLI와 Python SDK 외에도 기존 도구와 워크플로에서 버킷 데이터에 접근하는 여러 방법이 있어요. 로컬 파일시스템으로 마운트하거나, hf:// 경로로 데이터 도구에서 바로 읽거나, S3 API를 쓰는 등 상황에 맞게 고를 수 있답니다.

출처: 문서

본문

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, 학습 스크립트, 셸 명령 등.

[!TIP] 버킷은 읽기-쓰기로, 저장소는 읽기 전용으로 마운트돼요. 백엔드 옵션, 캐싱, 쓰기 모드를 포함한 전체 문서는 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 볼륨 마운트 가이드를 참고해요.

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")

DuckDB (Python 클라이언트):

import duckdb
from huggingface_hub import HfFileSystem

duckdb.register_filesystem(HfFileSystem())
duckdb.sql("SELECT * FROM 'hf://buckets/username/my-bucket/data.parquet' LIMIT 10")

hf:// 경로와 지원되는 연산에 대한 자세한 내용은 HfFileSystem 가이드와 Buckets Python 가이드를 참고해요.

더 알아보기 (Learn more)

• 어떤 도구든 쓰고 싶다면 hf-mount로 버킷을 로컬 파일시스템처럼 마운트하면 돼요.
• pandas·DuckDB 같은 Python 데이터 도구는 fsspec 기반 hf://buckets/ 경로로 버킷을 직접 읽을 수 있어요.