사전 정의된 시스템 스키마 외에도 Vertex ML Metadata는 커스텀 스키마를 통해 확장 가능한 데이터 모델을 제공합니다. 커스텀 스키마는 사용자 정의 MetadataSchemas입니다. 커스텀 스키마를 사용하여 메타데이터 속성 유형을 검사하고 'MyCustomModel 유형의 모든 아티팩트 나열'과 같이 스키마별 리소스 쿼리를 수행합니다.
커스텀 스키마를 정의하려면 예상된 스키마를 설명하는 특정 MetadataStore 내에서 MetadataSchema 리소스를 만들어야 합니다. 스키마 형식은 OpenAPI 3.0 사양 {class: external}의 일부이고 최상위 스키마가 object 유형이어야 합니다. 모든 OpenAPI 3.0 지원 데이터 유형(정수, 숫자, 문자열, 부울, 배열, 객체 등)은 이 최상위 스키마 객체의 속성으로 지원됩니다. 제한사항에 따라 속성 섹션 아래의 각 필드는 하나의 데이터 유형에만 할당될 수 있습니다. 혼합 유형은 지원되지 않습니다. 최소, 최대, 다중, 문자열 형식과 같은 고급 데이터 요구사항도 지원되지 않습니다.
고유 커스텀 스키마를 등록하는 방법
커스텀 MetadataSchema를 만드는 프로세스는 새 메타데이터 리소스를 만드는 것과 비슷합니다. 다음 안내에서는 샘플 MetadataSchema를 만드는 방법을 보여줍니다. MetadataSchemas 범위는 연관된 MetadataStore만으로 지정됩니다.
METADATA_STORE: MetadataSchema가 생성되는 메타데이터 스토어 ID입니다.
기본 메타데이터 저장소 이름은 default로 지정됩니다. 새 MetadataStore가 필요하지 않으면 기본 스토어를 사용할 수 있습니다.
METADATA_SCHEMA_ID: (선택사항) MetadataSchema 레코드의 ID입니다. ID가 지정되지 않았으면 Vertex ML Metadata가 이 MetadataSchema에 대한 고유 식별자를 만듭니다.
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
아티팩트 만들기, 가져오기, 나열을 위한 이후 호출은 schema_title 필드에 이름(demo.Artifact)을 지정하고 아티팩트 리소스의 schema_version에 버전(0.0.1)을 지정하여 이 스키마를 참조할 수 있습니다. 메타데이터 리소스 만들기, 가져오기, 나열 방법에 대한 자세한 내용은 Vertex ML Metadata 추적을 참조하세요.
스키마 버전 관리
모든 MetadataSchema 리소스는 버전 관리됩니다. 사용자는 다른 스키마와 동일한 schema_title을 사용하지만 다른 schema_version을 사용하는 스키마를 만들 수 있습니다.
다른 버전으로 metadataSchema 리소스를 만들려면 다른 버전 번호 및 수정된 스키마 콘텐츠를 제공할 수 있습니다.
다음 예시는 demo.Artifact 스키마의 0.0.2 버전을 만듭니다.
sample_schema_versioned=aip.MetadataSchema()sample_schema_versioned.schema_type=aip.MetadataSchema.MetadataSchemaType.ARTIFACT_TYPEsample_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 메타데이터 분석을 참조하세요.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-09(UTC)"],[],[],null,["# Create and use custom schemas\n\nIn addition to the predefined system schemas, Vertex ML Metadata provides\nan extensible data model through custom schemas. Custom schemas are user-defined\nMetadataSchemas. Use custom schemas to type check metadata properties and to\nquery resources by schema, for example,\n\"list all Artifacts of type `MyCustomModel`.\n\nTo define a custom schema, you must create a MetadataSchema resource within a\nspecific MetadataStore that describes the expected schema. The schema format is\na subset of the [OpenAPI 3.0 specification](https://swagger.io/specification/#schema-object){class: external},\nwith the restriction that the top-level schema must be of type `object`. All\nOpenAPI 3.0 supported [data types](https://swagger.io/docs/specification/data-models/data-types/)\n(for example, integer, number, string, boolean, array, object) are supported as\nproperties of this top-level schema object. A restriction is that each field\nunder the properties section can be assigned to only one data type. Mixed types\nare not supported. Advanced data requirements such as Minimum,\nMaximum, Multiples, and string formats are also not supported.\n| **Note:** Fields in the schema are always considered optional when the system performs type checking. When you create new metadata resources, you can still include fields that are not defined in the schema.\n\nHow to register your own custom schemas\n---------------------------------------\n\nThe process to create a custom MetadataSchema is similar to creating new\nmetadata resources. The following instructions show how to create a sample\nMetadataSchema. MetadataSchemas are scoped only to their associated\nMetadataStore. \n\n### REST\n\n\nBefore using any of the request data,\nmake the following replacements:\n\n- \u003cvar translate=\"no\"\u003eLOCATION_ID\u003c/var\u003e: The region of your MetadataStore.\n- \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: Your [project ID](/resource-manager/docs/creating-managing-projects#identifiers) or number.\n- \u003cvar translate=\"no\"\u003eMETADATA_STORE\u003c/var\u003e: The metadata store ID where the MetadataSchema is created. The default metadata store is named `default`. Unless a new MetadataStore is required, you can use the default store.\n- \u003cvar translate=\"no\"\u003eMETADATA_SCHEMA_ID\u003c/var\u003e: (Optional) The ID of the MetadataSchema record. If the ID is not specified, Vertex ML Metadata creates a unique identifier for this MetadataSchema .\n- \u003cvar translate=\"no\"\u003eMETADATA_SCHEMA_TITLE\u003c/var\u003e: The title of the schema that describes the metadata field. The title of the schema must meet the format \\`.\\`. The namespace must start with a lowercase letter, can contain lowercase characters and numbers, and can be two to twenty characters long. The schema name must start with an uppercase letter, can include letters and numbers, and can be two to fortynice characters long.\n- \u003cvar translate=\"no\"\u003eMETADATA_SCHEMA_VERSION\u003c/var\u003e: (Optional) The version of the schema that describes the metadata field. `schema_version` must be a string of three numbers separated by periods, for example, 1.0.0, 1.0.1. This format helps order and compare versions..\n- \u003cvar translate=\"no\"\u003eMETADATA_SCHEMA_TYPE\u003c/var\u003e: The type of metadata resource to which the created schema applies. Types are: `ARTIFACT_TYPE`, `EXECUTION_TYPE`, or `CONTEXT_TYPE`.\n- \u003cvar translate=\"no\"\u003eMETADATA_SCHEMA\u003c/var\u003e: The detailed schema to create.\n- \u003cvar translate=\"no\"\u003eDESCRIPTION\u003c/var\u003e: (Optional) A human readable string, that describes the purpose of the execution to be created..\n- \u003cvar translate=\"no\"\u003eARTIFACT_ID\u003c/var\u003e: (Optional) The ID of the artifact record. If the artifact ID is not specified, Vertex ML Metadata creates a unique identifier for this artifact..\n- \u003cvar translate=\"no\"\u003eDISPLAY_NAME\u003c/var\u003e: (Optional) The user-defined name of the artifact..\n\n\nHTTP method and URL:\n\n```\nPOST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/metadataSchemas?metadata_schema_id=METADATA_SCHEMA_ID\n```\n\n\nRequest JSON body:\n\n```\n{\n \"schemaVersion\": \"0.0.1\",\n \"schema\": \"title: test.Experiment\\ntype: object\",\n \"schemaType\": \"CONTEXT_TYPE\",\n}\n```\n\nTo send your request, expand one of these options:\n\n#### curl (Linux, macOS, or Cloud Shell)\n\n| **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](/sdk/gcloud/reference/init) or [`gcloud auth login`](/sdk/gcloud/reference/auth/login) , or by using [Cloud Shell](/shell/docs), which automatically logs you into the `gcloud` CLI . You can check the currently active account by running [`gcloud auth list`](/sdk/gcloud/reference/auth/list).\n\n\nSave the request body in a file named `request.json`.\nRun the following command in the terminal to create or overwrite\nthis file in the current directory: \n\n```\ncat \u003e request.json \u003c\u003c 'EOF'\n{\n \"schemaVersion\": \"0.0.1\",\n \"schema\": \"title: test.Experiment\\ntype: object\",\n \"schemaType\": \"CONTEXT_TYPE\",\n}\nEOF\n```\n\n\nThen execute the following command to send your REST request:\n\n```\ncurl -X POST \\\n -H \"Authorization: Bearer $(gcloud auth print-access-token)\" \\\n -H \"Content-Type: application/json; charset=utf-8\" \\\n -d @request.json \\\n \"https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/metadataSchemas?metadata_schema_id=METADATA_SCHEMA_ID\"\n```\n\n#### PowerShell (Windows)\n\n| **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](/sdk/gcloud/reference/init) or [`gcloud auth login`](/sdk/gcloud/reference/auth/login) . You can check the currently active account by running [`gcloud auth list`](/sdk/gcloud/reference/auth/list).\n\n\nSave the request body in a file named `request.json`.\nRun the following command in the terminal to create or overwrite\nthis file in the current directory: \n\n```\n@'\n{\n \"schemaVersion\": \"0.0.1\",\n \"schema\": \"title: test.Experiment\\ntype: object\",\n \"schemaType\": \"CONTEXT_TYPE\",\n}\n'@ | Out-File -FilePath request.json -Encoding utf8\n```\n\n\nThen execute the following command to send your REST request:\n\n```\n$cred = gcloud auth print-access-token\n$headers = @{ \"Authorization\" = \"Bearer $cred\" }\n\nInvoke-WebRequest `\n -Method POST `\n -Headers $headers `\n -ContentType: \"application/json; charset=utf-8\" `\n -InFile request.json `\n -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\n```\n\nYou should see output similar to the following. You can use the\n\u003cvar translate=\"no\"\u003eMETADATA_SCHEMA_ID\u003c/var\u003e is the ID of the MetadataSchema record.\n\n```\n{\n \"name\": \"projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/metadataSchemas/METADATA_SCHEMA_ID\",\n \"schemaVersion\": \"0.0.1\",\n \"schema\": \"title: test.Experiment\\ntype: object\",\n \"schemaType\": \"CONTEXT_TYPE\",\n \"createTime\": \"2021-04-06T05:24:04.575481815Z\"\n}\n\n```\n\nSubsequent calls to create, get, or list Artifacts can then refer to this schema\nby specifying the name (demo.Artifact) in the schema_title field and version\n(0.0.1) in the schema_version of the Artifact resource. For more information about\nhow to create, get, or list metadata resources, see\n[Track Vertex ML Metadata](/vertex-ai/docs/ml-metadata/tracking).\n\nVersion your schemas\n--------------------\n\nAll MetadataSchema resources are versioned. A user can create a schema that\nuses the same schema_title as another schema but a different schema_version.\nTo create a metadataSchema resource with a different version, a user can\nprovide a different version number and modified schema content.\n\nThe following example creates a 0.0.2 version of the demo.Artifact schema: \n\n sample_schema_versioned = aip.MetadataSchema()\n sample_schema_versioned.schema_type = aip.MetadataSchema.MetadataSchemaType.ARTIFACT_TYPE\n 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\\\"\"\n sample_schema_versioned.schema_version = \"0.0.2\"\n sample_schema_versioned.description = \"sample schema 2\"\n\n store_client.create_metadata_schema(parent=metadata_store.name, metadata_schema=sample_schema_versioned)\n\nFields in the schema are always considered optional, so there is\nno backward or forward compatibility between versions of the same\nschema_title. Users can still use the schema_title to filter and group\nresources for analysis. For more information about\nhow to use filter functions, see\n[Analyzing Vertex ML Metadata](/vertex-ai/docs/ml-metadata/analyzing).\n\nWhat's next\n-----------\n\n- [Get started tracking your Vertex ML Metadata](/vertex-ai/docs/ml-metadata/tracking)."]]
