Acionar Jobs quando modelos são atualizados

Use gatilhos de atualização de modelo para executar automaticamente um Job quando uma alteração de modelo ocorrer no Unity Catalog. Este recurso substitui a necessidade de programações cron ou clusters persistentes para acompanhar as atualizações de modelo.

info

Beta

Gatilhos de atualização de modelo estão em Beta.

Gatilhos de atualização de modelo são projetados para duas personas primárias:

• Cientistas de dados podem acionar jobs quando uma nova versão do modelo estiver pronta ou quando um alias for definido, em um único modelo ou em vários modelos ao mesmo tempo. Por exemplo, você pode executar jobs de validação, teste ou promoção automaticamente sempre que um modelo de sua propriedade for alterado. Consulte Exemplo: Validar modelos em novas versões ou aliases.
• Administradores podem monitorar todos os modelos em um metastore inteiro (ou um esquema). Por exemplo, os administradores podem auditar automaticamente cada novo modelo à medida que são criados. Consulte Exemplo: auditar modelos em um esquema ou metastore.

Como funcionam os gatilhos de atualização de modelo

Um trigger de atualização de modelo monitora um escopo no Unity Catalog para um evento de modelo e aciona uma execução de job quando um evento correspondente ocorre. Quando você configura um trigger de atualização de modelo, você escolhe um **escopo** e uma **condição**.

Os escopos disponíveis incluem:

• Modelo : um único modelo registrado.
• Esquema : todos os modelos em um esquema.
• **Metastore**: Todos os modelos no metastore. Apenas um administrador de metastore pode configurar um trigger com escopo de metastore.

A condição determina quando acionar uma execução:

• Modelo Criado : Um novo modelo registrado é criado no escopo.
• A versão do modelo está pronta : Uma nova versão do modelo fica pronta no escopo.
• O alias do modelo está definido : um alias especificado é aplicado a uma versão do modelo. Você pode especificar até 10 aliases por gatilho, e o gatilho responde quando qualquer um deles é aplicado.

Gatilhos de atualização de modelo não geram custos adicionais além dos custos do provedor de cloud.

Atualizações em lote

Atualizações do modelo Trigger a sondagem de novos eventos aproximadamente uma vez por minuto. As alterações detectadas em cada intervalo de sondagem são processadas em lotes e passadas para a próxima execução de Job como parâmetros de Job. Veja Parâmetros de Job associados a Trigger de atualização do modelo.

Uma única execução de Job processa no máximo nove atualizações. Quando mais de nove atualizações estão pendentes, o trigger processa nove na execução atual e transfere o restante para execuções posteriores, um lote por intervalo de pesquisa. Isso significa que o trigger drena as atualizações pendentes a uma taxa de até nove por minuto (aproximadamente 540 por hora).

Pequenos picos acima dessa taxa são normais e desaparecem nos minutos seguintes. Se um escopo produzir atualizações mais rápido do que o trigger pode processá-las por um período prolongado, o trigger será executado em cada intervalo sem conseguir acompanhar e, eventualmente, falhará e parará. Consulte Volume de eventos elevado e contínuo.

Volume de Eventos Alto e Sustentado

Um trigger de atualização de modelo funciona melhor para escopos onde as atualizações chegam, em média, a nove por minuto ou abaixo disso.

Para evitar um backlog cada vez maior, um trigger que é executado em cada intervalo de sondagem continuamente por aproximadamente uma hora falha e para. A falha é relatada no trigger. O trigger não se recupera automaticamente, e nenhuma outra execução começa até que você o recupere manualmente.

Para recuperar o Trigger:

1. Reduza a taxa de atualizações para que não exceda mais nove por minuto. Por exemplo, reduza o escopo do trigger ou divida o monitoramento entre múltiplos triggers, conforme descrito nas recomendações abaixo. Se você pular este passo, o trigger falha novamente após a recuperação.
2. Reset o trigger pausando-o e retomando-o. Pausar limpa o estado acumulado do trigger para que ele seja retomado do ponto atual. Use a seção **Programações e Triggers** do painel **Detalhes do Job**, ou pause_status defina PAUSED para e, em seguida, para UNPAUSED com a API Jobs. Consulte Gerenciar um trigger existente.

As opções avançadas Tempo mínimo entre triggers e Esperar após a última alteração controlam a frequência com que as execuções são criadas, mas elas não alteram quantas atualizações uma execução processa. Elas não evitam essa falha quando as atualizações excedem consistentemente nove por minuto.

Para monitorar um escopo de alto volume de forma confiável:

• Restrinja o escopo de cada trigger. Use triggers com escopo de esquema ou modelo em vez de um único trigger com escopo de metastore, para que um pico em uma área não interrompa o monitoramento para o metastore inteiro.
• Divida o monitoramento entre vários triggers e jobs para que cada trigger monitore um escopo de menor volume.
• Mantenha o Job Trigger leve e use uma tarefa For each para processar cada atualização. Consulte Processe as atualizações do modelo com uma tarefa For each.
• Para alto volume sustentado em um amplo escopo, entre em contato com a equipe de account do Databricks para discutir as opções.

