Hub documentation

S3 互換性

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

S3 互換性

Storage Buckets は S3 互換 API 経由でアクセスでき、既存の S3 ツール（AWS CLI、boto3、s5cmd、およびその他のほとんどの S3 SDK）を、コードを変更せずにバケットに対して使用できます。リクエストは https://s3.hf.co のゲートウェイサービスを経由します。

S3 APIは、バケットデータにアクセスするための複数の方法の一つです。個別のS3認証情報なしでHugging Faceネイティブなアクセス（hf CLI、hf://パス、ファイルシステムマウント）を行う場合は、アクセスパターンを参照してください。

S3 APIはStorage Bucketsでのみ動作します。その他のHugging Faceリポジトリタイプ（モデル、データセット、Spaces）は公開されていません。

S3認証情報の生成

ゲートウェイは、Hugging Faceのユーザーアクセストークンから派生したAWSスタイルのアクセスキーを使用して認証を行います。

アクセストークンの設定に移動します。まだトークンを持っていない場合は、新しいトークンの作成ボタンでトークンを作成してください。トークンの権限がS3認証情報の権限となります。バケットへの読み取り専用アクセスにはReadを、読み書きアクセスにはWriteを選択してください。
リストからトークンを見つけ、そのドロップダウンメニューを開いて、Generate S3 credentialsを選択します。
生成されたアクセスキーID（HFAK…で始まる）とシークレットアクセスキーを安全な場所にコピーしてください。シークレットは一度のみ表示されます。

S3の認証情報は、基盤となるアクセストークンの権限を継承します。細粒度のトークンの場合、使用する予定のネームスペースとバケットにのみスコープを限定してください。

組織のバケットにアクセスする自動化ワークフローでは、User Access Token の代わりに、サービスアカウントトークンから S3 認証情報を生成することもできます。

クライアントの構成

S3クライアントをゲートウェイエンドポイントに向かせ、必要なオプションをいくつか設定します。エンドポイントURLには、Hugging Faceのnamespace（ユーザー名または組織名）を使用します。詳細は以下のバケットのアドレス指定を参照してください。

設定	値	なぜ
`endpoint_url`	`https://s3.hf.co/<namespace>`	あなたの名前空間にスコープが設定されたゲートウェイ
`region`	`us-east-1`	必須。ゲートウェイは現在シングルリージョンです
`s3.addressing_style`	`path`	バケットはサブドメインではなく、パスセグメントとしてアドレス指定されます
`request_checksum_calculation`	`when_required`	最近のクライアントが末尾チェックサムを送信することを防止します
`response_checksum_validation`	`when_required`	最近のクライアントがレスポンスにチェックサムを期待することを防止します

最近のクライアントでは、2つのチェックサム設定が重要です。AWS CLI ≥ 2.23 および最近の boto3 バージョンは、デフォルトで末尾の CRC32 チェックサムを送信します（aws-chunked フレーム経由）。しかし、ゲートウェイはこれを解析しません。これらの設定により、クライアントは操作が厳密にチェックサムを要求する場合にのみ送信するようになります。

以下は任意ですが、大規模なアップロードでマルチパートの数をできるだけ少なくするために推奨されます:

設定	値
`s3.multipart_threshold`	`2GB`
`s3.multipart_chunksize`	`2GB`

例: AWS CLI プロファイル

~/.aws/config にプロファイルを追加します:

[profile hf]
region = us-east-1
endpoint_url = https://s3.hf.co/<namespace>
s3 =
    addressing_style = path
    multipart_threshold = 2GB
    multipart_chunksize = 2GB
request_checksum_calculation = when_required
response_checksum_validation = when_required

注: 上記の<namespace>は、バケットが保存されているユーザー名または組織名に置き換えてください。

プロファイルに対応する認証情報を~/.aws/credentialsに追加します:

[hf]
aws_access_key_id = HFAK...
aws_secret_access_key = ...

その後、プロファイルを使用して任意の S3 コマンドを実行します:

aws --profile hf s3 ls
aws --profile hf s3 mb s3://my-bucket
aws --profile hf s3 cp ./model.safetensors s3://my-bucket/models/model.safetensors

バケットの処理

AWS S3は、バケット名に対して単一のフラットでグローバルに一意な名前空間を使用しており、SDKはバケット名が/を含まないプレーンな文字列であることを前提としています。一方、Hugging Faceのバケットはnamespace/bucketとして識別され、namespaceはユーザー名または組織名です。この追加の階層がS3クライアントとの不一致を引き起こします。多くのクライアントはバケット名に/を受け入れないか、正しくURLエスケープしません。この問題を回避するには、2つの方法があります。

