トリガー

トリガーを使用すると、MLアプリケーション・プロバイダはMLジョブまたはパイプラインのトリガー・メカニズムを指定できるため、完全に自動化されたMLOpsの実装が容易になります。

トリガーは、MLワークフローの実行のエントリ・ポイントであり、MLアプリケーション・パッケージ内のYAMLファイルでインスタンス・コンポーネントとして定義されます。トリガーは、新しいMLアプリケーション・インスタンスの作成時に自動的に作成されますが、他のすべてのインスタンス・コンポーネントが作成された場合にのみ作成されます。したがって、トリガーが作成されると、以前に作成された他のインスタンス・コンポーネントを参照できます。アプリケーションの一部であるジョブまたはMLパイプラインは、MLアプリケーションのインスタンス・コンポーネントとしてトリガーを定義することでトリガーできます。トリガーを使用すると、プロバイダおよびコンシューマは一部のワークフローの実行を開始できます。

プロバイダは、トリガー定義内で次のものを指定できます。

トリガー・ターゲット: 実行内容を定義します。たとえば、トリガーがアクティブ化または起動されると、新しいパイプラインまたはジョブ実行が作成されます。

トリガー条件: トリガーが実行されるタイミングを定義します。instance was createdなどのトリガーまたはイベントをアクティブ化または起動するHTTPエンドポイント(WebHooks)を定義できます。

トリガー・パラメータ: アクティブ化(起動)時にトリガーに渡すことができるパラメータを定義します。パラメータ値をさらにトリガー・ターゲットに渡すことができます。たとえば、パイプラインまたはジョブで開始されたコンテナ・イメージへの参照を渡すことができます。

トリガーは、次によってアクティブ化または起動できます。

HTTPベースのトリガー

トリガーは、HTTPリクエストに応じて起動できます。ユーザーがトリガーを起動するためのHTTPリクエストを実行できるようにする2つのエンドポイント。

プロバイダ・エンドポイント: MLアプリケーション・インスタンス・ビュー・リソースで使用可能であり、プロバイダが使用することを想定しています。
コンシューマ・エンドポイント: MLアプリケーション・インスタンス・リソースで使用可能であり、コンシューマが使用することを想定しています。
MLアプリケーション・プロバイダには、次のような任意の組合せでこれらのエンドポイントを有効にするオプションがあります。
- プロバイダ・エンドポイントのみ。
- コンシューマ・エンドポイントのみ。
- プロバイダ・エンドポイントとコンシューマ・エンドポイントの両方。
- なし

イベントベースのトリガー

トリガーは、特定のリソースのライフサイクル・イベントに応答して起動されます。サポートされるリソースはMLアプリケーション・インスタンスのみです。サポートされているライフサイクル・イベントは次のとおりです。

MLアプリケーション・インスタンスの作成: プロバイダは、1回かぎりのトレーニング実行でMLアプリケーションを実装できます。
MLアプリケーション・インスタンスのアップグレード: 新しいバージョンのMLアプリケーション実装(たとえば、新しいトレーニング・アルゴリズム)がデプロイされたときに、プロバイダがモデルを再トレーニングする機能を追加できるようにします。

トリガー・ターゲットは、トリガー条件が満たされたときに作成されるOCIリソースの作成操作ペイロードです。サポートされているターゲット・タイプは、DataScienceJobRunおよびDataSciencePipelineRunです。

トリガー・ターゲット内では、次のような暗黙的な変数を参照できます。

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

たとえば、トリガー・パラメータ

${parameters.docker_image_tag}

暗黙的な変数参照は、インスタンスの作成、更新またはアップグレード時に実際の値に置き換えられます。パラメータ参照は、トリガーがアクティブ化されると値に置き換えられます。詳細は、MLアプリケーション・パッケージの暗黙的変数またはパラメータ化されたトリガーを参照してください。

トリガーの定義

トリガーは、アプリケーション・パッケージのinstance_componentsディレクトリの下にYAMLファイルとして定義されます。トリガー・ファイルは拡張子.trigger.yamlを使用し、次のようにスキーマに従う必要があります。

apiVersion
- description: この構成ファイルのスキーマのバージョン。
- 必須: true
- タイプ: 文字列
種類
- 説明: リソースの種類(ml-application-triggerのみサポート)。
- 必須: true
- タイプ: 文字列
メタデータ
- description: 特定のリソースのメタデータ。
- 必須: true
- タイプ: オブジェクト(マップ)
- プロパティ(サポートされているメタデータ):
  - 名前
    - description: リソースの特定のインスタンスの識別子としての名前。
    - 必須: true
    - タイプ: 文字列
