Agent Skills
返回列表
🔒

HF 云端推理镜像选型

IT 运维与安全 更新于 2026.08.29

将以下提示词粘贴到你的 AI 对话框中：

请根据 https://skillhub.cn/install/skillhub.md，安装 @org-02qudk26/hf-cloud-serving-image-selection。

技能介绍

问题从哪来

SageMaker 上 HuggingFace 推理端点最常见的「假成功」失败，是容器选错：标签过期、AMI 与 CUDA 不匹配、或把生成式重排序器丢进 TEI。表面现象往往是统一的 Failed to pass health check，排查会浪费大量时间。

技能在做什么

本技能把 规则零（HuggingFace 精选 DLC 优先） 和 AWS 官方 DLC 目录 绑成可执行决策：

  • 用决策表把模型类型映射到容器系列（huggingface-vllm、huggingface-vllm-omni、TEI、DJL Inference 等）
  • 说明 URI 应从 AWS available images 读取，并将 <region> 替换为实际区域
  • 区分 编码器交叉编码器重排序器（TEI） 与 生成式重排序器（vLLM），避免 TEI 在创建周期末尾才拒绝模型
  • 列出 vLLM 族（含 HuggingFace vLLM）在 cu130+ 时必须设置 InferenceAmiVersion=al2-ami-sagemaker-inference-gpu-3-1
  • 覆盖 TEI 的 GPU/CPU 变体与实例类型对应关系，以及 SM_VLLM_HOST=0.0.0.0 等必需环境变量

边界与注意

  • 不要用 TGI（已归档）；text-generation 应走 vLLM 路线
  • huggingface-pytorch-inference GPU 标签存在已知 NCCL/torch 链接问题，分类等任务应改 DJL 或 CPU/BYOC
  • VPC 内无 NAT 时，应使用区域 ECR URI，而非依赖 public.ecr.aws 拉取
  • 首次从 Hub 拉权重启动可能需 5–15 分钟以上，不等于部署失败

使用场景

  • 在 SageMaker 上部署 Qwen/Llama 文本生成端点，需从 AWS DLC 目录选定 huggingface-vllm 标签并配齐 SM_VLLM 环境变量
  • 上线 BGE 等嵌入模型，需按 ml.g5 或 ml.c5 实例在 TEI GPU 与 CPU 镜像之间选对 ECR URI
  • 部署 Qwen3-Reranker 等生成式重排序器，需确认走 vLLM 而非 TEI，避免端点创建后 classifier 类型被拒
  • cu130 的 vLLM 端点启动即失败且无 CloudWatch 日志，需核对是否缺少 al2-ami-sagemaker-inference-gpu-3-1

适合人员

  • 负责把 HuggingFace 模型推到 SageMaker 生产端点的 MLOps，需要统一镜像选型规则避免反复 health check 排错
  • 维护 deploy.py / deploy_async.py 流水线的人，需要在 --image-uri 与 --inference-ami-version 上填对目录 URI
  • 在私有 VPC 部署推理、遇到 ECR 拉取失败的平台工程师，需区分区域 DLC URI 与 public.ecr.aws 镜像复制
  • 做检索增强或排序服务、同时要区分交叉编码器重排与因果 LM 重排的算法工程师