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 事件和 Pod 日誌進行診斷。

診斷 Hugging Face 部署失敗

故障診斷步驟：

  1. 檢查 InferenceEndpointConfig 狀態和事件的錯誤詳細資訊：

    kubectl describe inferenceendpointconfig <name> -n <namespace>

    尋找 狀態中具有原因HuggingFaceDownloadFailed和DeploymentFailed條件的事件，其中包含特定的錯誤訊息。

  2. 如果初始化容器失敗 (Pod 顯示 Init:CrashLoopBackOff或 Init:Error)，請檢查初始化容器日誌：

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

  3. 檢查 Pod 狀態是否有初始化容器結束代碼：

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

Hugging Face 字符無效或過期

症狀：初始化容器失敗，出現 401 Unauthorized或 Access denied 錯誤。Pod 會進入 CrashLoopBackOff。

根本原因：

  • Kubernetes Secret 中的 Hugging Face API 權杖無效、過期或已撤銷。

  • 權杖無法存取 gated 模型。

解決方法：

  1. 在 https：//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. 刪除失敗的 Pod 以觸發新的下載嘗試：

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

網路連線失敗

徵狀：初始化容器因連線逾時或 DNS 解析錯誤而失敗。Pod 會進入 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. 造訪瀏覽器https://huggingface.co/<org>/<model>中的 ，確認模型 ID 存在。

  2. 請確定 InferenceEndpointConfig modelId中的 格式正確 org/model（例如 mistralai/Mistral-7B-Instruct-v0.3)。