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:

yaml
acceptance:
  minimum_f1: 0.85
  maximum_latency_ms: 200
  maximum_memory_mb: 2048
  require_no_nan: true

Métricas

Tipo de problemaMétricas
TodosPerda (train / validação)
ClassificaçãoAcurácia, F1, F1 macro, Precisão, Recall, ROC AUC
CalibraçãoECE, Brier
Regressão e sériesRMSE, MAE, R², MAPE
Modelos de linguagemPerplexidade, Tokens/s
ServiçoLatê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

PainelO que faz
ResumoMétricas, critérios e veredicto.
ExploradorO que o modelo aprendeu por dentro.
ExplicaçãoQuais variáveis pesam em cada previsão.
TestarPrevisões à mão: «E se…?» muda um valor e você vê o efeito, «Ao vivo · n ms».
FichaA ficha do modelo: o que faz, dados, métricas e limites.
ImplantaçãoServiço local e cliente tipado.
ContratoO 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

text
Desenvolvimento → Avaliação → Aprovado → Staging → Produção
                                       ↘ Rejeitado      ↘ Arquivado

Promover 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:

text
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:

0 de 7 feitos

Modos de consumo

ModoQuando
EmbutidoO modelo roda dentro da sua aplicação.
StandaloneUm executável próprio.
MicrosserviçoUm serviço HTTP chamado por outros.
BatchPontuar lotes de dados periodicamente.
StreamingPrevisõ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.

bash
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.