本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# Hugging Face Hub 模型部署失敗
<a name="sagemaker-hyperpod-model-deployment-ts-huggingface"></a>

**概觀：**使用模型來源類型從 Hugging Face Hub 部署`huggingface`模型時，部署可能會在模型下載階段失敗。本節涵蓋常見的故障案例，以及如何使用 Kubernetes 事件和 Pod 日誌進行診斷。

## 診斷 Hugging Face 部署失敗
<a name="sagemaker-hyperpod-model-deployment-ts-hf-diagnose"></a>

**故障診斷步驟：**

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

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

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

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

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

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

   ```
   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>

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

**根本原因：**
+ Kubernetes Secret 中的 Hugging Face API 權杖無效、過期或已撤銷。
+ 權杖無法存取 gated 模型。

**解決方法：**

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

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

## 網路連線失敗
<a name="sagemaker-hyperpod-model-deployment-ts-hf-network"></a>

**徵狀：**初始化容器因連線逾時或 DNS 解析錯誤而失敗。Pod 會進入 `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>

**症狀：**初始化容器失敗，出現 `Repository Not Found`或 `404`錯誤。

**根本原因：**
+ `modelId` 不正確，或 Hugging Face Hub 上不存在模型。
+ 模型是私有的，而且字符沒有存取權。

**解決方法：**

1. 造訪瀏覽器`https://huggingface.co/<org>/<model>`中的 ，確認模型 ID 存在。

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