Documentação do Oracle Cloud Infrastructure

Aciona

Os acionadores permitem que os provedores de Aplicativos de ML especifiquem o mecanismo de acionamento para seus jobs ou pipelines de ML, facilitando a implementação do MLOps totalmente automatizado.

Triggers são os pontos de entrada para as execuções dos workflows de ML e são definidos por arquivos YAML dentro do pacote de Aplicativos de ML como componentes de instância. Os acionadores são criados automaticamente quando uma nova Instância do Aplicativo ML é criada, mas somente quando todos os outros componentes da instância são criados. Assim, quando um trigger é criado, ele pode se referir a outros componentes de instância criados anteriormente. Os jobs ou Pipelines de ML que fazem parte do seu aplicativo podem ser acionados por meio da definição de triggers como componentes de instância em seu Aplicativo de ML. Os acionadores permitem que provedores e consumidores iniciem execuções de alguns fluxos de trabalho.

Na definição do acionador, os provedores podem especificar:
Alvo do trigger
Define o que é executado. Por exemplo, um novo pipeline ou execução de job é criado quando o trigger é ativado ou chamado.
Condição de trigger
Define quando o acionador é executado. Você pode definir quais pontos finais HTTP (WebHooks) ativam ou chamam o trigger ou eventos, como instance was created.
Parâmetros do trigger
Defina quais parâmetros podem ser passados para o acionador após sua ativação (chamada). Você pode transmitir os valores de parâmetro ainda mais para o alvo do trigger. Por exemplo, você pode especificar uma referência a uma imagem de contêiner iniciada em seu pipeline ou job.
Os triggers podem ser ativados ou chamados por:
Acionamento baseado em HTTP
Os acionadores podem ser acionados em resposta a solicitações HTTP. Dois pontos finais que permitem aos usuários fazer solicitações HTTP para disparar triggers.
  • Ponto final do provedor: Disponível no recurso de View da Instância do Aplicativo ML, ele deve ser usado pelos provedores.
  • Ponto final do consumidor: Disponível no recurso Instância do Aplicativo ML, ele deve ser usado pelos consumidores.
  • Os provedores de Aplicativos ML têm a opção de ativar esses pontos finais em qualquer combinação da seguinte forma:
    • Somente ponto final do provedor.
    • Somente ponto final do consumidor.
    • Pontos finais do provedor e do consumidor.
    • Nenhuma
Acionamento baseado em evento
Os acionadores são acionados em resposta a um evento de ciclo de vida em um recurso específico. O único recurso suportado é a Instância do Aplicativo ML. Os eventos de ciclo de vida suportados são:
  • Criando uma Instância de Aplicativo de ML: permita que os provedores implementem Aplicativos de ML com uma execução de treinamento único.
  • Atualização da Instância do Aplicativo ML: permite que os provedores adicionem a capacidade de treinar novamente o modelo quando uma nova versão da Implementação do Aplicativo ML (por exemplo, com um novo algoritmo de treinamento) for implantada.

O destino do trigger é um payload de operação de criação para recursos do OCI que são criados quando a condição do trigger é atendida. Os tipos de destino suportados são DataScienceJobRun e DataSciencePipelineRun.

Nos alvos do trigger, você pode se referir a variáveis implícitas, por exemplo, 
${app_instance.instance_components.oci_objectstorage_bucket.data_storage_bucket.name}
ou parâmetros de acionamento, por exemplo, 
${parameters.docker_image_tag}
As referências implícitas a variáveis são substituídas por valores reais quando a instância é criada, atualizada ou submetida a upgrade. As referências de parâmetro são substituídas por valores quando o trigger é ativado. Para obter mais informações, consulte Variáveis Implícitas para Pacotes de Aplicativos ML ou Triggers Parametrizados.

Definindo Acionadores

