Como colocar um modelo de machine learning em produção com ECS Fargate, Docker e Amazon ECR

Um guia prático publicado no AWS Builder Center mostra o caminho completo: treinar um modelo com scikit-learn, empacotar numa API FastAPI, subir para o Amazon ECR e rodar como serviço no ECS Fargate, atrás de um Application Load Balancer.

Um guia prático publicado no AWS Builder Center mostra o caminho completo: treinar um modelo com scikit-learn, empacotar numa API FastAPI, subir para o Amazon ECR e rodar como serviço no ECS Fargate, atrás de um Application Load Balancer.

Treinar um modelo é a parte fácil. O trabalho de verdade começa quando alguém precisa chamar esse modelo por HTTP, em produção, com escala e sem acordar às 3h porque o container caiu. Um guia publicado por Karan Singh no AWS Builder Center em 31 de outubro de 2026 percorre esse caminho do zero: do joblib.dump() até um serviço rodando no ECS Fargate atrás de um Application Load Balancer, com logs no CloudWatch. Este artigo reconstrói esse fluxo com os comandos e arquivos que você vai digitar de verdade.

O que você vai construir

A arquitetura final tem seis peças encaixadas: uma API FastAPI que serve previsões de um modelo scikit-learn, uma imagem Docker dessa API, um repositório no Amazon ECR guardando essa imagem, um serviço ECS rodando na Fargate (sem instância EC2 para gerenciar), um Application Load Balancer distribuindo tráfego entre as tasks, e grupos de log no CloudWatch registrando tudo.

O resultado é um endpoint HTTP público, do tipo POST /predict, que recebe um JSON com features e devolve a predição do modelo. É o padrão que normalmente aparece quando um time de dados entrega um modelo para o time de aplicação consumir: nenhuma das duas pontas precisa saber como a outra funciona por dentro.

Pré-requisitos

Antes de começar, você precisa ter:

• Uma conta AWS com permissão para criar recursos em ECR, ECS, IAM, EC2 (para VPC/subnets/security groups) e CloudWatch Logs.
• Um usuário ou role IAM com, no mínimo, as permissões ecr:CreateRepository, ecr:GetAuthorizationToken, ecr:PutImage, ecr:BatchCheckLayerAvailability, ecs:RegisterTaskDefinition, ecs:CreateService, ecs:CreateCluster, iam:PassRole e logs:CreateLogGroup.
• Uma ecsTaskExecutionRole já existente ou permissão para criar uma (ela é quem autoriza a task a puxar a imagem do ECR e escrever logs).
• AWS CLI v2 configurada (aws configure), Docker instalado e rodando localmente, e Python 3.11 com pip.
• Uma VPC com ao menos duas subnets em zonas de disponibilidade diferentes, necessárias para o Application Load Balancer e para o awsvpc network mode do Fargate.

Todos os comandos abaixo usam a região sa-east-1 (São Paulo); troque se sua conta operar em outra região.

Passo a passo

1. Treinando e empacotando o modelo

O guia original usa scikit-learn para treinar e joblib para serializar. Um exemplo mínimo, reproduzível localmente:

from sklearn.ensemble import RandomForestClassifier
from sklearn.datasets import load_iris
import joblib

X, y = load_iris(return_X_y=True)
clf = RandomForestClassifier()
clf.fit(X, y)
joblib.dump(clf, "model.joblib")

O arquivo model.joblib gerado é o artefato que vai dentro da imagem Docker. Em um projeto real, esse artefato normalmente vem de um pipeline de treino separado (SageMaker, um job no CI ou um notebook), não do mesmo repositório da API.

2. Criando a API com FastAPI

A API é a camada que transforma o modelo em contrato HTTP. Um app.py equivalente ao descrito na fonte:

import joblib
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()
model = joblib.load("model.joblib")

class Features(BaseModel):
    data: list[float]

@app.post("/predict")
def predict(features: Features):
    prediction = model.predict([features.data])
    return {"prediction": prediction.tolist()}

Repare que o modelo é carregado uma única vez, no escopo global do módulo. Carregar dentro da função predict() funcionaria, mas recarregaria o joblib a cada requisição, o que derruba a latência desnecessariamente.

3. Escrevendo o Dockerfile

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY model.joblib .
COPY app.py .

EXPOSE 8000

CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

O requirements.txt precisa de fastapi, uvicorn, scikit-learn e joblib. Usar python:3.11-slim em vez da imagem completa mantém a imagem final menor, o que acelera o docker push e o tempo de start da task no Fargate.

4. Testando a imagem localmente

docker build -t ml-inference-api .
docker run -p 8000:8000 ml-inference-api

Com o container rodando, um curl local confirma que a API responde antes de gastar um minuto sequer com ECR ou ECS:

curl -X POST http://localhost:8000/predict \
  -H "Content-Type: application/json" \
  -d '{"data": [5.1, 3.5, 1.4, 0.2]}'

5. Criando o repositório no Amazon ECR e enviando a imagem

aws ecr create-repository --repository-name ml-inference-api --region sa-east-1

aws ecr get-login-password --region sa-east-1 | \
  docker login --username AWS --password-stdin <account-id>.dkr.ecr.sa-east-1.amazonaws.com

docker tag ml-inference-api:latest <account-id>.dkr.ecr.sa-east-1.amazonaws.com/ml-inference-api:latest
docker push <account-id>.dkr.ecr.sa-east-1.amazonaws.com/ml-inference-api:latest

