Trigger

I trigger consentono ai provider di applicazioni ML di specificare il meccanismo di attivazione per i job o le pipeline ML, semplificando l'implementazione di MLOps completamente automatizzato.

I trigger sono i punti di accesso per le esecuzioni dei flussi di lavoro ML e sono definiti dai file YAML all'interno del package di applicazioni ML come componenti di istanza. I trigger vengono creati automaticamente quando viene creata una nuova istanza dell'applicazione ML, ma solo quando vengono creati tutti gli altri componenti dell'istanza. Pertanto, quando viene creato un trigger, può fare riferimento ad altri componenti dell'istanza creati in precedenza. I job o le pipeline ML che fanno parte dell'applicazione possono essere attivati definendo i trigger come componenti dell'istanza nell'applicazione ML. I trigger consentono a provider e consumer di avviare le esecuzioni di alcuni flussi di lavoro.

Nella definizione del trigger, i provider possono specificare:

Destinazione trigger: Definisce cosa viene eseguito. Ad esempio, viene creata una nuova pipeline o esecuzione del job quando il trigger viene attivato o richiamato.

Condizione di trigger: Definisce quando viene eseguito il trigger. È possibile definire quali endpoint HTTP (WebHooks) attivano o richiamano il trigger o gli eventi, ad esempio instance was created.

Parametri di trigger: Definire quali parametri possono essere passati al trigger al momento della sua attivazione (richiamo). È possibile passare i valori dei parametri alla destinazione del trigger. Ad esempio, è possibile passare un riferimento a un'immagine del contenitore avviata nella pipeline o nel job.

I trigger possono essere attivati o richiamati da:

Attivazione basata su HTTP

I trigger possono essere attivati in risposta alle richieste HTTP. Due endpoint che consentono agli utenti di effettuare richieste HTTP per i trigger di attivazione.

Endpoint del provider: disponibile nella risorsa di visualizzazione dell'istanza dell'applicazione ML, destinato a essere utilizzato dai provider.
Endpoint del consumer: disponibile nella risorsa Istanza applicazione ML, è destinato a essere utilizzato dai consumer.
I provider di applicazioni ML hanno la possibilità di abilitare questi endpoint in qualsiasi combinazione come indicato di seguito.
- Solo endpoint provider.
- Solo endpoint consumer.
- Endpoint di provider e consumer.
- Nessuna.

Attivazione basata su eventi

I trigger vengono attivati in risposta a un evento del ciclo di vita su una determinata risorsa. L'unica risorsa supportata è l'istanza dell'applicazione ML. Gli eventi del ciclo di vita supportati sono:

Creazione di un'istanza dell'applicazione ML: consente ai provider di implementare le applicazioni ML con un'esecuzione di formazione una tantum.
Upgrade dell'istanza dell'applicazione ML: consente ai provider di aggiungere la possibilità di riqualificare il modello quando viene distribuita una nuova versione dell'implementazione dell'applicazione ML (ad esempio, con un nuovo algoritmo di formazione).

La destinazione trigger è un payload dell'operazione di creazione per le risorse OCI che vengono create quando viene soddisfatta la condizione trigger. I tipi di destinazione supportati sono DataScienceJobRun e DataSciencePipelineRun.

All'interno delle destinazioni trigger è possibile fare riferimento a variabili implicite, ad esempio

${app_instance.instance_components.oci_objectstorage_bucket.data_storage_bucket.name}

o parametri di attivazione, ad esempio,

${parameters.docker_image_tag}

I riferimenti alle variabili implicite vengono sostituiti con valori effettivi quando l'istanza viene creata, aggiornata o aggiornata. I riferimenti ai parametri vengono sostituiti con valori quando il trigger viene attivato. Per ulteriori informazioni, vedere Variabili implicite per package applicazioni ML o Trigger con parametri.

Definizione dei trigger

I trigger sono definiti come file YAML nella directory instance_components nel pacchetto dell'applicazione. I file dei trigger utilizzano l'estensione .trigger.yaml e devono seguire lo schema nel modo seguente:

