用途:在确定 SageMaker 部署路径之后、创建资源之前,选择并校验某个区域下正确的服务容器镜像(URI),避免因镜像错误、标签过期或 AMI 不匹配导致的部署失败。
主要能力:
- 镜像家族决策表:文本生成 LLM 用 HuggingFace vLLM(多模态用 vLLM-Omni);嵌入与编码器/交叉编码器重排用 TEI;生成式重排(如 Qwen3-Reranker)用 HuggingFace vLLM;文生图/扩散用 DJL Inference;分类/NER/QA/摘要用 HF Inference Toolkit(CPU);用户指定 SGLang 或 DJL-LMI 时按对应家族;Amazon Nova 用 SageMaker JumpStart;自定义推理用 BYOC。
- 硬规则:当 HuggingFace 镜像与通用镜像(vllm、sglang、djl-inference 等)都能服务该模型时,必须优先 HuggingFace 镜像;仅三种情况可回退——已验证不兼容、目标区域无 HF 标签且无法镜像、该 HF 镜像在“已知损坏”清单中。通用仓库版本号更新不构成回退理由。
- URI 获取:以 AWS 官方 Deep Learning Containers 目录页 https://aws.github.io/deep-learning-containers/reference/available_images/ 为准,复制示例 URL 并把 <region> 替换为用户区域,再传给 deploy.py --image-uri(实时)或 deploy_async.py --image-uri(异步)。多数区域账号 ID 为 763104351884,个别区域不同(如 eu-south-1 为 692866216735)。
- 关键兼容处理:vLLM 标签含 cu130 或更高时,必须传 InferenceAmiVersion=al2-ami-sagemaker-inference-gpu-3-1(对应 deploy.py --inference-ami-version),否则容器启动即失败且无 CloudWatch 日志;cu129 或更低可省略。
- 重排模型预检:curl -s https://huggingface.co/<model-id>/raw/main/config.json,architectures 为 *ForCausalLM 走 vLLM,为 *ForSequenceClassification 走 TEI;TEI 还需确认(架构, 任务)组合受支持。
必要用法:vLLM 镜像需设 SM_VLLM_MODEL、SM_VLLM_HOST=0.0.0.0(否则只绑定 localhost 导致 ping 失败)、SM_VLLM_TRUST_REMOTE_CODE=true,门控模型需 HUGGING_FACE_HUB_TOKEN;可选调优变量如 SM_VLLM_MAX_MODEL_LEN、SM_VLLM_GPU_MEMORY_UTILIZATION、SM_VLLM_TENSOR_PARALLEL_SIZE、SM_VLLM_DTYPE,任意 vLLM CLI 参数可大写加 SM_VLLM_ 前缀。TEI 需 HF_MODEL_ID,门控模型需 HF_TOKEN,可选 MAX_BATCH_TOKENS、MAX_CLIENT_BATCH_SIZE。TEI 按实例选变体:ml.g*/p*/inf* 用 GPU 变体,ml.c*/m*/t* 用 CPU 变体。VPC 无 NAT 时用区域 ECR URI;需 public.ecr.aws 时用 scripts/mirror_image.py 镜像到私有 ECR。目录页无法渲染时,可退回到 GitHub YAML 数据或 aws ecr describe-images 查询。
已知限制与缺陷:huggingface-pytorch-inference GPU 标签存在 libtorch_cuda.so NCCL 符号错误(MMS 前端仍返回 /ping,Python worker 崩溃循环),建议改用 DJL Inference 或 BYOC,CPU 标签不受影响。TGI 已归档,不要使用。旧镜像可能因 huggingface_hub 过旧触发 HF XET CDN 403,可设 HF_HUB_ENABLE_HF_TRANSFER=0 或在 S3 预置权重。首次从 Hub 下载模型可能需 5–15 分钟以上才 InService,部署脚本等待上限为 30 分钟。