建立及使用自訂結構定義

除了預先定義的系統結構定義，Vertex 機器學習中繼資料也提供可擴充的資料模型，方便您透過自訂結構定義使用。自訂結構定義是使用者定義的 MetadataSchema。使用自訂結構定義檢查中繼資料屬性的型別，並依結構定義查詢資源，例如「列出所有 MyCustomModel 型別的 Artifact」。

如要定義自訂結構定義，您必須在特定 MetadataStore 中建立 MetadataSchema 資源，說明預期的結構定義。結構定義格式是 OpenAPI 3.0 規格{class: external} 的子集，但頂層結構定義必須為 object 型別。這個頂層架構物件的所有屬性都支援 OpenAPI 3.0 支援的資料類型 (例如整數、數字、字串、布林值、陣列、物件)。限制是屬性區段下的每個欄位只能指派給一種資料類型。系統不支援混合類型。也不支援進階資料規定，例如最小值、最大值、倍數和字串格式。

如何註冊自己的自訂結構定義

建立自訂 MetadataSchema 的程序與建立新的中繼資料資源類似。以下操作說明顯示如何建立範例 MetadataSchema。MetadataSchema 的範圍僅限於相關聯的 MetadataStore。

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/metadataSchemas?metadata_schema_id=METADATA_SCHEMA_ID

{
    "schemaVersion": "0.0.1",
    "schema": "title: test.Experiment\ntype: object",
    "schemaType": "CONTEXT_TYPE",
}

cat > request.json << 'EOF'
{
    "schemaVersion": "0.0.1",
    "schema": "title: test.Experiment\ntype: object",
    "schemaType": "CONTEXT_TYPE",
}
EOF

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/metadataSchemas?metadata_schema_id=METADATA_SCHEMA_ID"

@'
{
    "schemaVersion": "0.0.1",
    "schema": "title: test.Experiment\ntype: object",
    "schemaType": "CONTEXT_TYPE",
}
'@  | Out-File -FilePath request.json -Encoding utf8

$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/metadataSchemas?metadata_schema_id=METADATA_SCHEMA_ID" | Select-Object -Expand Content

{
  "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 機器學習中繼資料」。

管理結構定義版本

所有 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 機器學習中繼資料」。

後續步驟

• 開始追蹤 Vertex 機器學習中繼資料。