Guia de Uso - APIs `/model-registry`

Base URL: https://csuite.internut.com.br/model-registry

Documentação Swagger: https://csuite.internut.com.br/model-registry/docs

📋 Índice

Visão Geral
Models API
Versions API
Activation API
Exemplos Práticos
Troubleshooting

1. Visão Geral

O CSuite Model Registry é um sistema centralizado para gerenciar modelos de Machine Learning do ecossistema C-Suite. Permite registrar, versionar, ativar e fazer rollback de modelos de forma controlada.

Objetivos

Centralização: Modelos ML em um único lugar
Versionamento: Controle de versões de modelos
Ativação Controlada: Ativação/desativação de versões
Rollback: Capacidade de voltar para versões anteriores
Metadados: Armazenamento de métricas, features e informações de treinamento

Modelos Suportados

O Model Registry gerencia 4 modelos principais do 4C:

intent - Modelo de intenção de compra
offer - Modelo de recomendação de oferta
channel - Modelo de seleção de canal
timing - Modelo de timing de contato

Armazenamento

S3 (Produção): Armazenamento em AWS S3 (MODEL_REGISTRY_S3_BUCKET)
Local (Desenvolvimento): Armazenamento local (MODEL_REGISTRY_LOCAL_PATH)

Status de Versões

staging: Versão recém-registrada (padrão)
active: Versão ativa em produção
archived: Versão arquivada (desativada)

2. Models API

Base Path: /models

2.1 Listar Modelos

Endpoint: GET /models

Descrição: Lista todos os modelos disponíveis com suas versões.

Exemplo:

curl "https://csuite.internut.com.br/model-registry/models"

Resposta (Sucesso):

{
  "intent": [
    {
      "model_name": "intent",
      "version": "20251206_120000",
      "status": "active",
      "created_at": "2024-12-06T12:00:00Z",
      "metrics": {
        "accuracy": 0.85,
        "precision": 0.82,
        "recall": 0.88
      },
      "features": ["recency_days", "freq_90d", "value_90d"],
      "registered_at": "2024-12-06T12:00:00Z"
    },
    {
      "model_name": "intent",
      "version": "20251205_100000",
      "status": "archived",
      "created_at": "2024-12-05T10:00:00Z",
      "metrics": {
        "accuracy": 0.83,
        "precision": 0.80,
        "recall": 0.86
      },
      "registered_at": "2024-12-05T10:00:00Z"
    }
  ],
  "offer": [
    {
      "model_name": "offer",
      "version": "20251206_110000",
      "status": "active",
      "created_at": "2024-12-06T11:00:00Z",
      "registered_at": "2024-12-06T11:00:00Z"
    }
  ],
  "channel": [],
  "timing": []
}

Resposta (Modo Degradado):

{
  "intent": [],
  "offer": [],
  "channel": [],
  "timing": [],
  "registry_available": false,
  "note": "Model Registry não configurado (modo degradado)"
}

Campos da Resposta:
- intent, offer, channel, timing: Lista de versões de cada modelo
- registry_available: Se false, registry não está configurado
- note: Mensagem explicativa (se modo degradado)

2.2 Obter Informações de Modelo

Endpoint: GET /models/{model_name}

Descrição: Obtém informações de um modelo específico, incluindo todas as versões e versão ativa.

Parâmetros de Path:
- model_name (string, obrigatório) - Nome do modelo (intent, offer, channel, timing)

Exemplo:

curl "https://csuite.internut.com.br/model-registry/models/intent"

Resposta:

{
  "model_name": "intent",
  "versions": [
    {
      "model_name": "intent",
      "version": "20251206_120000",
      "status": "active",
      "created_at": "2024-12-06T12:00:00Z",
      "metrics": {
        "accuracy": 0.85,
        "precision": 0.82,
        "recall": 0.88
      },
      "features": ["recency_days", "freq_90d", "value_90d"],
      "registered_at": "2024-12-06T12:00:00Z"
    },
    {
      "model_name": "intent",
      "version": "20251205_100000",
      "status": "archived",
      "created_at": "2024-12-05T10:00:00Z",
      "registered_at": "2024-12-05T10:00:00Z"
    }
  ],
  "active_version": {
    "model_name": "intent",
    "version": "20251206_120000",
    "status": "active",
    "created_at": "2024-12-06T12:00:00Z",
    "metrics": {
      "accuracy": 0.85,
      "precision": 0.82,
      "recall": 0.88
    },
    "features": ["recency_days", "freq_90d", "value_90d"],
    "registered_at": "2024-12-06T12:00:00Z"
  }
}

