使用编码智能体在 Amazon SageMaker AI 上部署 Hugging Face 模型
把一个 Hugging Face 模型部署到生产环境，意味着一连串决策：为模型的架构挑选合适的服务容器、确认当前 AWS 区域可用的镜像 tag、再根据模型的显存占用匹配实例类型。基础设施之外，你还得接上自动扩缩容，免得闲着的端点白白烧掉 GPU 时长；还要配好 Amazon CloudWatch 告警，在用户发现问题之前先一步捕捉静默故障。这些决策做完，Amazon SageMaker AI 能把整件事压缩到几小时。而这类结构化、可重复的工作，正是 Kiro、Claude Code 这类编码智能体（coding agent）擅长的场景。
听起来很诱人：跟智能体描述一下要部署的模型，走开，回来就有一个跑通的端点。现实中，没有引导的智能体会做出错误决策，产出的端点要么脆弱，要么烧钱，要么表面正常实则有问题。新模型的情况更糟，因为它们的训练数据里可能压根没有最新的部署知识。
本文教你用 agent skills 在 SageMaker AI 上部署生产级的 Hugging Face 模型。你从 Hugging Face Skills 安装六个 skill，把编码智能体指向一个 Hugging Face 模型，就能拿回一个实时端点——自带自动扩缩容、CloudWatch 告警、从 AWS Deep Learning Containers（DLC）目录中选出的正确服务容器，以及一条经过验证的清理回收路径。实时端点是默认选项，但这些 skill 同时支持带缩容到零（scale-to-zero）的实时端点、无服务器推理（Serverless Inference）、异步推理、批量转换（Batch Transform）和 Amazon Bedrock 自定义模型导入（Custom Model Import）。这些 skill 开源，只用 Python 和 AWS 命令行工具（AWS CLI），在 macOS、Linux 和 Windows 上无需改动即可运行。
没有引导的编码智能体会出什么问题
要说明这些 skill 究竟挡住了哪些坑，最好的办法是看看一个能力不错的智能体在没有它们时会做什么。我们给 Kiro（Auto 或 Claude Fable 5）和 Claude Code（Opus 4.8）出了同一个任务：把小的 Qwen/Qwen3-0.6B 模型部署到实时端点，先把方案写成文件，并记录每一步操作。
两款编码智能体一开始都选了 Text Generation Inference（TGI）作为部署用的服务容器。这个选择不难理解：TGI 多年来一直是默认方案，模型训练数据里到处都是用它做部署的教程。但该区域可用的 TGI 版本早于 Qwen3 的架构，加载不了这个模型，端点的健康检查直接没过。智能体提高了 TGI 版本，重新部署，又失败了，这才转向 vLLM。结果是多次部署失败，每次都是 GPU 时间已经开始计费后才崩溃。第二次请求的失败更隐蔽。我们让同一个智能体部署一款多模态混合专家（MoE）扩散模型，该模型在测试前几周才刚刚发布。编码智能体确认模型确实存在，但又写了一个基于 TGI 的脚本——TGI 是文本生成服务器，根本没有支持离散扩散图文模型的后端。这次没有出现任何明显的失败信号，只有等到端点起不来时你才会发现。
这两次运行的根本原因相同：缺少部署相关的具体事实，而不是推理能力不行。智能体的规划和调试都没问题，它缺的是当下、具体的知识。比如，较新的 Qwen 模型需要 vLLM；Python 3.13 在机器学习（ML）技术栈的很多组件上还没有可用的 wheel；容器镜像应该从公开的 AWS Deep Learning Containers 目录中解析。这些知识的更新速度比模型权重还快。所以我们把它们写成可编辑的技能文件，而不是寄希望于最新版本的模型能自己吸收这些信息。表 1 对比了无引导的智能体与安装技能后的智能体各自的模型部署情况。
| 部署关注点 | 无技能的智能体 | 有技能 |
|---|---|---|
| 推理容器 | 先选 TGI → 健康检查失败 → 改用 vLLM | 直接选 vLLM，且在任何资源创建之前就已确定 |
| 镜像 URI | 靠反复试错才发现 | 从 AWS DLC 目录解析，查询被拒时还有兜底方案 |
| 自动扩缩容 | 无 | 目标追踪，1–2 个实例 |
| 监控 | 无 | 三条 CloudWatch 告警（延迟、错误、开销） |
| 文档 | README 推荐用 TGI、SageMaker SDK 和 Python 3.13 | 计划和脚本与实际运行的完全一致 |
| 区域、角色、环境 | 本来就正确 | 按规则校验正确 |
| 清理 | 提供一个可运行的脚本 | 脚本运行后，再核实资源确实已删除 |
表 1：同一个请求，分别在未安装技能和已安装技能两种情况下由智能体执行
本文接下来会介绍如何借助智能体技能，把 Hugging Face 模型部署到 SageMaker AI 终端节点（也就是表 1 右列展示的效果）。
用智能体技能在 SageMaker AI 上部署 Hugging Face 模型
Hugging Face Skills GitHub 仓库提供了六个技能，覆盖了端到端的部署流程。其中，planner（规划器）技能负责编排另外五个技能，如下图所示。
hf-cloud-sagemaker-deployment-planner（负责编排，只问必要的问题）
│
├── hf-cloud-aws-context-discovery（发现本地 AWS 环境）
├── hf-cloud-python-env-setup（搭建隔离的 Python 环境）
├── hf-cloud-sagemaker-iam-preflight（验证可用的执行角色）
├── hf-cloud-serving-image-selection（选择合适的容器族与镜像 URI）
└── hf-cloud-sagemaker-production-defaults（带自动扩缩、告警和标签部署）
Agent 技能示例
Agent 技能是一种开放标准包，本质是一个文件夹，里面必须有一个 SKILL.md 文件。这个文件包含元数据（至少要有名称和描述）和指令，告诉 agent 如何完成某项具体任务。技能采用渐进式加载：只有当当前任务匹配某个技能的描述时，agent 才会按需读取它。
下面是 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
---
服务镜像的选择
服务容器是最容易让一个「纸面上看起来没问题」的部署翻车的东西。容器选错、标签过时，或者 AMI 不对，都
都会报出同样含糊的 Failed to pass health check 错误。
端到端模型部署的各个阶段
这些技能会用到五个 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。
部署过程分为六个阶段：
- 通过只读调用摸清 AWS 环境（配置文件、区域、账户和调用者身份）。
- 搭建隔离的 Python 环境，使用受支持的 Python 版本和最新版 boto3。
- 查找已有的 SageMaker AI 执行角色；只有在角色不存在、且你有权限时，才新建一个。
- 选择推理容器系列，并从 AWS DLC 目录中解析出当前可用的镜像 URI。
- 创建模型、端点配置和端点，然后挂上自动扩缩容和 Amazon CloudWatch 告警。
- 对运行中的端点做冒烟测试，并汇报结果。
前提条件
要跟着操作，你需要准备：
- 一个有权限使用 Amazon SageMaker AI 的 AWS 账户，并拥有现成的 SageMaker AI 执行角色。技能可以自动找到角色，如果不存在且你的凭证允许，也能帮你创建一个。
- AWS CLI v2，并配置好该账户的凭证。
- Python 3.10、3.11 或 3.12。不支持 Python 3.13 及更高版本，因为大部分机器学习工具链还没为这些版本发布预编译包（wheel）。
- 一个支持技能的编程智能体。本文使用 Kiro IDE。
- Git，用来克隆技能仓库。
本文会把 Qwen/Qwen3-0.6B 部署到美国东部（弗吉尼亚北部）区域（us-east-1）的一台 ml.g5.xlarge 实时推理实例上。开始前，请确认你的账户对该实例类型有可用配额。注意，实时端点不管有没有流量都会持续计费，所以用完记得删除，或者按照本文末尾的清理步骤操作。
安装技能
Kiro 支持两种技能作用范围：工作区（workspace）和全局（global）。工作区技能存放在项目的 .kiro/skills/ 目录下，只对当前项目的工作流生效；全局技能存放在 ~/.kiro/skills/ 目录下，所有工作区都能使用。
要把 Hugging Face Skills GitHub 仓库里的六个技能装到当前工作区，在 Kiro 默认代理的对话窗口里输入下面这条请求：
Install six agent skills from the huggingface/skills repo, pinned to commit
f3186efbbc322121eb5d0f31e8a1d669ee961159，克隆到这个工作区。
来源：https://github.com/huggingface/skills.git
提交：f3186efbbc322121eb5d0f31e8a1d669ee961159
技能都放在仓库的 skills/ 目录下：
-
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 会总结安装的文件，如 Figure 1 所示。注意，本文测试使用的仓库固定在特定提交上：
f3186efbbc322121eb5d0f31e8a1d669ee961159。
Figure 1：Kiro 完成六个 agent 技能的安装
要确认六个技能目录都已就位，在 Kiro 聊天窗口输入 /，就能看到可用的技能以斜杠命令的形式列出，如 Figure 2 所示。
Figure 2：在 Kiro 聊天窗口输入 / 查看可用技能
用 Kiro 部署模型
技能装好之后，你只需要用大白话把模型描述给 agent，planner 技能就会接手。你不用指定用哪个容器系列、怎么找执行角色、要挂哪些生产默认配置——这些决策都藏在技能里。
在 Kiro 聊天窗口输入下面这段请求：
我需要在 AWS SageMaker 上部署一个模型，不想自己折腾控制台操作和 boto3。模型是 Qwen3 0.6B，固定在提交
c1899de289a04d12100db370d81485cdf75e47ca，由内部应用调用。帮我找出最合适的部署方式，并一步步带着我做。先把计划写到一个文件里，然后记录你执行的每一步操作。
部署模型分以下几步：
- 审阅计划。 agent 会把部署计划写到文件里，等你批准之后才会创建会产生费用的资源。
- 发现 AWS 上下文并选择容器。 agent 会识别当前的 AWS 上下文（profile、区域、账号）。hf-cloud-serving-image-selection 技能会为 Qwen3 选择 vLLM，并从 AWS DLC 目录中解析出镜像 URI。
- 在 agent 询问时批准部署。 hf-cloud-sagemaker-production-defaults 技能会把模型、端点配置和端点作为一个整体创建出来，然后挂上自动扩缩容和 CloudWatch 告警。
- 验证。 端点进入
InService状态后，查看 agent 报告的冒烟测试结果。
以下是 agent 在运行期间记录的部署日志片段：
## 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（否则 vLLM 只会绑定到 localhost，健康检查不通，容器直接挂掉） |
| SM_VLLM_TRUST_REMOTE_CODE | false |
| SM_VLLM_MAX_MODEL_LEN | 8192 | 如果是受限模型（gated model），需要额外添加一个 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 的设置。
| 资源 | 名称 | 计费模型 |
|---|---|---|
| 端点配置 | qwen3-06b-internal-20260904-1913-config |
无 |
| 端点 | qwen3-06b-internal-20260904-1913 |
每实例 $1.408/小时 |
| 自动扩缩目标与策略 | endpoint/.../variant/AllTraffic，最少 1 最多 4 |
无 |
| CloudWatch 告警 x3 | <endpoint>-Invocation5XXErrors、-ModelLatencyP99、-OverheadLatencyP99 |
可忽略不计 |
表 2：该技能为每个端点套用的生产环境默认配置
编码代理的自主决策
技能定义了工作流程，但在这个流程里，编码代理仍然会自己做判断。有一次，代理向 Amazon ECR 查询最新的镜像标签，请求被拒绝了，因为 IAM Identity Center 角色没有 ecr-public:DescribeImages 权限。代理没有让部署失败，而是退回到技能内置的已知可用标签作为兜底，并把原因记进了日志。
还有一种情况：冒烟测试明明返回了 HTTP 200，agent 却发现根本没有输出正式回答。原因是模型的回复在还没走出 Qwen3 推理块（reasoning block）时就被 max_tokens 截断了。agent 在日志里把这一点标记为配置问题：调用方应该调高 token 上限，而不是直接把这次测试当成通过。
清理资源
实时端点（real-time endpoint）只要存在，就会一直按实例计费。用完请删掉创建的资源，避免持续扣费。sagemaker-production-defaults 技能自带一个 teardown.py 脚本，负责删除部署资源，并确认它们已经删干净。
清理步骤如下：
- 让 agent 拆除部署，或者直接带着端点名和 Region 运行 teardown.py。
- 确认脚本报告端点、端点配置和模型都已删除。删除结果由脚本自行校验。
- 检查自动扩缩容策略和 CloudWatch 告警是否也已移除，有残留就手动删掉。
结论
六个可复用的 agent 技能，能把一个没有指引的编码 agent，变成能在 SageMaker AI 端点上部署 Hugging Face 模型、且具备生产级能力的 agent。每次部署都会用上合适的容器、自动扩缩容、CloudWatch 告警，以及一条经过验证的清理路径。没有这些技能，agent 会去抓过时的容器、跳过生产环境的防护措施，还留下误导人的文档。
本文逐一介绍了这些技能：AWS 上下文发现、Python 环境搭建、IAM 角色解析、从 AWS DLC 目录中挑选容器，以及带生产默认值的部署。想上手的话，可以从 Hugging Face Skills 的 GitHub 仓库安装这些技能，然后部署你的第一个模型。这些技能是开源的，欢迎贡献代码。
团队也可以用 Amazon SageMaker JumpStart，直接在控制台部署一批热门 Hugging Face 模型；再用 Inference Recommendations 自动做基准测试，为自己的工作负载挑出最合适的实例类型。
延伸阅读
- Amazon SageMaker AI 开发者指南 – 实时推理
- AWS Deep Learning Containers 文档
关于作者
Dario Salvati
Dario 拥有人工智能硕士学位，目前在 Hugging Face 担任工程师，负责云合作伙伴关系（包括与 AWS 的合作）以及开发者工具。他的工作横跨机器学习基础设施与系统，重点让大规模部署和训练机器学习模型变得更简单。
Álvaro Bartolomé
Álvaro Bartolomé 是 Hugging Face 的技术负责人，专注于在各大云平台上构建和优化可扩展的机器学习基础设施。他热衷于将生成式 AI 模型投入生产、高性能推理，以及通过开源和开放科学让前沿机器学习技术惠及更多人。
Qiong Zhang
Qiong（Jo）Zhang 博士是 AWS 的高级解决方案架构师，专攻数据与 AI。她目前关注分布式训练和 AI 驱动的软件开发。她拥有 30 多项专利，参与合著了 100 多篇期刊和会议论文，还曾获得 IEEE NetSoft 2016、IEEE ICC 2011、ONDM 2010 和 IEEE GLOBECOM 2005 的最佳论文奖。
Sanhita Sarkar
Sanhita Sarkar 博士在 AWS 负责全球 AI/ML 和生成式 AI 合作伙伴解决方案。她在边缘计算、云和数据中心领域拥有丰富的领导经验，持有多项专利，发表过多篇研究论文，并担任技术会议的主席。