검색할 수 있도록 자동 완성 데이터 가져오기

자동 완성은 사용자가 입력하는 단어의 나머지 부분을 예측하여 사용자 검색 환경을 개선할 수 있는 기능입니다. 제공된 데이터 세트 또는 제공된 사용자 이벤트를 기반으로 사전 입력 추천을 제공할 수 있습니다.

추가 제어 기능이 필요하거나(삭제 제외 목록, 거부 목록) 자체 자동 완성 데이터를 사용해야 하는 경우에만 자동 완성 데이터를 가져오세요. 자동 완성이 필요한 대부분의 경우 자동 학습을 사용 설정하면 충분합니다. 자동 학습은 사용자 검색 이벤트를 토대로 머신러닝 기반 추천 데이터 세트를 제공합니다. 자동 학습을 사용 설정하는 방법은 자동 완성을 참조하세요.

다음 안내는 자동 완성 데이터를 업로드하는 경우에만 해당됩니다. 자동 완성 데이터 세트를 항상 사용하려면 최신 상태로 유지하세요. 쿼리 시 자동 완성 결과를 가져오려면 CompletionService.CompleteQuery를 참조하세요. 자동 완성 데이터는 검색에만 사용됩니다. 추천에서는 이 데이터가 사용되지 않습니다.

시작하기 전에

자동 완성 정보를 가져오려면 먼저 시작하기 전에에서도 특히 프로젝트 설정, 서비스 계정 만들기, 로컬 환경에 서비스 계정 추가의 안내를 완료해야 합니다.

가져오기를 수행하려면 Retail 편집자 IAM 역할이 있어야 합니다.

자동 완성 가져오기 권장사항

자동 완성 데이터를 가져올 때는 다음 권장사항을 구현해야 합니다.

  • 다음 섹션 및 API 문서에 나열된 BigQuery 스키마를 읽습니다.

  • 자리표시자 값을 사용하지 마세요.

  • 필드를 가능한 한 많이 포함하세요.

  • 업로드된 자체 데이터 세트를 사용하려는 경우 자동 완성 데이터 세트를 최신 상태로 유지하세요.

  • 다른 프로젝트에서 데이터를 가져오는 것은 허용되지 않습니다.

자동 완성 데이터 가져오기

BigQuery에서 자동 완성 데이터 가져오기

소매업용 Vertex AI Search는 거부 목록, 삭제 제외 목록, 추천 용어 목록에 대한 BigQuery 데이터 가져오기를 지원합니다. 자세한 내용은 자동 완성을 참조하세요.

BigQuery에서 올바른 형식으로 자동 완성 데이터를 가져오려면 소매업용 Vertex AI Search 자동 완성 스키마를 사용하여 올바른 형식의 BigQuery 테이블을 만들고 자동 완성 데이터가 포함된 테이블을 로드합니다. 그런 다음 데이터를 소매업용 Vertex AI Search에 업로드합니다.

BigQuery 테이블에 대한 도움말은 테이블 소개를 참조하세요. BigQuery 쿼리에 대한 도움말은 BigQuery 데이터 쿼리 개요를 참조하세요.

BigQuery 데이터 세트 위치

자동 완성 BigQuery 테이블의 BigQuery 데이터 세트를 처음 만들 때 데이터 세트 위치가 멀티 리전 위치 "US"로 설정되었는지 확인합니다. 잘못 설정하면 가져오기 요청이 나중에 실패합니다. BigQuery 데이터 세트 위치에 대한 자세한 내용은 BigQuery 문서의 데이터 세트 위치를 참조하세요.

BigQuery에 데이터 채우기

소매업용 Vertex AI Search 자동 완성 스키마를 사용하여 자동 완성 데이터를 BigQuery에 업로드합니다.

BigQuery는 스키마를 사용하여 JSON 형식의 데이터에 올바른 필드 이름과 유형(예: STRING, INTEGER, RECORD)이 있는지 여부를 확인할 수 있지만 다음을 확인하는 것과 같은 유효성 검사는 수행할 수 없습니다.

  • 문자열 필드가 인식 가능한 열거형 값으로 매핑되는지 여부
  • 문자열 필드가 올바른 형식을 사용 중인지 여부
  • 정수 또는 float 필드의 값 범위가 올바른지 여부
  • 누락된 필드가 필수 필드인지 여부

데이터 품질과 최종 사용자 검색 환경을 보장하려면 스키마와 참조 문서에서 값과 형식에 대한 자세한 내용을 확인해야 합니다.

BigQuery 데이터 세트에 대한 액세스 설정

액세스를 설정하려면 BigQuery 데이터 세트가 소매업용 Vertex AI Search 서비스와 동일한 프로젝트에 있는지 확인하고 다음 단계를 완료하세요.

  1. Google Cloud 콘솔에서 IAM 페이지를 엽니다.

    IAM 페이지 열기

  2. 소매업용 Vertex AI Search 프로젝트를 선택합니다.

  3. IAM 및 관리자 페이지에서 액세스 권한 부여를 클릭합니다.

  4. 새 주 구성원에 cloud-retail-customer-data-access@system.gserviceaccount.com를 입력하고 BigQuery > BigQuery 데이터 뷰어 역할을 선택합니다.

    전체 프로젝트에 데이터 뷰어 역할을 제공하지 않으려면 이 역할을 데이터 세트에 직접 추가하면 됩니다. 자세히 알아보기

  5. 저장을 클릭합니다.

소매업용 Vertex AI Search로 데이터 가져오기 트리거

