ML メタデータの分析

Vertex ML Metadata を使用すると、機械学習(ML)システムによって生成されたメタデータの追跡と分析を行うことができます。このメタデータを追跡することで、ML システムの動作を簡単に分析できます。これは、システム パフォーマンスの変化の確認や、ML システムによって生成されたアーティファクトの比較を行う際に役立ちます。

Vertex ML Metadata を初めて使用する場合は、Vertex ML Metadata の概要で、ML ワークフローのメタデータの追跡と分析の詳細を確認してください。

このドキュメントでは、分析する ML メタデータを以下の方法でクエリする方法について説明します。

アーティファクト、実行、コンテキストのクエリ

REST API を使用すると、フィルタを使用して次のようなアーティファクト、実行、コンテキスト レコードをクエリできます。

  • 特定の品質基準を満たすトレーニング済みモデルのバージョンはどれか。
  • 特定のデータセットを使用したパイプライン実行はどれか。

以降のセクションでは、フィルタの作成方法と、アーティファクト実行コンテキストのクエリ方法について説明します。

フィルタ構文の概要

以降のセクションでは、フィルタを使用してアーティファクト、実行、コンテキストをクエリする方法について説明します。

フィールド

アーティファクト、実行、コンテキストをフィルタする場合、次のフィールドがサポートされます。

アーティファクト 実行 コンテキスト
name
display_name
schema_title
create_time
update_time
metadata
state
uri

フィルタは引用符で囲む必要があります。フィルタ内で引用符を使用する場合は、その引用符をバックスラッシュでエスケープする必要があります。

比較演算子

フィルタでは比較演算子(=!=<>>=<=)を使用できます。

たとえば、次のフィルタでは、表示名が my_artifact のアーティファクトがすべて検索されます。

"display_name=\"my_artifact\""

文字列フィールドでは、ワイルドカードとして * 文字を使用できます。

create_timeupdate_time などのタイムスタンプ フィールドでは、次のように、日付を RFC 3339 形式で指定する必要があります。

"create_time=\"2021-05-11T12:30:00-08:00\""

トラバーサル演算子を使用してメタデータをフィルタする

metadata フィールドは google.protobuf.Struct のインスタンスで、その形式は schema_title フィールドで指定されたスキーマに定義されています。google.protobuf.Struct は、キーを google.protobuf.Value インスタンスにマッピングするデータ構造です。google.protobuf.Value データ構造は、データ型に応じて値を異なるフィールドに格納します。たとえば、文字列は metadata.FIELD_NAME.string_value として、数値は metadata.FIELD_NAME.number_value として、ブール値は metadata.FIELD_NAME.bool_value として格納されます。

metadata でフィルタするには、トラバーサル演算子を使用してフィルタの対象となるフィールドを走査する必要があります。トラバーサル演算子は次の形式を使用します。

"metadata.FIELD_NAME.TYPE_NAME=\"FILTER_VALUE\""

たとえば、次のようなメタデータ構造を考えてみましょう。

{
   "field_1": 5,
   "field_2": "example",
   "field_3": {
     ...
   },
   "field_4": [],
   "field_5": true,
}

次のクエリでは、トラバーサル演算子を使用して、この例のメタデータをフィルタしています。

  • metadata.field_1 の値が 5 未満のレコードをフィルタします。

    "metadata.field_1.number_value<5"

  • metadata.field_2 の値が example に等しいレコードをフィルタします。

    "metadata.field_2.string_value=\"test\""

  • metadata.field_5 の値が true のレコードでフィルタします。

    "metadata.field_5.bool_value=true"

親子関係によってコンテキストをフィルタする

has 演算子を使用すると、指定したコンテキストの親または子のコンテンツを探すことができます。

has 演算子の形式は次のとおりです。

  • "parent_contexts:\"CONTEXT_RESOURCE_NAME\""
  • "child_contexts:\"CONTEXT_RESOURCE_NAME\""

コンテキスト名は、project/PROJECT/locations/LOCATION/metadataStores/METADATA-STORE/contexts/CONTEXT のようにコンテキストの完全なリソース名にする必要があります。

次のフィルタでは has 演算子を使用しています。

  • 指定したパイプラインの子であるすべてのコンテキストをフィルタします。

    "parent_contexts: \"project/12345/locations/us-central1/metadataStores/default/contexts/pipeline_1\""

  • 指定したパイプラインの親であるすべてのコンテキストをフィルタします。

    "child_contexts: \"project/12345/locations/us-central1/metadataStores/default/contexts/pipeline_1\""