Antes de começar

Os seguintes são necessários para usar gatilhos de atualização de modelo:

• O workspace deve ter o Unity Catalog habilitado.
• Você deve ter privilégio EXECUTE no modelo ou esquema de destino que você deseja que o trigger monitore. Sem EXECUTE, leituras e gravações para esses modelos podem falhar.
• Para configurar um gatilho com escopo de metastore, você deve ser um administrador do metastore. Você também deve conceder a si mesmo permissão EXECUTE em todos os catálogos atuais e futuros no metastore para que o Job possa acessar qualquer modelo no Unity Catalog.

Adicionar um gatilho de atualização do modelo

Para adicionar um gatilho de atualização do modelo a um job existente:

1. Na barra lateral do seu workspace do Databricks, clique em Jobs & Pipelines .

2. Na lista de Jobs, clique no nome do Job ao qual você deseja adicionar um gatilho.

3. No painel Detalhes do Job à direita, clique em Adicionar acionador .

4. Em **Tipo de trigger**, selecione **Atualização de modelo**.

5. Em **Escopo**, selecione **Modelo**, **Esquema** ou **Metastore**, e então especifique o modelo ou esquema para monitorar.

6. Em Condição , selecione o evento a ser acionado:

   • Modelo criado
   • A versão do modelo está pronta
   • **O alias do modelo está definido**. Especifique até 10 aliases para monitorar. O gatilho responde quando qualquer um dos aliases especificados é definido.

7. (Opcional) Configure opções avançadas:

   • Tempo mínimo entre gatilhos em segundos : O tempo mínimo para aguardar para acionar uma execução após uma execução anterior. Modelos atualizados durante este período acionam uma execução somente após o tempo de espera expirar. Use esta configuração para controlar a frequência de criação de execução.
   • **Aguardar após a última alteração em segundos**: o tempo para aguardar para acionar uma execução após uma atualização de modelo. Outra atualização de modelo durante este período reinicia o temporizador. Esta configuração pode ser usada quando as atualizações de modelo chegam em lotes, e o lote inteiro precisa ser processado depois que todas as atualizações chegam.

8. Para validar a configuração, clique em Testar gatilho . Se não houver erros, o botão mostrará Sucesso .

9. Clique em Salvar .

Depois de salvar o trigger, espere aproximadamente um minuto para o trigger inicializar. A mensagem **O trigger será avaliado em breve** indica que a inicialização está em andamento. Após a inicialização, qualquer evento de modelo correspondente no escopo aciona uma execução de Job.

Para editar, pausa ou remover este acionador mais tarde, use a seção **Programações e triggers** do painel **Detalhes do Job**. Consulte Gerenciar um acionador existente.

nota

Você também pode configurar triggers de atualização de modelo na API de Jobs. Consulte Configurar um gatilho de atualização de modelo com a API de Jobs.

Exemplo: Validar modelos em novas versões ou aliases

Para executar um Job de validação, teste ou promoção quando um modelo for alterado, configure um gatilho com o escopo **Modelo** e a condição **Versão do modelo está pronta** ou **Alias do modelo está definido**. Para alterações de alias, especifique os aliases a serem monitorados, como prod e staging. Para monitorar vários modelos ao mesmo tempo, use o escopo **Esquema** em vez disso. Após o gatilho ser inicializado, uma alteração correspondente em um modelo monitorado aciona uma execução de Job.

Exemplo: Auditar modelos em um esquema ou metastore

Para auditar cada modelo criado em um esquema ou metastore, configure um trigger com o escopo **Esquema** ou **Metastore** e a condição **Modelo é criado**. Depois que o trigger é inicializado, qualquer modelo criado no escopo aciona uma execução de job que pode registrar ou validar a alteração.

Parâmetros de Job associados a gatilhos de atualização de modelo

Quando um trigger de atualização de modelo é acionado, as informações sobre as alterações que acionaram a execução estão disponíveis para a execução do Job por meio da referência de valor dinâmico {{job.trigger.model.updates}}. O valor é uma lista JSON das atualizações de modelo no lote:

JSON

[
  {
    "full_name": "model.full.name1",
    "version": 123,
    "alias_name": "prod"
  }
]

Os campos são preenchidos da seguinte forma:

• full_name: Sempre preenchido com o nome do modelo que foi criado ou atualizado.
• version: Preenchido para eventos de A versão do modelo está pronta com a versão que ficou pronta, e para eventos de O alias do modelo foi definido com a versão que teve o alias definido.
• alias_name: Preenchido apenas para eventos de O alias do modelo foi definido com o nome do alias que foi definido.

Por exemplo, o valor do parâmetro para cada condição é o seguinte:

• **Modelo é criado**:

  JSON

  [{ "full_name": "model.number.one" }, { "full_name": "model.number.two" }]

• **Versão do modelo está pronta**:

  JSON

  [
    { "full_name": "model.number.one", "version": 7 },
    { "full_name": "model.number.two", "version": 3 }
  ]