Campos da Resposta:
- model_name: Nome do modelo
- versions: Lista de todas as versões (ordenadas por data, mais recente primeiro)
- active_version: Versão atualmente ativa (ou null se nenhuma)

Erros:
- 503: Model Registry não disponível

3. Versions API

Base Path: /models/{model_name}/versions

3.1 Listar Versões

Endpoint: GET /models/{model_name}/versions

Descrição: Lista todas as versões de um modelo.

Parâmetros de Path:
- model_name (string, obrigatório) - Nome do modelo

Exemplo:

curl "https://csuite.internut.com.br/model-registry/models/intent/versions"

Resposta:

{
  "model_name": "intent",
  "versions": [
    {
      "model_name": "intent",
      "version": "20251206_120000",
      "status": "active",
      "created_at": "2024-12-06T12:00:00Z",
      "metrics": {
        "accuracy": 0.85,
        "precision": 0.82,
        "recall": 0.88
      },
      "features": ["recency_days", "freq_90d", "value_90d"],
      "registered_at": "2024-12-06T12:00:00Z"
    },
    {
      "model_name": "intent",
      "version": "20251205_100000",
      "status": "archived",
      "created_at": "2024-12-05T10:00:00Z",
      "registered_at": "2024-12-05T10:00:00Z"
    }
  ]
}

Erros:
- 503: Model Registry não disponível

3.2 Obter Informações de Versão

Endpoint: GET /models/{model_name}/versions/{version}

Descrição: Obtém informações detalhadas de uma versão específica.

Parâmetros de Path:
- model_name (string, obrigatório) - Nome do modelo
- version (string, obrigatório) - Versão do modelo (ex: 20251206_120000)

Exemplo:

curl "https://csuite.internut.com.br/model-registry/models/intent/versions/20251206_120000"

Resposta:

{
  "model_name": "intent",
  "version": "20251206_120000",
  "status": "active",
  "created_at": "2024-12-06T12:00:00Z",
  "activated_at": "2024-12-06T12:05:00Z",
  "metrics": {
    "accuracy": 0.85,
    "precision": 0.82,
    "recall": 0.88,
    "f1_score": 0.85,
    "auc_roc": 0.92
  },
  "features": [
    "recency_days",
    "freq_90d",
    "value_90d",
    "avg_order_value",
    "preferred_channel"
  ],
  "training_config": {
    "algorithm": "xgboost",
    "hyperparameters": {
      "max_depth": 6,
      "learning_rate": 0.1,
      "n_estimators": 100
    },
    "train_size": 10000,
    "test_size": 2000
  },
  "registered_at": "2024-12-06T12:00:00Z",
  "model_path": "s3://csuite-models/intent/20251206_120000/model.pkl"
}

Campos da Resposta:
- model_name: Nome do modelo
- version: Versão do modelo
- status: Status (staging, active, archived)
- created_at: Data de criação
- activated_at: Data de ativação (se ativa)
- metrics: Métricas de performance (accuracy, precision, recall, etc.)
- features: Lista de features usadas no treinamento
- training_config: Configuração de treinamento (algoritmo, hiperparâmetros, etc.)
- registered_at: Data de registro
- model_path: Caminho do modelo (S3 ou local)

Erros:
- 404: Versão não encontrada
- 503: Model Registry não disponível

4. Activation API

Base Path: /models/{model_name}/versions/{version}/activate

4.1 Ativar Versão

Endpoint: POST /models/{model_name}/versions/{version}/activate

Descrição: Ativa uma versão do modelo (marca como active e desativa outras versões).

Parâmetros de Path:
- model_name (string, obrigatório) - Nome do modelo
- version (string, obrigatório) - Versão do modelo

Exemplo:

curl -X POST "https://csuite.internut.com.br/model-registry/models/intent/versions/20251206_120000/activate"

Resposta:

{
  "model_name": "intent",
  "version": "20251206_120000",
  "status": "activated"
}

