企业官网建设流程全解析

SageMaker 镜像选择实战指南：基于 Hugging Face 生态为模型部署挑选正确的 Serving 容器

【免费下载链接】skillsGive your agents the power of the Hugging Face ecosystem项目地址: https://gitcode.com/GitHub_Trending/skills7/skills

在 SageMaker 上部署 Hugging Face 模型时，Serving 容器（image）往往是"纸面上看起来完全正确"的部署最终失败的头号原因：选错容器、用了过期 tag、或者 AMI 版本不对，都会收敛到同一个无法区分的Failed to pass health check错误。本文以 skills/hf-cloud-serving-image-selection/SKILL.md 为核心，结合仓库内 模型到镜像决策表 与 mirror_image.py 源码，系统讲解 SageMaker DLC 镜像的决策规则、URI 获取方式、vLLM/TEI 的环境变量配置、AMI 匹配要求与已知坑点。读完你可以为任何 Hugging Face 模型（文本生成、多模态、Embedding、重排器、扩散模型）准确选出容器族与 URI，并正确配置deploy.py与deploy_async.py完成一次不被镜像问题打断的部署。

为什么镜像选择是部署成败的关键

Serving 容器是 SageMaker 部署链路中耦合最紧、最容易被忽视的一环。本技能文档开篇即点明：wrong container、stale tag、或错误的 AMI，三者都产生同一个不透明的Failed to pass health check。这意味着一旦镜像选错，你面对的不是一个能定位的报错，而是一个需要逐一排查的"黑盒"失败。

正确选镜像的本质不是"挑最新版本"，而是"挑与模型架构兼容的容器族"。这正是本技能文档的核心决策原则。

规则零：Hugging Face 官方镜像永远优先

这是整份文档的第一优先级规则（Rule zero）：当同一模型同时能被 Hugging Face 官方维护的容器族和通用容器族服务时，选择 Hugging Face 镜像是强制的，而不是可选项。

只有以下三种情况才允许回退到通用镜像：

1. 经验证的架构不兼容——模型需要的架构/模态/特性在当前可用的 Hugging Face tag 中都不支持（必须对照镜像目录确认，不能靠猜测）；
2. 目标区域没有对应的 Hugging Face tag，且无法通过镜像搬运（mirror）解决；
3. 该 Hugging Face 镜像位于下文"已知损坏镜像"列表中。

文档特别强调：通用仓库里更高的版本号不是选它的理由。AWS 的vllm仓库经常发布比huggingface-vllm更高的 vLLM 版本，但"更旧但兼容的huggingface-vllmtag 仍然胜出"——因为没有人要求"最新 vLLM"，要求的是"与模型兼容"。如果确实回退，必须在部署日志中记录使用的是上面三条理由中的哪一条。

为什么huggingface-vllm是 LLM 的默认项

从 references/model-to-image.md 可以看到，huggingface-vllm是直接构建在 AWS vLLM DLC 之上的：

• 与 AWS vLLM 镜像共享完全相同的SM_VLLM_*环境变量契约和cu130 AMI 规则（详见下文"vLLM AMI 要求"）；
• 额外携带较新的transformers、较新的huggingface_hub与hf_xet——这正是解决旧镜像在 Hugging Face XET CDN 下载模型时 403 失败的关键；
• 内置 ffmpeg（多模态预处理）与 Hugging Face 性能默认值（expandable-segments 分配器、LMCache CPU KV-offload）；
• 是 SageMaker SDK v3 的ModelBuilder对text-generation任务的自动路由目标（自 sagemaker-python-sdk PR #5960，2026 年 6 月合并）。

AWS 的vllm镜像在此定位仅是"兼容性逃生舱"，绝不能因为版本号更高而选它。

不要用 TGI

文档明确记录：Text Generation Inference（TGI）已归档（archived），归档后发布的模型（最典型的是 Qwen3）在 TGI 上会 ping 健康检查失败。因此新部署一律使用 vLLM 而非 TGI。SageMaker SDK v3 也佐证了这一方向：v2 时代的get_huggingface_llm_image_uri助手返回 TGI URI，v3 已完全移除该函数，改为按任务自动路由——text-generation→ HuggingFace vLLM DLC，多模态任务 → vLLM-Omni。