O guia da fonte alerta que armazenamento e transferência de dados do ECR podem gerar cobranças separadas da AWS, sem detalhar valores ou condições de isenção; vale conferir a página oficial de preços do serviço antes de deixar imagens acumulando no repositório.

6. Criando o cluster ECS e a task definition para Fargate

aws ecs create-cluster --cluster-name ml-inference-cluster --region sa-east-1

A task definition é o contrato que diz ao Fargate quanta CPU e memória alocar, qual imagem rodar e para onde mandar os logs:

{
  "family": "ml-inference-task",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "512",
  "memory": "1024",
  "executionRoleArn": "arn:aws:iam::<account-id>:role/ecsTaskExecutionRole",
  "containerDefinitions": [
    {
      "name": "ml-inference-api",
      "image": "<account-id>.dkr.ecr.sa-east-1.amazonaws.com/ml-inference-api:latest",
      "portMappings": [{"containerPort": 8000, "protocol": "tcp"}],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/ml-inference-api",
          "awslogs-region": "sa-east-1",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
  ]
}

aws ecs register-task-definition --cli-input-json file://task-definition.json

Atenção ao custo: o guia da fonte alerta que o Fargate pode gerar cobranças separadas da AWS; vale revisar os valores de cpu e memory da task definition (e por quanto tempo o serviço fica rodando) antes de considerar o teste encerrado, e conferir a página oficial de preços do Fargate para entender as condições de cobrança e eventual isenção.

7. Configurando o Application Load Balancer e o serviço ECS

O ALB precisa de um target group apontando para a porta 8000 e um listener na porta 80 (ou 443, com certificado TLS, se a API for pública). Depois de criado o ALB e o target group no console ou via aws elbv2 create-load-balancer, o serviço ECS é criado assim:

aws ecs create-service \
  --cluster ml-inference-cluster \
  --service-name ml-inference-service \
  --task-definition ml-inference-task \
  --desired-count 2 \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[subnet-abc123,subnet-def456],securityGroups=[sg-xyz789],assignPublicIp=ENABLED}" \
  --load-balancers "targetGroupArn=arn:aws:elasticloadbalancing:sa-east-1:<account-id>:targetgroup/ml-inference-tg/abc123,containerName=ml-inference-api,containerPort=8000"

desired-count 2 já deixa duas tasks rodando atrás do ALB, o que é o mínimo para sobreviver a um health check falho sem derrubar o serviço inteiro.

8. Monitorando com CloudWatch

A logConfiguration da task definition já manda stdout/stderr do container para o grupo /ecs/ml-inference-api. Além dos logs de aplicação, o ECS publica métricas de CPUUtilization e MemoryUtilization por serviço no CloudWatch. Vale criar um alarme simples sobre MemoryUtilization acima de 80%, sinal de que o memory: 1024 da task definition está subdimensionado para a carga real.

Testando

Com o serviço estável (visível como RUNNING em aws ecs describe-services --cluster ml-inference-cluster --services ml-inference-service), o DNS do ALB já responde às mesmas chamadas testadas localmente no passo 4:

curl -X POST http://ml-inference-alb-123456789.sa-east-1.elb.amazonaws.com/predict \
  -H "Content-Type: application/json" \
  -d '{"data": [5.1, 3.5, 1.4, 0.2]}'

Uma resposta {"prediction": [0]} (ou o índice de classe equivalente ao dataset usado) confirma que o tráfego chegou do ALB até o container, passou pelo uvicorn, caiu na função predict() e voltou. Se a chamada travar, o primeiro lugar para olhar é o grupo de log /ecs/ml-inference-api: a causa mais comum é o health check do target group batendo num path que a API não responde (por exemplo, esperando / enquanto só existe /predict).

Building a machine learning model is only the beginning. Making it reliable, scalable, and accessible is what turns it into a real-world application.

Building a machine learning model is only the beginning. Making it reliable, scalable, and accessible is what turns it into a real-world application.Karan Singh, autor do guia no AWS Builder Center

Limpando os recursos

Fargate cobra por task rodando, e o ALB cobra por hora ativo mais LCU processadas; nenhum dos dois pausa sozinho. Para não deixar cobrança rodando depois do teste, nesta ordem:

aws ecs update-service --cluster ml-inference-cluster --service ml-inference-service --desired-count 0
aws ecs delete-service --cluster ml-inference-cluster --service ml-inference-service
aws ecs delete-cluster --cluster ml-inference-cluster

aws elbv2 delete-load-balancer --load-balancer-arn <arn-do-alb>
aws elbv2 delete-target-group --target-group-arn <arn-do-target-group>

aws ecr delete-repository --repository-name ml-inference-api --force
aws logs delete-log-group --log-group-name /ecs/ml-inference-api

Confira também se alguma security group criada à parte para o ALB ou para as tasks ficou órfã: ela não gera cobrança sozinha, mas atrapalha o próximo teste se for reaproveitada sem revisão.

Próximos passos

O guia da fonte para no monitoramento básico e nas boas práticas de segurança (role com menor privilégio, segredos no Secrets Manager, subnets privadas para as tasks, HTTPS no ALB). Dali para frente, os pontos que normalmente aparecem num segundo momento são o Auto Scaling do serviço ECS atrelado à métrica CPUUtilization (para a Fargate subir e descer tasks sozinha conforme a carga de inferência), o versionamento de imagem por tag no ECR em vez de depender só de latest, e um pipeline de CI/CD (CodePipeline ou GitHub Actions) que builda, testa e faz o docker push automaticamente a cada commit no modelo ou na API.

Fonte: AWS Builder Center