apiVersion
- descrizione: la versione dello schema per questo file di configurazione.
- obbligatorio: true
- tipo: stringa
tipo
- descrizione: il tipo di risorsa (supportato solo ml-application-trigger).
- obbligatorio: true
- tipo: stringa
metadati
- descrizione: i metadati per una determinata risorsa.
- obbligatorio: true
- tipo: oggetto (mappa)
- proprietà (metadati supportati):
  - nome
    - descrizione: il nome come identificativo di una particolare istanza della risorsa.
    - obbligatorio: true
    - tipo: stringa
specifica
- descrizione: la specifica di una particolare risorsa.
- obbligatorio: true
- tipo: oggetto
- proprietà:
  - parametri
    - descrizione: una mappa dei parametri che possono essere passati al trigger al momento della sua attivazione (richiamo).
    - richiesto: false
    - type: la mappa (il nome del parametro è mappato alle proprietà del parametro)
      - il nome del parametro deve corrispondere a "\w+" regexp (almeno un carattere alfanumerico).
    - proprietà parametro:
      - obbligatorio
        
        tipo: booleano (vero o falso)
        
        obbligatorio: false (l'impostazione predefinita è false)
        
        Descrizione: indica se l'argomento specifico è obbligatorio o meno.
        Nota
        
        I parametri trigger obbligatori non sono consentiti per i trigger con consumerEndpoint o qualsiasi tipo di condizione basata su eventi.
      - description
        
        tipo: stringa
        
        richiesto: false
        
        descrizione: la descrizione del parametro.
      - validationRegexp
        
        tipo: stringa
        
        richiesto: false
        
        descrizione: l'espressione regolare utilizzata per la convalida del valore dell'argomento.
      - defaultValue
        
        tipo: stringa
        
        richiesto: false
        
        descrizione: il valore utilizzato quando il parametro non è specificato nella richiesta di attivazione (richiamo). È necessario specificare il valore predefinito per i parametri facoltativi. Può essere specificato per i parametri obbligatori. Quando si specifica il valore validationRegexp, il valore predefinito deve corrispondere.
  - condizione
    - descrizione: la condizione che definisce quando il trigger viene attivato.
    - obbligatorio: true
    - tipo: oggetto
    - proprietà:
      - richieste
        
        descrizione: la lista delle origini per le richieste di trigger diretto. Per ogni richiesta di questo tipo, il trigger tenta di attivarsi.
        
        obbligatorio: uno dei
        
        type: array di oggetti
        
        proprietà del tipo di elemento:
        
        origine
        
        descrizione: l'origine delle richieste di trigger: se è presente nell'array, significa che il trigger viene attivato su richiesta di questa risorsa.
        
        obbligatorio: true
        
        tipo: enum
        
        valore di enumerazione:
        
        providerEndpoint: se l'origine con questo tipo è visualizzata nella sezione richieste, l'attivazione mediante richiesta HTTP per i provider è abilitata (/mlApplicationInstanceView/<mlApplicationInstanceViewId>/action/trigger).
        
        consumerEndpoint: se l'origine con questo tipo è visualizzata nella sezione richieste, l'attivazione mediante richiesta HTTP per i consumer è abilitata (/mlApplicationInstance/<mlApplicationInstanceId>/action/trigger).
      - eventi
        
        descrizione: eventi per i quali viene attivato il trigger.
        
        obbligatorio: uno dei
        
        tipo: array (gli elementi sono oggetti polimorfici)
        
        proprietà comuni degli oggetti (genitore:polimorfismo):
        
        origine
        
        Descrizione: L'origine dell'evento: se è presente nell'array significa che il trigger viene attivato in base agli eventi in entrata provenienti da questa origine dell'evento (la prima parte del discriminatore per vari eventi).
        
        obbligatorio: true
        
        tipo: enum
        
        valore di enumerazione:
        
        mlApplicationInstance: l'istanza delle applicazioni ML è un'origine evento. Tipi supportati: onCreate, onVersionUpgrade
        
        digitare
        
        descrizione: il tipo di evento (proprietà comune per tutte le origini evento: la seconda parte del discriminatore per gli eventi).
        
        obbligatorio: true
        
        tipo: enum
        
        valori di enumerazione: in base all'origine dell'evento
        
        fonte: mlApplicationInstance
        
        eventi supportati (bambini specifici:polimorfismo):
        
        origine: mlApplicationInstance, tipo: onCreate
        
        descrizione: il trigger viene attivato alla creazione dell'istanza delle applicazioni ML.
        
        tipo: oggetto (figlio con delimitatore composto: sorgente, tipo).
        
        origine: mlApplicationInstance, tipo: onVersionUpgrade
        
        descrizione: il trigger viene attivato nell'upgrade della versione dell'istanza dell'applicazione ML.
        
        tipo: oggetto (figlio con delimitatore composto: sorgente, tipo)
        
        proprietà:
        
        packageVersion
        
        descrizione: il trigger viene attivato solo quando l'istanza delle applicazioni ML viene aggiornata alla versione di implementazione delle applicazioni ML con questa versione del package.
        
        obbligatorio: true
        
        tipo: stringa
        
        mlApplicationInstanceViewTagName
        
        descrizione: il trigger viene attivato solo quando l'istanza dell'applicazione ML aggiornata dispone di una tag con questo nome (e valore definito).
        
        richiesto: false
        
        tipo: stringa
        
        mlApplicationInstanceViewTagValue
        
        descrizione: il trigger viene attivato solo quando l'istanza dell'applicazione ML aggiornata ha una tag con questo valore (e un nome definito).
        
        richiesto: false
        
        tipo: stringa
  - destinazione
    - descrizione: la destinazione del trigger (ad esempio, JobRun).
    - tipo: oggetto
    - proprietà:
      - digitare
        
        descrizione: il tipo di destinazione del trigger.
        
        tipo: enum (valori: DataScienceJobRun, DataSciencePipelineRun)
        
        obbligatorio: true
      - modello
        
        descrizione: crea un payload per una risorsa utilizzata come destinazione. Può contenere vari segnaposto risolti dinamicamente e sostituiti con valori effettivi. Esistono due tipi di segnaposto: variabili implicite e parametri trigger.
        
        type: object (payload JSON previsto, nota: JSON è YAML valido)
        
        obbligatorio: true

Definizione YAML trigger di esempio

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}"
            }
          }
        }
      ]
    }

