hf-cloud-serving-image-selection

服务映像选择

服务容器是最有可能导致 SageMaker 部署出问题的环节，即使部署“纸面上看起来完全正确”也是如此。容器选错、标签过时或 AMI 不匹配，都会产生同一个含糊不清的错误：Failed to pass health check。

第一原则：始终优先使用 HuggingFace 映像

如果 HuggingFace 精选系列（huggingface-vllm、huggingface-vllm-omni、huggingface-sglang、tei、huggingface-pytorch-inference）和通用系列（vllm、vllm-omni、sglang、djl-inference）都能为该模型提供服务，就必须使用 HuggingFace 映像，而非仅仅优先考虑。只有以下情况才可以使用通用映像：

1. 已验证的不兼容——模型需要当前可用的 HuggingFace 标签都不支持的架构、模态或功能，并且已对照目录确认（而非凭空假设）。
2. 目标区域没有 HuggingFace 标签，且无法镜像。
3. 下方“已知有问题的映像”中列出了该 HuggingFace 映像。

通用仓库的版本号更新并非理由。 AWS 的 vllm 仓库发布的 vLLM 版本往往高于 huggingface-vllm；即使 huggingface-vllm 标签较旧，只要兼容，仍应优先使用。“使用最新的 vLLM”并不是任何人提出的要求，关键在于与模型兼容。如果改用通用映像，请在部署日志中记录适用的三种理由之一。

映像 URI 的来源

首选来源：AWS 官方深度学习容器目录。

URL：https://aws.github.io/deep-learning-containers/reference/available_images/

此页面由 AWS 维护，列出了每个映像系列的示例 URI、标签、CUDA 版本、Python 版本和平台（SageMaker 或 EC2/ECS/EKS）。为部署选择 URI 时，请直接从此页面读取——复制示例 URL，将 <region> 替换为用户所在的区域，然后传递给 deploy.py --image-uri。

大多数区域的示例 URL 使用 763104351884 作为账户 ID。少数区域使用不同的账户 ID（例如，eu-south-1 使用 692866216735）。如有疑问，请查看区域可用性页面。

例外：目前没有。 此工作流使用的所有映像系列都已列在 AWS 目录页面上（TEI 于 2026 年末加入）。如果遇到目录中没有的新系列，请通过 mirror_image.py 镜像，并直接传递生成的 URI。

快速决策

模型	容器系列	如何获取 URI
HuggingFace 文本生成大模型（Llama、Qwen、Mistral 等）	HuggingFace vLLM	AWS 目录 → "HuggingFace vLLM Inference"（ECR 存储库 huggingface-vllm）
与上方相同，支持多模态	HuggingFace vLLM-Omni	AWS 目录 → "HuggingFace vLLM-Omni Inference"（ECR 存储库 huggingface-vllm-omni）
HuggingFace 嵌入模型	TEI	AWS 目录 → "HuggingFace Text Embeddings Inference"
编码器／交叉编码器重排模型（BERT 系列 *ForSequenceClassification）	TEI	与嵌入模型相同
生成式重排模型（因果语言模型，例如 Qwen3-Reranker）	HuggingFace vLLM	与文本生成大模型相同——不是 TEI，参见“重排模型：TEI 还是 vLLM？”
文本转图像／扩散模型（Stable Diffusion、FLUX）	DJL Inference	AWS 目录 → "DJL Inference"——不是 HF Inference Toolkit，参见“已知有问题的镜像”
HuggingFace 分类器、NER、QA、摘要模型	HF Inference Toolkit（CPU）	AWS 目录 → "HuggingFace PyTorch Inference"；GPU 标签目前有问题——参见“已知有问题的镜像”
用户明确指定 SGLang	HuggingFace SGLang	AWS 目录 → "HuggingFace SGLang Inference"
没有兼容的 huggingface-vllm 标签（已验证不兼容或所在区域缺少该标签——参见“规则零”）	vLLM（AWS）	AWS 目录 → "vLLM" 部分——仅作备用，绝不能用于追求版本新
用户明确指定 DJL-LMI	DJL Inference	AWS 目录 → "DJL Inference"
Amazon Nova	SageMaker JumpStart	使用 JumpStart，不要直接创建端点
自定义推理代码	BYOC	用户提供 URI

