让编码代理把 Hugging Face 模型部署成可运营的 SageMaker 实时端点

预计阅读时间：13 分钟

把 Hugging Face 模型“跑起来”并不难，难的是把它变成可长期运营的服务：容器必须兼容模型任务和硬件，端点需要扩缩容，延迟异常要能告警，部署失败或实验结束后还必须完整释放资源。

一种更工程化的做法，是把这些工作拆成编码代理可以调用的技能：开发者只提供模型和部署约束，代理负责生成并执行部署计划，最终交付 SageMaker AI 实时端点、自动扩缩容策略、Amazon CloudWatch 告警，以及经过验证的清理流程。

六类技能不是六条命令，而是一条交付链

来源提到使用六个开源 agent skills，但摘要没有列出它们的具体名称。按生产部署职责，可以把这条链路理解为六类能力：

模型检查：识别模型任务、框架、参数规模、许可证，以及是否需要访问令牌或自定义代码。
推理容器选择：根据 Transformers、Text Generation Inference 或其他运行时，匹配区域、架构和加速器对应的 SageMaker 镜像。
资源部署：创建 SageMaker Model、Endpoint Configuration 和实时 Endpoint。
弹性配置：注册可扩缩目标，并配置基于调用量或其他指标的伸缩策略。
可观测性配置：创建 CloudWatch 告警，保留部署输出，并执行一次真实推理验证。
资源清理：按依赖顺序删除告警、伸缩目标、端点、端点配置和模型，再检查是否还有残留资源。

这里最重要的不是“让代理替人输入 CLI”，而是让它保留部署状态和资源关系。一个可靠的代理至少应输出一份清单，记录区域、模型名、端点名、实例类型、镜像 URI、伸缩策略和告警名称。否则清理阶段只能依赖模糊搜索，容易漏删资源。

容器选择是部署成败的分水岭

代理不能只根据模型仓库里出现了 transformers 就随便选择一个镜像。它还需要检查：

模型属于文本生成、分类、嵌入、视觉还是其他任务；
CPU、GPU及其显存是否足以容纳模型；
模型是否要求 trust_remote_code，以及是否允许执行仓库中的自定义代码；
当前 AWS 区域是否提供目标镜像和实例类型；
推理容器是否支持模型的数据类型、量化格式和批处理方式；
模型是否受限，需要凭证才能下载。

对于私有或受限模型，不应把 Hugging Face 令牌直接写进代理生成的脚本、Git 仓库或普通环境变量。可以改用受控的模型制品、短期凭证或组织批准的秘密管理流程。对于允许执行远程代码的模型，也应先审查仓库内容，再让部署任务继续。

生产环境还需要一个明确的审批点。比较稳妥的模式是：代理先输出部署计划和成本相关参数，操作者确认实例类型、最大副本数和区域后，代理再真正创建资源。

可以这样实践：部署、扩缩容与告警

下面是一套可复制改造的 AWS CLI 示例。它不是特定 agent skill 的内部实现，而是代理可以生成和执行的最小工作流。

运行前需要：

已配置 AWS CLI v2；
本机安装 jq；
一个允许 SageMaker 拉取镜像、读取模型并写入日志的执行角色；
一个与模型任务、区域和处理器架构兼容的 Hugging Face 推理镜像 URI；
当前账户在目标实例类型上有足够配额。

ml.g5.xlarge 会产生费用，也未必适合所有模型。运行前请根据模型显存需求和账户配额修改它。

#!/usr/bin/env bash
set -euo pipefail

export AWS_REGION="us-east-1"
export PREFIX="hf-agent-demo"
export MODEL_NAME="${PREFIX}-model"
export ENDPOINT_CONFIG="${PREFIX}-config"
export ENDPOINT="${PREFIX}-endpoint"
export VARIANT="AllTraffic"

# 修改为你的 SageMaker 执行角色 ARN。
export ROLE_ARN="arn:aws:iam::123456789012:role/SageMakerExecutionRole"

# 修改为经过验证、且与区域和硬件兼容的 Hugging Face 推理镜像。
export IMAGE_URI="123456789012.dkr.ecr.us-east-1.amazonaws.com/your-huggingface-inference-image:latest"

# 可替换为你已验证可由该镜像加载的公开模型。
export HF_MODEL_ID="distilbert/distilbert-base-uncased-finetuned-sst-2-english"
export HF_TASK="text-classification"

aws configure set region "$AWS_REGION"

CONTAINER_JSON=$(jq -n \
  --arg image "$IMAGE_URI" \
  --arg model "$HF_MODEL_ID" \
  --arg task "$HF_TASK" \
  '{Image:$image,Environment:{HF_MODEL_ID:$model,HF_TASK:$task}}')

aws sagemaker create-model \
  --model-name "$MODEL_NAME" \
  --execution-role-arn "$ROLE_ARN" \
  --primary-container "$CONTAINER_JSON"

VARIANTS_JSON=$(jq -n \
  --arg model "$MODEL_NAME" \
  --arg variant "$VARIANT" \
  '[{VariantName:$variant,ModelName:$model,InitialInstanceCount:1,InstanceType:"ml.g5.xlarge",InitialVariantWeight:1.0}]')

aws sagemaker create-endpoint-config \
  --endpoint-config-name "$ENDPOINT_CONFIG" \
  --production-variants "$VARIANTS_JSON"

aws sagemaker create-endpoint \
  --endpoint-name "$ENDPOINT" \
  --endpoint-config-name "$ENDPOINT_CONFIG"

aws sagemaker wait endpoint-in-service --endpoint-name "$ENDPOINT"
echo "Endpoint is ready: $ENDPOINT"

