本頁面由 Cloud Translation API 翻譯而成。

追蹤 Vertex ML 中繼資料

Vertex 機器學習中繼資料可讓您追蹤及分析機器學習 (ML) 工作流程產生的中繼資料。如果您是 Vertex 機器學習中繼資料的新手，請參閱 Vertex 機器學習中繼資料簡介，進一步瞭解如何追蹤及分析機器學習工作流程的中繼資料。

本指南將說明如何透過下列程序記錄中繼資料：

建立 Execution，代表機器學習工作流程中的步驟。
查詢現有構件找出已寫入中繼資料儲存庫的任何輸入構件。
為尚未寫入中繼資料儲存庫的執行輸入內容，以及這項執行作業產生的任何輸出內容建立構件。
建立 Events，代表執行作業與輸入和輸出構件之間的關係。
視需要將執行作業和構件新增至 Context。使用內容將多組執行作業和構件分組。舉例來說，如果您正在實驗，想找出訓練模型的最佳超參數組合，每次實驗可能都是不同的執行作業，各有自己的參數和指標組合。您可以比較環境中的執行作業，找出產生最佳模型的實驗。

如要將執行作業和構件新增至環境，請先建立環境。

建立 Vertex 機器學習中繼資料資產的方法有兩種。您可以選擇使用 REST 指令或 Python 適用的 Vertex AI SDK。Python SDK 可簡化各種資產類型的建立和探索作業。使用 Python 建立執行作業時，不必手動建構酬載。

事前準備

首次在Google Cloud 專案中使用 Vertex ML Metadata 時，Vertex AI 會建立專案的 Vertex ML Metadata 儲存庫。

如要使用客戶自行管理的加密金鑰 (CMEK) 加密中繼資料，請先使用 CMEK 建立中繼資料存放區，再使用 Vertex ML Metadata 追蹤或分析中繼資料。按照建立使用 CMEK 的中繼資料儲存庫操作說明，設定專案的中繼資料儲存庫。

可建立執行作業

執行作業代表機器學習工作流程中的一個步驟。請按照下列操作說明建立執行作業。

REST

使用任何要求資料之前，請先替換以下項目：

LOCATION_ID：您的區域。
PROJECT_ID：您的專案 ID。
METADATA_STORE：建立執行的中繼資料商店 ID。預設中繼資料儲存庫的名稱為 default。
EXECUTION_ID：執行記錄的 ID。如未指定執行 ID，Vertex ML Metadata 會為這項執行作業建立專屬 ID。
DISPLAY_NAME：執行的顯示名稱。這個欄位最多可包含 128 個 Unicode 字元。
EXECUTION_STATE：(選用) State 列舉中的值，代表目前執行狀態。這個欄位是由用戶端應用程式管理。 Vertex 機器學習中繼資料不會檢查狀態轉換的有效性。
METADATA_SCHEMA_TITLE：描述中繼資料欄位的結構定義標題。結構定義的標題必須符合 `.` 格式。命名空間開頭必須是小寫字母，可包含小寫字元和數字，長度為 2 到 20 個字元。結構定義名稱開頭須為大寫英文字母，可包含英文字母和數字，長度介於 2 到 49 個字元。
METADATA_SCHEMA_VERSION：(選用) 描述中繼資料欄位的結構定義版本。schema_version 必須是三個以半形句點分隔的數字字串，例如 1.0.0、1.0.1。這個格式有助於排序及比較版本。
METADATA：(選用) 說明執行的屬性，例如執行參數。
DESCRIPTION：(選用) 說明要建立的執行作業用途，使用者可理解的字串。
LABELS：選用。使用者定義的中繼資料，用於整理執行作業。

HTTP 方法和網址：

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions?executionId=EXECUTION_ID

JSON 要求主體：

{
  "displayName": "DISPLAY_NAME",
  "state": "EXECUTION_STATE",
  "schemaTitle": "METADATA_SCHEMA_TITLE",
  "schemaVersion": "METADATA_SCHEMA_VERSION",
  "metadata": {
    METADATA
  },
  "labels": {"LABEL_1":"LABEL_2"},
  "description": "DESCRIPTION"

}

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中。在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