Os acionadores são definidos como arquivos YAML no diretório instance_components do pacote de aplicativos. Os arquivos acionadores usam a extensão .trigger.yaml e devem seguir o esquema da seguinte forma:

  • apiVersion
    • descrição: a versão do esquema para este arquivo de configuração.
    • obrigatório: verdadeiro
    • tipo: string
  • tipo
    • descrição: o tipo de recurso (somente ml-application-trigger suportado).
    • obrigatório: verdadeiro
    • tipo: string
  • metadados
    • descrição: os metadados de um recurso específico.
    • obrigatório: verdadeiro
    • tipo: objeto (mapa)
    • propriedades (metadados suportados):
      • nome
        • descrição: o nome como um identificador para uma instância específica do recurso.
        • obrigatório: verdadeiro
        • tipo: string
  • especificação
    • descrição: a especificação de um recurso específico.
    • obrigatório: verdadeiro
    • tipo: objeto
    • propriedades:
      • parâmetros
        • descrição: Um mapa de parâmetros que podem ser passados para o gatilho após sua ativação (chamada).
        • obrigatório: falso
        • tipo: o mapa (nome do parâmetro mapeia para propriedades do parâmetro)
          • o nome do parâmetro deve corresponder a "\w+" regexp (pelo menos um caractere alfanumérico).
        • propriedades do parâmetro:
          • obrigatório
            • tipo: Booleano (verdadeiro ou falso)
            • obrigatório: falso (o padrão é falso)
            • Descrição: Se o argumento específico é obrigatório ou não.
              Observação

              Os parâmetros de trigger obrigatórios não são permitidos para triggers que tenham consumerEndpoint ou qualquer tipo de condição baseada em evento.
          • descrição
            • tipo: string
            • obrigatório: falso
            • descrição: A descrição do parâmetro.
          • validationRegexp
            • tipo: string
            • obrigatório: falso
            • descrição: A expressão regular usada para validação do valor do argumento.
          • defaultValue
            • tipo: string
            • obrigatório: falso
            • descrição: O valor usado quando o parâmetro não é especificado na solicitação de ativação (chamada). É necessário especificar um valor padrão para parâmetros opcionais. Ela pode ser especificada para parâmetros obrigatórios. Quando validationRegexp for especificado, o valor padrão deverá corresponder.
      • condição
        • descrição: A condição que define quando o acionador é acionado.
        • obrigatório: verdadeiro
        • tipo: objeto
        • propriedades:
          • solicitações
            • descrição: A lista de origens para solicitações de acionador direto. Para cada solicitação, o gatilho tenta disparar.
            • necessário: um de
            • tipo: matriz de objetos
            • propriedades do tipo de item:
              • origem
                • descrição: A origem das solicitações de trigger: se estiver presente no array, significa que o trigger é acionado a pedido desse recurso.
                • obrigatório: verdadeiro
                • tipo: enumeração
                • valores de enumeração:
                  • providerEndpoint: se a origem com esse tipo for apresentada na seção solicitações, o acionamento usando a solicitação HTTP para provedores será ativado (/mlApplicationInstanceView/<mlApplicationInstanceViewId>/action/trigger).
                  • consumerEndpoint: se a origem com esse tipo for apresentada na seção solicitações, o acionamento usando a solicitação HTTP para consumidores será ativado (/mlApplicationInstance/<mlApplicationInstanceId>/action/trigger).
          • eventos
            • descrição: Eventos para os quais o acionador é acionado.
            • necessário: um de
            • tipo: array (itens são objetos polimórficos)

            • propriedades comuns para itens (pai: polimorfismo):

              • origem
                • Descrição: A origem do evento: se estiver presente na matriz, significa que o acionador é acionado com base nos eventos de entrada provenientes dessa origem de evento (a primeira parte do discriminador para vários eventos).
                • obrigatório: verdadeiro
                • tipo: enumeração
                • valores de enumeração:
                  • mlApplicationInstance: A instância de Aplicativos ML é uma origem de evento. Tipos suportados: onCreate, onVersionUpgrade
              • type
                • Descrição: O tipo de evento (propriedade comum para todas as fontes de evento: a segunda parte do discriminador para eventos).
                • obrigatório: verdadeiro
                • tipo: enumeração
                • valores de enumeração: com base na origem do evento
                  • origem: mlApplicationInstance

            • eventos suportados (filhos específicos:polimorfismo):

              • source: mlApplicationInstance, type: onCreate
                • descrição: o trigger é acionado na criação da instância de Aplicativos ML.
                • tipo: objeto (filho com delimitador composto: origem, tipo).
              • source: mlApplicationInstance, type: onVersionUpgrade
                • descrição: o trigger é acionado no upgrade de versão da Instância do Aplicativo ML.
                • tipo: objeto (filho com delimitador composto: origem, tipo)
                • propriedades:
                  • packageVersion
                    • descrição: O trigger é acionado somente quando a instância de Aplicativos ML é atualizada para a versão de implementação de Aplicativos ML com esta versão do pacote.
                    • obrigatório: verdadeiro
                    • tipo: string
                  • mlApplicationInstanceViewTagName
                    • descrição: O trigger é acionado somente quando a Instância do Aplicativo ML atualizada tem uma tag com esse nome (e valor definido).
                    • obrigatório: falso
                    • tipo: string
                  • mlApplicationInstanceViewTagValue
                    • descrição: O trigger é acionado somente quando a Instância do Aplicativo ML atualizada tem uma tag com esse valor (e nome definido).
                    • obrigatório: falso
                    • tipo: string
      • alvo
        • descrição: O alvo do trigger (por exemplo, JobRun).
        • tipo: objeto
        • propriedades:
          • type
            • descrição: o tipo de alvo do trigger.
            • tipo: enum (valores: DataScienceJobRun, DataSciencePipelineRun)
            • obrigatório: verdadeiro
          • modelo
            • descrição: Crie uma carga útil para um recurso usado como destino. Ela pode conter vários placeholders que são resolvidos dinamicamente e substituídos por valores reais. Existem dois tipos de placeholders: variáveis implícitas e parâmetros de trigger.
            • tipo: objeto (carga útil JSON esperada; observação: JSON é YAML válido)
            • obrigatório: verdadeiro