只要 HuggingFace 精选 DLC 存在兼容版本，就必须使用它们（参见“规则零”）。 huggingface-vllm 直接基于 AWS vLLM DLC 构建——具有完全相同的 SM_VLLM_* 环境变量约定和相同的 cu130 AMI 规则——并提供较新的 transformers、较新的 huggingface_hub + hf_xet（避免旧镜像遇到的 XET-CDN 403 下载失败），以及 HF 性能默认设置。SageMaker SDK v3 也会自动路由到此镜像。AWS 的 vllm 镜像仅用于兼容性兜底；它显示的 vLLM 版本通常比 huggingface-vllm 更新，这并不是选择它的理由。

不要使用 TGI。 Text Generation Inference 已归档。归档后发布的模型（最典型的是 Qwen3）在 TGI 上无法通过 ping 健康检查。请改用 vLLM。（SageMaker SDK v3 也采用相同做法：自 PR #5960 起，自 2026 年 6 月起，其 ModelBuilder 会将 text-generation 自动路由到 HuggingFace vLLM DLC，并将多模态任务路由到 HuggingFace vLLM-Omni。）

各系列的详细理由见 references/model-to-image.md。

重排器：TEI 还是 vLLM？

“重排器”涵盖两种截然不同的架构，选错会浪费一次完整的端点创建流程（约 20 分钟），之后 TEI 才会拒绝该模型：

• 编码器交叉编码器（BAAI/bge-reranker-*、mixedbread、大多数 sentence-transformers 重排器）——带有分类头的 BERT 系列模型。config.json 中的 architectures: [..ForSequenceClassification] 属于 TEI 支持的编码器类型。→ TEI。
• 生成式重排器（Qwen/Qwen3-Reranker-* 及类似的因果 LM 判别器）——通过是/否令牌的对数概率来评估相关性的解码器 LLM。config.json 中的 architectures: [..ForCausalLM]。→ HuggingFace vLLM，部署方式与文本生成 LLM 完全相同。TEI 会加载该架构，然后因 classifier 模型类型而拒绝；TEI 对 Qwen3 的支持仅限于嵌入。调用方式（原始 completions API、max_tokens=1、使用 logprobs 评分）见 hf-cloud-sagemaker-production-defaults。

创建任何资源前先进行预检——发送一次 HTTP GET 即可确定：

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

对于 TEI，还需确认 (架构，任务) 组合：某个架构出现在 TEI 支持列表中，表示支持嵌入，不一定表示支持分类/重排。

提醒：SageMaker SDK v3（PR #5960）会无条件将 text-ranking 任务路由到 TEI——这对交叉编码器是正确的，对生成式重排器则不正确。不要把 SDK 的路由行为当作 TEI 能为特定重排器提供服务的依据。

工作流

对于每个模型系列：从 AWS 目录页面读取 URI。

1. 打开 https://aws.github.io/deep-learning-containers/reference/available_images/
2. 找到对应系列的部分（例如，HuggingFace LLM 使用 “HuggingFace vLLM Inference”，嵌入使用 “HuggingFace Text Embeddings Inference”）
3. 选择平台列中标记为 SageMaker 的最新一行——即该系列中最新的一行。不要因为其他系列的部分列出了更高的引擎版本就切换过去（参见“规则零”）
4. 将 <region> 替换为用户所在区域（来自 hf-cloud-aws-context-discovery）
5. 对于 vLLM：还要检查 AMI 要求（见下文“vLLM AMI 要求”）
6. 将 URI 传给 deploy.py --image-uri（实时）或 deploy_async.py --image-uri（异步）

TEI：选择正确的变体

TEI 目录行列出两个 URI——GPU（tei 仓库）和 CPU（tei-cpu 仓库）。根据实例类型选择：

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

混用会导致失败：在 GPU 实例上使用 CPU 镜像会浪费硬件，在 CPU 实例上使用 GPU 镜像则无法启动。

关于 TEI 账户 ID 的说明：目录页面显示 683313688378 作为示例账户，但 TEI 发布时使用的账户命名空间与 AWS DLC 主账户不同，而且各区域的账户 ID 也不一样。如果在 us-east-1 以外的区域访问 683313688378.dkr.ecr.<region>.amazonaws.com/tei:... 时出现 ECR 拉取错误，请查阅区域可用性页面，获取该区域的正确账户 ID。

vLLM AMI 要求

CUDA 13 或更高版本的 vLLM DLC 镜像（当前默认值：cu130）要求在 ProductionVariant 上设置 InferenceAmiVersion=al2-ami-sagemaker-inference-gpu-3-1。这同样适用于 huggingface-vllm 和 huggingface-vllm-omni（基于相同的 cu130 基础镜像），以及 AWS vllm 仓库。如果不设置，容器会在启动时崩溃，且不会创建任何 CloudWatch 日志。这种故障表现与许多其他问题（账户级问题、配额、网络）完全相同，经常会让人沿着错误的诊断路径排查。

