用编码智能体在 Amazon SageMaker AI 上部署 Hugging Face 模型

#用编码智能体在 Amazon SageMaker AI 上部署 Hugging Face 模型

把 Hugging Face 模型部署到生产环境，意味着要做十几项决定：为模型架构选择合适的服务容器，确认当前 AWS 区域（Region）的镜像标签，再按模型的内存占用匹配实例类型。基础设施之外，还必须接上自动扩缩（autoscaling），避免空闲端点白白消耗 GPU 小时。还要设置 Amazon CloudWatch 告警，在用户发现之前抓住无声失败。这些决定做完之后，Amazon SageMaker AI 能把这项工作压缩到几小时内完成。

这类结构化、可重复的工作，正是编码智能体（coding agent）要做的事，例如 Kiro 和 Claude Code。人们很容易在编码智能体里描述要部署的模型，然后走开，回来就看到一个能用的端点。实际中，没有引导的编码智能体可能做出错误决定，得到脆弱、昂贵或静默出错的端点。较新的模型问题更严重，因为它们的训练数据可能没有包含最新的部署知识。

在本文中，你将学习如何用智能体技能（agent skill）在 SageMaker AI 上部署可用于生产的 Hugging Face 模型。你从 Hugging Face Skills 安装六项技能，让编码智能体指向一个 Hugging Face 模型，并得到一个实时端点：带有自动扩缩、Amazon CloudWatch 告警、来自 AWS Deep Learning Containers (DLC) 目录的正确服务容器，以及一条经过核验的拆除路径。实时端点是默认选项，这些技能也支持可缩放到零的实时推理、无服务器推理、异步推理、批量转换，以及 Amazon Bedrock Custom Model Import。这些技能是开源的，只使用 Python 和 AWS Command Line Interface (AWS CLI)，在 macOS、Linux 和 Windows 上无需改动即可使用。

没有引导的编码智能体问题在哪

要看清这些技能实际挡住了什么，可以观察一个有能力的智能体在没有技能时会做什么。我们对同一请求测试了 Kiro（使用 Auto 或 Claude Fable 5）和 Claude Code（使用 Opus 4.8）：

