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 镜像是强制的而不是可选项。Hugging Face 官方容器族通用Generic容器族huggingface-vllmvllmhuggingface-vllm-omnivllm-omnihuggingface-sglangsglangteidjl-inferencehuggingface-pytorch-inference—只有以下三种情况才允许回退到通用镜像经验证的架构不兼容——模型需要的架构/模态/特性在当前可用的 Hugging Face tag 中都不支持必须对照镜像目录确认不能靠猜测目标区域没有对应的 Hugging Face tag且无法通过镜像搬运mirror解决该 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 #59602026 年 6 月合并。AWS 的vllm镜像在此定位仅是兼容性逃生舱绝不能因为版本号更高而选它。不要用 TGI文档明确记录Text Generation InferenceTGI已归档archived归档后发布的模型最典型的是 Qwen3在 TGI 上会 ping 健康检查失败。因此新部署一律使用 vLLM 而非 TGI。SageMaker SDK v3 也佐证了这一方向v2 时代的get_huggingface_llm_image_uri助手返回 TGI URIv3 已完全移除该函数改为按任务自动路由——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 来源这是文档中最核心的速查表完整继承如下模型容器族URI 获取方式Hugging Face 文本生成 LLMLlama、Qwen、Mistral 等HuggingFace vLLMAWS 目录 → HuggingFace vLLM InferenceECR 仓库huggingface-vllm同上但为多模态HuggingFace vLLM-OmniAWS 目录 → HuggingFace vLLM-Omni InferenceECR 仓库huggingface-vllm-omniHugging Face EmbeddingsTEIAWS 目录 → HuggingFace Text Embeddings InferenceEncoder / cross-encoder 重排器BERT 系*ForSequenceClassificationTEI同 Embeddings生成式重排器因果 LM如 Qwen3-RerankerHuggingFace vLLM同文本生成 LLM——不是 TEI见下文重排器选型文生图 / 扩散模型Stable Diffusion、FLUXDJL InferenceAWS 目录 → DJL Inference——不是HF Inference Toolkit见已知损坏镜像Hugging Face 分类、NER、QA、摘要HF Inference ToolkitCPUAWS 目录 → HuggingFace PyTorch InferenceGPU tag 当前损坏——见已知损坏镜像用户明确要求 SGLangHuggingFace SGLangAWS 目录 → HuggingFace SGLang Inference无兼容huggingface-vllmtag经验证不兼容或区域缺失——见规则零vLLMAWSAWS 目录 → vLLM——仅作回退绝不因版本新而选用户明确要求 DJL-LMIDJL InferenceAWS 目录 → DJL InferenceAmazon NovaSageMaker JumpStart用 JumpStart不要走裸端点创建自定义推理代码BYOC用户提供 URI补充说明来自决策表全文Inferentia / Trainium 硬件应选NeuronX系列文本生成 LLM 的完整 URI 模式为763104351884.dkr.ecr.region.amazonaws.com/huggingface-vllm:version-transformerstv-gpu-pypy-cucuda-ubuntu22.04AWS vLLM 回退镜像的模式为763104351884.dkr.ecr.region.amazonaws.com/vllm:version-gpu-pypy-cucuda-ubuntu22.04-sagemaker二者均以目录页实际最新 tag 为准。重排器选型TEI 还是 vLLMReranker覆盖两种架构迥异的模型选错会白白浪费一整轮端点创建周期约 20 分钟才被 TEI 拒绝。文档给出了清晰的判别方法Encoder cross-encodersBAAI/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.jsoncurl -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 v3PR #5960把text-ranking任务无条件路由到 TEI——这对 cross-encoders 是对的对生成式重排器是错的。因此不要把 SDK 的路由行为当作TEI 能服务某个重排器的证据。生成式重排器的调用方式原始 completions API、max_tokens1、logprobs 打分记录在 hf-cloud-sagemaker-production-defaults 中。标准工作流从目录页到部署文档给出的五步工作流每个镜像族都适用打开 AWS Deep Learning Containers 镜像目录页available_images找到对应容器族的区块LLM 用 HuggingFace vLLM InferenceEmbeddings 用 HuggingFace Text Embeddings Inference 等挑选平台列为SageMaker的最新一行——最新指的是该容器族内部的最新不要因为别的容器族版本更高而跨族切换见规则零将region替换为用户区域来自 hf-cloud-aws-context-discoveryvLLM 镜像额外核对 AMI 要求见下节将 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 上设置InferenceAmiVersional2-ami-sagemaker-inference-gpu-3-1。该要求对huggingface-vllm、huggingface-vllm-omni基于同一 cu130 底座和 AWSvllm仓库一视同仁。不设置的话容器启动即死且永远不会创建 CloudWatch 日志——这个失败表象与账号级问题、配额、网络问题高度相似经常把排查引向错误方向。文档给出的查找表tag 包含需要传入的 InferenceAmiVersioncu130或更高al2-ami-sagemaker-inference-gpu-3-1cu129或更低省略该参数默认 AMI 即可经验法则选的 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 / 实例兼容性矩阵这是文档中容易搞错且关键的部分完整继承tag 中的 CUDA默认 AMI使用al2-ami-sagemaker-inference-gpu-3-1cu124 / cu128g5、g6、p5 均可不需要cu129g6、p5 可用g5 失败驱动不匹配 →CannotStartContainerError预计可修复 g5未验证cu130处处失败——AMI 参数强制g5、g6、p5 均可用cu130-on-g5 于 2026 年 6 月验证原理驱动来自宿主 AMI 而非实例族因此传入 gpu-3-1 AMIvLLM 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 KEYVALUE; repeatable与 _common.py 的parse_env实现。每个 Hugging Face LLM 部署的必填项环境变量作用备注SM_VLLM_MODELHF 模型 ID如Qwen/Qwen3-0.6B或从 S3 加载时的/opt/ml/model—SM_VLLM_HOST必须为0.0.0.0否则 vLLM 只绑定 localhostping 失败容器在产生日志前就死掉。该镜像神秘失败的头号原因。SM_VLLM_TRUST_REMOTE_CODEQwen 及多个近期架构设为true无条件设置——副作用可忽略收益是模型能加载。HUGGING_FACE_HUB_TOKENHF token门控模型gated必需。可选调优项环境变量作用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_DTYPEauto、bfloat16、float16通用规则任何 vLLM CLI 参数都可用——转大写、横线换下划线、加SM_VLLM_前缀。配置 TEITEI 的环境变量契约比 vLLM 简单得多环境变量作用是否必需HF_MODEL_IDHF 模型 ID如BAAI/bge-large-en-v1.5或/opt/ml/model是HF_TOKENHF 认证 token仅门控模型MAX_BATCH_TOKENS每批最大 token 数默认 16384否MAX_CLIENT_BATCH_SIZE每客户端批最大请求数默认 32否无需配置 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-1aws ecr get-login-password --region region登录私有仓库仓库创建时开启scanOnPushtrue。目录页无法渲染、过期或出错时的备选方案AWS 目录页是重 JavaScript 页面某些抓取工具只能拿到空壳。文档给出按序回退的三个方案目录页的源数据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……。直接查询 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查看 aws/deep-learning-containers 仓库的 Release notes。另有两个场景tag 刚发布还没上目录页罕见AWS 每次发布都会更新页面可查 release notes目标架构当前镜像不支持TEI 场景可通过镜像上游版本来规避如前文所述。已知损坏镜像huggingface-pytorch-inference GPU tag截至文档最后核对时间2026 年 7 月huggingface-pytorch-inference的 GPU tag 全部不可用测试过的近期 tagPT 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 栈或 BYOCCPU 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_TRANSFER0强制走标准下载路径或把权重预置到 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 匹配、环境变量契约、网络可达性与已知缺陷规避。记住几条关键动作LLM 一律先看huggingface-vllm多模态用huggingface-vllm-omniEmbeddings 与 encoder 重排用 TEI生成式重排回 vLLM扩散模型用 DJLURI 从 AWS DLC 目录页现读现用不要凭记忆硬编码不要跨容器族比版本号vLLM 的 cu130 tag 必须带--inference-ami-version al2-ami-sagemaker-inference-gpu-3-1同时确保SM_VLLM_HOST0.0.0.0与SM_VLLM_TRUST_REMOTE_CODEtrueVPC 无 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 SageMaker 镜像选择实战指南：基于 Hugging Face 生态为模型部署挑选正确的 Serving 容器
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 镜像是强制的而不是可选项。Hugging Face 官方容器族通用Generic容器族huggingface-vllmvllmhuggingface-vllm-omnivllm-omnihuggingface-sglangsglangteidjl-inferencehuggingface-pytorch-inference—只有以下三种情况才允许回退到通用镜像经验证的架构不兼容——模型需要的架构/模态/特性在当前可用的 Hugging Face tag 中都不支持必须对照镜像目录确认不能靠猜测目标区域没有对应的 Hugging Face tag且无法通过镜像搬运mirror解决该 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 #59602026 年 6 月合并。AWS 的vllm镜像在此定位仅是兼容性逃生舱绝不能因为版本号更高而选它。不要用 TGI文档明确记录Text Generation InferenceTGI已归档archived归档后发布的模型最典型的是 Qwen3在 TGI 上会 ping 健康检查失败。因此新部署一律使用 vLLM 而非 TGI。SageMaker SDK v3 也佐证了这一方向v2 时代的get_huggingface_llm_image_uri助手返回 TGI URIv3 已完全移除该函数改为按任务自动路由——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 来源这是文档中最核心的速查表完整继承如下模型容器族URI 获取方式Hugging Face 文本生成 LLMLlama、Qwen、Mistral 等HuggingFace vLLMAWS 目录 → HuggingFace vLLM InferenceECR 仓库huggingface-vllm同上但为多模态HuggingFace vLLM-OmniAWS 目录 → HuggingFace vLLM-Omni InferenceECR 仓库huggingface-vllm-omniHugging Face EmbeddingsTEIAWS 目录 → HuggingFace Text Embeddings InferenceEncoder / cross-encoder 重排器BERT 系*ForSequenceClassificationTEI同 Embeddings生成式重排器因果 LM如 Qwen3-RerankerHuggingFace vLLM同文本生成 LLM——不是 TEI见下文重排器选型文生图 / 扩散模型Stable Diffusion、FLUXDJL InferenceAWS 目录 → DJL Inference——不是HF Inference Toolkit见已知损坏镜像Hugging Face 分类、NER、QA、摘要HF Inference ToolkitCPUAWS 目录 → HuggingFace PyTorch InferenceGPU tag 当前损坏——见已知损坏镜像用户明确要求 SGLangHuggingFace SGLangAWS 目录 → HuggingFace SGLang Inference无兼容huggingface-vllmtag经验证不兼容或区域缺失——见规则零vLLMAWSAWS 目录 → vLLM——仅作回退绝不因版本新而选用户明确要求 DJL-LMIDJL InferenceAWS 目录 → DJL InferenceAmazon NovaSageMaker JumpStart用 JumpStart不要走裸端点创建自定义推理代码BYOC用户提供 URI补充说明来自决策表全文Inferentia / Trainium 硬件应选NeuronX系列文本生成 LLM 的完整 URI 模式为763104351884.dkr.ecr.region.amazonaws.com/huggingface-vllm:version-transformerstv-gpu-pypy-cucuda-ubuntu22.04AWS vLLM 回退镜像的模式为763104351884.dkr.ecr.region.amazonaws.com/vllm:version-gpu-pypy-cucuda-ubuntu22.04-sagemaker二者均以目录页实际最新 tag 为准。重排器选型TEI 还是 vLLMReranker覆盖两种架构迥异的模型选错会白白浪费一整轮端点创建周期约 20 分钟才被 TEI 拒绝。文档给出了清晰的判别方法Encoder cross-encodersBAAI/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.jsoncurl -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 v3PR #5960把text-ranking任务无条件路由到 TEI——这对 cross-encoders 是对的对生成式重排器是错的。因此不要把 SDK 的路由行为当作TEI 能服务某个重排器的证据。生成式重排器的调用方式原始 completions API、max_tokens1、logprobs 打分记录在 hf-cloud-sagemaker-production-defaults 中。标准工作流从目录页到部署文档给出的五步工作流每个镜像族都适用打开 AWS Deep Learning Containers 镜像目录页available_images找到对应容器族的区块LLM 用 HuggingFace vLLM InferenceEmbeddings 用 HuggingFace Text Embeddings Inference 等挑选平台列为SageMaker的最新一行——最新指的是该容器族内部的最新不要因为别的容器族版本更高而跨族切换见规则零将region替换为用户区域来自 hf-cloud-aws-context-discoveryvLLM 镜像额外核对 AMI 要求见下节将 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 上设置InferenceAmiVersional2-ami-sagemaker-inference-gpu-3-1。该要求对huggingface-vllm、huggingface-vllm-omni基于同一 cu130 底座和 AWSvllm仓库一视同仁。不设置的话容器启动即死且永远不会创建 CloudWatch 日志——这个失败表象与账号级问题、配额、网络问题高度相似经常把排查引向错误方向。文档给出的查找表tag 包含需要传入的 InferenceAmiVersioncu130或更高al2-ami-sagemaker-inference-gpu-3-1cu129或更低省略该参数默认 AMI 即可经验法则选的 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 / 实例兼容性矩阵这是文档中容易搞错且关键的部分完整继承tag 中的 CUDA默认 AMI使用al2-ami-sagemaker-inference-gpu-3-1cu124 / cu128g5、g6、p5 均可不需要cu129g6、p5 可用g5 失败驱动不匹配 →CannotStartContainerError预计可修复 g5未验证cu130处处失败——AMI 参数强制g5、g6、p5 均可用cu130-on-g5 于 2026 年 6 月验证原理驱动来自宿主 AMI 而非实例族因此传入 gpu-3-1 AMIvLLM 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 KEYVALUE; repeatable与 _common.py 的parse_env实现。每个 Hugging Face LLM 部署的必填项环境变量作用备注SM_VLLM_MODELHF 模型 ID如Qwen/Qwen3-0.6B或从 S3 加载时的/opt/ml/model—SM_VLLM_HOST必须为0.0.0.0否则 vLLM 只绑定 localhostping 失败容器在产生日志前就死掉。该镜像神秘失败的头号原因。SM_VLLM_TRUST_REMOTE_CODEQwen 及多个近期架构设为true无条件设置——副作用可忽略收益是模型能加载。HUGGING_FACE_HUB_TOKENHF token门控模型gated必需。可选调优项环境变量作用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_DTYPEauto、bfloat16、float16通用规则任何 vLLM CLI 参数都可用——转大写、横线换下划线、加SM_VLLM_前缀。配置 TEITEI 的环境变量契约比 vLLM 简单得多环境变量作用是否必需HF_MODEL_IDHF 模型 ID如BAAI/bge-large-en-v1.5或/opt/ml/model是HF_TOKENHF 认证 token仅门控模型MAX_BATCH_TOKENS每批最大 token 数默认 16384否MAX_CLIENT_BATCH_SIZE每客户端批最大请求数默认 32否无需配置 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-1aws ecr get-login-password --region region登录私有仓库仓库创建时开启scanOnPushtrue。目录页无法渲染、过期或出错时的备选方案AWS 目录页是重 JavaScript 页面某些抓取工具只能拿到空壳。文档给出按序回退的三个方案目录页的源数据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……。直接查询 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查看 aws/deep-learning-containers 仓库的 Release notes。另有两个场景tag 刚发布还没上目录页罕见AWS 每次发布都会更新页面可查 release notes目标架构当前镜像不支持TEI 场景可通过镜像上游版本来规避如前文所述。已知损坏镜像huggingface-pytorch-inference GPU tag截至文档最后核对时间2026 年 7 月huggingface-pytorch-inference的 GPU tag 全部不可用测试过的近期 tagPT 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 栈或 BYOCCPU 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_TRANSFER0强制走标准下载路径或把权重预置到 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 匹配、环境变量契约、网络可达性与已知缺陷规避。记住几条关键动作LLM 一律先看huggingface-vllm多模态用huggingface-vllm-omniEmbeddings 与 encoder 重排用 TEI生成式重排回 vLLM扩散模型用 DJLURI 从 AWS DLC 目录页现读现用不要凭记忆硬编码不要跨容器族比版本号vLLM 的 cu130 tag 必须带--inference-ami-version al2-ami-sagemaker-inference-gpu-3-1同时确保SM_VLLM_HOST0.0.0.0与SM_VLLM_TRUST_REMOTE_CODEtrueVPC 无 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考