コンテナイメージ

Container Images は、Docker およびその他の OCI イメージ用の Hugging Face Hub 上のリポジトリタイプです。Hugging Face のコンテナレジストリ cr.hf.co は、Xet ストレージバックエンド上にイメージを保存します。推奨されるクライアントである hf image を使用してプッシュおよびプルできます。Docker、Podman、crane、skopeo、ORAS、Helm などの標準クライアントも動作します。

Container Imagesはプライベートベータ版です: お問い合わせください。組織で有効化できます。

リポジトリの作成

huggingface.co/new-container に移動し、組織、名前、可視性を指定してください。または、API を使用します:

curl -X POST https://huggingface.co/api/containers/my-org/my-app \
  -H "Authorization: Bearer $HF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"private": true}'

プッシュする前にリポジトリを作成してください。存在しないリポジトリへのプッシュはNAME_UNKNOWNエラーで失敗します。そのページhttps://huggingface.co/containers/my-org/my-appには、そのリポジトリのタグがリスト表示されます。プルとプッシュの権限は、リポジトリの可視性と、組織内での各メンバーのロールによって決まります。

hf image によるプッシュとプル

hf imageはhf CLIの拡張機能であり、各レイヤーのうち前バージョンから変更された部分のみを転送するため、他のOCIクライアントと比較してより高速な体験を提供します。

hf extensions install hf-image
hf auth login                                   # or set HF_TOKEN
hf image build -t cr.hf.co/my-org/my-app:v2 .   # optional: docker build works too
hf image push cr.hf.co/my-org/my-app:v2
hf image pull cr.hf.co/my-org/my-app:v2

Hugging Face の ユーザーアクセストークン（read で pull、write で push）を使用し、containerd イメージストア 付きの Docker が必要です。hf image で push されたイメージは、どのクライアントからも pull できます。

hf image はレイヤーを非圧縮で保存するため、プッシュされるイメージのダイジェストは docker push とは異なります。署名やダイジェストで固定されたデプロイメントのために docker push のダイジェストを維持する場合は、hf image push --preserve-digests を使用してください。この場合、docker push と同様に、変更されたレイヤーが完全にプッシュおよびプルされるため、処理は遅くなります。

Dockerおよびその他のOCIクライアントの使用

hf image（前節を参照）を使用してXet バックエンドの機能を最大限に活用することを推奨しますが、任意の OCI クライアントを通じてレジストリとやり取りすることもできます。

Hugging Face のユーザー名と、User Access Token をパスワードとしてログインします: read で pull 可能、write で push 可能。パブリックなイメージはログインせずに pull できます。

echo $HF_TOKEN | docker login cr.hf.co -u <username> --password-stdin
docker tag my-app cr.hf.co/my-org/my-app:v1
docker push cr.hf.co/my-org/my-app:v1
docker pull cr.hf.co/my-org/my-app:v1

他の OCI クライアントも同じ動作です。Helm は URL にチャート名を付加します。helm push mychart-0.1.0.tgz oci://cr.hf.co/my-org は my-org/mychart にプッシュしますが、これは事前に存在している必要があります。

画像の削除

Hubでは、画像またはタグのページで、メニューのこのタグを削除を使用してタグを削除します。hf imageでは、画像のタグを削除してから、ダイジェストを指定して削除します:

hf image untag cr.hf.co/my-org/my-app:v1                # prints the image's digest
hf image delete cr.hf.co/my-org/my-app@sha256:<digest>

別のタグなど、まだそのイメージを参照しているものがある場合、削除は拒否され、先に削除すべきものが一覧表示されます。マルチアーキテクチャのイメージを削除すると、そのプラットフォーム固有のイメージも削除されます。

ガーベジコレクション

レジストリは、タグが直接またはマルチアーキテクチャイメージを介して参照しなくなったイメージを削除します。例えば、新しいプッシュ後の以前のlatestなどです。また、残っているイメージが使用していないレイヤーも削除します。ダイジェストでイメージをプルし続けるには、そのイメージにタグを付与し続けてください。

制限

• 画像名はcr.hf.co/<namespace>/<name>の形式で、小文字です。
• レイヤーは最大100 GB、マニフェストは最大4 MiBです。
• タグのリストに新しいタグが表示されるまで、数秒かかる場合があります。