查找表：

标签包含	需传入的 InferenceAmiVersion
cu130（或更高版本）	al2-ami-sagemaker-inference-gpu-3-1
cu129 或更低版本	（省略该标志；默认 AMI 可正常工作）

经验法则：如果你选择的 vLLM 标签包含 cu130 或更高版本，则向 deploy.py 传入 --inference-ami-version al2-ami-sagemaker-inference-gpu-3-1。如果未来的 CUDA 版本（cu140+）需要不同的 AMI，请在 AWS 发布新镜像时向表格添加一行。

这是 vLLM 特有的问题。TEI 和 HF Inference Toolkit 镜像不需要覆盖 AMI。

配置 vLLM DLC（HuggingFace vLLM 和 AWS vLLM）

这两个镜像遵循相同的配置约定：在 SageMaker 模型定义中通过环境变量配置，并将 SM_VLLM_* 映射到 vLLM CLI 标志。huggingface-vllm 入口点还会在未设置 SM_VLLM_MODEL 时自动检测模型：如果挂载了 S3 构件，则从 /opt/ml/model 检测；否则从 HF_MODEL_ID 检测。生产环境中应将 SM_VLLM_MODEL 指向 /opt/ml/model；直接在运行时从 Hub 加载属于例外情况。

每个 HuggingFace LLM 部署都必须设置

环境变量	用途	备注
SM_VLLM_MODEL	HF 模型 ID（例如 Qwen/Qwen3-0.6B），或从 S3 加载时使用 /opt/ml/model	—
SM_VLLM_HOST	必须为 0.0.0.0	否则 vLLM 只会绑定 localhost，ping 会失败，容器也会在生成日志前崩溃。这是使用此镜像时导致疑难故障的首要原因。
SM_VLLM_TRUST_REMOTE_CODE	是否允许模型构件执行自定义 Python 代码	默认值为 false。 只有在特定架构无法在不使用其仓库代码的情况下加载时，才应在审核并固定这些构件后设置为 true。启用此选项会允许运行模型提供的代码。
HUGGING_FACE_HUB_TOKEN	HF 令牌	访问受限模型时必需。

将生产模型构件存放在由账户控制的 S3 存储桶中，将其 URI 作为 --model-s3-uri 传入，并使用 SM_VLLM_MODEL=/opt/ml/model。这样可以避免在运行时下载或执行仓库代码。只有在明确需要运行时访问 Hub 时才使用 Hub 模型 ID；除非该架构需要经过审核的自定义代码，否则请保持 SM_VLLM_TRUST_REMOTE_CODE=false。

调优（可选）

环境变量	用途
SM_VLLM_MAX_MODEL_LEN	最大序列长度——请设置此值；微调模型的默认值可能不正确
SM_VLLM_GPU_MEMORY_UTILIZATION	浮点数，范围为 0.0–1.0，约 0.9 较为合理
SM_VLLM_TENSOR_PARALLEL_SIZE	多 GPU 实例的 GPU 数量
SM_VLLM_DTYPE	auto、bfloat16、float16

任何 vLLM CLI 标志都适用——将其转为大写，用下划线替换连字符，并添加前缀 SM_VLLM_。

配置 TEI

环境变量配置约定比 vLLM 简单：

环境变量	用途	必需
HF_MODEL_ID	HF 模型 ID（例如 BAAI/bge-large-en-v1.5），或 /opt/ml/model	是
HF_TOKEN	HF 身份验证令牌	仅访问受限模型时需要
MAX_BATCH_TOKENS	每个批次的最大令牌数（默认值为 16384）	否
MAX_CLIENT_BATCH_SIZE	每个客户端批次的最大请求数（默认值为 32）	否

无需配置主机绑定，也无需设置 trust-remote-code 标志。TEI 支持的架构（BERT、CamemBERT、RoBERTa、XLM-RoBERTa、NomicBert、JinaBert、JinaCodeBert、Mistral、Qwen2/3、Gemma2/3、ModernBert）均已内置于镜像中。

CUDA / 实例兼容性

至关重要，也很容易弄错：

