컨테이너 이미지

Container Images는 Hugging Face Hub에서 Docker 및 기타 OCI 이미지를 위한 저장소 유형입니다. Hugging Face 컨테이너 레지스트리인 cr.hf.co는 이미지를 Xet 스토리지 백엔드에 저장합니다. 권장 클라이언트인 hf image를 사용하여 이미지를 push 및 pull할 수 있으며, 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를 사용하면 이미지의 태그를 제거한 후 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>

이미지를 참조하는 항목(예: 다른 태그)이 남아 있으면 삭제는 거부되며, 먼저 제거해야 할 항목이 나열됩니다. 멀티 아키텍처 이미지를 삭제하면 해당 플랫폼 이미지들도 함께 삭제됩니다.

가비지 컬렉션

레지스트리는 더 이상 어떤 태그도 가리키지 않는 이미지를 삭제합니다. 여기에는 직접적으로 참조되지 않는 경우와, 새로운 push 이후 이전 latest와 같은 멀티 아키텍처 이미지를 통해 간접적으로 참조되지 않는 경우도 포함됩니다. 또한, 남은 어떤 이미지에서도 사용하지 않는 레이어도 삭제합니다. digest를 통해 이미지를 계속 pull하려면 해당 이미지에 태그를 유지해야 합니다.

한계

• 이미지 이름은 소문자로 cr.hf.co/<namespace>/<name> 형식입니다.
• 레이어는 최대 100 GB, 매니페스트는 최대 4 MiB까지 지원됩니다.
• Tag lists에 새 태그가 표시되는 데 몇 초가 걸릴 수 있습니다.