1. エンドポイント URL に名前空間を含める（ほとんどのケースで推奨）。これにより、すべての操作がその名前空間にスコープが設定され、クライアントに渡すバケット名は HF バケット名のみで済みます。自分のバケットや単一の組織内のバケットには有効ですが、名前空間をまたぐ場合は機能しなくなります。例えば、個人バケットから組織バケットへのサーバーサイドのコピーなどが該当します。

aws --endpoint-url https://s3.hf.co/my-org s3api get-object \
  --bucket my-bucket --key some/object.txt ./object.txt

2. namespace をバケットとして扱う方法で、オブジェクトキーの先頭に HF バケット名を付加します。これによりオブジェクトレベルの操作（アップロード、ダウンロード）は機能しますが、バケットの作成や削除などのバケットレベルの操作では問題が発生します。

aws --endpoint-url https://s3.hf.co s3api get-object \
  --bucket my-org --key my-bucket/some/object.txt ./object.txt

AWS S3との制限事項および違い

Storage Buckets はすべての S3 の概念をモデル化していないため、一部の動作が異なるか、サポートされていない場合があります。

オブジェクトのダウンロード

ゲートウェイは現在、単一リージョン構成です。ダウンロードパフォーマンスを向上させるため、GetObject は通常、バイトを直接配信するのではなく、最も近い Hugging Face CDN エッジへの HTTP 302 リダイレクトで応答します。

一部のSDKはS3エンドポイントからのリダイレクトに従わないため、ゲートウェイはaws-cli、botocore（boto3を含む）、またはaws-sdk-rustと識別されるクライアントを検出し、それらのためにデータをゲートウェイ経由でプロキシします。その他のすべてのクライアント（rclone、s5cmd、curl、AWS Go SDKなど）は302を受け取り、ネイティブに従うため、ダウンロードを高速化するためにゲートウェイをデータパスから除外します。

オブジェクトキーの命名

バケットのオブジェクトキーはS3よりも制限が厳しく、キーは以下を満たさない必要があります:

/で始まるか終わる
連続スラッシュ(//)を含む
../ シーケンスを含む
./で始まる
..で終わる
バックスラッシュ (\) またはヌルバイト (\0) を含む

ListObjects

ListObjectsV1 はサポートされていません。ListObjectsV2 を使用してください。一部のクライアント（rclone など）では、ListObjectsV2 のみを使用するように設定する必要がある場合があります。
区切り文字として許可されているのは/のみです。

その他のAPIの違い

オブジェクトメタデータ: ユーザーが任意に設定するメタデータ (x-amz-meta-*) は保存も返却もされません。 Content-Type はサポートされています。
サポートされていない機能: ACL、バケットポリシー、オブジェクトタグ付け、オブジェクトバージョニング、ライフサイクルルール、サーバーサイド暗号化（SSE）、バケット通知はサポートされていません。オブジェクトは常にSTANDARDストレージクラスとして報告されます。関連するリクエストヘッダーおよびパラメーターは受け入れられますが、無視されます。
CopyObject: サーバーサイドコピーは、単一のネームスペース内でのみ動作します。ネームスペースをまたぐコピーおよびUploadPartCopy（既存のオブジェクトからマルチパートアップロードにパートをコピーする操作）はサポートされていません。
条件付きリクエスト: If-Match / If-None-Match の前提条件は、PutObject および CopyObject のコピー元では尊重されますが、GetObject では尊重されません。
マルチパートアップロードの有効期限: 完了または中止されないまま進行中のマルチパートアップロードは、7日後に自動的に期限切れとなり、クリーンアップされます。

例

一般的なタスク向けの実際のレシピです。それぞれは、上記のクライアント設定を基に構築されています。

boto3での読み書き

boto3 は、上記のクライアント設定でゲートウェイに対して動作します。<namespace>をユーザー名または組織名に置き換えてください:

import boto3
from botocore.config import Config

s3 = boto3.client(
    "s3",
    endpoint_url="https://s3.hf.co/<namespace>",
    aws_access_key_id="HFAK...",
    aws_secret_access_key="...",
    config=Config(
        region_name="us-east-1",
        s3={"addressing_style": "path"},
        request_checksum_calculation="when_required",
        response_checksum_validation="when_required",
    ),
)

s3.upload_file("model.safetensors", "my-bucket", "models/model.safetensors")
s3.download_file("my-bucket", "models/model.safetensors", "model.safetensors")

DuckDBでバケットをクエリする

DuckDB 2.0以降では、httpfs拡張機能によりhf://buckets/パスを直接読み取ることができ、hf拡張機能を使用すればBucketsへの書き込みも可能です。DuckDBでのクエリを参照してください。

DuckDBの以前のバージョンの場合、または拡張機能なしでCOPY ... TOを使用してクエリ結果をバケットに書き戻す場合は、代わりにS3ゲートウェイ経由で実行してください:

INSTALL httpfs;
LOAD httpfs;

CREATE SECRET hf (
    TYPE s3,
    KEY_ID 'HFAK...',
    SECRET '...',
    ENDPOINT 's3.hf.co/<namespace>',
    URL_STYLE 'path',
    REGION 'us-east-1'
);

SELECT * FROM read_parquet('s3://my-bucket/data.parquet');

URL_STYLE 'path' は必須です。これを指定しないと、DuckDB は仮想ホスト形式のアドレス指定（my-bucket.s3.hf.co）を使用しますが、ゲートウェイではこの形式に対応していません。そのため、「Could not resolve hostname」エラーが発生します。

rcloneを使用してデータをインポートする

rcloneは、2つのS3互換ストレージ間でデータをコピーする便利な方法であり、既存のAWS S3バケット（または任意のS3互換ソース）をStorage Bucketへ移行する用途に最適です。

アイデアは、ソースバケットと Hugging Face ゲートウェイという2つのリモートを宣言し、rclone がオブジェクトをストリーミングで転送できるようにすることです。両方のリモートを ~/.config/rclone/rclone.conf に追加します。最初のものは既存の S3 バケットを指します。ソースに合わせて調整してください（ここではプレーンな AWS S3 を想定しています）:

[aws]
type = s3
provider = AWS
access_key_id = AKIA...
secret_access_key = ...
region = us-east-1

2番目のポイントは Hugging Face のゲートウェイを指しています。他のクライアントと同様に、エンドポイントをnamespaceにスコープし、path アドレッシングを使用し、ListObjectsV2 を強制（ゲートウェイがサポートする唯一のリスト表示バージョン）し、マルチパートのサイズを大きくしてアップロードで使用するパート数を最小限に抑えてください:

[hf]
type = s3
provider = Other
endpoint = https://s3.hf.co/<namespace>
access_key_id = HFAK...
secret_access_key = ...
region = us-east-1
force_path_style = true
list_version = 2
upload_cutoff = 2G
chunk_size = 2G

注: 上記の<namespace>は、バケットが保存されているユーザー名または組織名に置き換えてください。また、アクセストークンから生成されたS3認証情報を使用してください。宛先バケットは、その名前空間の下に既に存在している必要があります。

次に、ソースバケットをStorage Bucketにコピーします:

rclone copy aws:my-source-bucket hf:my-bucket --progress

rclone copy は、転送先で欠落しているか変更されたオブジェクトのみを転送するため、中断されたインポートを再開したり、新しいオブジェクトを取得したりするために再実行しても安全です。ソースに存在しなくなったオブジェクトを転送先から削除して、転送先をソースの完全なミラーにするには、代わりにrclone syncを使用します:

rclone sync aws:my-source-bucket hf:my-bucket --progress

大規模なインポートを行う場合は、--transfers と --checkers を追加して並行度を上げてください（例: --transfers 16 --checkers 16）。その後、rclone check aws:my-source-bucket hf:my-bucket を実行して、すべてのオブジェクトが正常に転送されたことを確認してください。

DVCでバージョン管理

DVC は、リポジトリ内に小さなポインタファイルを保持し、実際のデータをリモートにプッシュすることで、git 上でデータセットとモデルのバージョン管理を行います。バケットはゲートウェイを介して DVC リモートとして機能するため、コードと.dvc ポインタは git に残ったまま、データはバケットに格納されます。S3 対応の DVC をインストール（pip install 'dvc[s3]'）し、上記のクライアント設定を使用してリモートを追加します。

dvc remote add -d hf-bucket s3://my-bucket/dvc-store
dvc remote modify hf-bucket endpointurl https://s3.hf.co/<namespace>
dvc remote modify hf-bucket region us-east-1

S3認証情報を環境変数として渡すか、dvc remote modify --local を使用して渡すことで、gitに含めずに済みます:

export AWS_ACCESS_KEY_ID=HFAK...
export AWS_SECRET_ACCESS_KEY=...

その後、通常通りトラッキング、プッシュ、プルを行います — dvc push はバケットにアップロードし、新しいクローンでの dvc pull はそれをダウンロードします:

dvc add data/
git add data.dvc .gitignore .dvc/config && git commit -m "Track data with DVC"
dvc push

endpointurl には namespace を、s3:// URL にはバケット名のみを使用してください。

Update on GitHub

←アクセスパターンバケット統合→