镜像标签中的 CUDA	默认 AMI	使用 al2-ami-sagemaker-inference-gpu-3-1
cu124 / cu128	g5、g6、p5 均可用	（不需要）
cu129	g6、p5 可用；g5 会失败（驱动不匹配 → CannotStartContainerError）	预计可修复 g5（未经验证）
cu130+	所有实例均会失败——必须使用 AMI 标志	g5、g6、p5 均可用（已于 2026 年 6 月验证 cu130 可在 g5 上运行）

驱动来自主机 AMI，而非实例系列，因此传入 gpu-3-1 AMI（无论如何，vLLM cu130 镜像都需要它）也能让 ml.g5.* 兼容 cu129+ 镜像。

VPC / NAT 网关问题

位于没有 NAT 网关的 VPC 中的 SageMaker 端点无法从 public.ecr.aws 拉取镜像。部署会因镜像拉取错误而失败，且错误信息不会提到“VPC”或“出站流量”。

对于位于 AWS 区域 ECR 上的镜像（目录中的所有镜像）：SageMaker 可通过内置路由访问，无需 NAT。请使用区域 URI 格式（<account>.dkr.ecr.<region>.amazonaws.com/...），不要使用 public.ecr.aws/... 格式。

对于需要访问 public.ecr.aws 的镜像（较少见）：使用 scripts/mirror_image.py 将镜像复制到你账户中的私有 ECR 仓库（支持跨平台；需要 Docker 和 aws CLI）。请在 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

目录页面无法显示、内容过时或有误时

页面无法显示 / 获取到的内容无效：目录页面大量依赖 JavaScript，一些获取工具会拿到空壳。可按以下顺序尝试备用方案：

1. 目录在 GitHub 上的源数据 — 页面由每个版本对应的一个 YAML 文件生成，其中列出了精确的标签、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，获取目标区域中的当前标签（适用于拥有 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. DLC GitHub 仓库上的发行说明。

某个标签刚刚发布，页面上还没有显示：这种情况很少见；AWS 会在每次发布时更新页面。请查看上面的发行说明。

所需架构尚未得到列出镜像的支持：具体来说，对于 TEI，你可以将 GHCR 上的上游镜像（ghcr.io/huggingface/text-embeddings-inference:<version>）复制到私有 ECR，然后将生成的 URI 直接传给 deploy.py --image-uri。使用同一个 mirror_image.py 脚本。

已知有问题的镜像（上次检查时间：2026 年 7 月）

镜像	缺陷	替代方案
huggingface-pytorch-inference GPU 标签 — 已测试所有近期版本（PT 2.3–2.6、cu121/cu124、transformers 4.48–5.5.3）	在 import torch 时出现 ImportError: libtorch_cuda.so: undefined symbol: ncclCommResume。镜像中捆绑的 NCCL 版本早于 torch 链接所用版本——这是容器内部的打包缺陷，在 g5 和 g6 上均存在，与 AMI、模型或推理代码无关。MMS Java 前端仍会响应 /ping，因此端点可能进入 InService，但 Python 工作进程会不断崩溃重启，无法提供服务。	DJL Inference（捆绑了完整的 CUDA/NCCL 技术栈）或 BYOC。CPU 标签不受影响。

AWS 发布新的 huggingface-pytorch-inference GPU 标签后，请重新检查——确认镜像已修复后移除此行。

通用备用方案：如果 HF DLC 因 CUDA/NCCL 链接器错误而失败，请改用 DJL Inference，而不是逐个尝试同系列标签——这类缺陷存在于仓库级别，而非标签级别（上述案例尝试了三个不同标签，均有问题）。

相关的 HF Hub 注意事项：较旧的 DLC 可能因 HF 的 XET CDN 返回 403 Forbidden 而无法下载模型（它们捆绑的 huggingface_hub 版本早于 XET 身份验证机制）。设置 HF_HUB_ENABLE_HF_TRANSFER=0 以强制使用标准下载路径，或预先将权重存放在 S3 中。

首次启动时的 Hub 下载时间

从 HF Hub 加载模型是在端点启动后、容器内进行的——即使是小型模型，也要预计 5–15+ 分钟才能进入 InService；多 GB 的模型则需要更长时间。首次启动较慢并不代表失败；在部署脚本的 30 分钟等待时间结束前，不要拆除部署或重新诊断。

对于生产环境或重复部署，请将模型权重预先存储到 S3，并向 deploy.py 传入 --model-s3-uri（模型随后会从 /opt/ml/model 加载）——这样速度更快、不受 Hub 速率限制或服务中断影响，而且运行时无需 HUGGING_FACE_HUB_TOKEN。