镜像 URI 从哪里来：AWS DLC 官方目录是唯一主源

文档给出的唯一主源（primary source）是AWS 官方 Deep Learning Containers 镜像目录（aws.github.io/deep-learning-containers的 available images 页面）。该页面由 AWS 维护，列出每个镜像族的示例 URI、tag、CUDA 版本、Python 版本以及平台（SageMaker vs EC2/ECS/EKS）。

选择 URI 的正确姿势：直接从该页面读取——复制示例 URL，将<region>替换为用户所在区域，然后传给deploy.py --image-uri。本技能在 部署工作流 中的定位正是为deploy.py提供--image-uri与--inference-ami-version这两个参数（见 deploy.py 中--image-uri与--inference-ami-version两个必选/条件参数的定义，其中 AMI 参数的帮助文本明确标注"REQUIRED for vLLM DLC with CUDA 13+"）。

账号 ID 的坑

大多数区域的示例 URI 使用763104351884作为账号 ID，但少数区域使用不同账号（例如eu-south-1使用692866216735）。TEI 更特殊：目录页示例账号是683313688378，但 TEI 由独立于主 DLC 的账号命名空间发布，各区域账号 ID 各不相同。文档给出的经验是：如果683313688378.dkr.ecr.<region>.amazonaws.com/tei:...在非 us-east-1 区域拉取报错，去 AWS 的 Region Availability 页面查对应区域的正确账号 ID。

例外：目前没有例外

文档记录：当前工作流用到的每个镜像族都已出现在 AWS 目录页（TEI 于 2026 年末加入）。如果遇到目录页上还没有的新镜像族，用mirror_image.py镜像后直接传入所得 URI。

快速决策表：模型族 → 容器族 → URI 来源

这是文档中最核心的速查表，完整继承如下：

补充说明（来自决策表全文）：Inferentia / Trainium 硬件应选NeuronX系列；文本生成 LLM 的完整 URI 模式为763104351884.dkr.ecr.<region>.amazonaws.com/huggingface-vllm:<version>-transformers<tv>-gpu-py<py>-cu<cuda>-ubuntu22.04，AWS vLLM 回退镜像的模式为763104351884.dkr.ecr.<region>.amazonaws.com/vllm:<version>-gpu-py<py>-cu<cuda>-ubuntu22.04-sagemaker，二者均以目录页实际最新 tag 为准。

重排器选型：TEI 还是 vLLM？

"Reranker"覆盖两种架构迥异的模型，选错会白白浪费一整轮端点创建周期（约 20 分钟）才被 TEI 拒绝。文档给出了清晰的判别方法：

• Encoder cross-encoders（BAAI/bge-reranker-*、mixedbread、多数sentence-transformers重排器）：BERT 系 + 分类头，config.json中architectures为 TEI 支持的 encoder 类型且以ForSequenceClassification结尾 →TEI；
• 生成式重排器（Qwen/Qwen3-Reranker-*及类似因果 LM 判分器）：decoder 型 LLM，通过 yes/no token 的 logprob 判相关度，config.json中architectures以ForCausalLM结尾 →HuggingFace vLLM，按文本生成 LLM 的方式部署。TEI 会加载该架构后拒绝classifier模型类型（Qwen3 在 TEI 中仅支持 embeddings）。

文档给出的预检方法是创建任何资源之前先发一个 HTTP GET 看config.json：

curl -s https://huggingface.co/<model-id>/raw/main/config.json # "architectures": ["Qwen3ForCausalLM"] → vLLM # "architectures": ["XLMRobertaForSequenceClassification"] → TEI

对 TEI 还要确认(architecture, task)组合：架构出现在 TEI 支持列表中只代表 embeddings 支持，不代表分类/重排支持。TEI 的支持是按 (架构, 任务) 组合粒度而非架构粒度——这正是 Qwen3 出现在列表里、但带分类头的 Qwen3 却被拒绝的原因。

需要注意的一个 SDK 陷阱：SageMaker SDK v3（PR #5960）把text-ranking任务无条件路由到 TEI——这对 cross-encoders 是对的，对生成式重排器是错的。因此不要把 SDK 的路由行为当作"TEI 能服务某个重排器"的证据。生成式重排器的调用方式（原始 completions API、max_tokens=1、logprobs 打分）记录在 hf-cloud-sagemaker-production-defaults 中。

