이 페이지는 Cloud Translation API를 통해 번역되었습니다.

스키마 제공 또는 자동 감지

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 필드를 포함할 필요가 없습니다.

참고: 키 속성을 사용하면 검색 및 추천 결과의 품질과 검색 자동 완성 정확성을 향상시킬 수 있습니다. 자동 스키마 감지를 사용하면 키 속성은 자동으로 추가되지 않습니다. schemas.patch 메서드를 사용하여 데이터 필드를 키 속성(특히 title, uri, description)으로 표시하는 것이 좋습니다.
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"
    }
  }
}

명령어 및 결과 예시

curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/dataStores/my-data-store/schemas/default_schema" -d '{
"structSchema": {
"$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"
}
}
}
}'

{
"name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/schemas/default_schema/operations/update-schema-10569824819404198922",
"metadata": {
"@type": "type.googleapis.com/google.cloud.discoveryengine.v1.UpdateSchemaMetadata"
}
}

선택사항: 스키마 정의 보기 절차를 수행하여 스키마를 검토합니다.