Manual de Adoção de ML

O que Manual de Adoção de ML faz?

Este skill fornece uma metodologia adaptativa para implementar modelos de machine learning em projetos de engenharia de software existentes. Ele preenche a lacuna entre a engenharia de software tradicional e o MLOps, estruturando como o ML deve ser pesquisado, desacoplado, treinado e integrado.

Quando Ativar

• Um usuário pede para "adicionar ML" ou "adicionar um algoritmo" à sua base de código existente.
• Planejamento da integração de um novo modelo (ex.: recomendação, classificação, previsão) em uma aplicação sem ML.
• Estruturação de um fluxo de trabalho para um agente construir, treinar e implantar um componente de ML de forma adaptativa.

Fase 1: Definição do Problema e Viabilidade

Antes de escrever código de modelo, estabeleça o "porquê" e o "como".

• Verificação Heurística: Pergunte ao usuário se uma heurística simples (ex.: regex, ordenação baseada em regras) poderia resolver o problema mais rapidamente. Se sim, comece por aí.
• Definição de Métrica: Defina qual métrica de negócio o modelo de ML está tentando melhorar (ex.: taxa de clique, latência reduzida).
• Orçamento de Erro: Defina como é uma previsão "ruim" e como o sistema deve lidar com ela.

Fase 2: Preparação de Dados

ML é inútil sem dados limpos e acessíveis.

• Auditar Fontes de Dados: Identifique onde os dados de treinamento residem. É um banco de dados ativo, um CSV estático ou uma API?
• Contrato de Dados: Estabeleça um esquema para os dados de entrada. Quais características são necessárias? O que acontece se uma característica estiver faltando?
• Prevenção de Vazamento: Garanta que a divisão de dados proposta pelo usuário não vaze acidentalmente informações futuras para o conjunto de treinamento (ex.: divisão cronológica para dados de série temporal).

Fase 3: Integração Arquitetural e Desacoplamento

Não acople fortemente a inferência do modelo à lógica de negócio central.

• Limite da API: Sugira colocar o modelo atrás de um endpoint de API (ex.: usando fastapi-patterns ou django-patterns) ou de uma classe de serviço dedicada.
• Mecanismos de Fallback: Projete um estado padrão. Se o modelo demorar muito para responder ou lançar um erro, o sistema deve cair graciosamente para uma regra codificada.
• Feature Flags: Envolva a chamada de inferência do novo ML em um feature flag para que possa ser ativada (ou desativada) com segurança.

Fase 4: Implementação e Treinamento do Modelo

Estruture o código para reprodutibilidade e iteração.

• Comece Simples: Construa primeiro um modelo de base (ex.: uma Regressão Logística simples do scikit-learn ou uma camada linear básica do PyTorch).
• Reprodutibilidade: Aplique pytorch-patterns ou práticas recomendadas semelhantes: fixe sementes aleatórias, torne o código independente de dispositivo e documente explicitamente as formas dos tensores/arrays.
• Evidência Automatizada: Exija testes para as transformações de dados e o esquema de inferência. Não aceite um modelo sem um script de avaliação que o compare com a linha de base.

Fase 5: Transferência para MLOps

Uma vez que o modelo de base esteja integrado, mude o foco para operações contínuas.

• Consulte mle-workflow: Oriente o usuário a configurar rastreamento de experimentos, registros de modelos e detecção de deriva.
• CI/CD: Adicione a etapa de avaliação do modelo ao pipeline de CI existente para garantir que commits futuros não degradem o desempenho do modelo.

Fluxo de Trabalho Iterativo do Agente

Ao ajudar um usuário através deste manual, os agentes devem:

1. Fazer perguntas esclarecedoras para completar a Fase 1 antes de propor arquiteturas.
2. Elaborar um contrato de dados na Fase 2 para aprovação do usuário.
3. Escrever a interface de desacoplamento (API/Serviço) na Fase 3 antes de escrever o loop de treinamento.
4. Entregar um script reproduzível na Fase 4 que treine o modelo e salve o artefato.