端点进入 InService 后，可以注册自动扩缩容。下面的目标值表示每个实例期望处理的调用量指标，实际数值必须通过压测校准，不能直接照搬到生产环境。

export RESOURCE_ID="endpoint/${ENDPOINT}/variant/${VARIANT}"

aws application-autoscaling register-scalable-target \
  --service-namespace sagemaker \
  --resource-id "$RESOURCE_ID" \
  --scalable-dimension sagemaker:variant:DesiredInstanceCount \
  --min-capacity 1 \
  --max-capacity 4

aws application-autoscaling put-scaling-policy \
  --policy-name "${PREFIX}-invocations-scaling" \
  --policy-type TargetTrackingScaling \
  --service-namespace sagemaker \
  --resource-id "$RESOURCE_ID" \
  --scalable-dimension sagemaker:variant:DesiredInstanceCount \
  --target-tracking-scaling-policy-configuration '{"TargetValue":20.0,"PredefinedMetricSpecification":{"PredefinedMetricType":"SageMakerVariantInvocationsPerInstance"},"ScaleInCooldown":300,"ScaleOutCooldown":60}'

再创建一个模型延迟告警。SageMaker 的 ModelLatency 使用微秒，因此下面的 2000000 表示两秒。示例只创建告警；如果希望真正通知值班人员，应额外配置 SNS Topic，并添加 --alarm-actions。

export ALARM_NAME="${PREFIX}-high-model-latency"

aws cloudwatch put-metric-alarm \
  --alarm-name "$ALARM_NAME" \
  --namespace AWS/SageMaker \
  --metric-name ModelLatency \
  --dimensions Name=EndpointName,Value="$ENDPOINT" Name=VariantName,Value="$VARIANT" \
  --statistic Average \
  --period 60 \
  --evaluation-periods 3 \
  --datapoints-to-alarm 2 \
  --threshold 2000000 \
  --comparison-operator GreaterThanThreshold \
  --treat-missing-data notBreaching

端点创建成功不等于部署成功

代理应该执行真实请求，而不是看到 InService 就宣布完成。对于上面的文本分类模型，可以这样验证：

cat > payload.json <<'JSON'
{
  "inputs": "Coding agents can make repeatable deployments easier to review."
}
JSON

aws sagemaker-runtime invoke-endpoint \
  --endpoint-name "$ENDPOINT" \
  --content-type application/json \
  --accept application/json \
  --body fileb://payload.json \
  response.json

cat response.json

验证逻辑不应只检查 HTTP 调用是否成功，还应确认：

返回的是合法 JSON；
输出字段符合当前模型任务；
没有出现容器加载错误、显存不足或模型下载失败；
CloudWatch 中已经出现调用量和延迟指标；
连续请求时，延迟和错误率处于可接受范围。

不同推理容器的请求格式可能不同。编码代理应从所选容器和模型任务推导 payload，而不是为所有模型硬编码同一个 inputs 结构。

清理路径也必须经过验证

实验环境最常见的问题不是部署失败，而是测试结束后留下持续计费的端点。清理顺序同样重要：先移除监控和伸缩配置，再删除端点，等待端点真正消失后，才能删除端点配置和模型。

#!/usr/bin/env bash
set -u

export AWS_REGION="us-east-1"
export PREFIX="hf-agent-demo"
export MODEL_NAME="${PREFIX}-model"
export ENDPOINT_CONFIG="${PREFIX}-config"
export ENDPOINT="${PREFIX}-endpoint"
export VARIANT="AllTraffic"
export ALARM_NAME="${PREFIX}-high-model-latency"
export RESOURCE_ID="endpoint/${ENDPOINT}/variant/${VARIANT}"

aws configure set region "$AWS_REGION"

aws cloudwatch delete-alarms --alarm-names "$ALARM_NAME" || true

aws application-autoscaling deregister-scalable-target \
  --service-namespace sagemaker \
  --resource-id "$RESOURCE_ID" \
  --scalable-dimension sagemaker:variant:DesiredInstanceCount || true

aws sagemaker delete-endpoint --endpoint-name "$ENDPOINT" || true
aws sagemaker wait endpoint-deleted --endpoint-name "$ENDPOINT" || true
aws sagemaker delete-endpoint-config --endpoint-config-name "$ENDPOINT_CONFIG" || true
aws sagemaker delete-model --model-name "$MODEL_NAME" || true

if aws sagemaker describe-endpoint --endpoint-name "$ENDPOINT" >/dev/null 2>&1; then
  echo "ERROR: endpoint still exists" >&2
  exit 1
fi

echo "Verified: endpoint no longer exists."

这段脚本只处理示例中创建的核心资源。实际项目还要检查 CloudWatch 日志组、SNS Topic、S3 模型制品、专用 IAM 角色、ECR 镜像以及代理创建的临时文件。删除端点会停止端点实例计费，但不会自动清除所有外围资源。

把代理权限限制在可审计边界内

编码代理适合处理重复、跨服务且容易遗漏的部署步骤，但不应获得不受限制的管理员权限。落地时可以采用以下检查表：

让代理先生成计划，再由人确认实例类型、最大副本数和预估成本；
使用限定资源前缀和标签的 IAM 权限；
禁止代理把令牌、角色凭证或私有模型地址写进代码仓库；
将容器 URI、模型版本和部署参数固定下来，避免同名标签漂移；
把真实推理测试、CloudWatch 指标检查和清理验证设为必经步骤；
为部署资源统一添加项目、环境、所有者和过期时间标签；
在 CI 中定期运行残留资源扫描，而不是只依赖一次性的清理脚本。

真正有价值的自动化，不是让模型更快地出现在控制台里，而是把“选对运行时、建好端点、证明它能工作、确认它能扩缩、发现异常、完整撤销”变成一条可重复、可审计的工程流程。