View a markdown version of this page

Hugging Face Hub 模型部署失败 - 亚马逊 SageMaker AI
诊断 Hugging Face 部署失败Hugging Face 代币无效或已过期网络连接故障未找到模型

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

Hugging Face Hub 模型部署失败

概述：使用模型源类型从 Hugging Face huggingface Hub 部署模型时，部署可能会在模型下载阶段失败。本节介绍常见的故障场景以及如何使用 Kubernetes 事件和 pod 日志对其进行诊断。

诊断 Hugging Face 部署失败

故障排除步骤：

  1. 检查 InferenceEndpointConfig 状态和事件以了解错误详情：

    kubectl describe inferenceendpointconfig <name> -n <namespace>

    查找状态中包含原因HuggingFaceDownloadFailed和DeploymentFailed条件的事件，其中包含特定的错误消息。

  2. 如果 init 容器出现故障（pod 显示Init:CrashLoopBackOff或Init:Error），请查看 init 容器日志：

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

  3. 检查 pod 状态以获取 init 容器退出代码：

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

Hugging Face 代币无效或已过期

症状：Init 容器失败并显示401 Unauthorized或Access denied错误。吊舱进来CrashLoopBackOff了。

根本原因：

  • Kubernetes Secret 中的 Hugging Face API 令牌无效、已过期或已撤销。

  • 令牌无权访问门控模型。

解决方法：

  1. 在 huggingface 处生成一个新代币。 co/settings/代币。

  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>

网络连接故障

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

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

解决方法：

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

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

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

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

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