# Образы контейнеров

Container Images — это тип репозитория на Hugging Face Hub для образов Docker и других [OCI](https://opencontainers.org/). Реестр контейнеров Hugging Face, `cr.hf.co`, хранит образы на хранилище [Xet](./xet/index). Загружайте и скачивайте их с помощью [`hf image`](#pushing-and-pulling-with-hf-image) — рекомендуемого клиента; также поддерживаются стандартные клиенты, такие как Docker, Podman, crane, skopeo, ORAS и Helm.

> [!NOTE]
> Контейнерные образы находятся в закрытой бете: [свяжитесь с нами](https://huggingface.co/contact/sales), чтобы включить их для вашей организации.

## Создание репозитория

Перейдите на [huggingface.co/new-container](https://huggingface.co/new-container) и выберите организацию, имя и видимость. Или используйте API:

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

Создайте репозиторий перед отправкой: попытка отправить в несуществующий репозиторий завершится ошибкой `NAME_UNKNOWN`. На его странице, `https://huggingface.co/containers/my-org/my-app`, перечислены теги. Права на получение и отправку определяются видимостью репозитория и ролью каждого участника в организации.

## Отправка и получение с помощью `hf image`

[`hf image`](https://github.com/huggingface/hf-image), расширение CLI `hf`, передаёт только те части каждого слоя, которые изменились с предыдущей версии, что обеспечивает более высокую скорость по сравнению с другими OCI-клиентами.

```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](./security-tokens) (`read` для получения, `write` для отправки) и требуется Docker с [хранилищем образов containerd](https://docs.docker.com/engine/storage/containerd/). Образы, отправленные с помощью `hf image`, могут быть получены любым клиентом.

Поскольку `hf image` хранит слои без сжатия, образы, которые он отправляет, получают другие дайджесты, чем при использовании `docker push`. Чтобы сохранить дайджесты `docker push`, например для подписей или развёртываний, закреплённых по дайджесту, используйте `hf image push --preserve-digests`. Это работает медленнее: изменённые слои в этом случае отправляются и загружаются целиком, как при `docker push`.

## Использование Docker и других клиентов OCI

Хотя мы рекомендуем использовать `hf image` (см. предыдущий раздел), чтобы в полной мере воспользоваться преимуществами [бэкенда Xet](./xet/index), вы также можете взаимодействовать с реестром через любой OCI-клиент.

Войдите, указав имя пользователя Hugging Face и [User Access Token](./security-tokens) в качестве пароля: `read` для получения, `write` для отправки. Публичные образы можно получить без входа.

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

Другие клиенты OCI работают аналогичным образом. Helm добавляет имя чарта к URL: `helm push mychart-0.1.0.tgz oci://cr.hf.co/my-org` выполняет публикацию в `my-org/mychart`, который должен существовать заранее.

## Удаление изображений

На Hub удалите тег с помощью **Удалить этот тег** в его меню на странице изображения или тега. С помощью [`hf image`](#pushing-and-pulling-with-hf-image) удалите теги изображения, а затем удалите его по дайджесту:

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

Если образ всё ещё используется, например, другим тегом, удаление отклоняется, и выводится список того, что необходимо удалить в первую очередь. Удаление многоплатформенного образа также приводит к удалению его платформенных образов.

## Сборка мусора

Реестр удаляет образы, на которые больше не указывает ни один тег, напрямую или через мультиархитектурный образ, например, предыдущий `latest` после новой загрузки. Он также удаляет слои, которые не используются ни одним из оставшихся образов. Чтобы продолжать получать образ по дайджесту, оставьте на нём тег.

## Ограничения

- Имена изображений имеют вид `cr.hf.co/<namespace>/<name>` и записываются строчными буквами.
- Слои до 100 ГБ, манифесты до 4 МБ.
- Отображение нового тега в списке может занять несколько секунд.