Trigger

Mit Triggern können ML-Anwendungsprovider den Auslösemechanismus für ihre ML-Jobs oder Pipelines angeben, um die Implementierung von vollautomatisiertem MLOps zu vereinfachen.

Trigger sind die Einstiegspunkte für die Ausführungen der ML-Workflows und werden durch YAML-Dateien innerhalb des ML-Anwendungspakets als Instanzkomponenten definiert. Trigger werden automatisch erstellt, wenn eine neue ML-Anwendungsinstanz erstellt wird, jedoch nur, wenn alle anderen Instanzkomponenten erstellt werden. Wenn ein Trigger erstellt wird, kann er sich also auf andere Instanzkomponenten beziehen, die zuvor erstellt wurden. Die Jobs oder ML-Pipelines, die Teil Ihrer Anwendung sind, können ausgelöst werden, indem Trigger als Instanzkomponenten in Ihrer ML-Anwendung definiert werden. Mit Triggern können Provider und Consumer die Ausführung einiger Workflows starten.

In der Trigger-Definition können Provider Folgendes angeben:

Triggerziel: Definiert, was ausgeführt wird. Beispiel: Eine neue Pipeline oder ein neuer Joblauf wird erstellt, wenn der Trigger aktiviert oder aufgerufen wird.

Triggerbedingung: Definiert, wann der Trigger ausgeführt wird. Sie können definieren, welche HTTP-Endpunkte (WebHooks) den oder die Trigger oder Ereignisse wie instance was created aktivieren oder aufrufen.

Triggerparameter: Definieren Sie, welche Parameter bei ihrer Aktivierung (Aufruf) an den Trigger übergeben werden können. Sie können die Parameterwerte weiter an das Triggerziel übergeben. Beispiel: Sie können eine Referenz an ein Containerimage übergeben, das in Ihrer Pipeline oder Ihrem Job gestartet wurde.

Trigger können aktiviert oder aufgerufen werden durch:

HTTP-basiertes Triggering

Trigger können als Antwort auf HTTP-Anforderungen ausgelöst werden. Zwei Endpunkte, mit denen Benutzer HTTP-Anforderungen zum Auslösen von Triggern erstellen können.

Providerendpunkt: In der Ressource "ML-Anwendungsinstanzansicht" verfügbar, die von Providern verwendet werden soll.
Consumer-Endpunkt: Verfügbar in der ML-Anwendungsinstanzressource. Er soll von Consumern verwendet werden.
ML-Anwendungsprovider haben die Möglichkeit, diese Endpunkte wie folgt in beliebiger Kombination zu aktivieren:
- Nur Providerendpunkt.
- Nur Consumer-Endpunkt.
- Provider- und Consumer-Endpunkte.
- Kein

Ereignisbasiertes Triggering

Trigger werden als Reaktion auf ein Lebenszyklusereignis für eine bestimmte Ressource ausgelöst. Die einzige unterstützte Ressource ist die ML-Anwendungsinstanz. Folgende Lebenszyklusereignisse werden unterstützt:

ML-Anwendungsinstanz erstellen: Ermöglichen Sie es Anbietern, ML-Anwendungen mit einem einmaligen Schulungslauf zu implementieren.
Upgrade der ML-Anwendungsinstanz: Provider können das Modell neu trainieren, wenn eine neue Version der ML-Anwendungsimplementierung bereitgestellt wird (z.B. mit einem neuen Trainingsalgorithmus).

Das Triggerziel ist eine Payload für Erstellungsvorgänge für OCI-Ressourcen, die erstellt wird, wenn die Triggerbedingung erfüllt ist. Die unterstützten Zieltypen sind DataScienceJobRun und DataSciencePipelineRun.

Innerhalb der Triggerziele können Sie implizite Variablen referenzieren, z.B.

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

oder Trigger-Parameter, z.B.

${parameters.docker_image_tag}

Implizite Variablenreferenzen werden durch tatsächliche Werte ersetzt, wenn die Instanz erstellt, aktualisiert oder upgegradet wird. Parameterreferenzen werden durch Werte ersetzt, wenn der Trigger aktiviert wird. Weitere Informationen finden Sie unter Implizite Variablen für ML-Anwendungspakete oder Parametrisierte Trigger.

Trigger definieren

Trigger werden als YAML-Dateien im Verzeichnis instance_components im Anwendungspaket definiert. Triggerdateien verwenden die Erweiterung .trigger.yaml und müssen dem Schema wie folgt folgen:

