시스템 스키마

각 메타데이터 리소스는 특정 MetadataSchema와 연관됩니다. 메타데이터 리소스 만들기 프로세스를 단순화하기 위해 Vertex ML Metadata는 공통 ML 개념에 대해 사전 정의된 유형의 호출된 시스템 스키마를 게시합니다. 시스템 스키마는 system 네임스페이스 아래에 유지됩니다. Vertex ML Metadata API에서 시스템 스키마에 MetadataSchema 리소스로 액세스할 수 있습니다. 스키마는 항상 버전이 지정됩니다. 시스템 스키마의 형식은 OpenAPI 3.0 사양의 일부입니다.

시스템 스키마 사용 방법

Vertex AI는 시스템 스키마를 사용하여 ML 워크플로 추적을 위해 메타데이터 리소스를 만듭니다. 그런 후 schema_title 필드를 사용하여 메타데이터 쿼리에서 리소스를 필터링 및 그룹화할 수 있습니다. 필터 함수 사용 방법에 대한 자세한 내용은 Vertex ML Metadata 분석을 참조하세요.

또한 Vertex ML Metadata API를 통해 시스템 스키마를 사용하여 메타데이터 리소스를 직접 만들 수도 있습니다. 스키마 타이틀 및 스키마 버전에 따라 시스템 스키마를 식별할 수 있습니다. 시스템 스키마의 필드는 항상 선택사항으로 간주됩니다. 사용자는 시스템 스키마의 사전 정의된 필드로 제한되지 않으며, 추가적인 임의 메타데이터를 모든 메타데이터 리소스에 로깅할 수도 있습니다. 시스템 스키마를 사용하여 메타데이터 리소스 만들기에 대한 자세한 내용은 Vertex ML Metadata 추적을 참조하세요.

스키마 나열

다음 명령어를 사용하여 기존의 모든 등록된 스키마 목록을 볼 수 있습니다.

REST

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

LOCATION_ID: 리전
PROJECT_ID: 프로젝트 ID입니다.

HTTP 메서드 및 URL:

GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/default/metadataSchemas?pageSize=100&filter=schema_title=%22system*%22+OR+schema_title=%22google*%22

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

다음 명령어를 실행합니다.

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/default/metadataSchemas?pageSize=100&filter=schema_title=%22system*%22+OR+schema_title=%22google*%22"

PowerShell(Windows)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/default/metadataSchemas?pageSize=100&filter=schema_title=%22system*%22+OR+schema_title=%22google*%22" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "metadataSchemas": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/default/metadataSchemas/system-resolver-execution-v0-0-1",
      "schemaVersion": "0.0.1",
      "schema": "title: system.ResolverExecution\ntype: object\n",
      "schemaType": "EXECUTION_TYPE",
      "createTime": "2022-07-27T17:41:35.634Z"
    },
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID//metadataStores/default/metadataSchemas/system-html-v0-0-1",
      "schemaVersion": "0.0.1",
      "schema": "title: system.HTML\ntype: object\n",
      "schemaType": "ARTIFACT_TYPE",
      "createTime": "2022-07-27T17:41:35.602Z"
    }
}

엄격한 스키마 매칭

Vertex ML Metadata는 스키마 작성자가 엄격한 스키마 일치를 적용할 수 있는 두 가지 플래그를 지원합니다.

additionalProperties

additionalProperties 값은 true 또는 false일 수 있습니다. JSON 스키마와 일치하도록 additionalProperties의 기본값은 true입니다. 이 플래그는 스키마의 최상위 수준에서 설정됩니다. false로 설정하면 선택적 속성이 허용되지 않습니다. 예를 들어 아래 스키마에서는 payload_format 및 container_format 필드만 이 스키마를 기반으로 메타데이터에 허용됩니다.

title: system.Dataset
version: 0.0.1
type: object
additionalProperties: false
properties:
  container_format:
    type: string
  payload_format:
    type: string

위 스키마는 다음과 같은 메타데이터를 허용합니다.

fields {
  key: 'container_format'
  value: { string_value: 'Text' }
}
fields {
  key: 'payload_format'
  value: { string_value: 'CSV' }
}

그러나 다음 메타데이터는 거부됩니다.

fields {
  key: 'container_format'
  value: { string_value: 'Text' }
}
fields {
  key: 'payload_format'
  value: { string_value: 'CSV' }
}
fields {
  key: 'optional_field'
  value: { string_value: 'optional_value' }
}

required

required 키워드는 0개 이상의 문자열 배열을 취합니다. JSON 스키마와 일관되게 속성 키워드로 정의된 속성은 필요하지 않습니다. required 키워드를 사용하여 필수 속성 목록을 제공할 수 있습니다. 예를 들어 다음 스키마에는 항상 container_format이 필요합니다. 중첩 속성에서도 작동합니다. 예를 들어 다음으로 인해 container_format이 필수가 됩니다.

title: system.Dataset
version: 0.0.1
type: object
required: ['container_format']
properties:
  container_format:
    type: string
  payload_format:
    type: string

위 스키마는 다음과 같은 메타데이터를 허용합니다.

fields {
  key: 'container_format'
  value: { string_value: 'Text' }
}

그러나 다음 메타데이터는 거부됩니다.

fields {
  key: 'payload_format'
  value: { string_value: 'CSV' }
}

스키마는 속성에 객체 유형 필드가 있는 중첩 속성을 지원합니다. 중첩 스키마에서 중첩 속성 노드는 required 키워드를 가질 수 있습니다. 예를 들면 다음과 같습니다.

title: system.Dataset
version: 0.0.1
type: object
properties:
  container_format:
    type: string
  payload:
    type: string
  nested_property:
    type: object
    required: ['property_1']
    properties:
      property_1:
        type: integer
      property_2:
        type: integer

nested_property 필드 자체는 필수가 아니므로 위의 스키마는 다음 메타데이터를 허용합니다.

fields {
  key: 'container_format'
  value: { string_value: 'Text' }
}

다음 메타데이터도 유효합니다.

fields {
  key: 'nested_property'
  value: {
    struct_value {
      fields {
        key: 'property_1'
        value: { number_value: 1 }
      }
      fields {
        key: 'property_2'
        value: { number_value: 1 }
      }
    }
  }
}

그러나 다음 메타데이터는 거부됩니다.

fields {
  key: 'nested_property'
  value: {
    struct_value {
      fields {
        key: 'property_2'
        value: { number_value: 1 }
      }
    }
  }
}