콘솔

  1. 컨트롤 페이지로 이동

  2. 자동 완성 컨트롤 탭으로 이동합니다.

  3. 용어 목록 섹션에서 가져오려는 목록 유형(거부 목록, 삭제 제외 목록 또는 추천 용어 목록 참조)을 찾고 가져오기 또는 바꾸기를 클릭합니다.

    가져오기 창이 열립니다.

  4. 데이터 위치의 BigQuery 경로를 입력하거나 찾아보기를 선택하여 위치를 선택합니다.

    BigQuery 경로는 동일한 프로젝트에 있어야 하고 스키마가 정확해야 합니다. 이를 확인하려면 찾아보기를 클릭하고 테이블 이름을 클릭하여 BigQuery 콘솔에서 콘텐츠를 확인합니다.

  5. 가져오기 창에서 가져오기를 클릭합니다.

    가져오기가 시작됩니다. 가져오기를 중단하지 않고 페이지에서 나갈 수 있습니다.

cURL

  1. 가져오기의 입력 매개변수에 대한 데이터 파일을 만듭니다. 입력 매개변수 값은 Cloud Storage 또는 BigQuery 중 어디에서 가져오는지에 따라 달라집니다.

    BigQuerySource 객체를 사용하여 BigQuery 데이터 세트를 가리킵니다.

    • dataset-id: BigQuery 데이터 세트의 ID입니다.
    • table-id: 데이터를 보관하는 BigQuery 테이블의 ID입니다.
    • data-schema: dataSchema 속성에 suggestions(기본값), allowlist, denylist 값을 사용합니다. 소매업용 Vertex AI Search 자동 완성 스키마를 사용합니다.
    {
  "inputConfig":{
    "bigQuerySource": {
      "datasetId":"dataset-id",
      "tableId":"table-id",
      "dataSchema":"data-schema"
    }
  }
}

  2. CompletionData:import REST 메서드에 POST 요청을 하고 데이터 파일의 이름을 제공하여 자동 완성 정보를 소매업용 Vertex AI Search로 가져옵니다(아래 예시에서 input.json으로 표시됨).

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" -d @./input.json
"https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/completionData:import"

    API를 사용하여 프로그래매틱 방식으로 상태를 확인할 수 있습니다. 다음과 같은 응답 객체가 수신됩니다.

    {
  "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/123456",
  "done": false
}

    이름 필드는 작업 객체의 ID입니다. 이 객체의 상태를 요청하려면 이름 필드를 가져오기 메서드에서 반환한 값으로 바꿉니다. 가져오기가 완료되면 done 필드가 true로 반환됩니다.

    curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/123456"

    작업이 완료되면 반환된 객체의 done 값이 true가 되며 다음 예시와 비슷한 상태 객체가 포함됩니다.

    {
  "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/123456",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ImportMetadata",
    "createTime": "2020-01-01T03:33:33.000001Z",
    "updateTime": "2020-01-01T03:34:33.000001Z",
    "successCount": "2",
    "failureCount": "1"
  },
  "done": true
  "response": {
    "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ImportCompletionDataResponse",
  }
}

자동 완성 데이터 형식

JSON 파일은 다음 예시와 유사합니다. 줄바꿈은 가독성을 위해 사용됩니다. 전체 추천을 한 줄에 제공해야 합니다. 각 추천은 한 줄에 하나씩 표시됩니다.

추천 최소 필수 필드:

{
  "suggestion": "ABC",
  "globalScore": "0.5"
}

또는

{
  "suggestion": "ABC",
  "frequency": "100"
}

자동 완성 데이터 가져오기 기간

BigQuery에서 하나의 가져오기가 완료되려면 일반적으로 몇 분에서 1시간 정도 소요됩니다.

데이터 세트 가져오기가 완료되면 작업 객체의 done 필드가 true로 표시됩니다. 그런 다음 데이터의 색인이 생성되고 프로덕션 서빙에 사용되는 데 1~2일 정도 더 걸릴 수 있습니다.

자동 완성 데이터 세트를 최신 상태로 유지하기

업로드된 데이터 세트를 사용하려는 경우 업로드된 데이터 세트를 정기적으로 최신 상태로 유지하는 것이 좋습니다.

일괄 업데이트

가져오기 메서드를 사용하여 자동 완성을 일괄 업데이트할 수 있습니다. 이 작업은 초기 가져오기를 수행할 때와 동일한 방식으로 실행합니다. 자동 완성 데이터 가져오기의 단계를 따르세요. 이렇게 하면 가져온 전체 데이터 세트가 변경됩니다.

가져오기 상태 모니터링

데이터 세트를 사용할 때 고품질 추천 결과를 얻으려면 데이터 세트를 최신 상태로 유지하는 것이 중요합니다. 가져오기 오류율을 모니터링하고 필요하다면 조치를 취해야 합니다.

소매업용 Vertex AI Search 자동 완성 스키마

BigQuery에서 자동 완성 데이터 세트를 가져올 때 아래의 소매업용 Vertex AI Search 스키마를 사용하여 올바른 형식의 BigQuery 테이블을 만들고 자동 완성 데이터로 로드합니다.

추천 스키마

이 데이터 세트는 자체 자동 완성 추천 문구를 자체 점수로 제공하는 데 사용됩니다.

차단 목록 스키마

이 데이터 세트는 구문이 추천되지 않도록 차단 목록으로 사용됩니다.

허용 목록 스키마

이 데이터 세트는 이 허용 목록의 모든 문구에 대한 후처리(예: 맞춤법 교정 및 결과가 없는 검색 필터링)를 건너뛰는 데 사용됩니다.