Definição YAML do Acionador de Exemplo

apiVersion: v1-beta
kind: ml-application-trigger
metadata:
  name: Training trigger
spec:
  parameters:
    docker_image_tag:
      description: "Tag of the docker image to be used by the DataScience Job"
      validationRegexp: ".+"
      defaultValue: "v1.0"
    scoring_threshold:
      validationRegexp: "[0-9]+"
      defaultValue: "10"
    an_optional_parameter_with_default:
      defaultValue: "v1.0"
    a_required_parameter:
      mandatory: true
      description: "This is a sample required parameter"
      validationRegexp: "abc.+"
    another_optional_parameter_with_default:
       mandatory: false
       defaultValue: "bar"
  condition:
    requests:
     :source: providerEndpoint # CP action for provider (provider set privilages)
     :source: consumerEndpoint # CP action for consumer (consumer set privilages)
    events:
     :source: mlApplicationInstance
        type: onCreate
     :source: mlApplicationInstance
        type: onVersionUpgrade
        packageVersion: 2.0
        mlApplicationInstanceViewTag: big-fish-customer    
   
  target:
    type: DataSciencePipelineRun
    template: {
      "projectId": "${app_impl.package_arguments.data_science_project_id}",
      "compartmentId": "${app.compartment_id}",
      "pipelineId": "${app_impl.application_components.oci_datascience_pipeline.ad_pipeline.id}",
      "stepOverrideDetails": [
        {
          "stepName": "ingestion",
          "stepConfigurationDetails": {
            "environmentVariables": {
              "MlApplicationInstance": "${app_instance.id}",
              "ML_APP_INST_OCID": "${app_instance.id}",
              "ENVIRONMENT_TYPE": "dev",
              "BIP_URL": "${app_instance.configuration.bip_url}",
              "BIP_USERNAME_SECRET_ID": "${app_instance.configuration.bip_username_secret_id}",
              "BIP_PASSWORD_SECRET_ID": "${app_instance.configuration.bip_password_secret_id}",
              "INGREDIENT_BUCKET": "${app_instance.instance_components.oci_objectstorage_bucket.data_storage_bucket.name}",
              "INGREDIENT_OBJECT": "${app_impl.package_arguments.ingredient_object_path_name}",
              "OS_NAMESPACE": "${app_impl.package_arguments.bucket_namespace}",
              "TARGET_INGESTION_PATH": "${app_impl.package_arguments.target_ingestion_dir}",
              "METRICS_NAMESPACE": "${app_impl.package_arguments.monitoring_namespace}",
              "METRICS_COMPARTMENT_ID": "${app.compartment_id}",
              "ML_APP_NAME": "${ml_app_name}",
              "ML_APP_IMPL_NAME":"${ml_app_impl_name}",
              "ML_APP_PACKAGE_VERSION":"1.11",
              "INGREDIENT_PATH":"${app_impl.package_arguments.ingredient_object_path_name}",
              "DIMENSION_CUSTOM": "CustomDimension1",
              "TENANT": "idsc-stripe"
            }
          }
        },
        {
          "stepName": "transformation",
          "stepConfigurationDetails": {
            "environmentVariables": {
              "MlApplicationInstance": "${app_instance.id}",
              "CUSTOMER_BUCKET": "${app_instance.instance_components.oci_objectstorage_bucket.data_storage_bucket.name}",
              "OS_NAMESPACE": "${app_impl.package_arguments.bucket_namespace}",
              "INPUT_FOLDER": "${app_impl.package_arguments.transformation_input_dir}",
              "OUTPUT_FOLDER": "${app_impl.package_arguments.transformation_output_dir}",
              "NUMBER_OF_WEEKS_TO_KEEP": "${app_impl.package_arguments.number_of_weeks_to_keep}"
            }
          }
        },
        {
          "stepName": "training",
          "stepConfigurationDetails": {
            "environmentVariables": {
              "MlApplicationInstance": "${app_instance.id}",
              "docker-image-tag": "${parameters.docker_image_tag}",
              "scoring-threshold": "${parameters.scoring_threshold}",
              "CUSTOMER_BUCKET": "${app_instance.instance_components.oci_objectstorage_bucket.data_storage_bucket.name}",
              "CONTAINER_ENTRYPOINT": "\"train\", \"oci://${app_instance.instance_components.oci_objectstorage_bucket.data_storage_bucket.name}/data/\", \"-a\", \"{\"refresh_date\":\"2030-01-01\", \"disable_requester_id\":\"1\"}\", \"-p\", \"http://pg\", \"-n\", \"ac_df_test_namespace\"",
              "MODEL_DEPLOYMENT_ID": "${app_instance.instance_components.oci_datascience_model_deployment.tf_model_deployment.id}"
            }
          }
        }
      ]
    }
