Google Cloud 콘솔을 사용하여 정형 데이터를 가져오면 Vertex AI Agent Builder에서 스키마를 자동 감지합니다. 엔진에서 이 자동 감지 스키마를 사용하거나 API를 사용하여 데이터 구조를 나타내는 스키마를 제공할 수 있습니다.
스키마를 제공한 후에 새 스키마로 업데이트하는 경우 새 스키마는 원래 스키마와 하위 호환되어야 합니다. 그렇지 않으면 스키마 업데이트가 실패합니다.
스키마에 대한 참조 정보는 dataStores.schemas
를 참조하세요.
데이터 스토어에 스키마를 제공하는 방법
정형 데이터의 스키마를 결정하는 방법은 다양합니다.
자동 감지 및 수정. Vertex AI Agent Builder에서 초기 스키마를 자동으로 감지하고 제안할 수 있습니다. 그러면 콘솔 인터페이스를 통해 스키마를 미세 조정합니다. 필드가 자동 감지된 후에 키 속성을 모든 중요한 필드에 매핑하는 것이 좋습니다.
이 방법은 검색 데이터 스토어 만들기 및 일반 추천 데이터 스토어 만들기에서 정형 데이터에 대한 Google Cloud 콘솔 안내를 따를 때 사용하는 방법입니다.
스키마를 JSON 객체로 제공. 스키마를 JSON 객체로 Vertex AI Agent Builder에 제공합니다. 올바른 JSON 객체를 준비해야 합니다. JSON 객체 예시는 JSON 객체로 된 스키마 예시를 참조하세요. 스키마를 만든 후에는 해당 스키마에 따라 데이터를 업로드합니다.
이 방법은 curl 명령어(또는 프로그램)를 사용하여 API를 통해 데이터 스토어를 만들 때 사용할 수 있는 방법입니다. 예시는 BigQuery에서 한 번 가져오기를 참조하세요. 자체 스키마 제공 안내도 참조하세요.
미디어: Google에서 정의한 스키마에 데이터 제공. 미디어용 데이터 스토어를 만드는 경우 Google 사전 정의 스키마를 사용할 수 있습니다. 이 옵션을 선택하면 JSON 객체를 미디어 문서 및 데이터 스토어 정보에서 제공하는 형식으로 구성했다고 가정하게 됩니다. 기본적으로 자동 감지는 데이터 수집 중에 찾은 새 필드를 스키마에 추가합니다.
이 방법은 미디어 앱 및 데이터 스토어 만들기의 안내를 따를 때 사용하는 방법입니다. 이 방법은 미디어 추천 시작하기 및 미디어 검색 시작하기 튜토리얼에서도 사용되는 방법입니다. 여기서 샘플 데이터가 Google 사전 정의 스키마에 제공됩니다.
미디어: 필수 미디어 속성이 포함되도록 자동 감지 및 수정. 미디어 데이터의 경우 자동 감지를 사용하여 스키마를 제안하고 수정하여 미세 조정할 수 있습니다. JSON 객체에는 미디어 키 속성(
title
,uri
,category
,media_duration
,media_available_time
)에 매핑할 수 있는 필드가 포함되어야 합니다.이 방법은 미디어 데이터가 Google에서 정의한 스키마에 없는 경우에 Google Cloud 콘솔을 통해 미디어 데이터를 가져올 때 사용하는 방법입니다.
미디어: 자체 스키마를 JSON 객체로 제공. 스키마를 JSON 객체로 Vertex AI Agent Builder에 제공합니다. 올바른 JSON 객체를 준비해야 합니다. 스키마에는 미디어 키 속성(
title
,uri
,category
,media_duration
,media_available_time
)에 매핑할 수 있는 필드가 포함되어야 합니다.JSON 객체 예시는 JSON 객체로 된 스키마 예시를 참조하세요. 스키마를 만든 후에는 해당 스키마에 따라 미디어를 업로드합니다.
이 방법에서는 curl 명령어(또는 프로그램)를 통해 API를 사용합니다. 자체 스키마 제공 안내를 참조하세요.
자동 감지 및 수정 정보
데이터를 가져오면 Vertex AI Search에서 가져온 첫 몇 개 문서를 샘플링합니다. 이러한 문서를 기반으로 데이터의 스키마가 제안되며 이 스키마를 검토하거나 수정할 수 있습니다.
키 속성에 매핑하려는 필드가 샘플링된 문서에 없으면 스키마를 검토할 때 이러한 필드를 수동으로 추가할 수 있습니다.
데이터를 가져온 후에 Vertex AI Search에서 추가 필드를 발견하면 이러한 필드를 가져와 스키마에 추가합니다. 모든 데이터를 가져온 후에 스키마를 수정하려면 스키마 업데이트를 참조하세요.
JSON 객체로 된 스키마 예시
JSON 문서를 정의, 주석 작성, 검증하는 오픈소스 선언적 언어인 JSON 스키마 형식을 사용하여 자체 스키마를 정의할 수 있습니다. 다음은 유효한 JSON 스키마 주석의 예시입니다.
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "dynamic": "true", "datetime_detection": true, "geolocation_detection": true, "properties": { "title": { "type": "string", "keyPropertyMapping": "title", "retrievable": true, "completable": true }, "description": { "type": "string", "keyPropertyMapping": "description" }, "categories": { "type": "array", "items": { "type": "string", "keyPropertyMapping": "category" } }, "uri": { "type": "string", "keyPropertyMapping": "uri" }, "brand": { "type": "string", "indexable": true, "dynamicFacetable": true }, "location": { "type": "geolocation", "indexable": true, "retrievable": true }, "creationDate": { "type": "datetime", "indexable": true, "retrievable": true }, "isCurrent": { "type": "boolean", "indexable": true, "retrievable": true }, "runtime": { "type": "string", "keyPropertyMapping": "media_duration" }, "releaseDate": { "type": "string", "keyPropertyMapping": "media_available_time" } } }
미디어 스키마를 정의하는 경우 미디어 키 속성에 매핑할 수 있는 필드를 포함해야 합니다. 이러한 키 속성은 이 예시에 나와 있습니다.
다음은 이 스키마 예시의 일부 필드입니다.
dynamic
.dynamic
이 문자열 값"true"
로 설정되면 가져온 데이터에서 발견된 모든 새로운 속성이 스키마에 추가됩니다.dynamic
이"false"
로 설정되면 가져온 데이터에서 발견된 새 속성은 무시되며 속성은 스키마에 추가되지도 않고 값을 가져오지 않습니다.예를 들어 스키마에
title
및description
이라는 속성 2개가 있고title
,description
,rating
의 속성이 포함된 데이터를 업로드합니다.dynamic
이"true"
이면 평점 속성과 데이터를 가져옵니다.dynamic
이"false"
이면title
및description
을 가져오지만rating
속성을 가져오지 않습니다.기본값은
"true"
입니다.datetime_detection
.datetime_detection
이 불리언true
로 설정된 경우 날짜/시간 형식의 데이터를 가져오면 스키마 유형이datetime
으로 설정됩니다. 지원되는 형식은 RFC 3339 및 ISO 8601입니다.예를 들면 다음과 같습니다.
2024-08-05 08:30:00 UTC
2024-08-05T08:30:00Z
2024-08-05T01:30:00-07:00
2024-08-05
2024-08-05T08:30:00+00:00
datatime_detection
이 불리언false
로 설정된 경우 날짜/시간 형식의 데이터를 가져오면 스키마 유형이string
으로 설정됩니다.기본값은
true
입니다.geolocation_detection
.geolocation_detection
이 불리언true
로 설정된 경우 위치정보 형식의 데이터를 가져오면 스키마 유형이geolocation
으로 설정됩니다. 위도 숫자와 경도 숫자가 포함된 객체이거나 주소 문자열이 포함된 객체인 경우에 데이터가 위치정보로 감지됩니다.예를 들면 다음과 같습니다.
"myLocation": {"latitude":37.42, "longitude":-122.08}
"myLocation": {"address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043"}
geolocation_detection
이 불리언false
로 설정된 경우 위치정보 형식의 데이터를 가져오면 스키마 유형이object
로 설정됩니다.기본값은
true
입니다.keyPropertyMapping
. 사전 정의된 키워드를 문서의 중요 필드에 매핑하는 필드로, 문맥적 의미를 명확하게 합니다. 값은title
,description
,uri
,category
입니다. 필드 이름은keyPropertyValues
값과 일치할 필요가 없습니다. 예를 들어my_title
필드의 경우 값이title
인keyPropertyValues
필드를 포함할 수 있습니다.검색 데이터 스토어의 경우 기본적으로
keyPropertyMapping
으로 표시된 필드에 색인을 생성하고 검색할 수 있지만 검색 가능하거나 완료 가능하거나 dynamicFacetable일 수는 없습니다. 즉, 예상되는 기본 동작을 얻기 위해keyPropertyValues
필드와 함께indexable
또는searchable
필드를 포함할 필요가 없습니다.type
. 필드 유형입니다.datetime
,geolocation
또는 기본 유형 중 하나(integer
,boolean
,object
,array
,number
또는string
)인 문자열 값입니다.
다음 속성 필드는 검색 앱에만 적용됩니다.
retrievable
. 이 필드를 검색 응답으로 반환할 수 있는지 여부를 나타냅니다.number
,string
,boolean
,integer
,datetime
,geolocation
유형의 필드에 설정할 수 있습니다. 필드를 최대 50개까지 검색 가능으로 설정할 수 있습니다. 기본적으로 사용자 정의 필드와keyPropertyValues
필드를 검색할 수 없습니다. 필드를 검색 가능하게 하려면 필드에"retrievable": true
를 포함합니다.indexable
.servingConfigs.search
메서드에서 이 필드를 필터링, 패싯, 부스팅 또는 정렬할 수 있는지 여부를 나타냅니다.number
,string
,boolean
,integer
,datetime
,geolocation
유형의 필드에 설정할 수 있습니다. 필드를 최대 50개까지 색인 생성 가능으로 설정할 수 있습니다. 기본적으로 사용자 정의 필드에는 색인이 생성되지 않습니다(keyPropertyMapping
필드가 포함된 필드 제외). 필드에 색인 생성이 가능하게 하려면 필드에"indexable": true
를 포함합니다.dynamicFacetable
. 필드를 동적 패싯으로 사용할 수 있음을 나타냅니다.number
,string
,boolean
,integer
유형의 필드에 설정할 수 있습니다. 필드를 동적으로 패싯하려면 색인 생성도 가능해야 합니다. 필드에"dynamicFacetable": true
및"indexable": true
를 포함합니다.searchable
. 이 필드의 역색인을 생성하여 비정형 텍스트 쿼리와 일치시킬 수 있는지 여부를 나타냅니다.string
유형의 필드에만 설정할 수 있습니다. 필드를 최대 50개까지 검색 가능으로 설정할 수 있습니다. 기본적으로 사용자 정의 필드를 검색할 수 없습니다(keyPropertyMapping
필드가 포함된 필드 제외). 필드를 검색 가능하게 하려면 필드에"searchable": true
를 포함합니다.completable
. 이 필드를 자동 완성 추천 용어로 반환할 수 있는지 여부를 나타냅니다.string
유형의 필드에만 설정할 수 있습니다. 필드를 완성할 수 있게 하려면 필드에"completable": true
를 포함합니다.
또한 다음 필드는 추천 앱에만 적용됩니다.
recommendationsFilterable
. 이 필드를 추천 필터 표현식에 사용할 수 있음을 나타냅니다. 추천 필터링 방법에 대한 일반적인 내용은 추천 필터링을 참조하세요.... "genres": { "type": "string", "recommendationsFilterable": true, ... },
자체 스키마를 JSON 객체로 제공
자체 스키마를 제공하려면 빈 스키마가 포함된 데이터 스토어를 만든 후 스키마를 업데이트하여 스키마를 JSON 객체로 제공합니다. 다음 단계를 따르세요.
JSON 객체로 된 스키마 예시를 가이드로 사용하여 스키마를 JSON 객체로 준비합니다.
데이터 스토어를 만듭니다.
curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores?dataStoreId=DATA_STORE_ID" \ -d '{ "displayName": "DATA_STORE_DISPLAY_NAME", "industryVertical": "INDUSTRY_VERTICAL" }'
다음을 바꿉니다.
PROJECT_ID
: Google Cloud 프로젝트의 ID입니다.DATA_STORE_ID
: 만들려는 Vertex AI Search 데이터 스토어의 ID입니다. 이 ID는 소문자, 숫자, 밑줄, 하이픈만 포함할 수 있습니다.DATA_STORE_DISPLAY_NAME
: 만들려는 Vertex AI Search 데이터 스토어의 표시 이름입니다.INDUSTRY_VERTICAL
:GENERIC
또는MEDIA
schemas.patch API 메서드를 사용하여 새 JSON 스키마를 JSON 객체로 제공합니다.
curl -X PATCH \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/schemas/default_schema" \ -d '{ "structSchema": JSON_SCHEMA_OBJECT }'
다음을 바꿉니다.
PROJECT_ID
: Google Cloud 프로젝트의 ID입니다.DATA_STORE_ID
: Vertex AI Search 데이터 스토어 ID입니다.JSON_SCHEMA_OBJECT
: JSON 객체로 된 새 JSON 스키마입니다. 예를 들면 다음과 같습니다.{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string", "keyPropertyMapping": "title" }, "categories": { "type": "array", "items": { "type": "string", "keyPropertyMapping": "category" } }, "uri": { "type": "string", "keyPropertyMapping": "uri" } } }
선택사항: 스키마 정의 보기 절차를 수행하여 스키마를 검토합니다.