标准工作流：从目录页到部署

文档给出的五步工作流，每个镜像族都适用：

1. 打开 AWS Deep Learning Containers 镜像目录页（available_images）；
2. 找到对应容器族的区块（LLM 用 "HuggingFace vLLM Inference"，Embeddings 用 "HuggingFace Text Embeddings Inference" 等）；
3. 挑选平台列为SageMaker的最新一行——最新指的是该容器族内部的最新，不要因为别的容器族版本更高而跨族切换（见"规则零"）；
4. 将<region>替换为用户区域（来自 hf-cloud-aws-context-discovery）；
5. vLLM 镜像额外核对 AMI 要求（见下节）；
6. 将 URI 传给deploy.py --image-uri（实时端点）或deploy_async.py --image-uri（异步端点）。

TEI：选对 GPU / CPU 变体

TEI 在目录页中列两个 URI——GPU 版（tei仓库）和 CPU 版（tei-cpu仓库）。按实例类型选择：

• ml.g*、ml.p*、ml.inf*→ GPU 变体
• ml.c*、ml.m*、ml.t*→ CPU 变体

混用会失败：CPU 镜像跑在 GPU 实例上浪费硬件，GPU 镜像跑在 CPU 实例上则直接起不来。从 决策表 补充的选型依据看：CPU Embeddings 成本远低于 GPU 且通常够快，ml.c6i.2xlarge（约 $0.20/小时）是常见起点；大模型（>1B 参数）或持续高吞吐才需要 GPU。

vLLM AMI 要求：cu130 与 InferenceAmiVersion 的对应表

CUDA 13 及以上（当前默认cu130）的 vLLM DLC 镜像必须在 ProductionVariant 上设置InferenceAmiVersion=al2-ami-sagemaker-inference-gpu-3-1。该要求对huggingface-vllm、huggingface-vllm-omni（基于同一 cu130 底座）和 AWSvllm仓库一视同仁。不设置的话，容器启动即死且永远不会创建 CloudWatch 日志——这个失败表象与账号级问题、配额、网络问题高度相似，经常把排查引向错误方向。

文档给出的查找表：

经验法则：选的 vLLM tag 含cu130或更高，就传--inference-ami-version al2-ami-sagemaker-inference-gpu-3-1给deploy.py；未来 AWS 发布 cu140+ 需要新 AMI 时，再给上表加行。

这是 vLLM 专属问题。TEI 与 HF Inference Toolkit 镜像不需要 AMI 覆盖。

源码侧佐证：在 deploy.py 的create_endpoint_config中，inference_ami_version参数被注入production_variant["InferenceAmiVersion"]，注释明确写着 "InferenceAmiVersion required for vLLM DLC with CUDA 13+. Without it the container dies on startup with no logs"，并指向本技能文档；deploy_async.py 的异步端点配置同理。

CUDA / 实例兼容性矩阵

这是文档中"容易搞错且关键"的部分，完整继承：

原理：驱动来自宿主 AMI 而非实例族，因此传入 gpu-3-1 AMI（vLLM cu130 镜像本来就需要它）同时也会让ml.g5.*对 cu129+ 镜像变得可用。

配置 HuggingFace vLLM / AWS vLLM DLC

两个镜像共享同一套配置契约：在 SageMaker 模型定义中通过环境变量配置，SM_VLLM_*映射到 vLLM CLI 参数。此外，huggingface-vllm的入口在SM_VLLM_MODEL未设置时会自动探测模型——从挂载的/opt/ml/model或回退到HF_MODEL_ID——但显式设置SM_VLLM_MODEL在两个镜像上都可用，也是仓库示例采用的方式（对应--env重复参数，见 deploy.py 中--env KEY=VALUE; repeatable与 _common.py 的parse_env实现）。

每个 Hugging Face LLM 部署的必填项

可选调优项

通用规则：任何 vLLM CLI 参数都可用——转大写、横线换下划线、加SM_VLLM_前缀。

配置 TEI

