O desafio de colocar um modelo em produção no SageMaker
Fazer o deploy de um modelo Hugging Face em produção envolve uma série de decisões técnicas encadeadas: escolher o container de serving adequado para a arquitetura do modelo, confirmar a tag de imagem correta para a região AWS, ajustar o tipo de instância ao consumo de memória do modelo, configurar autoescalonamento para não desperdiçar horas de GPU ociosa e criar alarmes no Amazon CloudWatch que detectem falhas silenciosas antes que os usuários as percebam.
O Amazon SageMaker AI já reduz bastante esse esforço — o que levaria dias pode ser feito em horas. Mas existe uma armadilha: agentes de código como o Kiro e o Claude Code, usados sem orientação adequada, tomam decisões baseadas em conhecimento desatualizado e produzem endpoints frágeis, caros ou silenciosamente incorretos.
O que acontece quando o agente age sem orientação
Para ilustrar o problema, a AWS testou o comportamento de agentes não guiados com dois cenários reais.
No primeiro, foi solicitado o deploy do modelo Qwen/Qwen3-0.6B em um endpoint de inferência em tempo real. Tanto o Kiro quanto o Claude Code escolheram o Text Generation Inference (TGI) como container de serving — uma escolha compreensível, já que o TGI foi o padrão por anos e os dados de treinamento desses modelos estão cheios de tutoriais que o utilizam. O problema: a versão do TGI disponível na região não suportava a arquitetura do Qwen3. O endpoint falhou no health check. O agente tentou atualizar a versão do TGI, falhou de novo, e então migrou para o vLLM — acumulando cobranças de GPU a cada tentativa frustrada.
No segundo cenário, foi solicitado o deploy de um modelo multimodal de difusão lançado apenas semanas antes do teste. O agente confirmou que o modelo existia e gerou um script baseado em TGI — um servidor de geração de texto sem suporte a modelos de difusão de imagem. Nenhum erro explícito apareceu de imediato; o problema só seria descoberto quando o endpoint simplesmente não subisse.
A causa raiz dos dois casos é a mesma: falta de conhecimento atualizado sobre deploy, não falha de raciocínio. O agente planeja e depura bem — o que falta são fatos específicos e atuais: modelos Qwen recentes precisam de vLLM; Python 3.13 ainda não tem wheels funcionais para boa parte do ecossistema de Machine Learning (ML); as imagens de container devem ser resolvidas a partir do catálogo oficial de AWS Deep Learning Containers (DLC). Esse conhecimento muda mais rápido do que os pesos dos modelos são atualizados.
A solução: agent skills especializadas
A resposta proposta é transformar esse conhecimento em arquivos de skill editáveis, em vez de depender do modelo de linguagem absorvê-lo em seus pesos. Uma agent skill é um pacote de padrão aberto composto por uma pasta com um arquivo SKILL.md obrigatório, contendo metadados e instruções que ensinam o agente a executar uma tarefa específica. As skills são carregadas por divulgação progressiva: o agente lê uma skill sob demanda quando a tarefa atual corresponde à sua descrição.
Seis skills do repositório Hugging Face Skills no GitHub cobrem o fluxo completo de deploy. A skill planejadora orquestra as outras cinco:
hf-cloud-sagemaker-deployment-planner— orquestra o fluxo e solicita apenas o que é necessáriohf-cloud-aws-context-discovery— descobre o contexto AWS local (perfil, região, conta, identidade)hf-cloud-python-env-setup— configura um ambiente Python isolado com versão suportada e boto3 atualizadohf-cloud-sagemaker-iam-preflight— verifica e, se necessário, cria uma execution role válidahf-cloud-serving-image-selection— seleciona a família de container correta e resolve o URI da imagem no catálogo DLChf-cloud-sagemaker-production-defaults— faz o deploy com autoescalonamento, alarmes e tags de produção
As skills são open source, usam apenas Python e a Interface de Linha de Comando da AWS (AWS CLI), e funcionam sem alterações no macOS, Linux e Windows.
Serviços AWS envolvidos no fluxo
As skills acionam cinco serviços da AWS. O Amazon SageMaker AI hospeda o endpoint. O Gerenciamento de Identidade e Acesso da AWS (IAM) fornece a execution role. O Amazon Elastic Container Registry (Amazon ECR) e os AWS Deep Learning Containers fornecem a imagem de serving. O Amazon CloudWatch alimenta os alarmes. Todos os scripts auxiliares das skills chamam esses serviços via Boto3 e AWS CLI, mantendo controle total sobre o que é criado.
Pré-requisitos para seguir o guia
- Conta AWS com permissões para usar o Amazon SageMaker AI, incluindo uma execution role existente (as skills podem encontrar uma automaticamente ou criar uma, se as credenciais permitirem)
- AWS CLI v2 configurada com credenciais para essa conta
- Python 3.10, 3.11 ou 3.12 — Python 3.13 ou superior não é suportado, pois grande parte do ecossistema de ML ainda não publica wheels para essas versões
- Um agente de código com suporte a skills — o guia usa o Kiro IDE
- Git, para clonar o repositório de skills
O exemplo do post faz o deploy do modelo Qwen/Qwen3-0.6B em uma instância ml.g5.xlarge de inferência em tempo real na região US East (N. Virginia) (us-east-1). É importante confirmar a cota disponível para esse tipo de instância antes de começar — e lembrar que um endpoint em tempo real cobra continuamente enquanto existir, mesmo sem receber tráfego.
Instalando as skills no Kiro
O Kiro suporta dois escopos de skills: workspace (projeto específico, em .kiro/skills/) e global (disponível em todos os workspaces, em ~/.kiro/skills/). Para instalar as seis skills do repositório Hugging Face Skills no workspace atual, basta enviar o seguinte prompt em uma sessão de chat do agente padrão do 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
Para confirmar que os seis diretórios de skill estão presentes, basta digitar / na sessão de chat do Kiro para ver as skills disponíveis como slash commands.
Fazendo o deploy com o agente guiado pelas skills
Com as skills instaladas, basta descrever o modelo ao agente em linguagem natural. Não é necessário especificar qual família de container usar, como localizar a execution role ou quais padrões de produção aplicar — essas decisões vivem nas skills. O prompt usado no exemplo foi:
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.O fluxo de deploy segue seis fases:
- Revisão do plano: o agente grava um plano de deploy em arquivo e aguarda aprovação antes de criar qualquer recurso que gere cobrança.
- Descoberta de contexto AWS e seleção de container: o agente descobre perfil, região e conta. A skill
hf-cloud-serving-image-selectionseleciona o vLLM para o Qwen3 e resolve o URI da imagem no catálogo DLC. - Aprovação do deploy: a skill
hf-cloud-sagemaker-production-defaultscria o modelo, a configuração do endpoint e o endpoint como uma unidade, e então aplica autoescalonamento e alarmes no CloudWatch. - Verificação: o agente reporta o resultado do smoke test após o endpoint atingir o status
InService.
O log de deploy registrou, entre outras informações, a resolução da imagem de serving:
## 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` |Resolução da execution role
Um ponto de atenção comum em ambientes corporativos: chamadas a iam:CreateRole frequentemente falham em contas que usam AWS IAM Identity Center sem permissão de escrita no IAM. A skill hf-cloud-sagemaker-iam-preflight resolve isso invertendo a ordem de operação — ela busca primeiro, e só cria como último recurso. O script check_role.py procura roles existentes com padrões como AmazonSageMaker-ExecutionRole-* e *SageMaker*Execution*, ranqueia pelo último uso e valida a trust policy. A role só é criada quando nenhuma existe e o caller tem permissão iam:CreateRole. A role criada recebe AmazonSageMakerFullAccess — a recomendação é ajustá-la para conceder apenas as permissões necessárias, seguindo o princípio do menor privilégio.
Padrões de produção aplicados automaticamente
A skill hf-cloud-sagemaker-production-defaults transforma o endpoint de uma demo em um deploy de produção. Para cada endpoint, ela aplica automaticamente: configuração de autoescalonamento com rastreamento de alvo (mínimo 1, máximo 4 instâncias) e três alarmes no CloudWatch monitorando erros 5XX de invocação, latência P99 do modelo e latência P99 de overhead.
Decisões autônomas do agente
As skills definem o fluxo, mas o agente ainda toma decisões dentro dele. Em um caso, quando a consulta ao Amazon ECR para obter a tag de imagem mais recente foi negada por falta de permissão ecr-public:DescribeImages, o agente utilizou a tag conhecida como estável que a skill carrega como fallback e registrou o motivo no log. Em outro caso, após o smoke test retornar HTTP 200, o agente identificou que a resposta do modelo estava sendo truncada em max_tokens dentro do bloco de raciocínio do Qwen3, e sinalizou isso no log como um problema de configuração a ser corrigido pela aplicação chamadora.
Limpeza dos recursos
Um endpoint em tempo real cobra pela instância o tempo todo em que existe. Para evitar cobranças contínuas, a skill sagemaker-production-defaults inclui um script teardown.py que remove os recursos do deploy e confirma a exclusão. O processo envolve solicitar ao agente que execute o teardown (ou rodar o teardown.py diretamente com o nome do endpoint e a região), confirmar que o script reporta endpoint, configuração de endpoint e modelo como deletados, e verificar que a política de autoescalonamento e os alarmes do CloudWatch também foram removidos.
Conclusão
As seis skills reutilizáveis transformam um agente de código sem orientação em um que faz deploy de modelos Hugging Face no SageMaker AI com recursos prontos para produção: container correto, autoescalonamento, alarmes no CloudWatch e teardown verificado. Sem essas skills, os agentes recorrem a containers desatualizados, ignoram salvaguardas de produção e deixam documentação enganosa.
Para começar, basta instalar as skills a partir do repositório Hugging Face Skills no GitHub e fazer o deploy do primeiro modelo. As skills são open source e contribuições são bem-vindas.
Saiba mais
- Guia do Desenvolvedor do Amazon SageMaker AI – Inferência em tempo real
- Documentação dos AWS Deep Learning Containers
Fonte
Deploy Hugging Face models on Amazon SageMaker AI with coding agents (https://aws.amazon.com/blogs/machine-learning/deploy-hugging-face-models-on-amazon-sagemaker-ai-with-coding-agents/)
