Imagens de Container

As Imagens de Container são um tipo de repositório no Hugging Face Hub para imagens Docker e outras imagens OCI. O registro de containers do Hugging Face, cr.hf.co, armazena as imagens no backend de armazenamento Xet. Envie e baixe-as com hf image, o cliente recomendado; clientes padrão, como Docker, Podman, crane, skopeo, ORAS e Helm, também funcionam.

As Imagens de Container estão em beta privado: entre em contato conosco para ativá-las para sua organização.

Criando um Repositório

Acesse huggingface.co/new-container e escolha a organização, um nome e a visibilidade. Ou use a 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}'

Crie o repositório antes de fazer o push: um push para um repositório inexistente falha com NAME_UNKNOWN. A página dele, https://huggingface.co/containers/my-org/my-app, lista as tags. Quem pode fazer pull e push segue a visibilidade do repositório e o papel de cada membro na organização.

Pushing e Pulling com hf image

hf image, uma extensão do CLI hf, transfere apenas as partes de cada camada que foram alteradas desde a versão anterior, resultando em uma experiência mais rápida em comparação com outros clientes 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

Ele usa seu User Access Token do Hugging Face (read para puxar, write para enviar) e requer o Docker com o containerd image store. As imagens enviadas com hf image podem ser puxadas por qualquer cliente.

Como hf image armazena as camadas sem compressão, as imagens que ele envia recebem digests diferentes dos obtidos com docker push. Para manter os digests do docker push, por exemplo para assinaturas ou implantações fixadas por digest, use hf image push --preserve-digests. Esse processo é mais lento: as camadas alteradas são então enviadas e baixadas por completo, assim como no docker push.

Usando Docker e outros clientes OCI

Embora recomendemos o uso de hf image (veja a seção anterior) para aproveitar plenamente o backend Xet, você também pode interagir com o registro por meio de qualquer cliente OCI.

Faça login com seu nome de usuário do Hugging Face e um User Access Token como senha: read para puxar, write para enviar. Imagens públicas podem ser puxadas sem fazer login.

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

Outros clientes OCI funcionam da mesma forma. O Helm adiciona o nome do gráfico à URL: helm push mychart-0.1.0.tgz oci://cr.hf.co/my-org envia para my-org/mychart, que deve existir previamente.

Excluindo Imagens

No Hub, remova uma tag usando Excluir esta tag no menu, na página da imagem ou da tag. Com hf image, remova as tags de uma imagem e, em seguida, exclua-a pelo digest:

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>

Se algo ainda referencia a imagem, como outra tag, a exclusão é recusada e lista o que deve ser removido primeiro. A exclusão de uma imagem multi-arch também exclui suas imagens de plataforma.

Coleta de Lixo

O registro exclui as imagens que nenhuma tag aponta mais, diretamente ou por meio de uma imagem multi-arquitetura, como a latest anterior após um novo push. Ele também exclui as camadas que nenhuma imagem restante utiliza. Para continuar puxando uma imagem por digest, mantenha uma tag nela.

Limites

• Os nomes de imagem são cr.hf.co/<namespace>/<name>, em minúsculas.
• Camadas de até 100 GB, manifests de até 4 MiB.
• Listas de tags podem levar alguns segundos para exibir uma nova tag.