apiVersion
- Beschreibung: Die Version des Schemas für diese Konfigurationsdatei.
- Erforderlich: true
- Typ: Zeichenfolge
Art
- Beschreibung: die Art der Ressource (wird nur von ml-application-trigger unterstützt).
- Erforderlich: true
- Typ: Zeichenfolge
Metadaten
- Beschreibung: Die Metadaten für eine bestimmte Ressource.
- Erforderlich: true
- Typ: Objekt (Karte)
- Eigenschaften (unterstützte Metadaten):
  - name
    - Beschreibung: Der Name als ID für eine bestimmte Instanz der Ressource.
    - Erforderlich: true
    - Typ: Zeichenfolge
spez
- Beschreibung: die Spezifikation einer bestimmten Ressource.
- Erforderlich: true
- Typ: Objekt
- properties:
  - Parameter
    - Beschreibung: Eine Karte von Parametern, die bei ihrer Aktivierung (Aufruf) an den Trigger übergeben werden können.
    - erforderlich: false
    - Typ: die Zuordnung (Parametername wird Parametereigenschaften zugeordnet)
      - Der Parametername muss mit dem regulären Ausdruck "\w+" (mindestens ein alphanumerisches Zeichen) übereinstimmen.
    - Parametereigenschaften:
      - Obligatorisch
        
        Typ: Boolescher Wert (true oder false)
        
        Erforderlich: false (Standard ist false)
        
        Beschreibung: Gibt an, ob das bestimmte Argument obligatorisch ist.
        Hinweis
        
        Obligatorische Triggerparameter sind für Trigger mit consumerEndpoint oder einer ereignisbasierten Bedingung nicht zulässig.
      - description
        
        Typ: Zeichenfolge
        
        erforderlich: false
        
        Beschreibung: Die Parameterbeschreibung.
      - validationRegexp
        
        Typ: Zeichenfolge
        
        erforderlich: false
        
        Beschreibung: Der reguläre Ausdruck für die Validierung des Argumentwerts.
      - defaultValue
        
        Typ: Zeichenfolge
        
        erforderlich: false
        
        Beschreibung: Der Wert, der verwendet wird, wenn der Parameter nicht in der Aktivierungsanforderung (Aufrufanforderung) angegeben ist. Der Standardwert muss für optionale Parameter angegeben werden. Es kann für erforderliche Parameter angegeben werden. Wenn validationRegexp angegeben wird, muss der Standardwert übereinstimmen.
  - Bedingung
    - Beschreibung: Die Bedingung, die definiert, wann der Trigger ausgelöst wird.
    - Erforderlich: true
    - Typ: Objekt
    - properties:
      - Anforderungen
        
        Beschreibung: Die Liste der Quellen für direkte Triggeranforderungen. Für jede solche Anforderung versucht der Trigger zu starten.
        
        erforderlich: eine der
        
        Typ: Array von Objekten
        
        Elementtyp-Eigenschaften:
        
        Quelle
        
        Beschreibung: Die Quelle von Triggeranforderungen: Wenn sie im Array vorhanden sind, bedeutet dies, dass der Trigger auf Anforderung dieser Ressource ausgelöst wird.
        
        Erforderlich: true
        
        Typ: enum
        
        enum-Werte:
        
        providerEndpoint: Wenn die Quelle mit diesem Typ im Abschnitt Anforderungen angezeigt wird, ist das Auslösen der HTTP-Anforderung für Provider aktiviert (/mlApplicationInstanceView/<mlApplicationInstanceViewId>/action/trigger).
        
        consumerEndpoint: Wenn die Quelle mit diesem Typ im Abschnitt Anforderungen angezeigt wird, ist das Auslösen der HTTP-Anforderung für Consumer aktiviert (/mlApplicationInstance/<mlApplicationInstanceId>/action/trigger).
      - Ereignisse
        
        Beschreibung: Ereignisse, bei denen der Trigger ausgelöst wird.
        
        erforderlich: eine der
        
        Typ: Array (Elemente sind polymorphe Objekte)
        
        Allgemeine Eigenschaften für Elemente (übergeordnet:Polymorphismus):
        
        Quelle
        
        Beschreibung: Die Ereignisquelle: Wenn sie im Array vorhanden ist, bedeutet dies, dass der Trigger basierend auf eingehenden Ereignissen aus dieser Ereignisquelle ausgelöst wird (der erste Teil des Diskriminators für verschiedene Ereignisse).
        
        Erforderlich: true
        
        Typ: enum
        
        enum-Werte:
        
        mlApplicationInstance: Die ML-Anwendungsinstanz ist eine Ereignisquelle. Unterstützte Typen: onCreate, onVersionUpgrade
        
        type
        
        Beschreibung: Der Ereignistyp (gemeinsame Eigenschaft für alle Ereignisquellen: der zweite Teil des Diskriminators für Ereignisse).
        
        Erforderlich: true
        
        Typ: enum
        
        Enumerationswerte: basierend auf Ereignisquelle
        
        Quelle: mlApplicationInstance
        
        Unterstützte Ereignisse (spezifische untergeordnete Elemente: Polymorphismus):
        
        Quelle: mlApplicationInstance, Typ: onCreate
        
        Beschreibung: Der Trigger wird bei der Erstellung der ML-Anwendungsinstanz ausgelöst.
        
        Typ: Objekt (untergeordnetes Element mit zusammengesetztem Trennzeichen: Quelle, Typ).
        
        Quelle: mlApplicationInstance, Typ: onVersionUpgrade
        
        Beschreibung: Der Trigger wird beim Versionsupgrade der ML-Anwendungsinstanz ausgelöst.
        
        Typ: Objekt (untergeordnetes Element mit zusammengesetztem Trennzeichen: Quelle, Typ)
        
        properties:
        
        packageVersion
        
        Beschreibung: Der Trigger wird nur ausgelöst, wenn die ML-Anwendungsinstanz mit dieser Packageversion auf die ML-Anwendungsimplementierungsversion upgegradet wird.
        
        Erforderlich: true
        
        Typ: Zeichenfolge
        
        mlApplicationInstanceViewTagName
        
        Beschreibung: Der Trigger wird nur ausgelöst, wenn die aktualisierte ML-Anwendungsinstanz ein Tag mit diesem Namen (und definiertem Wert) aufweist.
        
        erforderlich: false
        
        Typ: Zeichenfolge
        
        mlApplicationInstanceViewTagValue
        
        Beschreibung: Der Trigger wird nur ausgelöst, wenn die aktualisierte ML-Anwendungsinstanz ein Tag mit diesem Wert (und definiertem Namen) aufweist.
        
        erforderlich: false
        
        Typ: Zeichenfolge
  - Ziel
    - Beschreibung: Das Triggerziel (Beispiel: JobRun).
    - Typ: Objekt
    - properties:
      - type
        
        Beschreibung: Der Typ des Triggerziels.
        
        Typ: enum (Werte: DataScienceJobRun, DataSciencePipelineRun)
        
        Erforderlich: true
      - Template
        
        Beschreibung: Erstellen Sie eine Payload für eine Ressource, die als Ziel verwendet wird. Es kann verschiedene Platzhalter enthalten, die dynamisch aufgelöst und durch tatsächliche Werte ersetzt werden. Es gibt zwei Arten von Platzhalter: implizite Variablen und Triggerparameter.
        
        Typ: Objekt (erwartete JSON-Payload, Hinweis: JSON ist gültige YAML)
        
        Erforderlich: true