TEI 的环境变量契约比 vLLM 简单得多：

无需配置 host 绑定，没有 trust-remote-code 参数。TEI 支持的架构（BERT、CamemBERT、RoBERTa、XLM-RoBERTa、NomicBert、JinaBert、JinaCodeBert、Mistral、Qwen2/3、Gemma2/3、ModernBert）直接编译在镜像内。从 生产默认值技能 可确认：TEI 部署不需要--inference-ami-version，环境变量也更简单（HF_MODEL_ID而非SM_VLLM_*）。

需要注意的是 AWS 发布的 TEI DLC 有时会滞后上游数月——如果刚需某个近期架构而当前镜像不支持，可用mirror_image.py从上游镜像仓库镜像text-embeddings-inference:<version>到私有 ECR，再把结果直接传给deploy.py --image-uri。

VPC / NAT 网关问题与镜像搬运

SageMaker 端点位于没有 NAT 网关的 VPC 内时，无法从public.ecr.aws拉取镜像，部署会以一条完全不提 VPC 或 egress的镜像拉取错误失败。

• 对于 AWS 区域 ECR 上的镜像（目录中所有镜像都属此类）：SageMaker 通过内置路由可达，无需 NAT。务必使用区域 URI 模式（<account>.dkr.ecr.<region>.amazonaws.com/...），而不是public.ecr.aws/...模式；
• 对于确实需要public.ecr.aws访问的镜像（较少见）：用 mirror_image.py 搬运到账户内的私有 ECR 仓库。

镜像脚本的用法（跨平台，需要 Docker 与awsCLI，在 AWS CLI 可用的 shell 中运行）：

# macOS / Linux PRIVATE_URI=$(python3 scripts/mirror_image.py \ public.ecr.aws/deep-learning-containers/vllm:<tag> \ vllm-mirror)

# Windows (PowerShell) — capture stdout into a variable $PRIVATE_URI = python scripts\mirror_image.py ` public.ecr.aws/deep-learning-containers/vllm:<tag> vllm-mirror

源码级的镜像搬运实现细节

从 mirror_image.py 源码可以看到几个值得注意的实现决策：

• 拒绝隐式:latest（第 66-73 行）：如果公共 URI 无 tag，脚本直接报错退出，避免隐式 latest 带来的不可复现性；支持第三个参数<tag-override>显式指定 tag；
• 幂等性（第 102-109 行）：私有仓库中已存在该 tag 时直接跳过 pull/push 并输出私有 URI——重复执行不会重复搬运；
• 区域解析顺序（第 43-48 行）：AWS_REGION→AWS_DEFAULT_REGION→aws configure get region，与 hf-cloud-aws-context-discovery 的区域解析原则一致；
• 双端登录（第 111-127 行）：aws ecr-public get-login-password --region us-east-1登录公共仓库（ECR Public 认证固定走 us-east-1），aws ecr get-login-password --region <region>登录私有仓库；仓库创建时开启scanOnPush=true。

目录页无法渲染、过期或出错时的备选方案

AWS 目录页是重 JavaScript 页面，某些抓取工具只能拿到空壳。文档给出按序回退的三个方案：

1. 目录页的源数据（GitHub 上的 aws/deep-learning-containers 仓库）——页面由每个版本一个 YAML 文件生成，精确列出 tag、CUDA 与 Python 版本。先列出一个容器族的文件，再抓取最新版：

   curl -s https://api.github.com/repos/aws/deep-learning-containers/contents/docs/src/data/huggingface-vllm curl -s https://raw.githubusercontent.com/aws/deep-learning-containers/main/docs/src/data/huggingface-vllm/0.21.0-gpu-sagemaker.yml

   目录名与 ECR 仓库名一一对应（huggingface-vllm、huggingface-vllm-omni、huggingface-tei、vllm、djl-inference……）。

2. 直接查询 ECR 获取目标区域的当前 tag（需要能读 DLC 注册表的凭证；若返回 AccessDenied 则用 YAML 文件）：

   aws ecr describe-images --registry-id 763104351884 --repository-name huggingface-vllm \ --region <region> --query 'sort_by(imageDetails,&imagePushedAt)[-5:].imageTags' --output json