Nota

Il valore apiVersion corrente (per lo schema di definizione del trigger) è v1-beta.
kind deve essere sempre ml-application-trigger.
È necessario specificare requests o events. Una definizione di trigger che non specifica né requests né events non è valida.
requests, se specificato, non deve essere vuoto.
events, se specificato, non deve essere vuoto.
Per quanto riguarda il tipo di evento Aggiornamento della versione dell'istanza dell'applicazione ML (origine: mlApplicationInstance, tipo: onCreate):
- Ogni volta che si specifica mlApplicationInstanceViewTagName, è necessario specificare anche mlApplicationInstanceViewTagValue.
- Ogni volta che si specifica mlApplicationInstanceViewTagValue, è necessario specificare anche mlApplicationInstanceViewTagName.
- Quando specificato, è necessario specificare sia mlApplicationInstanceViewTagName che mlApplicationInstanceViewTagValue.
Il modello per il tipo di destinazione DataScienceJobRun deve seguire lo schema CreateJobRunDetails.
Il modello per il tipo di destinazione DataSciencePipelineRun deve seguire lo schema CreatePipelineRunDetails.
I valori utilizzati nel payload del modello possono contenere vari segnaposto, come descritto in Variabili implicite per package applicazioni ML.
I segnaposto devono utilizzare il formato ${variable_name}, ovvero, il segnaposto deve iniziare con $ e deve essere seguito dal nome della variabile all'interno delle parentesi graffe {}.
jobId nel modello DataScienceJobRun deve fare riferimento o risolvere un componente dell'applicazione DataScienceJob appartenente all'implementazione dell'applicazione ML.
pipelineId nel modello DataSciencePipelineRun deve fare riferimento o risolvere un componente dell'applicazione DataSciencePipeline appartenente all'implementazione delle applicazioni ML.
la progettazione è definita in Definizione dei trigger.

