커스텀 스키마 만들기 및 사용

사전 정의된 시스템 스키마 외에도 Vertex ML Metadata는 커스텀 스키마를 통해 확장 가능한 데이터 모델을 제공합니다. 커스텀 스키마는 사용자 정의 MetadataSchemas입니다. 커스텀 스키마를 사용하여 메타데이터 속성 유형을 검사하고 'MyCustomModel 유형의 모든 아티팩트 나열'과 같이 스키마별 리소스 쿼리를 수행합니다.

커스텀 스키마를 정의하려면 예상된 스키마를 설명하는 특정 MetadataStore 내에서 MetadataSchema 리소스를 만들어야 합니다. 스키마 형식은 OpenAPI 3.0 사양 {class: external}의 일부이고 최상위 스키마가 object 유형이어야 합니다. 모든 OpenAPI 3.0 지원 데이터 유형(정수, 숫자, 문자열, 부울, 배열, 객체 등)은 이 최상위 스키마 객체의 속성으로 지원됩니다. 제한사항에 따라 속성 섹션 아래의 각 필드는 하나의 데이터 유형에만 할당될 수 있습니다. 혼합 유형은 지원되지 않습니다. 최소, 최대, 다중, 문자열 형식과 같은 고급 데이터 요구사항도 지원되지 않습니다.

고유 커스텀 스키마를 등록하는 방법

커스텀 MetadataSchema를 만드는 프로세스는 새 메타데이터 리소스를 만드는 것과 비슷합니다. 다음 안내에서는 샘플 MetadataSchema를 만드는 방법을 보여줍니다. MetadataSchemas 범위는 연관된 MetadataStore만으로 지정됩니다.

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

LOCATION_ID: MetadataStore의 리전입니다.
PROJECT_ID: 프로젝트 ID 또는 번호입니다.
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

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)을 지정하고 아티팩트 리소스의 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_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 메타데이터 분석을 참조하세요.

다음 단계

Vertex ML Metadata 추적 시작하기