ML-Metadaten analysieren

Mithilfe von Vertex ML-Metadaten können Sie die von Ihren Systemen für maschinelles Lernen (ML) generierten Metadaten verfolgen und analysieren. Das Verfolgen dieser Metadaten vereinfacht das Analysieren des Verhaltens Ihres ML-Systems. Damit können Sie Änderungen der Systemleistung nachvollziehen oder die Artefakte vergleichen, die das ML-System generiert.

Wenn Sie neu bei Vertex ML Metadata sind, lesen Sie die Einführung in Vertex ML Metadata, um weitere Informationen zum Tracking und Analysieren der Metadaten Ihres ML-Workflows zu erhalten.

In diesem Dokument werden die Abfragen für die ML-Metadaten erläutert, die Sie analysieren möchten:

Artefakten, Ausführungen und Kontexte abfragen

Mit der REST API können Sie Artefakte, Ausführungen und Kontextdatensätze abfragen und anhand von Filtern Abfragen wie diese erstellen:

  • Welche Versionen eines trainierten Modells haben einen bestimmten Qualitätsgrenzwert erreicht?
  • Welche Pipelineausführungen verwenden ein bestimmtes Dataset?

In den folgenden Abschnitten wird gezeigt, wie Sie Filter erstellen und wie Sie damit Abfragen nach Artefakten, Ausführungen und Kontexten durchführen können.

Übersicht über die Filtersyntax

In den folgenden Abschnitten wird beschrieben, wie Sie mithilfe von Filtern Artefakte, Ausführungen und Kontexte abfragen.

Felder

Die folgenden Felder werden beim Filtern von Artefakten, Ausführungen und Kontexten unterstützt.

Artefakt Ausführung Kontext
name
display_name
schema_title
create_time
update_time
metadata
state
uri

Der Filter muss in Anführungszeichen gesetzt werden und alle Anführungszeichen, die Teil des Filters sind, müssen mit einem umgekehrten Schrägstrich maskiert werden.

Vergleichsoperator

Sie können die folgenden Vergleichsoperatoren in den Filtern verwenden: =, !=, <, >, >=, <=.

Mit den folgenden Filtern können Sie beispielsweise alle Artefakte ermitteln, deren Anzeigename my_artifact lautet.

"display_name=\"my_artifact\""

Für Stringfelder können Sie die Platzhalterfilterung mit dem *-Zeichen verwenden.

Bei Zeitstempelfeldern wie create_time und update_time müssen Sie das Datum im Format RFC 3339 formatieren. Beispiel:

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

Mit dem Operator "traversal" nach Metadaten filtern

Das Feld metadata ist eine Instanz von google.protobuf.Struct, dessen Format in dem Schema definiert ist, das im Feld schema_title angegeben wird. google.protobuf.Struct ist eine Datenstruktur, die google.protobuf.Value-Instanzen Schlüssel zuordnet. In der Datenstruktur google.protobuf.Value werden Werte je nach Datentyp in unterschiedlichen Feldern gespeichert. Beispiel: Strings werden als metadata.FIELD_NAME.string_value, Zahlen als metadata.FIELD_NAME.number_value und boolesche Werte als metadata.FIELD_NAME.bool_value gespeichert.

Wenn Sie nach metadata filtern möchten, müssen Sie den Operator "traversal" verwenden, um zu dem Feld zu gelangen, nach dem Sie filtern möchten. Der Operator "traversal" hat folgendes Format:

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

Betrachten Sie beispielsweise die folgende Metadatenstruktur:

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

Die folgenden Abfragen zeigen, wie Sie mit dem Operator "traversal" nach diesen Beispielmetadaten filtern können.

  • Filtern Sie nach Einträgen mit metadata.field_1 mit einem Wert unter 5.

    "metadata.field_1.number_value<5"

  • Filtern Sie nach Einträgen mit metadata.field_2 mit einem Wert gleich example.

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

  • Filtern Sie nach Einträgen mit metadata.field_5 mit einem Wert gleich true.

    "metadata.field_5.bool_value=true"

Nach Kontexten anhand ihrer übergeordneten/untergeordneten Beziehungen filtern

Mit dem Operator has können Sie nach Kontexten suchen, die einem bestimmten Kontext über- oder untergeordnet sind.

Der „has“-Operator hat folgendes Format:

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

Der Kontextname muss der vollständige Ressourcenname des Kontextes sein, wie im Folgenden dargestellt: project/PROJECT/locations/LOCATION/metadataStores/METADATA-STORE/contexts/CONTEXT.

Die folgenden Filter zeigen, wie der Operator „has“ verwendet wird:

  • Nach allen Kontexten filtern, die der angegebenen Pipeline untergeordnet sind.

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

  • Nach allen Kontexten filtern, die der angegebenen Pipeline übergeordnet sind.

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

Nach Artefakten und Ausführungen in einem bestimmten Kontext filtern

Mit der Funktion in_context() können Sie nach Artefakten oder Ausführungen filtern, die einem Kontext zugeordnet sind.

Die Funktion in_context() hat das folgende Format:

"in_context(\"CONTEXT_RESOURCE_NAME\")"

Der Kontextname muss der vollständige Ressourcenname des Kontextes sein, wie im Folgenden dargestellt.

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

Das folgende Beispiel zeigt, wie Sie nach Objekten in der angegebenen Pipeline filtern.

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

Logische Operatoren

Sie können die logischen Operatoren AND und OR verwenden, um Filter zu kombinieren und eine komplexe Abfrage zu erstellen.

