アクセスパターン

CLIとPython SDKに加えて、既存のツールやワークフローからバケットデータにアクセスする方法はいくつかあります。

アクセス方法の選択

バケットをバックエンドとして使用するツール（SkyPilot、Inspect など）については、統合を参照してください。ポーリングせずにクライアントをバケットと同期させるには、変更の追跡を参照してください。

ローカルファイルシステムとしてマウント

hf-mount を使用すると、NFS（推奨）または FUSE を介して、バケット（およびリポジトリ）をローカルファイルシステムとしてマウントできます。ファイルは遅延取得されます。つまり、ネットワークにアクセスするのは、コードが実際に読み取ったバイトのみです。

Homebrewでインストール:

brew install hf-mount

バケットのマウント:

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

マウントが完了すると、ファイルの読み書きを行うあらゆるツールがバケットと連携して動作します。pandas、DuckDB、vLLM、学習スクリプト、シェルコマンドなどが該当します。

バケットは読み書き可能でマウントされ、リポジトリは読み取り専用です。バックエンドのオプション、キャッシュ、書き込みモードを含む完全なドキュメントについては、hf-mount リポジトリを参照してください。

JobsとSpacesにおけるVolume Mounts

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以降では、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'。バケットはバージョン管理されないため、@revision構文はバケットパスには適用されません。httpfsは読み取り専用です。クエリ結果をバケットに書き込むには、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 ガイドを参照してください。