在 SageMaker 上部署 HuggingFace…

部署模型到 SageMaker 端点、需要挑选服务容器镜像 URI 时，按模型类型选对镜像家族并从 AWS 官方目录读取当前 URI，避免健康检查失败和区域错误。

适用场景

解决思路

1. 规则零：当 HuggingFace 官方镜像家族（huggingface-vllm、huggingface-vllm-omni、huggingface-sglang、tei、huggingface-pytorch-inference）与通用家族（vllm、vllm-omni、sglang、djl-inference）都能服务该模型时，必须选 HuggingFace 镜像，而非优先选它。
2. 仅以下三种情况才可使用通用镜像：1) 已验证不兼容——模型需要的架构/模态/特性没有任何 HuggingFace 标签支持，且已对照目录确认（不是假设）；2) 目标区域没有 HuggingFace 标签且无法镜像；3) HuggingFace 镜像出现在下方“已知损坏镜像”列表中。
3. 通用仓库版本号更新不是选用它的理由：AWS vllm 仓库常发布比 huggingface-vllm 更高的 vLLM 版本，但兼容的旧 huggingface-vllm 标签仍然胜出。若回退到通用镜像，在部署日志中记录属于上述三种原因中的哪一种。
4. 镜像 URI 的主要来源是 AWS 官方 Deep Learning Containers 目录：https://aws.github.io/deep-learning-containers/reference/available_images/ 。挑选 URI 时直接读取该页面，复制示例 URL，把 <region> 替换为用户所在区域，再传给 deploy.py --image-uri。
5. 示例 URL 中大多数区域使用账号 ID 763104351884，少数区域使用不同账号（如 eu-south-1 使用 692866216735）。有疑问时查阅 Region Availability 页面 https://aws.github.io/deep-learning-containers/reference/region_availability/ 。
6. 按模型类型选镜像家族：HuggingFace 文本生成 LLM（Llama、Qwen、Mistral 等）→ HuggingFace vLLM（ECR 仓库 huggingface-vllm）；多模态 → HuggingFace vLLM-Omni（huggingface-vllm-omni）；HuggingFace 嵌入 → TEI；编码器/交叉编码器重排器（BERT 系 *ForSequenceClassification）→ TEI；生成式重排器（因果 LM，如 Qwen3-Reranker）→ HuggingFace vLLM（不是 TEI）；文生图/扩散（Stable Diffusion、FLUX）→ DJL Inference（不是 HF Inference Toolkit）；HuggingFace 分类器、NER、QA、摘要 → HF Inference Toolkit（CPU）；用户明确要 SGLang → HuggingFace SGLang；无兼容 huggingface-vllm 标签 → vLLM (AWS) 仅作回退；用户明确要 DJL-LMI → DJL Inference；Amazon Nova → SageMaker JumpStart；自定义推理代码 → BYOC（用户提供 URI）。
7. 不要使用 TGI：Text Generation Inference 已归档，归档后发布的模型（最著名的是 Qwen3）在 TGI 上无法通过 ping 健康检查，改用 vLLM。
8. 区分两类重排器：编码器交叉编码器（BAAI/bge-reranker-*、mixedbread、多数 sentence-transformers 重排器）config.json 中 architectures 为 [..ForSequenceClassification] 且基于 TEI 支持的编码器类型 → 用 TEI；生成式重排器（Qwen/Qwen3-Reranker-* 及类似因果 LM 评判器）config.json 中 architectures 为 [..ForCausalLM] → 用 HuggingFace vLLM，像文本生成 LLM 一样部署。TEI 会加载架构后拒绝 classifier 模型类型（TEI 对 Qwen3 的支持仅限 embeddings）。
9. 创建任何资源前先做预检，一次 HTTP GET 即可判定：curl -s https://huggingface.co/<model-id>/raw/main/config.json ，若 architectures 为 ["Qwen3ForCausalLM"] 则用 vLLM，若为 ["XLMRobertaForSequenceClassification"] 则用 TEI。对 TEI 还要确认 (architecture, task) 组合：架构出现在 TEI 支持列表中只代表支持 embeddings，不一定支持分类/重排。
10. 注意 SageMaker SDK v3（PR #5960）会把 text-ranking 任务无条件路由到 TEI——对交叉编码器正确，对生成式重排器错误，不要把 SDK 的路由当作 TEI 能服务某重排器的证据。
11. 每个家族都从 AWS 目录页面读取 URI：1) 打开 https://aws.github.io/deep-learning-containers/reference/available_images/ ；2) 找到正确家族的章节；3) 选该家族内平台列为 SageMaker 的最新一行，不要因为别的家族列出更高引擎版本就切换家族；4) 把 <region> 替换为用户区域（来自 hf-cloud-aws-context-discovery）；5) 对 vLLM 还要检查 AMI 要求；6) 把 URI 传给 deploy.py --image-uri（实时）或 deploy_async.py --image-uri（异步）。
12. 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 实例上无法启动。
13. TEI 账号 ID 注意：目录页示例账号为 683313688378，但 TEI 发布在与主 AWS DLC 不同的账号命名空间，各区域账号 ID 不同。若 683313688378.dkr.ecr.<region>.amazonaws.com/tei:... 在非 us-east-1 区域返回 ECR 拉取错误，查阅 Region Availability 页面获取该区域正确账号 ID。
14. vLLM AMI 要求：CUDA 13 或更高（当前默认 cu130）的 vLLM DLC 镜像需要在 ProductionVariant 上设置 InferenceAmiVersion=al2-ami-sagemaker-inference-gpu-3-1。这同样适用于 huggingface-vllm、huggingface-vllm-omni（基于同一 cu130 基础层）和 AWS vllm 仓库。不设置则容器启动即死且不会创建任何 CloudWatch 日志。
15. AMI 查找表：标签含 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 覆盖。
16. 配置 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 加载是例外。
17. 每个 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 token，门控模型必需）。
18. 生产环境应把模型工件暂存到账号可控的 S3 桶，把其 URI 作为 --model-s3-uri 传入，并使用 SM_VLLM_MODEL=/opt/ml/model。这避免运行时下载或执行仓库代码。仅在明确需要运行时 Hub 访问时才用 Hub 模型 ID；除非该架构需要经审查的自定义代码，否则保持 SM_VLLM_TRUST_REMOTE_CODE=false。
19. vLLM 可选调优环境变量：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_。
20. 配置 TEI（比 vLLM 更简单的环境变量契约）：HF_MODEL_ID（HF 模型 ID 如 BAAI/bge-large-en-v1.5，或 /opt/ml/model）必需；HF_TOKEN 仅门控模型需要；MAX_BATCH_TOKENS（每批最大 token 数，默认 16384）可选；MAX_CLIENT_BATCH_SIZE（每客户端批最大请求数，默认 32）可选。无需配置主机绑定，无 trust-remote-code 标志。TEI 支持的架构（BERT、CamemBERT、RoBERTa、XLM-RoBERTa、NomicBert、JinaBert、JinaCodeBert、Mistral、Qwen2/3、Gemma2/3、ModernBert）已烘焙进镜像。
21. CUDA/实例兼容性：cu124/cu128 镜像在 g5、g6、p5 上均可用；cu129 在 g6、p5 可用，g5 失败（驱动不匹配 → CannotStartContainerError），加 al2-ami-sagemaker-inference-gpu-3-1 预期可修复 g5（未验证）；cu130+ 在所有实例上失败，AMI 标志是强制的，加标志后 g5、g6、p5 均可用（cu130-on-g5 已于 2026 年 6 月验证）。驱动来自宿主 AMI 而非实例家族，所以传 gpu-3-1 AMI（vLLM cu130 镜像本就要求）也能让 ml.g5.* 适用于 cu129+ 镜像。
22. VPC/NAT 网关问题：没有 NAT 网关的 VPC 内 SageMaker 端点无法从 public.ecr.aws 拉取，部署失败并报不提及 VPC 或 egress 的镜像拉取错误。对于 AWS 区域 ECR 上的镜像（目录中所有镜像），SageMaker 通过内置路由访问，无需 NAT，使用区域 URI 模式（<account>.dkr.ecr.<region>.amazonaws.com/...）而非 public.ecr.aws/... 模式。
23. 对于需要 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：$PRIVATE_URI = python scripts\mirror_image.py public.ecr.aws/deep-learning-containers/vllm:<tag> vllm-mirror。
24. 当目录页面无法渲染或返回垃圾内容时（该页 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 仓库的发布说明 https://github.com/aws/deep-learning-containers/releases 。
25. 若某标签刚发布尚未出现在页面上（罕见，AWS 每次发布都会更新页面），查阅上述发布说明。
26. 若所列镜像尚不支持你需要的架构：对 TEI 可专门把上游镜像从 GHCR（ghcr.io/huggingface/text-embeddings-inference:<version>）镜像到私有 ECR，把结果 URI 直接传给 deploy.py --image-uri，同样用 mirror_image.py 脚本。
27. 已知损坏镜像（最后检查于 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 worker 崩溃循环、什么都不服务。改用 DJL Inference（自带完整 CUDA/NCCL 栈）或 BYOC。CPU 标签不受影响。AWS 发布新的 huggingface-pytorch-inference GPU 标签时重新检查，确认修复后删除该行。
28. 通用回退规则：当 HF DLC 出现 CUDA/NCCL 链接错误时，改用 DJL Inference，而不是在同仓库的兄弟标签间反复尝试——该缺陷类别是按仓库而非按标签的（上述案例试了三个不同标签，全部损坏）。
29. 相关 HF Hub 陷阱：较旧的 DLC 可能因 HF 的 XET CDN 返回 403 Forbidden 而下载模型失败（其捆绑的 huggingface_hub 早于 XET 认证）。设置 HF_HUB_ENABLE_HF_TRANSFER=0 强制走标准下载路径，或把权重预置到 S3。
30. 首次启动从 Hub 下载的时间：从 HF Hub 加载模型发生在端点启动后的容器内部——即使小模型也预期 5–15+ 分钟才 InService，多 GB 模型更久。首次启动慢不是失败，不要在部署脚本 30 分钟等待到期前就拆除或重新诊断。
31. 生产或重复部署时，把权重预置到 S3 并给 deploy.py 传 --model-s3-uri（模型随后从 /opt/ml/model 加载）——更快、不受 Hub 速率限制/中断影响，且运行时无需 HUGGING_FACE_HUB_TOKEN。

适用边界 · 注意事项

• 不要凭记忆硬编码容器 URI，也不要默认使用 TGI。
• 不要仅因为通用镜像仓库版本号更新就选用它，也不要因为别的镜像家族列出更高引擎版本就切换家族。
• 不要在没有 NAT 网关的 VPC 中使用 public.ecr.aws 模式的 URI（区域 ECR 镜像无需 NAT）。