Comportamento:
1. Verifica se a versão existe
2. Desativa todas as outras versões ativas do mesmo modelo (marca como archived)
3. Ativa a versão especificada (marca como active)
4. Atualiza activated_at com timestamp atual

Erros:
- 400: Falha ao ativar versão (versão não existe ou erro ao atualizar)
- 503: Model Registry não disponível

Casos de Uso:
- Deploy de nova versão em produção
- Rollback para versão anterior
- Ativação após validação em staging

5. Exemplos Práticos

5.1 Fluxo Completo: Listar → Ver Versão → Ativar

# 1. Listar todos os modelos
curl "https://csuite.internut.com.br/model-registry/models"

# 2. Ver informações do modelo intent
curl "https://csuite.internut.com.br/model-registry/models/intent"

# 3. Ver detalhes de uma versão específica
curl "https://csuite.internut.com.br/model-registry/models/intent/versions/20251206_120000"

# 4. Ativar versão
curl -X POST "https://csuite.internut.com.br/model-registry/models/intent/versions/20251206_120000/activate"

# 5. Verificar versão ativa
curl "https://csuite.internut.com.br/model-registry/models/intent"

5.2 Rollback para Versão Anterior

# 1. Listar versões do modelo
curl "https://csuite.internut.com.br/model-registry/models/intent/versions"

# 2. Identificar versão anterior (ex: 20251205_100000)
# 3. Ativar versão anterior
curl -X POST "https://csuite.internut.com.br/model-registry/models/intent/versions/20251205_100000/activate"

# 4. Verificar que versão anterior está ativa
curl "https://csuite.internut.com.br/model-registry/models/intent"

5.3 Verificar Status de Todos os Modelos

# Listar todos os modelos e suas versões ativas
curl "https://csuite.internut.com.br/model-registry/models" | \
  python3 -c "import sys, json; data = json.load(sys.stdin); \
  [print(f\"{model}: {v.get('version') if (v := next((v for v in versions if v.get('status') == 'active'), None)) else 'Nenhuma versão ativa'}\") \
  for model, versions in data.items() if isinstance(versions, list)]"

5.4 Comparar Métricas de Versões

# Obter métricas de versão atual
curl "https://csuite.internut.com.br/model-registry/models/intent/versions/20251206_120000" | \
  python3 -c "import sys, json; data = json.load(sys.stdin); print(f\"Accuracy: {data.get('metrics', {}).get('accuracy')}\")"

# Obter métricas de versão anterior
curl "https://csuite.internut.com.br/model-registry/models/intent/versions/20251205_100000" | \
  python3 -c "import sys, json; data = json.load(sys.stdin); print(f\"Accuracy: {data.get('metrics', {}).get('accuracy')}\")"

6. Troubleshooting

Erro: "Not Found" (404)

Verifique se o serviço csuite-model-registry está rodando
Verifique se o path está correto (/model-registry/models, etc.)
Verifique se o endpoint existe na documentação OpenAPI

Erro: "Model Registry não disponível" (503)

Verifique se common_model_registry está disponível
Verifique se MODEL_REGISTRY_S3_BUCKET ou MODEL_REGISTRY_LOCAL_PATH está configurado
Verifique logs do serviço para erros de inicialização
O serviço funciona em modo degradado (retorna estruturas vazias)

Erro: "Versão não encontrada" (404)

Verifique se a versão existe: GET /models/{model_name}/versions
Verifique se o nome da versão está correto (case-sensitive)
Verifique se o modelo existe: GET /models

Erro: "Falha ao ativar versão" (400)

Verifique se a versão existe antes de ativar
Verifique se há permissões de escrita no S3 ou sistema de arquivos
Verifique logs do serviço para erros específicos
Verifique se o metadata.json está acessível

Versões não aparecem

Verifique se modelos foram registrados corretamente
Verifique se S3 bucket ou diretório local está acessível
Verifique se metadata.json existe para cada versão
Verifique logs do serviço para erros de listagem

Modo Degradado

Se registry_available: false:
- O serviço funciona mas retorna estruturas vazias
- Verifique configuração de MODEL_REGISTRY_S3_BUCKET ou MODEL_REGISTRY_LOCAL_PATH
- Verifique se common_model_registry está disponível
- Verifique se boto3 está instalado (para S3)