コンテキスト内のアーティファクトと実行をフィルタする

in_context() 関数を使用すると、コンテキストに関連するアーティファクトまたは実行をフィルタできます。

in_context() 関数の形式は次のどおりです。

"in_context(\"CONTEXT_RESOURCE_NAME\")"

コンテキスト名は、次のようにコンテキストの完全なリソース名にする必要があります。

project/PROJECT/locations/LOCATION/metadataStores/METADATA-STORE/contexts/CONTEXT

次の例では、指定したパイプラインに含まれるオブジェクトをフィルタしています。

"in_context(\"project/12345/locations/us-central1/metadataStores/default/contexts/pipeline_1\")"

論理演算子

論理演算子 ANDOR を使用してフィルタを組み合わせると、複雑なクエリを作成できます。

次の例は、ai_platform.model タイプのアーティファクトと、0.9 より大きい数値を持つ metadata フィールド precision をクエリしています。

"schema_title=\"ai_platform.Model\" AND metadata.precision.number_value>0.9"

アーティファクトのクエリ

アーティファクトは、データセットやモデルなど、ML ワークフローによって使用または生成されるデータを表します。次の手順でアーティファクトをクエリします。

リクエストのデータを使用する前に、次のように置き換えます。

  • LOCATION: 使用するリージョン。
  • PROJECT: プロジェクト ID またはプロジェクト番号。
  • METADATA_STORE: アーティファクトが作成されるメタデータ ストア ID。デフォルトのメタデータ ストアの名前は default です。
  • PAGE_SIZE: 省略可。返されるアーティファクトの最大数。この値が指定されていない場合は、最大 100 件のレコードが返されます。
  • PAGE_TOKEN: 省略可。前回取得した MetadataService.ListArtifacts 呼び出しのページトークン。次の結果ページを取得するには、このトークンを指定します。
  • FILTER: 結果セットにアーティファクトを含めるために必要な条件を指定します。

HTTP メソッドと URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/artifacts?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN&filter=FILTER

リクエストを送信するには、次のいずれかのオプションを展開します。

次のような JSON レスポンスが返されます。

{
  "artifacts": [
    {
      "name": "projects/12345/locations/us-central1/metadataStores/default/artifacts/example-artifact",
      "displayName": "Example artifact",
      "uri": "gs://your_bucket_name/artifacts/dataset.csv",
      "etag": "67891011",
      "createTime": "2021-05-18T00:33:13.833Z",
      "updateTime": "2021-05-18T00:33:13.833Z",
      "state": "LIVE",
      "schemaTitle": "system.Dataset",
      "schemaVersion": "0.0.1",
      "metadata": {
        "payload_format": "CSV"
      },
      "description": "Description of the example artifact."
    },
    {
      "name": "projects/12345/locations/us-central1/metadataStores/default/artifacts/example-artifact-2",
      "displayName": "Another example artifact",
      "uri": "gs://your_bucket_name/artifacts/dataset-2.csv",
      "etag": "67891012",
      "createTime": "2021-05-18T00:29:24.344Z",
      "updateTime": "2021-05-18T00:29:24.344Z",
      "state": "LIVE",
      "schemaTitle": "system.Dataset",
      "schemaVersion": "0.0.1",
      "metadata": {
        "payload_format": "CSV"
      },
      "description": "Description of the other example artifact."
    }
  ]
}

実行のクエリ

実行は、データの前処理やモデルのトレーニングなど、ML ワークフローのステップを表します。実行をクエリするには、次の操作を行います。

リクエストのデータを使用する前に、次のように置き換えます。

  • LOCATION: 使用するリージョン。
  • PROJECT: プロジェクト ID またはプロジェクト番号。
  • METADATA_STORE: 実行が作成されたメタデータ ストア ID。デフォルトのメタデータ ストアの名前は default です。
  • PAGE_SIZE: 省略可。返される実行の最大数。この値が指定されていない場合は、最大 100 件のレコードが返されます。
  • PAGE_TOKEN: 省略可。前回取得した MetadataService.ListExecutions 呼び出しのページトークン。次の結果ページを取得するには、このトークンを指定します。
  • FILTER: 結果セットに実行を含めるために必要な条件を指定します。

HTTP メソッドと URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/executions?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN&filter=FILTER

リクエストを送信するには、次のいずれかのオプションを展開します。

次のような JSON レスポンスが返されます。