cat > request.json << 'EOF'
{
  "displayName": "DISPLAY_NAME",
  "state": "EXECUTION_STATE",
  "schemaTitle": "METADATA_SCHEMA_TITLE",
  "schemaVersion": "METADATA_SCHEMA_VERSION",
  "metadata": {
    METADATA
  },
  "labels": {"LABEL_1":"LABEL_2"},
  "description": "DESCRIPTION"

}
EOF

接著，請執行下列指令來傳送 REST 要求：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions?executionId=EXECUTION_ID"

PowerShell (Windows)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中。在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

@'
{
  "displayName": "DISPLAY_NAME",
  "state": "EXECUTION_STATE",
  "schemaTitle": "METADATA_SCHEMA_TITLE",
  "schemaVersion": "METADATA_SCHEMA_VERSION",
  "metadata": {
    METADATA
  },
  "labels": {"LABEL_1":"LABEL_2"},
  "description": "DESCRIPTION"

}
'@  | Out-File -FilePath request.json -Encoding utf8

接著，請執行下列指令來傳送 REST 要求：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions?executionId=EXECUTION_ID" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

{
  "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID",
  "displayName": "Example Execution",
  "etag": "67891011",
  "labels": {
    "test_label": "test_label_value"
  },
  "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

from typing import Any, Dict, List, Optional

from google.cloud import aiplatform
from google.cloud.aiplatform.metadata.schema.system import execution_schema


def create_execution_sample(
    display_name: str,
    input_artifacts: List[aiplatform.Artifact],
    output_artifacts: List[aiplatform.Artifact],
    project: str,
    location: str,
    execution_id: Optional[str] = None,
    metadata: Optional[Dict[str, Any]] = None,
    schema_version: Optional[str] = None,
    description: Optional[str] = None,
):
    aiplatform.init(project=project, location=location)

    with execution_schema.ContainerExecution(
        display_name=display_name,
        execution_id=execution_id,
        metadata=metadata,
        schema_version=schema_version,
        description=description,
    ).create() as execution:
        execution.assign_input_artifacts(input_artifacts)
        execution.assign_output_artifacts(output_artifacts)
        return execution

display_name：執行的顯示名稱。這個欄位最多可包含 128 個 Unicode 字元。
input_artifacts：一或多個 aiplatform.Artifact 執行個體的清單，代表輸入構件。
output_artifacts：一或多個 aiplatform.Artifact 執行個體的清單，代表輸出 Artifact。
project：您的專案 ID。您可以在 Google Cloud 控制台歡迎頁面中找到這些 ID。
location：請參閱「可用位置清單」。
execution_id：執行記錄的 ID。如未指定執行 ID，Vertex ML Metadata 會為這項執行作業建立專屬 ID。
metadata：描述執行的屬性，例如執行參數。
schema_version：描述中繼資料欄位的結構定義版本。
description：(選用) 方便使用者閱讀的字串，說明要建立的執行作業用途。

查詢現有構件

構件代表機器學習工作流程使用或產生的資料，例如資料集和模型。請按照下列操作說明查詢現有構件。

REST

使用任何要求資料之前，請先替換以下項目：

LOCATION_ID：您的區域。
PROJECT_ID：您的專案 ID。
METADATA_STORE：建立構件的中繼資料儲存庫 ID。預設中繼資料儲存庫的名稱為 default。
PAGE_SIZE：(選用) 要傳回的構件數量上限。如未指定這個值，服務最多會傳回 100 筆記錄。
PAGE_TOKEN：(選用) 先前 MetadataService.ListArtifacts 呼叫傳回的頁面符記。指定這個符記即可取得下一頁結果。
FILTER：指定將構件納入結果集所需的條件。

HTTP 方法和網址：

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

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

執行下列指令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "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"

PowerShell (Windows)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "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" | Select-Object -Expand Content

畫面會顯示類似以下的輸出內容。 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

from typing import Optional

from google.cloud import aiplatform


def list_artifact_sample(
    project: str,
    location: str,
    display_name_filter: Optional[str] = "display_name=\"my_model_*\"",
    create_date_filter: Optional[str] = "create_time>\"2022-06-11\"",
    order_by: Optional[str] = None,
):
    aiplatform.init(project=project, location=location)

    combined_filters = f"{display_name_filter} AND {create_date_filter}"
    return aiplatform.Artifact.list(
        filter=combined_filters,
        order_by=order_by,
    )

project：您的專案 ID。您可以在 Google Cloud 控制台歡迎頁面中找到這些 ID。
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。
ARTIFACT_ID：(選用) 構件記錄的 ID。如未指定構件 ID，Vertex ML Metadata 會為這個構件建立專屬 ID。
DISPLAY_NAME：(選用) 使用者定義的構件名稱。
URI：(選用) 儲存構件的位置
ARTIFACT_STATE：(選用) State 列舉中的值，代表構件的目前狀態。這個欄位是由用戶端應用程式管理。Vertex 機器學習中繼資料不會檢查狀態轉換的有效性。
METADATA_SCHEMA_TITLE：描述中繼資料欄位的結構定義標題。結構定義的標題必須符合 `.` 格式。命名空間開頭必須是小寫字母，可包含小寫字元和數字，長度為 2 到 20 個字元。結構定義名稱開頭須為大寫英文字母，可包含英文字母和數字，長度介於 2 到 49 個字元。
METADATA_SCHEMA_VERSION：(選用) 描述中繼資料欄位的結構定義版本。schema_version 必須是三個數字組成的字串，中間以半形句點分隔，例如 1.0.0、1.0.1。這個格式有助於排序及比較版本。
METADATA：(選用)。描述構件的屬性，例如資料集類型。
DESCRIPTION：(選用) 方便使用者閱讀的字串，說明要建立的執行作業用途。
LABELS：選用。使用者定義的中繼資料，用於整理構件。

HTTP 方法和網址：

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts?artifactId=ARTIFACT_ID

JSON 要求主體：

{
  "displayName": "DISPLAY_NAME",
  "uri": "URI",
  "state": "ARTIFACT_STATE",
  "schemaTitle": "METADATA_SCHEMA_TITLE",
  "schemaVersion": "METADATA_SCHEMA_VERSION",
  "metadata": {
    METADATA
  },
  "labels": {"LABEL_1":"LABEL_2"},
  "description": "DESCRIPTION"
}

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

將要求主體儲存在名為 request.json 的檔案中。在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

cat > request.json << 'EOF'
{
  "displayName": "DISPLAY_NAME",
  "uri": "URI",
  "state": "ARTIFACT_STATE",
  "schemaTitle": "METADATA_SCHEMA_TITLE",
  "schemaVersion": "METADATA_SCHEMA_VERSION",
  "metadata": {
    METADATA
  },
  "labels": {"LABEL_1":"LABEL_2"},
  "description": "DESCRIPTION"
}
EOF

接著，請執行下列指令來傳送 REST 要求：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts?artifactId=ARTIFACT_ID"

PowerShell (Windows)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中。在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

@'
{
  "displayName": "DISPLAY_NAME",
  "uri": "URI",
  "state": "ARTIFACT_STATE",
  "schemaTitle": "METADATA_SCHEMA_TITLE",
  "schemaVersion": "METADATA_SCHEMA_VERSION",
  "metadata": {
    METADATA
  },
  "labels": {"LABEL_1":"LABEL_2"},
  "description": "DESCRIPTION"
}
'@  | Out-File -FilePath request.json -Encoding utf8

接著，請執行下列指令來傳送 REST 要求：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts?artifactId=ARTIFACT_ID" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

{
  "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",
  "labels": {
    "test_label": "test_label_value"
  },
  "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."
}

Python

from typing import Dict, Optional

from google.cloud.aiplatform.metadata.schema.system import artifact_schema


def create_artifact_sample(
    project: str,
    location: str,
    uri: Optional[str] = None,
    artifact_id: Optional[str] = None,
    display_name: Optional[str] = None,
    schema_version: Optional[str] = None,
    description: Optional[str] = None,
    metadata: Optional[Dict] = None,
):
    system_artifact_schema = artifact_schema.Artifact(
        uri=uri,
        artifact_id=artifact_id,
        display_name=display_name,
        schema_version=schema_version,
        description=description,
        metadata=metadata,
    )
    return system_artifact_schema.create(project=project, location=location,)

project：您的專案 ID。您可以在 Google Cloud 控制台歡迎頁面中找到這些 ID。
location：請參閱「可用位置清單」。
uri：(選用) 如果構件檔案有統一資源識別碼，請提供該識別碼。如果沒有實際的構件檔案，則可能為空白。
artifact_id：(選用) 構件記錄的 ID。如未指定構件 ID，Vertex ML Metadata 會為這個構件建立專屬 ID。
display_name：(選用) 使用者定義的構件名稱。
schema_version：描述中繼資料欄位的結構定義版本。
description：(選用) 說明待建立構件用途的字串，方便使用者閱讀。
metadata：描述構件的屬性，例如構件參數。

建立事件，將構件連結至執行作業

事件代表執行作業與輸入和輸出構件之間的關係。請按照下列操作說明建立事件，將構件連結至執行作業。

REST

使用任何要求資料之前，請先替換以下項目：

LOCATION_ID：您的區域。
PROJECT_ID：您的專案 ID。
METADATA_STORE：建立執行的中繼資料商店 ID。預設中繼資料儲存庫的名稱為 default。
EXECUTION_ID：執行記錄的 ID。
ARTIFACT：構件的資源名稱。資源名稱的格式如下： projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID
EVENT_TYPE：(選用) EventType 列舉中的值，用於指定構件是否為執行的輸入或輸出。

HTTP 方法和網址：

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID:addExecutionEvents

JSON 要求主體：

{
  "events": [
    {
      "artifact": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID",
      "type": "EVENT_TYPE"
    }
  ]
}

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

將要求主體儲存在名為 request.json 的檔案中。在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

cat > request.json << 'EOF'
{
  "events": [
    {
      "artifact": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID",
      "type": "EVENT_TYPE"
    }
  ]
}
EOF

接著，請執行下列指令來傳送 REST 要求：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID:addExecutionEvents"

PowerShell (Windows)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中。在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

@'
{
  "events": [
    {
      "artifact": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID",
      "type": "EVENT_TYPE"
    }
  ]
}
'@  | Out-File -FilePath request.json -Encoding utf8

接著，請執行下列指令來傳送 REST 要求：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID:addExecutionEvents" | Select-Object -Expand Content

您應該會收到執行成功的狀態碼 (2xx) 和空白回應。

Python

from typing import Any, Dict, List, Optional

from google.cloud import aiplatform
from google.cloud.aiplatform.metadata.schema.system import execution_schema


def create_execution_sample(
    display_name: str,
    input_artifacts: List[aiplatform.Artifact],
    output_artifacts: List[aiplatform.Artifact],
    project: str,
    location: str,
    execution_id: Optional[str] = None,
    metadata: Optional[Dict[str, Any]] = None,
    schema_version: Optional[str] = None,
    description: Optional[str] = None,
):
    aiplatform.init(project=project, location=location)

    with execution_schema.ContainerExecution(
        display_name=display_name,
        execution_id=execution_id,
        metadata=metadata,
        schema_version=schema_version,
        description=description,
    ).create() as execution:
        execution.assign_input_artifacts(input_artifacts)
        execution.assign_output_artifacts(output_artifacts)
        return execution

input_artifacts：一或多個 aiplatform.Artifact 執行個體的清單，代表輸入構件。
output_artifacts：一或多個 aiplatform.Artifact 執行個體的清單，代表輸出 Artifact。
project：您的專案 ID。您可以在 Google Cloud 控制台歡迎頁面中找到這些 ID。
location：請參閱「可用位置清單」。
execution_id：執行記錄的 ID。如未指定執行 ID，Vertex ML Metadata 會為這項執行作業建立專屬 ID。
metadata 描述執行的屬性，例如執行參數。
schema_version：描述中繼資料欄位的結構定義版本。
description：(選用) 方便使用者閱讀的字串，說明要建立的執行作業用途。

建立脈絡

您可以將一組構件和執行項目分在同一個環境中。請按照下列操作說明建立內容。請注意，Vertex AI Experiments 會建立環境，並自動記錄該環境的構件和執行作業 (請參閱「建立或刪除實驗」)。

REST

使用任何要求資料之前，請先替換以下項目：

LOCATION_ID：您的區域。
PROJECT_ID：您的專案 ID。
METADATA_STORE：建立執行的中繼資料商店 ID。預設中繼資料儲存庫的名稱為 default。
CONTEXT_ID：(選用) 內容記錄的 ID。如未指定內容 ID，Vertex ML Metadata 會為這個內容建立專屬 ID
DISPLAY_NAME：情境的顯示名稱。這個欄位最多可包含 128 個 Unicode 字元。
PARENT_CONTEXT：指定任何父項環境的資源名稱。一個內容最多只能有 10 個父項內容。
METADATA_SCHEMA_TITLE：描述中繼資料欄位的結構定義標題。結構定義的標題必須符合 `.` 格式。命名空間開頭必須是小寫字母，可包含小寫字元和數字，長度為 2 到 20 個字元。結構定義名稱開頭須為大寫英文字母，可包含英文字母和數字，長度介於 2 到 49 個字元。
METADATA_SCHEMA_VERSION：(選用) 描述中繼資料欄位的結構定義版本。schema_version 必須是三個數字組成的字串，中間以半形句點分隔，例如 1.0.0、1.0.1。這個格式有助於排序及比較版本。
METADATA：描述背景資訊的屬性，例如背景資訊參數。
DESCRIPTION(選用) 說明要建立的執行作業用途，使用者容易理解的字串。
LABELS：選用。使用者定義的中繼資料，用於整理情境。

HTTP 方法和網址：

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts?contextId=CONTEXT_ID

JSON 要求主體：

{
  "displayName": "DISPLAY_NAME:",
  "parentContexts": [
    "PARENT_CONTEXT_1",
    "PARENT_CONTEXT_2"
  ],
  "schemaTitle": "METADATA_SCHEMA_TITLE",
  "schemaVersion": "METADATA_SCHEMA_VERSION",
  "metadata": {
    METADATA
  },
  "labels": {"LABEL_1":"LABEL_2"},
  "description": "DESCRIPTION"

}

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

將要求主體儲存在名為 request.json 的檔案中。在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

cat > request.json << 'EOF'
{
  "displayName": "DISPLAY_NAME:",
  "parentContexts": [
    "PARENT_CONTEXT_1",
    "PARENT_CONTEXT_2"
  ],
  "schemaTitle": "METADATA_SCHEMA_TITLE",
  "schemaVersion": "METADATA_SCHEMA_VERSION",
  "metadata": {
    METADATA
  },
  "labels": {"LABEL_1":"LABEL_2"},
  "description": "DESCRIPTION"

}
EOF

接著，請執行下列指令來傳送 REST 要求：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts?contextId=CONTEXT_ID"

PowerShell (Windows)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中。在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

@'
{
  "displayName": "DISPLAY_NAME:",
  "parentContexts": [
    "PARENT_CONTEXT_1",
    "PARENT_CONTEXT_2"
  ],
  "schemaTitle": "METADATA_SCHEMA_TITLE",
  "schemaVersion": "METADATA_SCHEMA_VERSION",
  "metadata": {
    METADATA
  },
  "labels": {"LABEL_1":"LABEL_2"},
  "description": "DESCRIPTION"

}
'@  | Out-File -FilePath request.json -Encoding utf8

接著，請執行下列指令來傳送 REST 要求：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts?contextId=CONTEXT_ID" | Select-Object -Expand Content

畫面會顯示類似以下的輸出內容。 CONTEXT_ID 是內容記錄的 ID。

{
  "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts/CONTEXT_ID",
  "displayName": "Example context:",
  "etag": "67891011",
  "labels": {
    "test_label": "test_label_value"
  },
  "createTime": "2021-05-18T01:52:51.642Z",
  "updateTime": "2021-05-18T01:52:51.642Z",
  "schemaTitle": "system.Experiment",
  "schemaVersion": "0.0.1",
  "metadata": {},
  "description": "Description of the example context."
}

Python

from typing import Any, Dict, Optional

from google.cloud import aiplatform
from google.cloud.aiplatform.metadata.schema.system import context_schema


def create_context_sample(
    display_name: str,
    project: str,
    location: str,
    context_id: Optional[str] = None,
    metadata: Optional[Dict[str, Any]] = None,
    schema_version: Optional[str] = None,
    description: Optional[str] = None,
):
    aiplatform.init(project=project, location=location)

    return context_schema.Experiment(
        display_name=display_name,
        context_id=context_id,
        metadata=metadata,
        schema_version=schema_version,
        description=description,
    ).create()

display_name：情境的顯示名稱。這個欄位最多可包含 128 個 Unicode 字元。
project：您的專案 ID。您可以在 Google Cloud 控制台歡迎頁面中找到這些 ID。
location：請參閱「可用位置清單」。
context_id：(選用) 內容記錄的 ID。
metadata 描述內容的屬性，例如內容參數。
schema_version：描述中繼資料欄位的結構定義版本。
description：(選用) 說明要建立的環境用途，使用者可理解的字串。

在環境中新增構件和執行作業

請按照下列操作說明，將構件和執行作業新增至環境。

REST

使用任何要求資料之前，請先替換以下項目：

LOCATION_ID：您的區域。
PROJECT_ID：您的專案 ID。
METADATA_STORE：建立執行的中繼資料商店 ID。預設中繼資料儲存庫的名稱為 default。
CONTEXT：(選用) 內容記錄的 ID。
指定要新增至這個環境的任何構件的 ARTIFACT 資源名稱。資源名稱的格式如下：
projects/PROJECT_ID/locations/location/metadataStores/metadata-store/artifacts/artifact
指定要新增至這個環境的任何執行作業的 EXECUTION 資源名稱。資源名稱的格式如下：
projects/PROJECT_ID/locations/location/metadataStores/metadata-store/executions/execution

HTTP 方法和網址：

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts/CONTEXT:addContextArtifactsAndExecutions

JSON 要求主體：

{
  "artifacts": [
    "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID"
  ],
  "executions": [
  "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID"
  ]
}

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

將要求主體儲存在名為 request.json 的檔案中。在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

cat > request.json << 'EOF'
{
  "artifacts": [
    "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID"
  ],
  "executions": [
  "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID"
  ]
}
EOF

接著，請執行下列指令來傳送 REST 要求：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts/CONTEXT:addContextArtifactsAndExecutions"

PowerShell (Windows)

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中。在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

@'
{
  "artifacts": [
    "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID"
  ],
  "executions": [
  "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID"
  ]
}
'@  | Out-File -FilePath request.json -Encoding utf8

接著，請執行下列指令來傳送 REST 要求：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts/CONTEXT:addContextArtifactsAndExecutions" | Select-Object -Expand Content

您應該會收到執行成功的狀態碼 (2xx) 和空白回應。

筆記本

如要瞭解詳情，請在所選環境中執行下列筆記本：

「追蹤 Vertex AI 自訂訓練工作的指標和參數，並執行詳細分析」：
在 Colab 中開啟 | 在 Colab Enterprise 中開啟 | 在 Vertex AI Workbench 使用者管理的筆記本中開啟 | 在 GitHub 上查看
「追蹤機器學習訓練工作的指標和參數，並使用 Vertex AI SDK 分析這項中繼資料」：
在 Colab 中開啟 | 在 Colab Enterprise 中開啟 | 在 Vertex AI Workbench 使用者管理的筆記本中開啟 | 在 GitHub 上查看
「使用 Vertex 機器學習中繼資料，追蹤 Vertex AI 管道執行作業中的構件和指標」：
在 Colab 中開啟 | 在 Colab Enterprise 中開啟 | 在 Vertex AI Workbench 使用者管理的筆記本中開啟 | 在 GitHub 上查看

後續步驟

開始分析 Vertex 機器學習中繼資料。

追蹤 Vertex ML 中繼資料 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

可建立執行作業

REST

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

Python

Python

查詢現有構件

REST

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

Python

Python

可建立構件

REST

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

Python

Python

建立事件，將構件連結至執行作業

REST

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

Python

Python

建立脈絡

REST

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

Python

Python

在環境中新增構件和執行作業

REST

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

筆記本

後續步驟

追蹤 Vertex ML 中繼資料