Beispiel für YAML-Triggerdefinition

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

Hinweis

Das aktuelle apiVersion (für das Triggerdefinitionsschema) ist v1-beta.
kind muss immer ml-application-trigger. sein
Sie müssen entweder requests oder events angeben. Eine Triggerdefinition, die weder requests noch events angibt, ist ungültig.
requests darf, sofern angegeben, nicht leer sein.
events darf, sofern angegeben, nicht leer sein.
In Bezug auf das Versionsupgrade der ML-Anwendungsinstanz des Ereignistyps (Quelle: mlApplicationInstance, Typ: onCreate):
- Wenn mlApplicationInstanceViewTagName angegeben wird, muss auch mlApplicationInstanceViewTagValue angegeben werden.
- Wenn mlApplicationInstanceViewTagValue angegeben wird, muss auch mlApplicationInstanceViewTagName angegeben werden.
- Wenn angegeben, müssen sowohl mlApplicationInstanceViewTagName als auch mlApplicationInstanceViewTagValue angegeben werden.
Die Vorlage für den Zieltyp DataScienceJobRun muss dem CreateJobRunDetails-Schema entsprechen.
Die Vorlage für den Zieltyp DataSciencePipelineRun muss dem CreatePipelineRunDetails-Schema entsprechen.
Die in der Vorlagen-Payload verwendeten Werte können verschiedene Platzhalter enthalten, wie unter Implizite Variablen für ML-Anwendungspakete beschrieben.
Die Platzhalter müssen das Format ${variable_name}, verwenden, d.h. der Platzhalter muss mit $ beginnen und auf den Variablennamen in geschweiften Klammern {} folgen.
jobId in der DataScienceJobRun-Vorlage muss eine DataScienceJob-Anwendungskomponente referenzieren oder auflösen, die zur ML-Anwendungsimplementierung gehört.
pipelineId in der DataSciencePipelineRun-Vorlage muss eine DataSciencePipeline-Anwendungskomponente referenzieren oder auflösen, die zur ML-Anwendungsimplementierung gehört.
Design wird unter Trigger definieren definiert.

