翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# Hugging Face Hub モデルのデプロイの失敗
<a name="sagemaker-hyperpod-model-deployment-ts-huggingface"></a>

**概要:** モデルソースタイプを使用して Hugging Face Hub から`huggingface`モデルをデプロイする場合、モデルのダウンロードフェーズ中にデプロイが失敗することがあります。このセクションでは、一般的な障害シナリオと、Kubernetes イベントとポッドログを使用してそれらを診断する方法について説明します。

## Hugging Face のデプロイ失敗の診断
<a name="sagemaker-hyperpod-model-deployment-ts-hf-diagnose"></a>

**トラブルシューティングのステップ:**

1. InferenceEndpointConfig のステータスとイベントでエラーの詳細を確認します。

   ```
   kubectl describe inferenceendpointconfig <name> -n <namespace>
   ```

   特定のエラーメッセージを含む、ステータスに理由`HuggingFaceDownloadFailed`と`DeploymentFailed`条件があるイベントを探します。

1. init コンテナが失敗した場合 (ポッドが `Init:CrashLoopBackOff`または を表示`Init:Error`)、init コンテナログを確認します。

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

1. init コンテナの終了コードのポッドステータスを確認します。

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

## 無効または期限切れの Hugging Face トークン
<a name="sagemaker-hyperpod-model-deployment-ts-hf-token"></a>

**症状:** Init コンテナは `401 Unauthorized`または `Access denied` エラーで失敗します。ポッドが に入ります`CrashLoopBackOff`。

**根本原因:**
+ Kubernetes シークレットの Hugging Face API トークンが無効、期限切れ、または取り消されました。
+ トークンはゲートモデルにアクセスできません。

**解決策**:

1. [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) で新しいトークンを生成します。

1. ゲートモデルの場合は、Hugging Face Hub モデルページでモデルのライセンス契約に同意していることを確認してください。

1. 新しいトークンで Kubernetes シークレットを更新します。

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

1. 失敗したポッドを削除して、新しいダウンロード試行をトリガーします。

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

## ネットワーク接続の失敗
<a name="sagemaker-hyperpod-model-deployment-ts-hf-network"></a>

**症状:** Init コンテナが接続タイムアウトまたは DNS 解決エラーで失敗します。ポッドが に入ります`CrashLoopBackOff`。

**根本原因:** クラスターノードには Hugging Face ドメイン (`*.huggingface.co` および ) へのアウトバウンドインターネットアクセスがありません`*.hf.co`。これは、NAT ゲートウェイのないプライベートサブネットで一般的です。

**解決策**:

1. VPC に、クラスターノードが実行されるプライベートサブネット用に NAT ゲートウェイが設定されていることを確認します。

1. セキュリティグループがアウトバウンド HTTPS (ポート 443) トラフィックを許可していることを確認します。

1. ネットワーク ACLsインターネットへのアウトバウンドトラフィックを許可していることを確認します。

1. クラスター内から接続をテストします。

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

**注記**  
アウトバウンドインターネットアクセスが利用できない場合は、代わりに Amazon S3 または Amazon FSx をモデルソースとして使用することを検討してください。最初にモデルを Amazon S3 にダウンロードし、`s3`次にモデルソースタイプを使用してデプロイします。

## モデルが見つかりません
<a name="sagemaker-hyperpod-model-deployment-ts-hf-model-not-found"></a>

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

**根本原因:**
+ `modelId` が正しくないか、Hugging Face Hub にモデルが存在しません。
+ モデルはプライベートであり、トークンにはアクセスできません。

**解決策**:

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

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