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. init コンテナの終了コードのポッドステータスを確認します。

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

無効または期限切れの Hugging Face トークン

症状: Init コンテナは 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次にモデルソースタイプを使用してデプロイします。

モデルが見つかりません

症状: Init コンテナは Repository Not Foundまたは 404 エラーで失敗します。

根本原因:

  • modelId が正しくないか、Hugging Face Hub にモデルが存在しません。

  • モデルはプライベートであり、トークンにはアクセスできません。

解決策:

  1. ブラウザで にアクセスして、モデル ID が存在するhttps://huggingface.co/<org>/<model>ことを確認します。

  2. InferenceEndpointConfig modelIdの が正しいorg/model形式 (例: ) であることを確認しますmistralai/Mistral-7B-Instruct-v0.3。