Informationen zu Trigger-bezogenen Endpunkten

Trigger-bezogene Endpunkte
Endpunkt	Zugehörige Ressource	Erforderliche Berechtigung	Verwendet von
`/mlApplicationInstances/<mlApplicationInstanceId>/actions/trigger`	ML-Anwendungsinstanz	DATA_SCIENCE_APPLICATION_INSTANCE_TRIGGER	Consumer
`/mlApplicationInstanceViews/<mlApplicationInstanceViewId>/actions/trigger`	ML-Anwendungsinstanzansicht	DATA_SCIENCE_APPLICATION_INSTANCE_VIEW_TRIGGER	Provider
`/mlApplicationInstanceViews/<mlApplicationInstanceViewId>/actions/disableTrigger`	ML-Anwendungsinstanzansicht	DATA_SCIENCE_APPLICATION_INSTANCE_VIEW_READDATA_SCIENCE_APPLICATION_INSTANCE_VIEW_UPDATE	Provider
`/mlApplicationInstanceViews/<mlApplicationInstanceViewId>/actions/enableTrigger`	ML-Anwendungsinstanzansicht	DATA_SCIENCE_APPLICATION_INSTANCE_VIEW_READDATA_SCIENCE_APPLICATION_INSTANCE_VIEW_UPDATE	Provider

Parametrisierte Trigger

Trigger können Ziele (Job- oder Pipelineausführungen) parametrisieren, indem sie auf implizite Variablen verweisen. Implizite Variablen werden jedoch nur aktualisiert, wenn die Instanz erstellt, aktualisiert oder upgegradet wird. Wenn Sie einen bestimmten Parameter mit einem Wert übergeben müssen, der nur zum Zeitpunkt der Triggeraktivierung (Aufruf) bekannt ist, können Sie Triggerparameter verwenden.

Triggerparameter können optional in der Trigger-YAML-Datei definiert werden. Wenn die Parameter definiert sind, können Sie ihre Namen und Werte in die Payload der Triggeraktivierungs-(Aufruf-)Anforderungen aufnehmen. Alle Referenzen auf die Parameter in der Zieldefinition werden durch tatsächliche Werte ersetzt, die in der Payload der Anforderung angegeben sind.

Um einen parametrisierten Trigger zu aktivieren (aufrufen), müssen Sie einen HTTP-POST an den Triggerendpunkt senden. Beispiel:

Parametergesteuerte Triggeraktivierung:

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

Parametrisierte Triggeranforderung:

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

Trigger und Resource Principals

Trigger, die von Providern in ML-Anwendungspackages als YAML-Dateien definiert werden, können sowohl Providern als auch Verbrauchern zur Verfügung gestellt werden. Provider und Consumer können die Trigger aktivieren (auslösen oder auslösen) und eine Ausführung einer Pipeline oder eines Jobs starten.

Der Resource Principal, mit dem die Ausführung gestartet wird, unterscheidet sich bei Consumer- und Provideraufrufen.

Wenn Consumer Trigger aktivieren, wird der Resource Principal der ML-Anwendungsinstanz verwendet (datasciencemlappinstanceint). Wenn Provider hingegen Trigger aktivieren, wird der Resource Principal für die Ansicht der ML-Anwendungsinstanz verwendet (datasciencemlappinstanceviewint).

Dies bedeutet, dass Sie Policys definieren müssen, mit denen die Instanz oder Instanz den Resource Principal erstellen kann. Da Ausführungen von Netzwerken und Logging abhängen, müssen die Resource Principals auch Networking und Logging verwenden. Weitere Informationen finden Sie im Abschnitt Policy-Setup.