指定
- description: 特定のリソースの仕様。
- 必須: true
- タイプ: object
- プロパティ:
  - パラメータ
    - description: アクティブ化(起動)時にトリガーに渡すことができるパラメータのマップ。
    - 必須: false
    - type: マップ(パラメータ名はパラメータ・プロパティにマップされます)
      - パラメータ名は、"\w+"正規表現(英数字が1文字以上)と一致する必要があります。
    - パラメータのプロパティ:
      - 必要な
        
        type: Boolean (trueまたはfalse)
        
        required: false (デフォルトはfalse)
        
        説明: 特定の引数が必須かどうか。
        ノート
        
        必須のトリガー・パラメータは、consumerEndpointまたは任意の種類のイベントベースの条件を持つトリガーには使用できません。
      - 説明
        
        タイプ: 文字列
        
        必須: false
        
        description: パラメータの説明。
      - validationRegexp
        
        タイプ: 文字列
        
        必須: false
        
        description: 引数値の検証に使用される正規表現。
      - defaultValue
        
        タイプ: 文字列
        
        必須: false
        
        description: パラメータがアクティブ化(起動)リクエストで指定されていない場合に使用される値。オプションのパラメータにはデフォルト値を指定する必要があります。必須パラメータに指定できます。validationRegexpを指定する場合は、デフォルト値が一致する必要があります。
  - 条件
    - description: トリガーが起動するタイミングを定義する条件。
    - 必須: true
    - タイプ: object
    - プロパティ:
      - リクエスト
        
        description: 直接トリガー・リクエストのソースのリスト。このようなリクエストごとに、トリガーは起動しようとします。
        
        必須: いずれか
        
        type: オブジェクトの配列
        
        アイテム・タイプのプロパティ:
        
        ソース
        
        description: トリガー・リクエストのソース: 配列に存在する場合、このリソースからのリクエストでトリガーが起動することを意味します。
        
        必須: true
        
        型: 列挙
        
        列挙型の値:
        
        providerEndpoint: このタイプのソースが「リクエスト」セクションに表示されている場合、プロバイダに対するHTTPリクエストを使用したトリガーが有効になります(/mlApplicationInstanceView/<mlApplicationInstanceViewId>/action/trigger)。
        
        consumerEndpoint: このタイプのソースが「リクエスト」セクションに表示されている場合、コンシューマに対するHTTPリクエストの使用をトリガーできます(/mlApplicationInstance/<mlApplicationInstanceId>/action/trigger)。
      - イベント
        
        description: トリガーが起動するイベント。
        
        必須: いずれか
        
        type: array (項目は多相オブジェクト)
        
        アイテムの共通プロパティ(親: ポリモフィズム):
        
        ソース
        
        description: イベント・ソース: 配列内に存在する場合、このイベント・ソース(様々なイベントの識別子の最初の部分)からの受信イベントに基づいてトリガーが起動されることを意味します。
        
        必須: true
        
        型: 列挙
        
        列挙型の値:
        
        mlApplicationInstance: MLアプリケーション・インスタンスはイベント・ソースです。サポートされているタイプ: onCreate、 onVersionUpgrade
        
        type
        
        description: イベント・タイプ(すべてのイベント・ソースの共通プロパティ: イベントの識別子の2番目の部分)。
        
        必須: true
        
        型: 列挙
        
        列挙値: イベント・ソースに基づく
        
        ソース: mlApplicationInstance
        
        サポートされているイベント(特定の子: ポリモフィズム):
        
        source: mlApplicationInstance、type: onCreate
        
        説明: MLアプリケーション・インスタンスの作成時にトリガーが起動します。
        
        type: object (複合デリミタを持つ子: source、type)。
        
        source: mlApplicationInstance、type: onVersionUpgrade
        
        description: トリガーは、MLアプリケーション・インスタンスのバージョン・アップグレード時に起動します。
        
        type: object (子と複合デリミタ: source、 type)
        
        プロパティ:
        
        packageVersion
        
        説明: このパッケージ・バージョンでMLアプリケーション・インスタンスがMLアプリケーション実装バージョンにアップグレードされた場合のみ、トリガーが起動します。
        
        必須: true
        
        タイプ: 文字列
        
        mlApplicationInstanceViewTagName
        
        description: トリガーは、アップグレードされたMLアプリケーション・インスタンスにこの名前(および定義された値)のタグがある場合にのみ起動します。
        
        必須: false
        
        タイプ: 文字列
        
        mlApplicationInstanceViewTagValue
        
        description: トリガーは、アップグレードされたMLアプリケーション・インスタンスにこの値(および定義済の名前)のタグがある場合にのみ起動します。
        
        必須: false
        
        タイプ: 文字列
  - ターゲット
    - 説明: トリガー・ターゲット(JobRunなど)。
    - タイプ: object
    - プロパティ:
      - type
        
        説明: トリガターゲットのタイプ。
        
        type: 列挙(値: DataScienceJobRun、DataSciencePipelineRun)
        
        必須: true
      - 型板
        
        description: ターゲットとして使用するリソースのペイロードを作成します。動的に解決され、実際の値に置き換えられる様々なプレースホルダを含めることができます。暗黙的な変数とトリガー・パラメータの2つのタイプのプレースホルダが存在します。
        
        type: object (JSONペイロードが必要です。ノート: JSONは有効なYAMLです)
        
        必須: true

トリガーのYAML定義の例

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

ノート

