本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

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

**概述：**使用模型源类型从 Hugging Face `huggingface` Hub 部署模型时，部署可能会在模型下载阶段失败。本节介绍常见的故障场景以及如何使用 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. 如果 init 容器出现故障（pod 显示`Init:CrashLoopBackOff`或`Init:Error`），请查看 init 容器日志：

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

1. 检查 pod 状态以获取 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 Secret 中的 Hugging Face API 令牌无效、已过期或已撤销。
+ 令牌无权访问门控模型。

**解决方法：**

1. 在 [huggingface 处生成一个新代币。 co/settings/代币](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>

**症状：**Init 容器因连接超时或 DNS 解析错误而失败。吊舱进来`CrashLoopBackOff`了。

**根本原因：**集群节点无法访问 Hugging Face 域`*.huggingface.co`（`*.hf.co`和）的出站互联网。这在没有 NAT 网关的私有子网中很常见。

**解决方法：**

1. 验证您的 VPC 是否已为运行集群节点的私有子网配置了 NAT 网关。

1. 确认安全组允许出站 HTTPS（端口 443）流量。

1. 验证网络 ACL 是否允许互联网的出站流量。

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. 在浏览器`https://huggingface.co/<org>/<model>`中访问以验证模型 ID 是否存在。

1. 请`modelId`确保您的`org/model`格式 InferenceEndpointConfig 正确（例如，`mistralai/Mistral-7B-Instruct-v0.3`）。