# Konteyner Görselleri

Container Images, Hugging Face Hub'da Docker ve diğer [OCI](https://opencontainers.org/) görüntüleri için bir depo türüdür. Hugging Face konteyner kayıt defteri olan `cr.hf.co`, görüntüleri [Xet](./xet/index) depolama altyapısında saklar. Bunları, önerilen istemci olan [`hf image`](#pushing-and-pulling-with-hf-image) ile gönderin ve çekin; Docker, Podman, crane, skopeo, ORAS ve Helm gibi standart istemciler de çalışır.

> [!NOTE]
> Container Images özel beta aşamasındadır: [bize ulaşın](https://huggingface.co/contact/sales) ve bunları organizasyonunuz için etkinleştirin.

## Depo Oluşturma

[huggingface.co/new-container](https://huggingface.co/new-container) adresine gidin ve kuruluşu, bir ad ile görünürlüğü seçin. Veya API'yi kullanın:

```bash
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}'
```

İtmadan önce depoyu oluşturun: mevcut olmayan bir depoya yapılan itme `NAME_UNKNOWN` hatasıyla başarısız olur. Sayfası olan `https://huggingface.co/containers/my-org/my-app`, etiketlerini listeler. Kimlerin çekebileceği ve itebileceği, depoyun görünürlüğüne ve her bir üyenin organizasyondaki veya Resource Group'taki rolüne bağlıdır: bkz. [Erişim Kontrolü](./container-images-access).

## `hf image` ile İtme ve Çekme

[`hf image`](https://github.com/huggingface/hf-image), `hf` CLI'nin bir uzantısı olarak, her katmanın önceki sürümden bu yana değişen kısımlarını aktarır ve bu sayede diğer OCI istemcilerine kıyasla daha hızlı bir deneyim sunar.

```bash
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 [Kullanıcı Erişim Anahtarınızı](./security-tokens) (`read` ile çekmek, `write` ile itmek için) kullanır ve [containerd image store](https://docs.docker.com/engine/storage/containerd/) ile Docker gerektirir. `hf image` ile itilen görüntüler herhangi bir istemci tarafından çekilebilir.

`hf image` katmanları sıkıştırılmamış olarak sakladığı için, ittiği görüntülerin `docker push` ile elde edilenlerden farklı özetleri (digest) olur. İmzalar veya öze göre sabitlenmiş dağıtımlar için `docker push` özetlerini korumak istiyorsanız `hf image push --preserve-digests` kullanın. Bu işlem daha yavaştır: değiştirilen katmanlar, `docker push` ile olduğu gibi tam olarak itilir ve çekilir.

## Docker ve Diğer OCI İstemcilerini Kullanma

[Xet backend](./xet/index)'in tüm avantajlarından yararlanmak için `hf image` kullanmanızı önerirsek de (önceki bölümü bkz.), kayıt defteriyle herhangi bir OCI istemcisi üzerinden de etkileşime girebilirsiniz.

Hugging Face kullanıcı adınız ve şifre olarak bir [User Access Token](./security-tokens) ile oturum açın: çekmek için `read`, itmek için `write`. Halka açık görüntüler oturum açmadan çekilebilir.

```bash
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
```

Diğer OCI istemcileri de aynı şekilde çalışır. Helm, URL'ye grafik adını ekler: `helm push mychart-0.1.0.tgz oci://cr.hf.co/my-org` komutu, `my-org/mychart` konumuna gönderim yapar ve bu konumun önceden var olması gerekir.

## Görselleri Silme

Hub'da, bir etiketi, görselin veya etiketin sayfasındaki menüsündeki **Bu etiketi sil** seçeneğini kullanarak kaldırın. [`hf image`](#pushing-and-pulling-with-hf-image) ile bir görselin etiketlerini kaldırın, ardından onu digest ile silin:

```bash
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>
```

Eğer görüntüye başka bir etiket gibi bir şey hâlâ atıfta bulunuyorsa, silme işlemi reddedilir ve önce nelerin kaldırılması gerektiği listelenir. Çoklu mimari bir görüntünün silinmesi, platform görüntülerinin de silinmesine neden olur.

## Çöp Toplama

Kayıt defteri, artık doğrudan veya çok mimarili bir görüntü yoluyla herhangi bir etiketin işaret etmediği görüntüleri, örneğin yeni bir gönderimden sonraki önceki `latest` etiketini, siler. Ayrıca, kalan görüntülerin hiçbiri tarafından kullanılmayan katmanları da siler. Bir görüntüyü özetiyle (digest) çekmeye devam edebilmek için üzerinde bir etiket bulundurun.

## Sınırlar

- Görsel adları küçük harfle `cr.hf.co/<namespace>/<name>` biçimindedir.
- 100 GB'a kadar katmanlar, 4 MiB'a kadar manifestler.
- Etiket listeleri yeni bir etiketi göstermek için birkaç saniye sürebilir.