現在のapiVersion (トリガー定義スキーマの場合)はv1-beta.です
kindは常にml-application-trigger.である必要があります
requestsまたはeventsを指定する必要があります。requestsもeventsも指定しないトリガー定義は無効です。
requestsは、指定する場合は常に空にできません。
eventsは、指定する場合は常に空にできません。
イベント・タイプMLアプリケーション・インスタンス・バージョン・アップグレード(ソース: mlApplicationInstance、タイプ: onCreate):
- mlApplicationInstanceViewTagNameを指定する場合は常に、mlApplicationInstanceViewTagValueも指定する必要があります。
- mlApplicationInstanceViewTagValueを指定する場合は常に、mlApplicationInstanceViewTagNameも指定する必要があります。
- 指定する場合は常に、mlApplicationInstanceViewTagNameとmlApplicationInstanceViewTagValueの両方を指定する必要があります。
DataScienceJobRunターゲット・タイプのテンプレートは、CreateJobRunDetailsスキーマに従う必要があります。
DataSciencePipelineRunターゲット・タイプのテンプレートは、CreatePipelineRunDetailsスキーマに従う必要があります。
テンプレート・ペイロードで使用される値には、MLアプリケーション・パッケージの暗黙的変数で説明されているように、様々なプレースホルダを含めることができます。
プレースホルダは、${variable_name}という形式を使用する必要があります。つまり、プレースホルダは$で始まり、その後に中カッコ{}内の変数名が続く必要があります。
DataScienceJobRunテンプレートのjobIdは、MLアプリケーション実装に属するDataScienceJobアプリケーション・コンポーネントを参照または解決する必要があります。
DataSciencePipelineRunテンプレートのpipelineIdは、MLアプリケーション実装に属するDataSciencePipelineアプリケーション・コンポーネントを参照するか、このコンポーネントに解決する必要があります。
設計は、「トリガーの定義」で定義します。

トリガー関連エンドポイントに関する情報

トリガー関連エンドポイント
エンドポイント	関連リソース	必要な権限	次が使用
`/mlApplicationInstances/<mlApplicationInstanceId>/actions/trigger`	MLアプリケーション・インスタンス	DATA_SCIENCE_APPLICATION_INSTANCE_TRIGGER	コンシューマ
`/mlApplicationInstanceViews/<mlApplicationInstanceViewId>/actions/trigger`	MLアプリケーションインスタンスビュー	DATA_SCIENCE_APPLICATION_INSTANCE_VIEW_TRIGGER	プロバイダ
`/mlApplicationInstanceViews/<mlApplicationInstanceViewId>/actions/disableTrigger`	MLアプリケーションインスタンスビュー	DATA_SCIENCE_APPLICATION_INSTANCE_VIEW_READDATA_SCIENCE_APPLICATION_INSTANCE_VIEW_UPDATE	プロバイダ
`/mlApplicationInstanceViews/<mlApplicationInstanceViewId>/actions/enableTrigger`	MLアプリケーションインスタンスビュー	DATA_SCIENCE_APPLICATION_INSTANCE_VIEW_READDATA_SCIENCE_APPLICATION_INSTANCE_VIEW_UPDATE	プロバイダ

パラメータ化されたトリガー

トリガーは、暗黙的な変数を参照することでターゲット(ジョブまたはパイプライン実行)をパラメータ化できます。ただし、暗黙的な変数は、インスタンスの作成、更新またはアップグレード時にのみ更新されます。トリガー・アクティブ化(起動)時にのみ認識される値を持つ特定のパラメータを渡す必要がある場合は、トリガー・パラメータを使用できます。

トリガー・パラメータは、オプションでトリガーYAMLファイルに定義できます。パラメータを定義するときに、トリガー・アクティブ化(起動)リクエストのペイロードに名前と値を含めることができます。ターゲット定義のパラメータに対するすべての参照は、リクエストのペイロードに指定された実際の値に置き換えられます。

パラメータ化されたトリガーをアクティブ化(起動)するには、トリガー・エンドポイントにHTTP POSTを送信する必要があります。例:

パラメータ化されたトリガーのアクティブ化:

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

パラメータ化されたトリガー・リクエスト:

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

トリガーとリソース・プリンシパル

ML ApplicationsパッケージのプロバイダによってYAMLファイルとして定義されているトリガーは、プロバイダとコンシューマの両方に公開できます。プロバイダとコンシューマは、トリガーをアクティブ化(起動またはトリガー)して、パイプラインまたはジョブの実行を開始できます。

実行の開始に使用されるリソース・プリンシパルは、コンシューマおよびプロバイダの呼出しで異なります。

コンシューマがトリガーをアクティブ化すると、MLアプリケーション・インスタンス・リソース・プリンシパルが使用されます(datasciencemlappinstanceint)。一方、プロバイダがトリガーをアクティブ化すると、MLアプリケーション・インスタンス・ビューのリソース・プリンシパル(datasciencemlappinstanceviewint)が使用されます。

これは、インスタンスまたはインスタンス・ビューにリソース・プリンシパルの作成を実行させるポリシーを定義する必要があることを意味します。実行はネットワーキングおよびロギングに依存するため、リソース・プリンシパルでネットワーキングおよびロギングも使用できるようにする必要があります。詳細は、「ポリシー設定」の項を参照してください。