{
  "executions": [
    {
      "name": "projects/12345/locations/us-central1/metadataStores/default/executions/example-execution-1",
      "displayName": "Example execution 1",
      "etag": "67891011",
      "createTime": "2021-05-18T00:06:56.177Z",
      "updateTime": "2021-05-18T00:06:56.177Z",
      "schemaTitle": "system.Run",
      "schemaVersion": "0.0.1",
      "metadata": {},
      "description": "Descrption of the example execution."
    },
    {
      "name": "projects/12345/locations/us-central1/metadataStores/default/executions/example-execution-2",
      "displayName": "Example execution 2",
      "etag": "67891011",
      "createTime": "2021-05-18T00:04:49.659Z",
      "updateTime": "2021-05-18T00:04:49.659Z",
      "schemaTitle": "system.Run",
      "schemaVersion": "0.0.1",
      "metadata": {},
      "description": "Descrption of the example execution."
    }
  ]
}

コンテキストのクエリ

コンテキストを使用すると、実行、アーティファクト、その他のコンテキストをグループ化できます。コンテキストのクエリを行うには、次の操作を行います。

リクエストのデータを使用する前に、次のように置き換えます。

  • LOCATION: 使用するリージョン。
  • PROJECT: プロジェクト ID またはプロジェクト番号。
  • METADATA_STORE: コンテキストが作成されたメタデータ ストア ID。デフォルトのメタデータ ストアの名前は default です。
  • PAGE_SIZE: 省略可。返されるコンテキストの最大数。この値が指定されていない場合は、最大 100 件のレコードが返されます。
  • PAGE_TOKEN: 省略可。前回取得した MetadataService.ListExecutions 呼び出しのページトークン。次の結果ページを取得するには、このトークンを指定します。
  • FILTER: 結果セットにコンテキストを含めるために必要な条件を指定します。

HTTP メソッドと URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/contexts?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN&filter=FILTER

リクエストを送信するには、次のいずれかのオプションを展開します。

次のような JSON レスポンスが返されます。

{
  "contexts": [
    {
      "name": "projects/12345/locations/us-central1/metadataStores/default/contexts/experiment-1",
      "displayName": "Experiment 1",
      "etag": "67891011",
      "createTime": "2021-05-18T22:36:02.153Z",
      "updateTime": "2021-05-18T22:36:02.153Z",
      "parentContexts": [],
      "schemaTitle": "system.Experiment",
      "schemaVersion": "0.0.1",
      "metadata": {}
    },
    {
      "name": "projects/12345/locations/us-central1/metadataStores/default/contexts/pipeline-run-1",
      "displayName": "Pipeline run 1",
      "etag": "67891011",
      "createTime": "2021-05-18T22:35:02.600Z",
      "updateTime": "2021-05-18T22:35:02.600Z",
      "parentContexts": [],
      "schemaTitle": "system.PipelineRun",
      "schemaVersion": "0.0.1",
      "metadata": {}
    }
  ]
}

実行の入力 / 出力アーティファクトのクエリ

コンテキストのアーティファクトと実行、アーティファクトと実行を接続するイベントをクエリするには、次の操作を行います。

リクエストのデータを使用する前に、次のように置き換えます。

  • LOCATION: 使用するリージョン。
  • PROJECT: プロジェクト ID またはプロジェクト番号。
  • METADATA_STORE: 実行が作成されたメタデータ ストア ID。デフォルトのメタデータ ストアの名前は default です。
  • EXECUTION_ID: 実行レコードの ID。

HTTP メソッドと URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/executions/EXECUTION:queryExecutionInputsAndOutputs

リクエストを送信するには、次のいずれかのオプションを展開します。

次のような JSON レスポンスが返されます。