S3 não acessível

Verifique credenciais AWS (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
Verifique região AWS (AWS_DEFAULT_REGION)
Verifique permissões do bucket S3
Verifique conectividade de rede com S3

7. Documentação Relacionada

7.1 Documentação Interna

Common Model Registry: common/common_model_registry.py
Docker Stack: csuite-model-registry/docker-stack.yml

7.2 Integrações

Scoring Service (4C): Consome modelos do registry
ML Pipeline: Registra novos modelos no registry
Feature Store: Features usadas no treinamento são armazenadas no registry

8. Schema de Armazenamento

Estrutura S3

s3://csuite-models/
  intent/
    20251206_120000/
      metadata.json
      model.pkl
    20251205_100000/
      metadata.json
      model.pkl
  offer/
    20251206_110000/
      metadata.json
      model.pkl

Estrutura Local

/app/models/
  intent/
    20251206_120000/
      metadata.json
      model.pkl
    20251205_100000/
      metadata.json
      model.pkl
  offer/
    20251206_110000/
      metadata.json
      model.pkl

Formato de metadata.json

{
  "model_name": "intent",
  "version": "20251206_120000",
  "status": "active",
  "created_at": "2024-12-06T12:00:00Z",
  "activated_at": "2024-12-06T12:05:00Z",
  "metrics": {
    "accuracy": 0.85,
    "precision": 0.82,
    "recall": 0.88,
    "f1_score": 0.85,
    "auc_roc": 0.92
  },
  "features": [
    "recency_days",
    "freq_90d",
    "value_90d"
  ],
  "training_config": {
    "algorithm": "xgboost",
    "hyperparameters": {
      "max_depth": 6,
      "learning_rate": 0.1,
      "n_estimators": 100
    },
    "train_size": 10000,
    "test_size": 2000
  },
  "registered_at": "2024-12-06T12:00:00Z"
}

9. Configuração

Variáveis de Ambiente

# S3 (Produção)
MODEL_REGISTRY_S3_BUCKET=csuite-models
AWS_ACCESS_KEY_ID=***
AWS_SECRET_ACCESS_KEY=***
AWS_DEFAULT_REGION=sa-east-1

# Local (Desenvolvimento)
MODEL_REGISTRY_LOCAL_PATH=/app/models

# Path
ROOT_PATH=/model-registry

10. Próximos Passos

Adicionar endpoint de registro de novos modelos via API
Adicionar endpoint de download de modelos
Adicionar validação de métricas antes de ativar
Adicionar A/B testing de versões
Adicionar monitoramento de performance em produção
Adicionar alertas para degradação de performance

11. Documentação OpenAPI

Swagger UI: https://csuite.internut.com.br/model-registry/docs

OpenAPI JSON: https://csuite.internut.com.br/model-registry/openapi.json

ReDoc: https://csuite.internut.com.br/model-registry/redoc

Última atualização: 2024-12-20
Versão: 0.1.0

Guia de Uso - APIs /model-registry

📋 Índice

1. Visão Geral

Objetivos

Modelos Suportados

Armazenamento

Status de Versões

2. Models API

2.1 Listar Modelos

2.2 Obter Informações de Modelo

3. Versions API

3.1 Listar Versões

3.2 Obter Informações de Versão

4. Activation API

4.1 Ativar Versão

5. Exemplos Práticos

5.1 Fluxo Completo: Listar → Ver Versão → Ativar

5.2 Rollback para Versão Anterior

5.3 Verificar Status de Todos os Modelos

5.4 Comparar Métricas de Versões

6. Troubleshooting

Erro: "Not Found" (404)

Erro: "Model Registry não disponível" (503)

Erro: "Versão não encontrada" (404)

Erro: "Falha ao ativar versão" (400)

Versões não aparecem

Modo Degradado

S3 não acessível

7. Documentação Relacionada

7.1 Documentação Interna

7.2 Integrações

8. Schema de Armazenamento

Estrutura S3

Estrutura Local

Formato de metadata.json

9. Configuração

Variáveis de Ambiente

10. Próximos Passos

11. Documentação OpenAPI

🔊 Text-to-Speech

Guia de Uso - APIs `/model-registry`