View a markdown version of this page

Hugging Face Hub 모델 배포 실패 - Amazon SageMaker AI
Hugging Face 배포 실패 진단유효하지 않거나 만료된 Hugging Face 토큰네트워크 연결 실패모델을 찾을 수 없음

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

Hugging Face Hub 모델 배포 실패

개요: 모델 소스 유형을 사용하여 Hugging Face Hub에서 huggingface 모델을 배포할 때 모델 다운로드 단계에서 배포가 실패할 수 있습니다. 이 섹션에서는 일반적인 장애 시나리오와 Kubernetes 이벤트 및 포드 로그를 사용하여 이를 진단하는 방법을 다룹니다.

Hugging Face 배포 실패 진단

문제 해결 단계:

  1. InferenceEndpointConfig 상태 및 이벤트에서 오류 세부 정보를 확인합니다.

    kubectl describe inferenceendpointconfig <name> -n <namespace>

    특정 오류 메시지가 포함된 상태 HuggingFaceDownloadFailed DeploymentFailed 및 이유가 있는 이벤트를 찾습니다.

  2. init 컨테이너가 실패하는 경우(포드에 Init:CrashLoopBackOff 또는가 표시됨Init:Error) init 컨테이너 로그를 확인합니다.

    kubectl logs <pod-name> -c hf-model-downloader -n <namespace>

  3. 포드 상태에서 컨테이너 종료 코드 초기화를 확인합니다.

    kubectl get pod <pod-name> -n <namespace> -o jsonpath='{.status.initContainerStatuses[0].state}'

유효하지 않거나 만료된 Hugging Face 토큰

증상: 401 Unauthorized 또는 Access denied 오류와 함께 컨테이너 초기화가 실패합니다. 포드가에 들어갑니다CrashLoopBackOff.

근본 원인:

  • Kubernetes 보안 암호의 Hugging Face API 토큰이 유효하지 않거나 만료되었거나 취소되었습니다.

  • 토큰은 게이트 모델에 액세스할 수 없습니다.

​해결 방법:

  1. huggingface.co/settings/tokens 새 토큰을 생성합니다.

  2. 게이트 모델의 경우 Hugging Face Hub 모델 페이지에서 모델의 라이선스 계약에 동의했는지 확인합니다.

  3. Kubernetes 보안 암호를 새 토큰으로 업데이트합니다.

    kubectl delete secret <secret-name> -n <namespace>
kubectl create secret generic <secret-name> \
  --from-literal=token=hf_NEW_TOKEN_HERE \
  -n <namespace>

  4. 실패한 포드를 삭제하여 새 다운로드 시도를 트리거합니다.

    kubectl delete pod -l app=<iec-name> -n <namespace>

네트워크 연결 실패

증상: Init 컨테이너가 연결 제한 시간 또는 DNS 확인 오류와 함께 실패합니다. 포드가에 들어갑니다CrashLoopBackOff.

근본 원인: 클러스터 노드에 Hugging Face 도메인(*.huggingface.co 및 )에 대한 아웃바운드 인터넷 액세스 권한이 없습니다*.hf.co. 이는 NAT 게이트웨이가 없는 프라이빗 서브넷에서 일반적입니다.

​해결 방법:

  1. VPC에 클러스터 노드가 실행되는 프라이빗 서브넷에 대해 구성된 NAT 게이트웨이가 있는지 확인합니다.

  2. 보안 그룹이 아웃바운드 HTTPS(포트 443) 트래픽을 허용하는지 확인합니다.

  3. 네트워크 ACLs이 인터넷으로의 아웃바운드 트래픽을 허용하는지 확인합니다.

  4. 클러스터 내에서 연결을 테스트합니다.

    kubectl run test-connectivity --image=curlimages/curl --rm -it --restart=Never -- \
  curl -sI https://huggingface.co
참고

아웃바운드 인터넷 액세스를 사용할 수 없는 경우 Amazon S3 또는 Amazon FSx를 모델 소스로 대신 사용하는 것이 좋습니다. 먼저 모델을 Amazon S3에 다운로드한 다음 s3 모델 소스 유형을 사용하여 배포합니다.

모델을 찾을 수 없음

증상: Repository Not Found 또는 404 오류와 함께 컨테이너 초기화가 실패합니다.

근본 원인:

  • modelId이 잘못되었거나 Hugging Face Hub에 모델이 없습니다.

  • 모델은 프라이빗이며 토큰에 액세스할 수 없습니다.

​해결 방법:

  1. 브라우저에서를 방문하여 모델 IDhttps://huggingface.co/<org>/<model>가 존재하는지 확인합니다.

  2. InferenceEndpointConfigmodelId의가 올바른 org/model 형식(예: mistralai/Mistral-7B-Instruct-v0.3)인지 확인합니다.