Observação

  • O apiVersion atual (para esquema de definição de trigger) é v1-beta.
  • kind sempre deve ser ml-application-trigger.
  • requests ou events deve ser especificado. Uma definição de trigger que não especifica requests nem events é inválida.
  • requests, sempre que especificado, não deve ficar vazio.
  • events, sempre que especificado, não deve ficar vazio.
  • Sobre o tipo de evento Upgrade da Versão da Instância do Aplicativo ML (Origem: mlApplicationInstance, tipo: onCreate):
    • Sempre que mlApplicationInstanceViewTagName for especificado, mlApplicationInstanceViewTagValue também deverá ser especificado.
    • Sempre que mlApplicationInstanceViewTagValue for especificado, mlApplicationInstanceViewTagName também deverá ser especificado.

    • Sempre que especificado, mlApplicationInstanceViewTagName e mlApplicationInstanceViewTagValue devem ser especificados.

  • O modelo para o tipo de destino DataScienceJobRun deve seguir o Esquema CreateJobRunDetails.

  • O modelo para o tipo de destino DataSciencePipelineRun deve seguir o Esquema CreatePipelineRunDetails.

  • Os valores usados no payload do modelo podem conter vários placeholders, conforme explicado em Variáveis Implícitas para Pacotes de Aplicativos ML.
  • Os placeholders devem usar o formato ${variable_name}, ou seja, o placeholder deve começar com $ e deve ser seguido pelo nome da variável entre chaves {}.
  • jobId no modelo DataScienceJobRun deve fazer referência a um componente do aplicativo DataScienceJob pertencente à Implementação do Aplicativo ML, ou resolvê-lo.
  • pipelineId no modelo DataSciencePipelineRun deve fazer referência a um componente de aplicativo DataSciencePipeline pertencente à Implementação de Aplicativos de ML ou resolvê-lo.
  • o design é definido em Definindo acionadores.