• **Alias do modelo está definido**:

  JSON

  [
    { "full_name": "model.number.one", "version": 7, "alias_name": "prod" },
    { "full_name": "model.number.two", "version": 3, "alias_name": "staging" }
  ]

Para disponibilizar as atualizações para uma tarefa, adicione um parâmetro de Job cujo valor é {{job.trigger.model.updates}}. Para adicionar um parâmetro, clique em Editar parâmetros no painel lateral do Job, em seguida, defina o valor do parâmetro como {{job.trigger.model.updates}}. Para mais informações sobre parâmetros do Job, consulte Parametrizar Jobs.

O Notebook a seguir lê um parâmetro chamado events e processa as atualizações de modelo passadas para a execução:

Python

import json

json_list = dbutils.widgets.get("events")
data = json.loads(json_list)

for item in data:
    print(f"Full Name: {item['full_name']}, Version: {item.get('version')}, Alias Name: {item.get('alias_name')}")

Processar atualizações de modelo com uma tarefa Para cada

Uma tarefa For each executa uma tarefa aninhada uma vez por elemento em uma lista. Para gatilhos de atualização de modelo, você pode executar uma iteração por elemento em {{job.trigger.model.updates}}:

1. Configure a tarefa **Para cada** para {{job.trigger.model.updates}} receber como sua entrada.
2. Configure a tarefa aninhada para ler os valores de cada entrada fornecida pela iteração.
3. Os valores de cada atualização estão disponíveis como parâmetros de widget para a tarefa aninhada.

O notebook a seguir lê os valores por iteração em uma tarefa aninhada:

Python

full_name = dbutils.widgets.get("full_name")
version = dbutils.widgets.get("version")
alias_name = dbutils.widgets.get("alias_name")

print(f"Full Name: {full_name}, Version: {version}, Alias Name: {alias_name}")

Configure um trigger de atualização de modelo com a API de Jobs

É possível configurar um trigger de atualização de modelo adicionando um objeto trigger a uma operação jobs/create, jobs/update ou jobs/reset. O exemplo a seguir usa jobs/update:

JSON

{
  "job_id": 574587036927544,
  "new_settings": {
    "trigger": {
      "pause_status": "UNPAUSED",
      "model": {
        "securable_name": "main.default",
        "condition": "MODEL_ALIAS_SET",
        "aliases": ["alias1", "alias2"],
        "min_time_between_triggers_seconds": 3600,
        "wait_after_last_change_seconds": 120
      }
    },
    "parameters": [
      {
        "default": "{{job.trigger.model.updates}}",
        "name": "events"
      }
    ]
  }
}

Para o objeto de gatilho model:

• securable_name: O esquema ou modelo a ser monitorado. Deixe em branco ou omita-o para monitorar o metastore inteiro.
• condition: Um de MODEL_CREATED, MODEL_VERSION_READY ou MODEL_ALIAS_SET.
• aliases: Os aliases a serem monitorados. Aplica-se apenas à condição MODEL_ALIAS_SET.

Receber notificações de falhas de gatilhos de atualização de modelo

Para ser notificado se um gatilho de atualização de modelo falhar ao avaliar, configure notificações por email ou destino do sistema em caso de falha do Job. Consulte Adicionar notificações em um Job.

Limitações

Gatilhos de atualização de modelo têm as seguintes limitações:

• Um máximo de 100 gatilhos de atualização de modelo podem ser configurados por workspace. Esse limite pode ser aumentado caso a caso.
• Uma única execução de Job processa no máximo nove atualizações de modelo. Atualizações pendentes adicionais são processadas em execuções posteriores, até nove por minuto. Consulte Atualizações em lotes.
• Cada trigger de atualização de modelo pode monitorar até 10 aliases.
• Se um trigger é executado continuamente em cada intervalo de sondagem por aproximadamente uma hora, ele falha com um erro e para de acionar execuções. Não se recupera automaticamente: é preciso reduzir a taxa de atualizações e, em seguida, Reset o Trigger pausando-o e despausando-o. Isso acontece quando um escopo produz atualizações mais rapidamente do que o trigger pode processá-las por um período prolongado. Consulte Volume de Eventos Alto e Sustentado.
• Para configurar um gatilho com escopo de metastore, você deve ser um administrador de metastore e deve conceder a si mesmo o privilégio EXECUTE em cada catálogo atual e futuro no Unity Catalog para o Job acessar qualquer modelo.

Perguntas frequentes

Quando devo usar Jobs de implantação em vez de gatilhos de atualização de modelo?

Use gatilhos de atualização de modelo quando precisar:

• Monitore eventos de criação de modelo ou alterações de alias.
• Monitore eventos em um escopo mais amplo que um único modelo, como um esquema ou metastore.
• Monitore vários modelos com um único trigger, em vez de configurar um job separado para cada modelo.

Use jobs de implantação quando precisar de acoplamento estreito da UI e logs de atividade sobre a relação entre a criação de versão do modelo e as execuções de job.