deploy the small [Qwen/Qwen3-0.6B] (https://huggingface.co/Qwen/Qwen3-0.6B) model to a real-time endpoint, write the plan to a file first, and keep a log of every action.

两个编码智能体最初都选择 Text Generation Inference (TGI) 作为部署用的服务容器。考虑到 TGI 多年来一直是默认选择，而且模型训练数据里充满指向它的教程，这个选择可以理解。但该区域里可用的 TGI 构建早于 Qwen3 的架构，无法加载模型。端点健康检查失败。智能体提高了 TGI 版本，重新部署，再次失败，然后转向 vLLM。结果是多次部署失败，每一次在启动后崩溃时都会计费 GPU 时间。

第二个请求失败得更安静。我们让同一个智能体部署一个多模态混合专家（mixture-of-experts, MoE）扩散模型，该模型在测试前几周才发布。编码智能体确认它存在，然后再次写了一个基于 TGI 的脚本。TGI 是文本生成服务器，没有面向离散扩散图文模型的后端。没有任何响亮的失败。你只有在端点拒绝启动时才会发现。

两次运行的根因相同：缺少部署事实，而不是推理失败。智能体的计划和调试都做得好。它缺少的是当前的、具体的知识。较新的 Qwen 模型需要 vLLM。Python 3.13 对机器学习（machine learning, ML）技术栈的很大一部分没有可用的 wheel。容器镜像应从已发布的 AWS Deep Learning Containers 目录解析。这类知识比模型权重更新得更快。因此我们把它做成可编辑的技能文件，而不是指望模型的最新版本自己吸收这些知识。

表 1 比较了没有引导的智能体所做的模型部署，以及安装技能之后的智能体。

表 1：同一请求，分别由未安装技能和已安装技能的智能体运行

本文其余部分说明，我们如何用智能体技能在 SageMaker AI 端点上部署 Hugging Face 模型（即表 1 右侧一列）。

在 SageMaker AI 上部署 Hugging Face 模型的智能体技能

Hugging Face Skills GitHub 仓库中的六项技能覆盖端到端部署工作流。规划技能编排另外五项，如下图所示。

hf-cloud-sagemaker-deployment-planner (orchestrate, ask only what's needed)
│
├── hf-cloud-aws-context-discovery (discover local AWS context)
├── hf-cloud-python-env-setup (set up an isolated Python environment)
├── hf-cloud-sagemaker-iam-preflight (verify a usable execution role)
├── hf-cloud-serving-image-selection (select the right container family and image URI)
└── hf-cloud-sagemaker-production-defaults (deploy with autoscaling, alarms, and tags)

一个智能体技能示例

智能体技能（agent skill） 是一种开放标准包，由一个文件夹和必需的 SKILL.md 文件组成。该文件至少包含元数据（名称和描述）以及告诉智能体如何执行特定任务的指令。技能通过渐进式披露加载。当当前任务与技能描述匹配时，智能体按需读取该技能。下面是 hf-cloud-serving-image-selection 技能的删节版本。

---
name: hf-cloud-serving-image-selection
description: Pick the right serving container for a SageMaker model deployment and find its current image URI. Use this skill whenever about to deploy a model to a SageMaker endpoint and an image URI needs to be chosen --- including when the user says "deploy this LLM", "host this HuggingFace model", "serve this fine-tuned model", "deploy this embedding model", "host a reranker", "serve a sentence-transformers model", or when about to hardcode any container URI in deployment code. HuggingFace-curated Deep Learning Containers are ALWAYS preferred: HuggingFace vLLM (LLMs and generative rerankers), HuggingFace vLLM-Omni (multimodal), TEI (embeddings/cross-encoder rerankers), HF Inference Toolkit (other transformers). Generic images (AWS vLLM, DJL-LMI, SGLang) are used only when no HuggingFace image is compatible --- never merely because they carry a newer version. Never hardcode a container URI from memory and never default to TGI. Prevents stale-image failures and wrong-region URIs
---
Serving Image Selection
The serving container is the single thing most likely to break a deployment
that "looked correct on paper". Wrong container, stale tag, or wrong AMI all
produce the same opaque `Failed to pass health check` error.

端到端模型部署阶段

这些技能驱动五项 AWS 服务。Amazon SageMaker AI 托管端点，AWS Identity and Access Management (IAM) 提供执行角色。Amazon Elastic Container Registry (Amazon ECR) 和 AWS Deep Learning Containers 提供服务镜像，Amazon CloudWatch 支撑告警。技能中的全部辅助脚本通过 Boto3 和 AWS Command Line Interface (AWS CLI) 调用这些服务，从而保留对所创建内容的完整控制。SageMaker Python SDK 也可以用，但这些技能默认使用 Boto3。

部署分为六个阶段：

1. 用只读调用发现 AWS 上下文（配置文件、区域、账户和调用方身份）。

2. 搭建隔离的 Python 环境，使用受支持的 Python 版本和当前的 boto3。

3. 查找已有的 SageMaker AI 执行角色；仅当不存在且你有权限时才创建。

4. 选择服务容器系列，并从 AWS DLC 目录解析当前镜像 URI。

5. 创建模型、端点配置和端点，然后挂上自动扩缩和 Amazon CloudWatch 告警。

6. 对已上线的端点运行冒烟测试并报告结果。

前提条件

要跟着做，你需要：

• 一个 AWS 账户，具备使用 Amazon SageMaker AI 的权限，包括一个已有的 SageMaker AI 执行角色。技能可以自动找到一个；如果不存在且你的凭证允许，也可以创建一个。

• AWS CLI v2，并已为该账户配置凭证。

• Python 3.10、3.11 或 3.12。不支持 Python 3.13 或更高版本，因为 ML 技术栈的很大一部分尚未为这些版本发布 wheel。

• 一个支持技能的 编码智能体。本文使用 Kiro IDE。

• Git，用于克隆技能仓库。

本文将 Qwen/Qwen3-0.6B 部署到 US East (N. Virginia) Region (us-east-1) 中的单个 ml.g5.xlarge 实时推理实例。开始之前，确认你的账户对该实例类型有可用配额。

请注意，实时端点无论是否有流量都会持续计费，因此做完后删除端点，或按本文末尾的拆除步骤操作。

安装技能

Kiro 支持两种技能范围：工作区和全局。工作区技能位于项目下的 .kiro/skills/，只用于该项目的工作流。全局技能位于 ~/.kiro/skills/，可在所有工作区使用。

要在当前工作区安装来自 Hugging Face Skills GitHub 仓库的六项技能，在 Kiro 默认智能体聊天会话中输入以下请求：

Install six agent skills from the huggingface/skills repo, pinned to commit
f3186efbbc322121eb5d0f31e8a1d669ee961159, into this workspace.
Source: https://github.com/huggingface/skills.git
Commit: f3186efbbc322121eb5d0f31e8a1d669ee961159
Skills live under the repo's skills/ directory:
- hf-cloud-sagemaker-deployment-planner
- hf-cloud-aws-context-discovery
- hf-cloud-python-env-setup
- hf-cloud-sagemaker-iam-preflight
- hf-cloud-serving-image-selection
- hf-cloud-sagemaker-production-defaults

Kiro 会汇总已安装的文件，如图 1 所示。请注意，本文测试并使用的仓库固定在特定 SHA：f3186efbbc322121eb5d0f31e8a1d669ee961159。

图 1：Kiro 完成六项智能体技能的安装

要确认六个技能目录都在，在 Kiro 聊天会话中输入 /，以斜杠命令查看可用技能，如图 2 所示。

图 2：输入 / 以在 Kiro 聊天会话中查看可用技能

用 Kiro 部署模型

技能安装之后，你用自然语言向智能体描述模型，规划技能随即接管。你不必指定使用哪个容器系列、如何找到执行角色，或要附加哪些生产默认项，因为这些决定写在技能里。

在 Kiro 聊天会话中输入以下请求：

I need to deploy a model on AWS SageMaker, and I don't want to deal with all the console selecting and boto3 myself. The model is Qwen3 0.6B, pinned to commit `c1899de289a04d12100db370d81485cdf75e47ca`, called from an internal app. Figure out the best way to deploy it and walk me through it. Write the plan to a file first, and keep a log of every action you take.

要部署模型，完成以下步骤：

审阅计划。 智能体把部署计划写入文件，并在创建任何可计费资源之前等待你批准。

AWS 上下文发现与容器选择。 智能体发现 AWS 上下文（配置文件、区域、账户）。hf-cloud-serving-image-selection 技能为 Qwen3 选择 vLLM，并从 AWS DLC 目录解析镜像 URI。

批准部署，在智能体询问时进行。hf-cloud-sagemaker-production-defaults 技能把模型、端点配置和端点作为一个单元创建，然后挂上自动扩缩和 CloudWatch 告警。

核验。 端点达到 InService 之后，查看智能体报告的冒烟测试结果。

下面几行来自智能体在本次运行中保留的部署日志：

## Step 5: Serving Image Selection
| Value | Resolved to |
| Image URI | `763104351884.dkr.ecr.us-east-1.amazonaws.com/huggingface-vllm:0.28.0-transformers5.15.0-gpu-py312-cu130-ubuntu24.04` |
| InferenceAmiVersion | `al2-ami-sagemaker-inference-gpu-3-1` |
| `SM_VLLM_MODEL` | `Qwen/Qwen3-0.6B` |
| `SM_VLLM_HOST` | `0.0.0.0` (else vLLM binds localhost, ping fails, container dies) |
| `SM_VLLM_TRUST_REMOTE_CODE` | `false` |
| `SM_VLLM_MAX_MODEL_LEN` | `8192` |

对于受限模型，增加一个 HUGGING_FACE_HUB_TOKEN 环境变量。

解析执行角色

在企业账户上调用 iam:CreateRole 失败时，部署常常停在执行角色这一步。这类账户的 AWS IAM Identity Center 会话没有 IAM 写权限。hf-cloud-sagemaker-iam-preflight 技能把顺序反过来：先查找，只在最后才创建。

它的 check_role.py 脚本在账户中搜索匹配 AmazonSageMaker-ExecutionRole-* 和 *SageMaker*Execution* 等模式的已有角色，并按最近使用日期排序。它还会校验信任策略并返回 Amazon Resource Name (ARN)。仅当不存在任何角色且调用方拥有 iam:CreateRole 权限时，它才创建角色。请注意，创建出的角色带有 AmazonSageMakerFullAccess。我们建议按最小权限原则更新该角色，只授予它需要的权限。

应用生产默认项

hf-cloud-sagemaker-production-defaults 技能把端点从演示变成生产部署。它对每个端点应用表 2 中的默认项，建立运维基线。生产部署还需要加入用户特定配置，例如 Amazon Virtual Private Cloud 和 AWS Key Management Service 配置。

表 2：技能应用到每个端点的生产默认项

编码智能体自行做出的决定

智能体技能定义工作流，但编码智能体仍会在其中做判断。有一次，智能体向 Amazon ECR 查询最新镜像标签时，调用被拒绝，因为 IAM Identity Center 角色缺少 ecr-public:DescribeImages 权限。智能体没有让部署失败，而是回退到技能自带的已知可用标签，并把原因记入日志。另一次，冒烟测试返回 HTTP 200 之后，智能体注意到实际答案从未输出。这是因为模型回复在仍处于 Qwen3 推理块内部时，于 max_tokens 处被截断。智能体在日志中把这标为配置问题：调用方应用应提高 token 上限，而不是把这次测试当成通过。

清理

实时端点在其存续期间按实例持续计费。删除你创建的资源，以避免持续费用。sagemaker-production-defaults 技能包含 teardown.py 脚本，它会移除部署资源，然后确认这些资源已经消失。

要清理，完成以下步骤：

1. 让智能体拆除部署，或直接用端点名称和区域运行 teardown.py。

2. 确认脚本报告端点、端点配置和模型已删除。脚本会核验删除结果。

3. 检查自动扩缩策略和 CloudWatch 告警已被移除。删除任何仍然存在的项。

结论

六项可复用的智能体技能，把没有引导的编码智能体变成能够在 SageMaker AI 端点上部署 Hugging Face 模型、并带上生产所需能力的智能体。每次部署都包含正确的容器、自动扩缩、CloudWatch 告警，以及一条经过核验的拆除路径。没有这些技能时，智能体会去用过时容器，跳过生产防护，并留下误导性文档。本文逐一走过每项技能：AWS 上下文发现、Python 环境搭建、IAM 角色解析、从 AWS DLC 目录选择容器，以及带生产默认项的部署。

要开始，从 Hugging Face Skills GitHub 仓库安装技能，并部署你的第一个模型。这些技能是开源的，欢迎贡献。

团队也可以使用 Amazon SageMaker JumpStart，直接从控制台部署一组常用的 Hugging Face 模型，并使用 Inference Recommendations 自动做基准测试，为工作负载选择最优实例类型。

PRIMARY_SOURCE: https://aws.amazon.com/blogs/machine-learning/deploy-hugging-face-models-on-amazon-sagemaker-ai-with-coding-agents