Resumo executivo
O ai-dat (AI Deployment Template) é um template cookie-cutter que resolve uma dor recorrente em equipes de ML: o gap entre um notebook funcionando e uma API pronta para produção. Construído e validado na Pickcells, reduziu o tempo de deploy em aproximadamente 50% e se tornou o ponto de partida padrão para cada novo serviço de IA na empresa.
Problema
A maioria das equipes de ML gasta tempo desproporcional em trabalho não relacionado ao modelo ao fazer o deploy em produção:
- Configurar estrutura de projeto, gerenciamento de dependências e ambientes virtuais do zero a cada vez.
- Conectar um servidor web, validação de requisições e tratamento de erros ao redor de um modelo.
- Escrever Dockerfiles e descobrir otimização de build para imagens Python de ML.
- Adicionar testes que cobrem o contrato da API, não apenas testes unitários na lógica do modelo.
Esse overhead se multiplica em ambiente de startup, onde engenheiros alternam frequentemente entre projetos e novos membros precisam se integrar rapidamente.
Solução
O ai-dat fornece uma base opinativa, pronta para clonar, que codifica convenções conquistadas com experiência:
Estrutura de projeto. Um layout consistente para diretórios src/, tests/, models/ e app/ — previsível o suficiente para que qualquer membro da equipe navegue em qualquer serviço.
FastAPI + Pydantic. Schemas de requisição/resposta definidos com Pydantic garantem validação de entrada e documentação OpenAPI gerada automaticamente em /docs. Novos endpoints são adicionados seguindo o padrão estabelecido.
Docker. Um Dockerfile multi-estágio separa o ambiente de build da imagem de runtime, mantendo as imagens finais enxutas. Um docker-compose.yml cobre desenvolvimento local e testes de integração.
Testes com Pytest. O template inclui fixtures, configuração de cliente de teste e exemplos de testes para o endpoint de saúde e de inferência do modelo — facilitando a manutenção de cobertura de testes à medida que os modelos evoluem.
Gerenciamento de dependências com Poetry. Lockfiles reprodutíveis, separação de dependências de dev e prod, e gerenciamento limpo de ambientes virtuais.
Impacto
- ~50% de redução no tempo de deploy para novos serviços de IA na Pickcells.
- O onboarding de novos cientistas de dados na base de código de produção passou de dias para horas.
- Estabeleceu um vocabulário compartilhado para deploy em toda a equipe, reduzindo fricção em revisões e mal-entendidos sobre ambientes.
Uso
# Clonar e renomear
git clone https://github.com/viniciusnvcosta/ai-dat meu-novo-servico
cd meu-novo-servico
# Instalar dependências
poetry install
# Executar localmente
poetry run uvicorn app.main:app --reload
# Executar testes
poetry run pytest
# Build e execução com Docker
docker compose up --build
Lições aprendidas
O maior insight foi que disciplina de template se paga mais rápido em equipes com alta rotatividade. O valor não está apenas no tempo inicial economizado — está na consistência que facilita o debugging quando algo quebra em produção. Um segundo insight: manter o template mínimo e opinativo é difícil; a tentação é adicionar mais funcionalidades, mas o valor vem do caminho feliz estreito e bem compreendido.