创建和使用自定义架构

除了预定义的系统架构之外，Vertex ML Metadata 还通过自定义架构提供可扩展的数据模型。自定义架构是用户定义的 MetadataSchema。使用自定义架构检查元数据属性的类型并按架构查询资源，例如“列出 MyCustomModel 类型的所有工件”。

要定义自定义架构，您必须在描述预期架构的特定 MetadataStore 中创建一个 MetadataSchema 资源。架构格式是 OpenAPI 3.0 规范{class: external} 的子集，并且顶层架构必须是 object 类型。所有 OpenAPI 3.0 支持的数据类型（例如整数、数字、字符串、布尔值、数组和对象）均可作为此顶级架构对象的属性。但有一个限制，即属性部分下的每个字段只能分配给一种数据类型。不支持混合类型，也不支持高级数据要求，例如最小、最大、倍数和字符串格式。

如何注册自定义架构

创建自定义 MetadataSchema 的过程与创建新元数据资源类似。以下说明介绍了如何创建示例 MetadataSchema。MetadataSchema 的范围仅限于其关联的 MetadataStore。

REST

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

LOCATION_ID：您的 MetadataStore 的区域。
PROJECT_ID：您的项目 ID 或编号。
METADATA_STORE：在其中创建 MetadataSchema 的元数据存储区 ID。默认元数据存储区名为 default。除非需要新的元数据存储区，否则您可以使用默认存储区。
METADATA_SCHEMA_ID：（可选）MetadataSchema 记录的 ID。如果未指定 ID，Vertex ML Metadata 会为此 MetadataSchema 创建唯一标识符。
METADATA_SCHEMA_TITLE：描述元数据字段的架构的标题。架构的标题必须符合格式“.”。命名空间必须以小写字母开头，可以包含小写字符和数字，并且长度可以是 2 到 20 个字符。架构名称必须以大写字母开头，可以包含字母和数字，并且长度可以是 2 到 49 个字符。
METADATA_SCHEMA_VERSION：（可选）描述元数据字段的架构的版本。 schema_version 必须是用句点分隔的 3 个数字的字符串，例如 1.0.0、1.0.1。此格式有助于对版本进行排序和比较。
METADATA_SCHEMA_TYPE：所创建的架构适用的元数据资源类型。类型包括：ARTIFACT_TYPE、EXECUTION_TYPE 或 CONTEXT_TYPE。
METADATA_SCHEMA：要创建的详细架构。
DESCRIPTION：（可选）人类可读的字符串，用于描述要创建的执行的用途。
ARTIFACT_ID：（可选）工件记录的 ID。如果未指定工件 ID，Vertex ML Metadata 会为此工件创建一个唯一标识符。
DISPLAY_NAME：（可选）用户定义的工件名称。

HTTP 方法和网址：

POST http://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STOREmetadataSchemas?metadata_schema_id=METADATA_SCHEMA_ID

请求 JSON 正文：

{
    "schemaVersion": "0.0.1",
    "schema": "title: test.Experiment\ntype: object",
    "schemaType": "CONTEXT_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'
{
    "schemaVersion": "0.0.1",
    "schema": "title: test.Experiment\ntype: object",
    "schemaType": "CONTEXT_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 \
    "http://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STOREmetadataSchemas?metadata_schema_id=METADATA_SCHEMA_ID"

PowerShell (Windows)

将请求正文保存在名为 request.json 的文件中。在终端中运行以下命令，在当前目录中创建或覆盖此文件：

@'
{
    "schemaVersion": "0.0.1",
    "schema": "title: test.Experiment\ntype: object",
    "schemaType": "CONTEXT_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 "http://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STOREmetadataSchemas?metadata_schema_id=METADATA_SCHEMA_ID" | Select-Object -Expand Content

您应该会看到类似如下所示的输出。您可以使用 METADATA_SCHEMA_ID，它是 MetadataSchema 记录的 ID。

{
  "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/metadataSchemas/METADATA_SCHEMA_ID",
  "schemaVersion": "0.0.1",
  "schema": "title: test.Experiment\ntype: object",
  "schemaType": "CONTEXT_TYPE",
  "createTime": "2021-04-06T05:24:04.575481815Z"
}

后续的创建、获取或列出工件的调用可以通过在工件资源的 schema_title 字段中指定名称 (demo.Artifact) 以及在 schema_version 字段中指定版本 (0.0.1) 来引用此架构。如需详细了解如何创建、获取或列出元数据资源，请参阅跟踪 Vertex ML Metadata。

对架构进行版本控制

所有 MetadataSchema 资源都受版本控制。用户可以创建一个架构，它使用与另一个架构相同的 schema_title，但具有不同的 schema_version。要创建不同版本的 metadataSchema 资源，用户可以提供不同的版本号和修改后的架构内容。

以下示例将创建 0.0.2 版的 demo.Artifact 架构：

sample_schema_versioned = aip.MetadataSchema()
sample_schema_versioned.schema_type = aip.MetadataSchema.MetadataSchemaType.ARTIFACT_TYPE
sample_schema_versioned.schema ="title: demo.Artifact\ntype: object\nproperties:\n  framework:\n    type: string\n    description: \"The framework type\"\n  model_version:\n    type: integer\n    description: \"The version of the model\""
sample_schema_versioned.schema_version = "0.0.2"
sample_schema_versioned.description = "sample schema 2"

store_client.create_metadata_schema(parent=metadata_store.name, metadata_schema=sample_schema_versioned)

架构中的字段始终被视为可选字段，因此同一 schema_title 的版本之间不存在向后兼容性或向前兼容性。用户仍然可以使用 schema_title 对资源进行过滤和分组以供分析。如需详细了解如何使用过滤函数，请参阅分析 Vertex ML Metadata。

后续步骤

开始跟踪 Vertex ML Metadata。