跟踪 Vertex ML Metadata

通过 Vertex ML Metadata，您可以跟踪和分析机器学习 (ML) 工作流生成的元数据。如果您刚开始接触 Vertex ML Metadata，请参阅 Vertex ML Metadata 简介以详细了解如何跟踪和分析机器学习工作流的元数据。

本指南演示了如何通过以下流程记录元数据：

1. 创建一个执行作业，表示机器学习工作流中的一个步骤。
2. 查询现有工件以找到任何已写入元数据存储区的输入工件。
3. 为执行作业尚未写入元数据存储区的输入以及此执行作业生成的任何输出创建工件。
4. 创建事件以表示执行作业与其输入和输出工件之间的关系。

5. （可选）为上下文添加执行作业和工件。使用上下文将执行作业和工件集组合在一起。例如，如果您要通过实验找到最佳的超参数集来训练模型，则每个实验都可能是不同的使用其各自参数和指标集的执行作业。您可以比较上下文中的执行作业，以找到生成最佳模型的实验。

   您必须先创建上下文，然后才能为上下文添加执行作业和工件。

您可以通过以下两种方法创建 Vertex ML Metadata 资源。您可以使用 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 会为执行作业创建一个唯一标识符。
• DISPLAY_NAME：执行作业的显示名称。此字段最多可包含 128 个 Unicode 字符。
• EXECUTION_STATE：（可选）状态枚举中的值，表示执行作业的当前状态。此字段由客户端应用管理。Vertex ML Metadata 不会检查状态转换的有效性。
• METADATA_SCHEMA_TITLE：描述元数据字段的架构的标题。架构的标题必须符合格式“.”。命名空间必须以小写字母开头，可以包含小写字符和数字，并且长度可以是 2 到 20 个字符。架构名称必须以大写字母开头，可以包含字母和数字，并且长度可以是 2 到 49 个字符。
• METADATA_SCHEMA_VERSION：（可选）描述元数据字段的架构的版本。 schema_version 必须是用句点分隔的 3 个数字的字符串，例如 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

Python

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 实例的列表。
• project：您的项目 ID。 您可以在 Google Cloud 控制台的欢迎页面中找到这些 ID。
• location：请参阅可用位置列表。
• execution_id：执行记录的 ID。如果未指定执行作业 ID，则 Vertex ML Metadata 会为执行作业创建一个唯一标识符。
• 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）

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

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

Python

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 会为此工件创建一个唯一标识符。
• DISPLAY_NAME：（可选）用户定义的工件名称。
• URI：（可选）工件的存储位置。
• ARTIFACT_STATE：（可选）状态枚举中的值，表示工件的当前状态。此字段由客户端应用管理。Vertex ML Metadata 不会检查状态转换的有效性。
• METADATA_SCHEMA_TITLE：描述元数据字段的架构的标题。架构的标题必须符合格式“.”。命名空间必须以小写字母开头，可以包含小写字符和数字，并且长度可以是 2 到 20 个字符。架构名称必须以大写字母开头，可以包含字母和数字，并且长度可以是 2 到 49 个字符。
• METADATA_SCHEMA_VERSION：（可选）描述元数据字段的架构的版本。 schema_version 必须是用句点分隔的 3 个数字的字符串，例如 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）

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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

Python

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 会为此工件创建一个唯一标识符。
• 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）

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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

Python

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 实例的列表。
• project：您的项目 ID。 您可以在 Google Cloud 控制台的欢迎页面中找到这些 ID。
• location：请参阅可用位置列表。
• execution_id：执行记录的 ID。如果未指定执行作业 ID，则 Vertex ML Metadata 会为执行作业创建一个唯一标识符。
• metadata：描述执行作业的属性，例如执行参数。
• schema_version：描述元数据字段的架构的版本。
• description：（可选）人类可读的字符串，用于描述要创建的执行的用途。

创建上下文

借助上下文，您可以将工件和执行作业集组合在一起。按照以下说明创建上下文。请注意，Vertex AI Experiments 会创建一个上下文，以根据该上下文自动记录工件和执行（请参阅创建或删除实验）。

REST

在使用任何请求数据之前，请先进行以下替换：

• LOCATION_ID：您的区域。
• PROJECT_ID：您的项目 ID。
• METADATA_STORE：在其中创建执行作业的元数据存储区的 ID。默认元数据存储区名为 default。
• CONTEXT_ID：（可选）上下文记录的 ID。如果未指定上下文 ID，则 Vertex ML Metadata 会为此上下文创建一个唯一标识符
• DISPLAY_NAME：上下文的显示名称。此字段最多可包含 128 个 Unicode 字符。
• PARENT_CONTEXT：为任何父级上下文指定资源名称。一个上下文包含的父级上下文不能超过 10 个。
• METADATA_SCHEMA_TITLE：描述元数据字段的架构的标题。架构的标题必须符合格式“.”。命名空间必须以小写字母开头，可以包含小写字符和数字，并且长度可以是 2 到 20 个字符。架构名称必须以大写字母开头，可以包含字母和数字，并且长度可以是 2 到 49 个字符。
• METADATA_SCHEMA_VERSION：（可选）描述元数据字段的架构的版本。 schema_version 必须是用句点分隔的 3 个数字的字符串，例如 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）

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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

Python

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）

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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) 和一个空响应。

笔记本

如需了解详情，请在您选择的环境中运行以下 Jupyter 笔记本：

• “跟踪 Vertex AI 自定义训练作业的指标和参数，并执行详细分析”：

  在 Colab 中打开 | 在 Colab Enterprise 中打开 | 在 Vertex AI Workbench 用户管理的笔记本中打开 | 在 GitHub 上查看

• “使用 Vertex AI SDK 跟踪机器学习训练作业的指标和参数并分析此元数据”：

  在 Colab 中打开 | 在 Colab Enterprise 中打开 | 在 Vertex AI Workbench 用户管理的笔记本中打开 | 在 GitHub 上查看

• “使用 Vertex ML Metadata 在 Vertex AI Pipelines 运行之间跟踪工件和指标”：

  在 Colab 中打开 | 在 Colab Enterprise 中打开 | 在 Vertex AI Workbench 用户管理的笔记本中打开 | 在 GitHub 上查看

后续步骤

• 开始分析 Vertex ML Metadata。