Documentação / ML Studio
Avaliação e modelos
Avaliação independente, métricas, robustez e equidade, campeão contra desafiante, o registro de modelos, o versionamento em disco e como publicar.
Nesta página
Um modelo não está pronto porque terminou de treinar. Ele está pronto quando uma avaliação independente diz que cumpre os critérios, uma pessoa o aprova e o seu pacote passa nos testes.
Avaliação independente
O Yuli avalia cada versão separadamente, sobre a partição de teste · fora do treinamento: dados que o modelo nunca viu ao treinar nem ao escolher parâmetros. O veredicto é claro:
- «Cumpre os critérios (n/N)», ou
- «Não cumpre: …», com o critério que falhou.
Os critérios são os de acceptance em yuli-ml.yaml:
acceptance:
minimum_f1: 0.85
maximum_latency_ms: 200
maximum_memory_mb: 2048
require_no_nan: trueMétricas
| Tipo de problema | Métricas |
|---|---|
| Todos | Perda (train / validação) |
| Classificação | Acurácia, F1, F1 macro, Precisão, Recall, ROC AUC |
| Calibração | ECE, Brier |
| Regressão e séries | RMSE, MAE, R², MAPE |
| Modelos de linguagem | Perplexidade, Tokens/s |
| Serviço | Latência p95 (ms) |
Com classes desbalanceadas, a Acurácia mente: um modelo que sempre diz «não» acerta 95 % se só 5 % for «sim». Use F1, F1 macro ou Recall conforme o erro que custar mais caro.
Matriz de confusão
Em classificação, a Matriz de confusão mostra, para cada classe real, quantas vezes o modelo acertou e com o que a confundiu. É a forma mais rápida de ver onde ele falha.
Robustez e equidade
Robustez e equidade verifica como o modelo muda com dados perturbados e entre grupos. Cada teste sai como robusto, sensível ou frágil. Se o modelo afeta pessoas, revise-a sempre.
Histórico de avaliações
Cada avaliação fica registrada com Quando, Suíte, Dados de teste, Critérios e Veredicto, e com a Melhoria vs produção: quanto melhora (ou piora) em relação ao modelo que está em serviço.
Os painéis do modelo
| Painel | O que faz |
|---|---|
| Resumo | Métricas, critérios e veredicto. |
| Explorador | O que o modelo aprendeu por dentro. |
| Explicação | Quais variáveis pesam em cada previsão. |
| Testar | Previsões à mão: «E se…?» muda um valor e você vê o efeito, «Ao vivo · n ms». |
| Ficha | A ficha do modelo: o que faz, dados, métricas e limites. |
| Implantação | Serviço local e cliente tipado. |
| Contrato | O formato de entrada e saída que a sua aplicação pode esperar. |
Campeão contra desafiante
O campeão é a versão que está em produção. Um desafiante é uma versão nova que compete com ele nos mesmos dados de teste. Só faz sentido promover o desafiante se ele melhorar de forma mensurável.
Registro e estados
Desenvolvimento → Avaliação → Aprovado → Staging → Produção
↘ Rejeitado ↘ ArquivadoPromover para produção é sempre feito por uma pessoa. Rollback em um clique. Nenhum agente pode promover um modelo.
Versionamento em disco
Cada versão fica em models/<nome>/v<major>.<minor>/ com tudo o que é necessário para reproduzi-la e auditá-la:
models/bajas-clientes/v1.2/
├── model.yaml
├── lineage.json
├── configs/
├── experiments/
│ └── run-3.json
├── artifacts/
│ ├── weights/
│ ├── checkpoints/
│ ├── metrics/
│ └── reports/
├── evaluation/
│ └── evaluation-report.json
└── exports/Publicar
A aba Publicar percorre uma cadeia de passos sobre a versão validada:
Modos de consumo
| Modo | Quando |
|---|---|
| Embutido | O modelo roda dentro da sua aplicação. |
| Standalone | Um executável próprio. |
| Microsserviço | Um serviço HTTP chamado por outros. |
| Batch | Pontuar lotes de dados periodicamente. |
| Streaming | Previsões sobre eventos em fluxo. |
Serviço local
Servir sobe o modelo em 127.0.0.1 com POST /predict (os LLMs, com API compatível com a OpenAI). Ele só escuta
na sua máquina.
curl -s http://127.0.0.1:<porta>/predict \
-H "Content-Type: application/json" \
-d '{"inputs": [{"antiguedad_meses": 4, "plan": "basico", "tickets_90d": 7}]}'Responde {"predictions": [...]}, com o mesmo formato descrito pelo painel Contrato (model-contract.json).
SDK cliente tipado
Em Cliente tipado (SDK), gere um cliente para TypeScript, Python, Java, Go ou C#. Para integrá-lo com timeout, circuit breaker e volta às suas regras se o modelo falhar, peça ao agente.
Veja também Privacidade e sandbox de ML.