カスタム スキーマを作成して使用する

Vertex ML Metadata は、事前定義のシステム スキーマに加えて、カスタム スキーマを使用した拡張可能なデータモデルを提供します。カスタム スキーマは、ユーザー定義の MetadataSchema です。カスタム スキーマを使用してメタデータ プロパティの型をチェックし、スキーマごとにリソースをクエリします（たとえば、MyCustomModel 型のすべてのアーティファクトを一覧表示します）。

カスタム スキーマを定義するには、想定されるスキーマを記述する特定の MetadataStore 内に MetadataSchema リソースを作成する必要があります。スキーマ形式は OpenAPI 3.0 仕様{class: external}のサブセットですが、トップレベルのスキーマは object 型にする必要があります。このトップレベルのスキーマ オブジェクトのプロパティとして、OpenAPI 3.0 でサポートされているすべてのデータ型（integer、number、string、boolean、array、object など）がサポートされています。ただし、プロパティ セクションの各フィールドに割り当てることができるデータ型は 1 つだけです。混合型はサポートされていません。最小、最大、複数、文字列形式などの高度なデータ要件もサポートされていません。

注: 型チェックの際に、スキーマ内のフィールドは常にオプションとみなされます。新しいメタデータ リソースを作成する場合にも、スキーマで定義されていないフィールドを含めることができます。

独自のカスタム スキーマを登録する方法

カスタム MetadataSchema の作成プロセスは、新しいメタデータ リソースの作成と似ています。次の手順では、サンプルの MetadataSchema を作成する方法を示します。MetadataSchema のスコープは、関連付けられた MetadataStore に限定されます。

REST

リクエストのデータを使用する前に、次のように置き換えます。

• LOCATION_ID: MetadataStore のリージョン。
• PROJECT_ID: プロジェクト ID またはプロジェクト番号。
• METADATA_STORE: MetadataSchema が作成される MetadataStore ID。デフォルトのメタデータ ストアの名前は default です。新しい MetadataStore が必要でない限り、デフォルトのストアを使用できます。
• METADATA_SCHEMA_ID: 省略可。MetadataSchema レコードの ID。ID が指定されていない場合、この MetadataSchema の固有識別子が Vertex ML Metadata により作成されます。
• METADATA_SCHEMA_TITLE: メタデータ フィールドを記述するスキーマのタイトル。スキーマのタイトルは . の形式にする必要があります。名前空間名は 2～20 文字にし、先頭を小文字にします。名前には文字と数字を使用できます。スキーマ名は 2～49 文字にし、先頭は大文字にする必要があります。名前には英字と数字を使用できます。
• METADATA_SCHEMA_VERSION: 省略可。メタデータ フィールドを記述するスキーマのバージョン。schema_version は、1.0.0、1.0.1 のように、3 つの数字をピリオドで区切った文字列にする必要があります。この形式はバージョンの順序付けや比較に役立ちます。
• METADATA_SCHEMA_TYPE: 作成されたスキーマが適用されるメタデータ リソースのタイプ。タイプは ARTIFACT_TYPE、EXECUTION_TYPE、または CONTEXT_TYPE です。
• METADATA_SCHEMA: 作成する詳細なスキーマ。
• DESCRIPTION: 省略可。人が読める形式の文字列。作成する実行の目的を記述します。
• ARTIFACT_ID: 省略可。アーティファクト レコードの ID。アーティファクト ID が指定されていない場合、このアーティファクトの固有識別子が Vertex ML Metadata により作成されます。
• DISPLAY_NAME: 省略可。アーティファクトのユーザー定義の名前。

HTTP メソッドと URL:

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/metadataSchemas?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 \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/metadataSchemas?metadata_schema_id=METADATA_SCHEMA_ID"

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を 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 "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

出力は次のようになります。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）を指定し、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 の追跡を開始する。