Vertex ML Metadata を使用すると、ML システムによって生成されたメタデータの追跡と分析を行うことができます。このメタデータを追跡することで、ML システムの動作を簡単に分析できます。これは、システム パフォーマンスの変化の確認や、ML システムによって生成されたアーティファクトの比較を行う際に役立ちます。
Vertex ML Metadata を初めて使用する場合は、Vertex ML Metadata の概要で、ML ワークフローのメタデータの追跡と分析の詳細を確認してください。
分析する Vertex ML Metadata を以下の方法でクエリする方法について説明します。
- フィルタ条件と一致するすべてのアーティファクト、実行、コンテキストをクエリする。
- 実行の入力 / 出力アーティファクト、アーティファクトを実行に接続するために使用されたイベントをクエリする。
- コンテキストのリネージ サブグラフをクエリする。このクエリは、コンテキストのアーティファクトと実行、アーティファクトと実行を接続するイベントを返します。
アーティファクト、実行、コンテキストのクエリ
Vertex AI SDK for Python または REST API で、フィルタを使用してアーティファクト、実行、コンテキストのレコードのクエリを実行し、次のようなクエリを作成できます。
- 特定の品質基準を満たすトレーニング済みモデルのバージョンはどれか。
- 特定のパイプラインで使用されるデータセットはどれか。
以降のセクションでは、フィルタの作成方法と、アーティファクト、実行、コンテキストのクエリ方法について説明します。
フィルタ構文の概要
以降のセクションでは、フィルタを使用してアーティファクト、実行、コンテキストをクエリする方法について説明します。
フィールド
アーティファクト、実行、コンテキストをフィルタする場合、次のフィールドがサポートされます。
アーティファクト | 実行 | コンテキスト | |
---|---|---|---|
name |
|||
display_name |
|||
schema_title |
|||
create_time |
|||
update_time |
|||
metadata |
|||
state |
|||
uri |
フィルタは引用符で囲む必要があります。フィルタ内で引用符を使用する場合は、その引用符をバックスラッシュでエスケープする必要があります。
比較演算子
フィルタでは比較演算子(=
、!=
、<
、>
、>=
、<=
)を使用できます。
たとえば、次のフィルタでは、表示名が my_artifact のアーティファクトがすべて検索されます。
REST
display_name=\"my_artifact\"
Python
"display_name=\"my_artifact\""
文字列フィールドでは、ワイルドカードとして *
文字を使用できます。
create_time
や update_time
などのタイムスタンプ フィールドでは、次のように、日付を RFC 3339 形式で指定する必要があります。
REST
create_time=\"2021-05-11T12:30:00-08:00\"
Python
"create_time=\"2021-05-11T12:30:00-08:00\""
論理演算子
論理演算子 AND
と OR
を使用してフィルタを組み合わせると、複雑なクエリを作成できます。
次の例は、ai_platform.model
タイプのアーティファクトと、0.9 より大きい数値を持つ metadata
フィールド precision
をクエリしています。
REST
schema_title=\"ai_platform.Model\"+AND+metadata.precision.number_value>0.9
Python
"create_time=\"schema_title=\"ai_platform.Model\" AND metadata.precision.number_value>0.9"
トラバーサル演算子を使用してメタデータをフィルタする
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
でフィルタするには、トラバーサル演算子を使用してフィルタの対象となるフィールドを走査する必要があります。トラバーサル演算子は次の形式を使用します。
REST
metadata.FIELD_NAME.TYPE_NAME=\"FILTER_VALUE\"
Python
"metadata.FIELD_NAME.TYPE_NAME=\"FILTER_VALUE\""
たとえば、次のようなメタデータ構造を考えてみましょう。
{
"field_1": 5,
"field_2": "example",
"field_3": {
...
},
"field_4": [],
"field_5": true,
}
次のクエリでは、トラバーサル演算子を使用して、この例のメタデータをフィルタしています。
metadata.field_1
の値が 5 未満のレコードをフィルタします。
REST
metadata.field_1.number_value<5
Python
"metadata.field_1.number_value<5"
metadata.field_2
の値が example に等しいレコードをフィルタします。
REST
metadata.field_2.string_value=\"example\"
Python
"metadata.field_2.string_value=\"example\""
metadata.field_5
の値が true のレコードでフィルタします。
REST
metadata.field_5.bool_value=true
Python
"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 演算子を使用しています。
指定したパイプラインの子であるすべてのコンテキストをフィルタします。
REST
parent_contexts:\"project/12345/locations/us-central1/metadataStores/default/contexts/pipeline_1\"
Python
"parent_contexts:\"project/12345/locations/us-central1/metadataStores/default/contexts/pipeline_1\""
指定したパイプラインの親であるすべてのコンテキストをフィルタします。
REST
child_contexts:\"project/12345/locations/us-central1/metadataStores/default/contexts/pipeline_1\"
Python
"child_contexts:\"project/12345/locations/us-central1/metadataStores/default/contexts/pipeline_1\""
コンテキスト、実行、アーティファクトを関連付けとアトリビューションでフィルタする
in_context()
関数を使用すると、コンテキストに関連するアーティファクトまたは実行をフィルタできます。with_execution()
関数を使用すると、実行に関連する特定のアーティファクトまたはコンテキストをフィルタできます。同様に、with_artifact()
関数を使用すると、アーティファクトに関連付けられた特定の実行やコンテキストをフィルタできます。
フィルタ関数は、次の形式で使用します。
"in_context(\"CONTEXT_RESOURCE_NAME\")"
"with_execution(\"EXECUTION_RESOURCE_NAME\")"
"with_artifact(\"ARTIFACT_RESOURCE_NAME\")"
コンテキスト名、実行名、アーティファクト名は、次のように完全なリソース名にする必要があります。
project/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA-STORE/contexts/CONTEXT
project/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA-STORE/executions/EXECUTION
project/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA-STORE/artifacts/ARTIFACT
次の例では、指定したパイプラインに含まれるオブジェクトをフィルタしています。
REST
in_context(\"project/12345/locations/us-central1/metadataStores/default/contexts/pipeline_1\")
Python
"in_context(\"project/12345/locations/us-central1/metadataStores/default/contexts/pipeline_1\")"
フィルタ関数でワイルドカード *
を使用すると、各リソースのパラメータをフィルタできます。たとえば、以下を使用して system.model
アーティファクト タイプに影響するすべての実行をフィルタできます。
REST
with_artifact(\"*\",\"schema_title='name.model'\")
Python
"with_artifact(\"*\",\"schema_title='name.model'\")"
フィルタできるその他のサポートされているパラメータは次のとおりです。
input=true/false
: 入力または出力アーティファクトのタイプをフィルタします。event_time
: 実行時間またはアーティファクト イベント時間をフィルタします。- その他のサポートされているフィルタ フィールド
フィールドを論理オペランドと組み合わせると、複雑なフィルタクエリを作成できます。サポートされるネスト関数の最大深度は 5 です。
アーティファクトのクエリ
アーティファクト(データセットやモデルなど)は、ML ワークフローによって使用または生成されるデータを表します。次の手順でアーティファクトをクエリします。
REST
リクエストのデータを使用する前に、次のように置き換えます。
- LOCATION_ID: 使用するリージョン。
- PROJECT_ID: 実際のプロジェクト ID。
- METADATA_STORE: アーティファクトが作成されるメタデータ ストア ID。デフォルトのメタデータ ストアの名前は
default
です。 - PAGE_SIZE: 省略可。返されるアーティファクトの最大数。この値が指定されていない場合は、最大 100 件のレコードが返されます。
- PAGE_TOKEN: 省略可。前回取得した MetadataService.ListArtifacts 呼び出しのページトークン。次の結果ページを取得するには、このトークンを指定します。
FILTER: 結果セットにアーティファクトを含めるために必要な条件を指定します。
HTTP メソッドと URL:
GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN&filter=FILTER
リクエストを送信するには、次のいずれかのオプションを開きます。
出力は次のようになります。ARTIFACT_ID は、アーティファクト レコードの ID です。
{ "artifacts": [ { "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/default/artifacts/ARTIFACT_ID", "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/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID", "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." } ] }
Python
Python
project
: 実際のプロジェクト ID。これらの ID は、Google Cloud コンソールの [ようこそ] ページで確認できます。location
: 利用可能なロケーションの一覧をご覧ください。display_name_filter
: リソースの一覧表示中に表示名に適用されるフィルタ。display_name=\"my_filter\" という形式で指定します。create_date_filter
: リソースの一覧表示中に create_date 名に適用されるフィルタ。create_time>\"2022-06-11T12:30:00-08:00\" の形式で指定します。
実行のクエリ
実行は、データの前処理やモデルのトレーニングなど、ML ワークフローのステップを表します。実行をクエリするには、次の操作を行います。
REST
リクエストのデータを使用する前に、次のように置き換えます。
- LOCATION_ID: 使用するリージョン。
- PROJECT_ID: 実際のプロジェクト ID。
- METADATA_STORE: 実行が作成されたメタデータ ストア ID。デフォルトのメタデータ ストアの名前は
default
です。 - PAGE_SIZE: 省略可。返されるアーティファクトの最大数。この値が指定されていない場合は、最大 100 件のレコードが返されます。
- PAGE_TOKEN: 省略可。前回取得した MetadataService.ListArtifacts 呼び出しのページトークン。次の結果ページを取得するには、このトークンを指定します。
FILTER: 結果セットに実行を含めるために必要な条件を指定します。
HTTP メソッドと URL:
GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN&filter=FILTER
リクエストを送信するには、次のいずれかのオプションを開きます。
出力は次のようになります。EXECUTION_ID は、実行レコードの ID です。
{ "executions": [ { "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID", "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": "Description of the example execution." }, { "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID", "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": "Description of the example execution." } ] }
Python
Python
project
: 実際のプロジェクト ID。これらの ID は、Google Cloud コンソールの [ようこそ] ページで確認できます。location
: 利用可能なロケーションの一覧をご覧ください。display_name_filter
: リソースの一覧表示中に表示名に適用されるフィルタ。display_name=\"my_filter\" という形式で指定します。create_date_filter
: リソースの一覧表示中に create_date 名に適用されるフィルタ。create_time>\"2022-06-11T12:30:00-08:00\" の形式で指定します。
コンテキストのクエリ
コンテキストを使用すると、実行、アーティファクト、その他のコンテキストをグループ化できます。コンテキストのクエリを行うには、次の操作を行います。
REST
リクエストのデータを使用する前に、次のように置き換えます。
- LOCATION_ID: 使用するリージョン。
- PROJECT_ID: 実際のプロジェクト ID。
- METADATA_STORE: コンテキストが作成されたメタデータ ストア ID。デフォルトのメタデータ ストアの名前は
default
です。 - PAGE_SIZE: 省略可。返されるアーティファクトの最大数。この値が指定されていない場合は、最大 100 件のレコードが返されます。
- PAGE_TOKEN: 省略可。前回取得した MetadataService.ListArtifacts 呼び出しのページトークン。次の結果ページを取得するには、このトークンを指定します。
FILTER: 結果セットにコンテキストを含めるために必要な条件を指定します。
HTTP メソッドと URL:
GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN&filter=FILTER
リクエストを送信するには、次のいずれかのオプションを開きます。
出力は次のようになります。CONTEXT_ID は、コンテキスト レコードの ID です。
{ "contexts": [ { "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts/CONTEXT_ID", "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/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts/CONTEXT_ID", "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": {} } ] }
実行の入力 / 出力アーティファクトのクエリ
コンテキストのアーティファクトと実行、アーティファクトと実行を接続するイベントをクエリするには、次の操作を行います。
Vertex AI SDK for Python
入力アーティファクト
この Python SDK サンプルには、実行の入力アーティファクトのクエリが含まれます。
Python
出力アーティファクト
この Python SDK サンプルには、実行の出力アーティファクトに対するクエリが含まれています。
Python
REST
この REST サンプルには、実行の入力アーティファクトと出力アーティファクトの両方に対するクエリの実行が含まれています。
REST
リクエストのデータを使用する前に、次のように置き換えます。
- LOCATION_ID: 使用するリージョン。
- PROJECT_ID: 実際のプロジェクト ID。
- METADATA_STORE: 実行が作成されたメタデータ ストア ID。デフォルトのメタデータ ストアの名前は
default
です。 - EXECUTION_ID: 実行レコードの ID。
HTTP メソッドと URL:
GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID:queryExecutionInputsAndOutputs
リクエストを送信するには、次のいずれかのオプションを開きます。
出力は次のようになります。EXECUTION_ID は、実行レコードの ID です。実行 ID が指定されていない場合、Vertex ML Metadata はこの実行に一意の ID を作成しています。ARTIFACT_ID は、アーティファクト レコードの ID です。
{ "artifacts": [ { "name": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID", "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/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID", "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/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID", "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/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID", "execution": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/executions/EXECUTION_ID", "eventTime": "2021-05-18T00:04:49.659Z",, "type": "INPUT", }, { "artifact": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID", "execution": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/executions/EXECUTION_ID", "eventTime": "2021-05-18T00:04:49.659Z",, "type": "OUTPUT", } ] }
コンテキストのリネージ サブグラフのクエリ
コンテキストのアーティファクトと実行、アーティファクトと実行を接続するイベントをクエリするには、次の操作を行います。
REST
リクエストのデータを使用する前に、次のように置き換えます。
- LOCATION_ID: 使用するリージョン。
- PROJECT_ID: 実際のプロジェクト ID。
- METADATA_STORE: 実行が作成されたメタデータ ストア ID。デフォルトのメタデータ ストアの名前は
default
です。 - CONTEXT_ID: 省略可。コンテキスト レコードの ID。
HTTP メソッドと URL:
GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts/CONTEXT_ID:queryContextLineageSubgraph
リクエストを送信するには、次のいずれかのオプションを開きます。
出力は次のようになります。EXECUTION_ID は、実行レコードの ID です。実行 ID が指定されていない場合、Vertex ML Metadata はこの実行に一意の ID を作成しています。ARTIFACT_ID は、アーティファクト レコードの ID です。
{ "artifacts": [ { "name": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID", "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/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID", "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/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/executions/EXECUTION_ID", "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/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID", "execution": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/executions/EXECUTION_ID", "eventTime": "2021-05-18T00:04:49.659Z",, "type": "INPUT", }, { "artifact": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID", "execution": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/executions/EXECUTION_ID", "eventTime": "2021-05-18T00:04:49.659Z",, "type": "OUTPUT", } ] }