Informações sobre Pontos Finais Relacionados ao Trigger

Pontos Finais Relacionados ao Trigger
Ponto Final Recurso Relacionado Permissão Necessária Utilizado Por
/mlApplicationInstances/<mlApplicationInstanceId>/actions/trigger Instância do Aplicativo ML DATA_SCIENCE_APPLICATION_INSTANCE_TRIGGER Consumidores
/mlApplicationInstanceViews/<mlApplicationInstanceViewId>/actions/trigger ML - Visualização da Instância do Aplicativo DATA_SCIENCE_APPLICATION_INSTANCE_VIEW_TRIGGER Provedores
/mlApplicationInstanceViews/<mlApplicationInstanceViewId>/actions/disableTrigger ML - Visualização da Instância do Aplicativo DATA_SCIENCE_APPLICATION_INSTANCE_VIEW_READDATA_SCIENCE_APPLICATION_INSTANCE_VIEW_UPDATE Provedores
/mlApplicationInstanceViews/<mlApplicationInstanceViewId>/actions/enableTrigger ML - Visualização da Instância do Aplicativo DATA_SCIENCE_APPLICATION_INSTANCE_VIEW_READDATA_SCIENCE_APPLICATION_INSTANCE_VIEW_UPDATE Provedores

Triggers Parametrizados

Os acionadores podem parametrizar alvos (execuções de Job ou Pipeline) fazendo referência a variáveis implícitas. No entanto, as variáveis implícitas são atualizadas somente quando a instância é criada, atualizada ou submetida a upgrade. Quando você precisar informar um parâmetro específico com um valor que seja conhecido apenas no momento da ativação do trigger (chamada), poderá usar parâmetros de trigger.

Os parâmetros do acionador podem ser definidos opcionalmente no arquivo YAML do acionador. Quando os parâmetros são definidos, você pode incluir seus nomes e valores no payload das solicitações de ativação (chamada) do trigger. Todas as suas referências aos parâmetros na definição de destino são substituídas pelos valores reais fornecidos na carga útil da solicitação.

Para ativar (chamar) um trigger parametrizado, você precisa enviar um HTTP POST para o ponto final do trigger. Por exemplo:

Ativação do Trigger Parametrizado:
oci raw-request --auth security_token --http-method POST \
    --target-uri https://<region>/20190101/mlApplicationInstanceViews/<ocidid>/actions/trigger \
  --request-body file://./triggerInvocationPayload.json
Solicitação de Trigger Parametrizado:
{
    "triggerName": "training job",
    "parameters": [
        {
            "name": "scoring_threshold",
            "value": "99"
        },
        {
            "name": "a_required_parameter",
            "value": "must_value"
        }
    ]
}

Triggers e Controladores de Recursos

Os acionadores que são definidos por provedores em pacotes de Aplicativos ML como arquivos YAML podem ser expostos a provedores e consumidores. Provedores e consumidores podem ativar (disparar ou acionar) os gatilhos e iniciar uma execução de um pipeline ou job.

O controlador de recursos usado para iniciar a execução é diferente para chamadas de consumidor e provedor.

Quando os consumidores ativam acionadores, o controlador de recursos da Instância do Aplicativo ML é usado (datasciencemlappinstanceint). Por outro lado, quando os provedores ativam acionadores, o controlador de recursos da view Instância do Aplicativo ML é usado (datasciencemlappinstanceviewint).

Isso implica que você precisa definir políticas que permitam que a instância ou a instância exiba a criação do controlador de recursos. Como as execuções dependem da rede e do log, você deve permitir que os controladores de recursos usem a rede e o log também. Para obter detalhes, consulte a seção Configuração de Política.