Informazioni sugli endpoint correlati ai trigger

Endpoint correlati ai trigger
Endpoint	Risorsa correlata	Autorizzazione richiesta	Uso di
`/mlApplicationInstances/<mlApplicationInstanceId>/actions/trigger`	Istanza dell'applicazione ML	DATA_SCIENCE_APPLICATION_INSTANCE_TRIGGER	Consumer
`/mlApplicationInstanceViews/<mlApplicationInstanceViewId>/actions/trigger`	Vista dell'istanza dell'applicazione ML	DATA_SCIENCE_APPLICATION_INSTANCE_VIEW_TRIGGER	Provider
`/mlApplicationInstanceViews/<mlApplicationInstanceViewId>/actions/disableTrigger`	Vista dell'istanza dell'applicazione ML	DATA_SCIENCE_APPLICATION_INSTANCE_VIEW_READDATA_SCIENCE_APPLICATION_INSTANCE_VIEW_UPDATE	Provider
`/mlApplicationInstanceViews/<mlApplicationInstanceViewId>/actions/enableTrigger`	Vista dell'istanza dell'applicazione ML	DATA_SCIENCE_APPLICATION_INSTANCE_VIEW_READDATA_SCIENCE_APPLICATION_INSTANCE_VIEW_UPDATE	Provider

Trigger parametrizzati

I trigger possono parametrizzare le destinazioni (esecuzione job o pipeline) facendo riferimento a variabili implicite. Tuttavia, le variabili implicite vengono aggiornate solo quando l'istanza viene creata, aggiornata o aggiornata. Quando è necessario passare un parametro specifico con un valore noto solo al momento dell'attivazione del trigger (richiamo), è possibile utilizzare i parametri del trigger.

I parametri del trigger possono essere definiti facoltativamente nel file YAML del trigger. Quando i parametri vengono definiti, è possibile includere i relativi nomi e valori nel payload delle richieste di attivazione (richiamo) del trigger. Tutti i riferimenti ai parametri nella definizione della destinazione vengono sostituiti con i valori effettivi forniti nel payload della richiesta.

Per attivare (richiamare) un trigger con parametri, è necessario inviare un POST HTTP all'endpoint del trigger. Ad esempio:

Attivazione del trigger con parametri:

oci raw-request --auth security_token --http-method POST \
    --target-uri https://<region>/20190101/mlApplicationInstanceViews/<ocidid>/actions/trigger \
  --request-body file://./triggerInvocationPayload.json

Richiesta trigger con parametri:

{
    "triggerName": "training job",
    "parameters": [
        {
            "name": "scoring_threshold",
            "value": "99"
        },
        {
            "name": "a_required_parameter",
            "value": "must_value"
        }
    ]
}

Trigger e principal risorse

I trigger definiti dai provider nei package delle applicazioni ML come file YAML possono essere esposti sia ai provider che ai consumer. I provider e i consumer possono attivare (accendere o attivare) i trigger e avviare un'esecuzione di una pipeline o di un job.

Il principal risorsa utilizzato per avviare l'esecuzione è diverso per i richiami del consumer e del provider.

Quando i consumer attivano i trigger, viene utilizzato il principal risorsa dell'istanza dell'applicazione ML (datasciencemlappinstanceint). D'altra parte, quando i provider attivano i trigger, viene utilizzato il principal risorsa vista Istanza applicazione ML (datasciencemlappinstanceviewint).

Ciò implica che è necessario definire criteri che consentano l'esecuzione del principal risorsa vista istanza o istanza. Poiché le esecuzioni dipendono dalla rete e dal log, è necessario lasciare che anche i principal delle risorse utilizzino la rete e il log. Per i dettagli, vedere la sezione Impostazione dei criteri.