{
  "artifacts": [
    {
      "name": "projects/12345/locations/us-central1/metadataStores/default/artifacts/example-artifact-1",
      "displayName": "Example artifact",
      "uri": "gs://your_bucket_name/artifacts/dataset.csv",
      "etag": "678901011",
      "createTime": "2021-05-18T00:29:24.344Z",
      "updateTime": "2021-05-18T00:29:24.344Z",
      "state": "LIVE",
      "schemaTitle": "system.Dataset",
      "schemaVersion": "0.0.1",
      "metadata": {
        "payload_format": "CSV"
      },
      "description": "Description of the example artifact."
    },
    {
      "name": "projects/12345/locations/us-central1/metadataStores/default/artifacts/example-artifact-2",
      "displayName": "Example artifact 2",
      "uri": "gs://your_bucket_name/artifacts/dataset.csv",
      "etag": "678901011",
      "createTime": "2021-05-18T00:33:13.833Z",
      "updateTime": "2021-05-18T00:33:13.833Z",
      "state": "LIVE",
      "schemaTitle": "system.Dataset",
      "schemaVersion": "0.0.1",
      "metadata": {
        "payload_format": "CSV"
      },
      "description": "Description of the example artifact."
    }
  ],
  "executions": [
    {
      "name": "projects/12345/locations/us-central1/metadataStores/default/executions/example-execution-1",
      "displayName": "Example execution 1",
      "etag": "678901011",
      "createTime": "2021-05-18T00:04:49.659Z",
      "updateTime": "2021-05-18T00:04:49.659Z",
      "schemaTitle": "system.Run",
      "schemaVersion": "0.0.1",
      "metadata": {},
      "description": "Description of the example execution."
    }
  ],
  "events": [
    {
      "artifact": "projects/12345/locations/us-central1/metadataStores/default/artifacts/example-artifact-1",
      "execution": "projects/12345/locations/us-central1/metadataStores/default/executions/example-execution-1",
      "eventTime": "2021-05-18T00:04:49.659Z",,
      "type": "INPUT",
    },
    {
      "artifact": "projects/12345/locations/us-central1/metadataStores/default/artifacts/example-artifact-2",
      "execution": "projects/12345/locations/us-central1/metadataStores/default/executions/example-execution-1",
      "eventTime": "2021-05-18T00:04:49.659Z",,
      "type": "OUTPUT",
    }
  ]
}

コンテキストのリネージ サブグラフのクエリ

コンテキストのアーティファクトと実行、アーティファクトと実行を接続するイベントをクエリするには、次の操作を行います。

リクエストのデータを使用する前に、次のように置き換えます。

  • LOCATION: 使用するリージョン。
  • PROJECT: プロジェクト ID またはプロジェクト番号。
  • METADATA_STORE: 実行が作成されたメタデータ ストア ID。デフォルトのメタデータ ストアの名前は default です。
  • CONTEXT_ID: コンテキスト レコードの ID。

HTTP メソッドと URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/contexts/CONTEXT_ID:queryContextLineageSubgraph

リクエストを送信するには、次のいずれかのオプションを展開します。

次のような JSON レスポンスが返されます。

{
  "artifacts": [
    {
      "name": "projects/12345/locations/us-central1/metadataStores/default/artifacts/example-artifact-1",
      "displayName": "Example artifact",
      "uri": "gs://your_bucket_name/artifacts/dataset.csv",
      "etag": "678901011",
      "createTime": "2021-05-18T00:29:24.344Z",
      "updateTime": "2021-05-18T00:29:24.344Z",
      "state": "LIVE",
      "schemaTitle": "system.Dataset",
      "schemaVersion": "0.0.1",
      "metadata": {
        "payload_format": "CSV"
      },
      "description": "Description of the example artifact."
    },
    {
      "name": "projects/12345/locations/us-central1/metadataStores/default/artifacts/example-artifact-2",
      "displayName": "Example artifact 2",
      "uri": "gs://your_bucket_name/artifacts/dataset.csv",
      "etag": "678901011",
      "createTime": "2021-05-18T00:33:13.833Z",
      "updateTime": "2021-05-18T00:33:13.833Z",
      "state": "LIVE",
      "schemaTitle": "system.Dataset",
      "schemaVersion": "0.0.1",
      "metadata": {
        "payload_format": "CSV"
      },
      "description": "Description of the example artifact."
    }
  ],
  "executions": [
    {
      "name": "projects/12345/locations/us-central1/metadataStores/default/executions/example-execution-1",
      "displayName": "Example execution 1",
      "etag": "678901011",
      "createTime": "2021-05-18T00:04:49.659Z",
      "updateTime": "2021-05-18T00:04:49.659Z",
      "schemaTitle": "system.Run",
      "schemaVersion": "0.0.1",
      "metadata": {},
      "description": "Description of the example execution."
    }
  ],
  "events": [
    {
      "artifact": "projects/12345/locations/us-central1/metadataStores/default/artifacts/example-artifact-1",
      "execution": "projects/12345/locations/us-central1/metadataStores/default/executions/example-execution-1",
      "eventTime": "2021-05-18T00:04:49.659Z",,
      "type": "INPUT",
    },
    {
      "artifact": "projects/12345/locations/us-central1/metadataStores/default/artifacts/example-artifact-2",
      "execution": "projects/12345/locations/us-central1/metadataStores/default/executions/example-execution-1",
      "eventTime": "2021-05-18T00:04:49.659Z",,
      "type": "OUTPUT",
    }
  ]
}

次のステップ