정형 데이터, 정형 데이터가 포함된 웹사이트 데이터 또는 기타 메타데이터가 포함된 비정형 데이터와 같이 스키마를 지원하는 데이터가 포함된 모든 데이터의 스키마를 업데이트할 수 있습니다.
Google Cloud 콘솔에서 또는 schemas.patch
API 메서드를 사용하여 스키마를 업데이트할 수 있습니다.
웹사이트의 스키마 업데이트는 REST API를 통해서만 지원됩니다.
스키마를 업데이트하려면 새 필드를 추가하거나, 필드의 색인 생성 가능, 검색 가능, 가져오기 가능 주석을 변경하거나, 필드를 키 속성(예: title
, uri
, description
)으로 표시하면 됩니다.
스키마 업데이트
Google Cloud 콘솔에서 또는 API를 사용하여 스키마를 업데이트할 수 있습니다.
콘솔
Google Cloud 콘솔에서 스키마를 업데이트하려면 다음 단계를 따르세요.
요구사항 및 제한사항 섹션을 검토하여 스키마 업데이트가 유효한지 확인합니다.
필드 주석을 업데이트하는 경우(필드를 색인 생성 가능, 가져오기 가능, 동적 패싯 생성 가능, 검색 가능, 완성 가능으로 설정) 각 주석 유형의 제한사항 및 요구사항에 관한 필드 설정 구성을 검토하세요.
데이터 수집이 완료되었는지 확인합니다. 그렇지 않으면 아직 스키마를 수정할 수 없을 수 있습니다.
Google Cloud 콘솔에서 Agent Builder 페이지로 이동합니다.
탐색 메뉴에서 데이터 스토어를 클릭합니다.
이름 열에서 업데이트할 스키마가 있는 데이터 스토어를 클릭합니다.
스키마 탭을 클릭하여 데이터의 스키마를 봅니다.
필드를 처음 수정하는 경우 이 탭이 비어 있을 수 있습니다.
수정 버튼을 클릭합니다.
스키마를 업데이트합니다.
키 속성 매핑: 스키마의 키 속성 열에서 필드를 매핑할 키 속성을 선택합니다. 예를 들어
details
라는 필드에 항상 문서의 설명이 포함되는 경우 이 필드를 키 속성 Description에 매핑합니다.측정기준 수 업데이트(고급): Vertex AI Search에서 커스텀 벡터 임베딩을 사용하는 경우 이 설정을 업데이트할 수 있습니다. 고급: 커스텀 임베딩 사용을 참조하세요.
필드 주석 업데이트: 필드의 주석을 업데이트하려면 필드의 주석 설정을 선택하거나 선택 해제합니다. 사용 가능한 주석은 가져오기 가능, 색인 생성 가능, 동적 패싯 생성 가능, 검색 가능, 완성 가능입니다. 일부 필드 설정에는 제한사항이 있습니다. 각 주석 유형에 대한 설명과 요구사항은 필드 설정 구성을 참조하세요.
새 필드 추가: 새 필드가 포함된 새 문서를 가져오기 전에 새 필드를 스키마에 추가하면 가져오기 후 Vertex AI Agent Builder가 데이터의 색인을 재생성하는 데 걸리는 시간이 단축될 수 있습니다.
새 필드 추가를 클릭하여 섹션을 펼칩니다.
add_box 노드 추가를 클릭하고 새 필드의 설정을 지정합니다.
배열을 나타내려면 배열을 예로 설정합니다. 예를 들어 문자열 배열을 추가하려면 유형을
string
으로, 배열을Yes
로 설정합니다.웹사이트 데이터 스토어 색인의 경우 추가하는 모든 필드는 기본적으로 배열입니다.
저장을 클릭하여 스키마 변경사항을 적용합니다.
스키마를 변경하면 색인 재생성이 트리거됩니다. 대규모 데이터 스토어의 경우 색인을 재생성하는 데 몇 시간이 걸릴 수 있습니다.
REST
API를 사용하여 스키마를 업데이트하려면 다음 단계를 따르세요.
요구사항 및 제한사항 및 제한사항 예시(REST만 해당) 섹션을 검토하여 스키마 변경사항이 유효한지 확인합니다.
웹사이트 또는 메타데이터가 포함된 비정형 데이터가 있는 데이터 스토어의 스키마를 업데이트하려면 5단계로 건너뛰어
schema.patch
메서드를 호출합니다.필드 주석을 업데이트하는 경우(필드를 색인 생성 가능, 가져오기 가능, 동적 패싯 생성 가능, 검색 가능으로 설정) 각 주석 유형의 제한사항 및 요구사항에 관한 필드 설정 구성을 검토하세요.
자동 감지된 스키마를 수정하는 경우 데이터 수집이 완료되었는지 확인합니다. 그렇지 않으면 아직 스키마를 수정할 수 없을 수 있습니다.
데이터 스토어 ID를 찾습니다. 데이터 스토어 ID가 이미 있는 경우 다음 단계로 건너뜁니다.
Google Cloud 콘솔에서 Agent Builder 페이지로 이동하고 탐색 메뉴에서 데이터 스토어를 클릭합니다.
데이터 스토어 이름을 클릭합니다.
데이터 스토어의 데이터 페이지에서 데이터 스토어 ID를 가져옵니다.
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" } } }
선택사항: 스키마 정의 보기 절차를 수행하여 스키마를 검토합니다.
C#
자세한 내용은 Vertex AI Agent Builder C# API 참고 문서를 확인하세요.
Vertex AI Agent Builder에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
Go
자세한 내용은 Vertex AI Agent Builder Go API 참고 문서를 확인하세요.
Vertex AI Agent Builder에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
Java
자세한 내용은 Vertex AI Agent Builder Java API 참고 문서를 확인하세요.
Vertex AI Agent Builder에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
Python
자세한 내용은 Vertex AI Agent Builder Python API 참고 문서를 확인하세요.
Vertex AI Agent Builder에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
Ruby
자세한 내용은 Vertex AI Agent Builder Ruby API 참고 문서를 확인하세요.
Vertex AI Agent Builder에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
요구사항 및 제한사항
스키마를 업데이트할 때는 새 스키마가 업데이트 중인 스키마와 하위 호환되는지 확인합니다. 하위 호환되지 않는 새 스키마로 스키마를 업데이트하려면 데이터 스토어의 모든 문서를 삭제하고 스키마를 삭제한 후 새 스키마를 만들어야 합니다.
스키마를 업데이트하면 모든 문서의 색인 재생성이 트리거됩니다. 이 과정에 시간이 걸리고 추가 비용이 발생할 수 있습니다.
시간. 대규모 데이터 스토어의 색인을 재생성하는 데 몇 시간 또는 며칠이 걸릴 수 있습니다.
비용. 색인 재생성은 파서에 따라 비용이 발생할 수 있습니다. 예를 들어 OCR 파서 또는 레이아웃 파서를 사용하는 데이터 스토어의 색인을 재생성하면 비용이 발생합니다. 자세한 내용은 Document AI 기능 가격 책정을 참조하세요.
스키마 업데이트는 다음을 지원하지 않습니다.
- 필드 유형 변경. 스키마 업데이트는 필드 유형 변경을 지원하지 않습니다. 예를 들어 정수에 매핑된 필드는 문자열로 변경할 수 없습니다.
- 필드 삭제. 필드는 정의한 후에는 삭제할 수 없습니다. 새 필드를 계속 추가할 수 있지만 기존 필드는 삭제할 수 없습니다.
제한사항 예시(REST만 해당)
이 섹션에서는 유효한 스키마 업데이트 유형과 잘못된 스키마 업데이트 유형의 예시를 보여줍니다. 해당 예시에서는 다음과 같은 JSON 스키마 예시를 사용합니다.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string",
"keyPropertyMapping": "description"
},
"categories": {
"type": "array",
"items": {
"type": "string",
"keyPropertyMapping": "category"
}
}
}
}
지원되는 업데이트의 예시
예시 스키마에 대해 다음과 같은 업데이트가 지원됩니다.
필드 추가. 이 예시에서
properties.uri
필드가 스키마에 추가되었습니다.{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string", "keyPropertyMapping": "description" }, "uri": { // Added field. This is supported. "type": "string", "keyPropertyMapping": "uri" }, "categories": { "type": "array", "items": { "type": "string", "keyPropertyMapping": "category" } } } }
title
,description
,uri
의 키 속성 주석을 추가하거나 삭제합니다. 이 예시에서는keyPropertyMapping
이title
필드에 추가되었습니다.{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string", "keyPropertyMapping": "title" // Added "keyPropertyMapping". This is supported. }, "description": { "type": "string", "keyPropertyMapping": "description" }, "categories": { "type": "array", "items": { "type": "string", "keyPropertyMapping": "category" } } } }
잘못된 스키마 업데이트의 예시
예시 스키마에 대해 다음과 같은 업데이트는 지원되지 않습니다.
필드 유형 변경. 이 예시에서
title
필드의 유형이 문자열에서 숫자로 변경되었습니다. 이 기능은 지원되지 않습니다.{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "number" // Changed from string. Not allowed. }, "description": { "type": "string", "keyPropertyMapping": "description" }, "categories": { "type": "array", "items": { "type": "string", "keyPropertyMapping": "category" } } } }
필드 삭제. 이 예시에서는
title
필드가 삭제되었습니다. 이 기능은 지원되지 않습니다.{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { // "title" is removed. Not allowed. "description": { "type": "string", "keyPropertyMapping": "description" }, "uri": { "type": "string", "keyPropertyMapping": "uri" }, "categories": { "type": "array", "items": { "type": "string", "keyPropertyMapping": "category" } } } }