Das folgende Beispiel zeigt, wie Artefakte vom Typ ai_platform.model und das metadata-Feld precision mit einem numerischen Wert größer als 0,9 abgefragt werden.

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

Artefakte abfragen

Artefakte stellen Daten dar, die von Ihrem ML-Workflow verwendet oder erstellt werden, z. B. Datasets und Modelle. Verwenden Sie die folgende Anleitung, um Artifakte abzufragen.

Ersetzen Sie dabei folgende Werte für die Anfragedaten:

  • LOCATION: Ihre Region.
  • PROJECT: Ihre Projekt-ID oder Projektnummer
  • METADATA_STORE: Die ID des Metadatenspeichers, in dem das Artefakt erstellt wird. Der Standardmetadatenspeicher heißt default.
  • PAGE_SIZE: (Optional) Die maximale Anzahl der zurückzugebenden Artefakte. Wenn dieser Wert nicht angegeben ist, werden maximal 100 Einträge zurückgegeben.
  • PAGE_TOKEN: (Optional) Ein Seitentoken aus einem vorherigen Aufruf von MetadataService.ListArtifacts. Geben Sie dieses Token an, um die nächste Ergebnisseite abzurufen.
  • FILTER: Gibt die Bedingungen an, die erforderlich sind, um eine Ausführung in die Ergebnismenge aufzunehmen.

HTTP-Methode und URL:

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

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

Ausführungen abfragen

Ausführungen stellen einen Schritt in Ihrem ML-Workflow dar, wie z. B. das Vorverarbeiten von Daten oder das Trainieren eines Modells. Gehen Sie nach der folgenden Anleitung vor, um Ausführungen abzufragen.

Ersetzen Sie dabei folgende Werte für die Anfragedaten:

  • LOCATION: Ihre Region.
  • PROJECT: Ihre Projekt-ID oder Projektnummer
  • METADATA_STORE: Die ID des Metadatenspeichers, in dem die Ausführung erstellt wird. Der Standardmetadatenspeicher heißt default.
  • PAGE_SIZE: (Optional) Die maximale Anzahl der Ausführungen, die zurückgegeben werden sollen. Wenn dieser Wert nicht angegeben ist, werden maximal 100 Einträge zurückgegeben.
  • PAGE_TOKEN: (Optional) Ein Seitentoken aus einem früheren MetadataService.ListExecutions-Aufruf. Geben Sie dieses Token an, um die nächste Ergebnisseite abzurufen.
  • FILTER: Gibt die Bedingungen an, die erforderlich sind, um eine Ausführung in die Ergebnismenge aufzunehmen.

HTTP-Methode und URL:

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

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

Kontexte abfragen

Mit Kontexten können Sie Ausführungen, Artefakte und andere Kontexte gruppieren. Verwenden Sie die folgende Anleitung, um Kontexte abzufragen.

Ersetzen Sie dabei folgende Werte für die Anfragedaten:

  • LOCATION: Ihre Region.
  • PROJECT: Ihre Projekt-ID oder Projektnummer
  • METADATA_STORE: Die ID des Metadatenspeichers, in dem die Ausführung erstellt wird. Der Standardmetadatenspeicher heißt default.
  • PAGE_SIZE: (Optional) Die maximale Anzahl von Kontexten, die zurückgegeben werden sollen. Wenn dieser Wert nicht angegeben ist, werden maximal 100 Einträge zurückgegeben.
  • PAGE_TOKEN: (Optional) Ein Seitentoken aus einem früheren MetadataService.ListExecutions-Aufruf. Geben Sie dieses Token an, um die nächste Ergebnisseite abzurufen.
  • FILTER: Gibt die Bedingungen an, die erforderlich sind, um einen Kontext in die Ergebnismenge aufzunehmen.

HTTP-Methode und URL:

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie müssten in etwa folgende JSON-Antwort erhalten:

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

Eingabe- und Ausgabeartefakte einer Ausführung abfragen

Gehen Sie nach der folgenden Anleitung vor, um die Artefakte und Ausführungen im angegebenen Kontext sowie die Ereignisse abzufragen, die Artefakte mit den Ausführungen verbinden.

Ersetzen Sie dabei folgende Werte für die Anfragedaten:

  • LOCATION: Ihre Region.
  • PROJECT: Ihre Projekt-ID oder Projektnummer
  • METADATA_STORE: Die ID des Metadatenspeichers, in dem die Ausführung erstellt wird. Der Standardmetadatenspeicher heißt default.
  • EXECUTION_ID: Die ID des Ausführungsdatensatzes.

HTTP-Methode und URL:

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie müssten in etwa folgende JSON-Antwort erhalten:

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

Abfrage des Herkunftsunterdiagramms eines Kontexts

Gehen Sie nach der folgenden Anleitung vor, um die Artefakte und Ausführungen im angegebenen Kontext sowie die Ereignisse abzufragen, die Artefakte mit den Ausführungen verbinden.

Ersetzen Sie dabei folgende Werte für die Anfragedaten:

  • LOCATION: Ihre Region.
  • PROJECT: Ihre Projekt-ID oder Projektnummer
  • METADATA_STORE: Die ID des Metadatenspeichers, in dem die Ausführung erstellt wird. Der Standardmetadatenspeicher heißt default.
  • CONTEXT_ID: Die ID des Kontext-Eintrags.

HTTP-Methode und URL:

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten in etwa folgende JSON-Antwort erhalten:

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

Nächste Schritte