3. 查看 aws/deep-learning-containers 仓库的 Release notes。

另有两个场景：tag 刚发布还没上目录页（罕见，AWS 每次发布都会更新页面，可查 release notes）；目标架构当前镜像不支持（TEI 场景可通过镜像上游版本来规避，如前文所述）。

已知损坏镜像：huggingface-pytorch-inference GPU tag

截至文档最后核对时间（2026 年 7 月），huggingface-pytorch-inference的 GPU tag 全部不可用（测试过的近期 tag：PT 2.3–2.6、cu121/cu124、transformers 4.48–5.5.3），症状是：

ImportError: libtorch_cuda.so: undefined symbol: ncclCommResume

这是镜像内部的打包缺陷：镜像内捆绑的 NCCL 比 torch 链接要求的版本旧，在import torch时触发。已在 g5 和 g6 上验证，与 AMI、模型或推理代码无关。更隐蔽的是：MMS 的 Java 前端会持续应答/ping，所以端点可能进入 InService，而 Python worker 崩溃循环、实际不服务任何请求。

• 替代方案：DJL Inference（自带完整 CUDA/NCCL 栈）或 BYOC；CPU tag 不受影响。
• 通用回退规则：HF DLC 出现 CUDA/NCCL 链接错误时，直接切换到 DJL Inference，而不要在兄弟 tag 之间反复尝试——该类缺陷是按仓库而非按 tag 存在的（上面案例试过三个不同 tag，全部损坏）。
• 当 AWS 发布新的huggingface-pytorch-inferenceGPU tag 时需重新核对，确认修复后再移除该行记录。

相关的 HF Hub 坑：旧 DLC 可能因内置huggingface_hub早于 XET 认证时代，下载模型时从 HF 的 XET CDN 得到403 Forbidden。设置HF_HUB_ENABLE_HF_TRANSFER=0强制走标准下载路径，或把权重预置到 S3。

首次启动的 Hub 下载时间与 S3 预置

从 HF Hub 加载模型发生在端点启动之后的容器内部——即使是小模型，也要预期5–15 分钟以上才能进入 InService，多 GB 模型更久。慢首次启动不是失败；在部署脚本的 30 分钟等待超时之前不要拆除或重新诊断。仓库内 deploy.py 的wait_for_endpoint（来自 _common.py）正是按 30 分钟超时轮询DescribeEndpoint至InService的。

生产环境或重复部署建议预置权重到 S3并传--model-s3-uri给deploy.py（模型从/opt/ml/model加载）——更快、免疫 Hub 限流/故障，且运行时不需要HUGGING_FACE_HUB_TOKEN。源码侧对应 deploy.py 中--model-s3-uri参数与create_model里的ModelDataUrl设置（见 _common.py 的create_model）。

小结

镜像选择看似只是部署脚本里的一行--image-uri，实际上它串联了容器族决策、URI 来源、AMI 匹配、环境变量契约、网络可达性与已知缺陷规避。记住几条关键动作：

1. LLM 一律先看huggingface-vllm，多模态用huggingface-vllm-omni，Embeddings 与 encoder 重排用 TEI，生成式重排回 vLLM，扩散模型用 DJL；
2. URI 从 AWS DLC 目录页现读现用，不要凭记忆硬编码，不要跨容器族比版本号；
3. vLLM 的 cu130+ tag 必须带--inference-ami-version al2-ami-sagemaker-inference-gpu-3-1，同时确保SM_VLLM_HOST=0.0.0.0与SM_VLLM_TRUST_REMOTE_CODE=true；
4. VPC 无 NAT 时用区域 ECR URI 模式，必要时用mirror_image.py搬运；GPU 推理遇到 NCCL 链接错误直接转 DJL。

按照本技能的工作流，镜像这一个环节就不会再成为部署失败的来源。完整推理与决策表可继续查阅 references/model-to-image.md，镜像搬运脚本见 scripts/mirror_image.py，端点落地与 AMI 参数注入见 hf-cloud-sagemaker-production-defaults 及其 deploy.py、deploy_async.py。

【免费下载链接】skillsGive your agents the power of the Hugging Face ecosystem项目地址: https://gitcode.com/GitHub_Trending/skills7/skills