이 문서는 Recommendations AI, Retail Search, 새로운 Retail 콘솔에 대한 문서입니다.

자동 완성 데이터 가져오기

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

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

시작하기 전에

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

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

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

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

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

  • 더미 또는 자리표시자 값을 사용하지 않습니다.

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

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

자동 완성 데이터 가져오기

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

BigQuery에서 올바른 형식으로 자동 완성 데이터를 가져오려면 올바른 형식의 Retail 자동 완성 스키마~BigQuery 테이블 만들기를 사용하고 자동 완성 데이터로 테이블을 로드합니다. 그런 다음 데이터를 Retail에 업로드합니다.

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

BigQuery 데이터 세트 위치

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

BigQuery에 데이터 채우기

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

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

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

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

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

curl

  1. BigQuery 데이터 세트가 다른 프로젝트에 있으면 Retail이 BigQuery 데이터 세트에 액세스할 수 있도록 필요한 권한을 구성합니다. 자세히 알아보기

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

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

    • dataset-id: BigQuery 데이터 세트의 ID입니다.
    • table-id: 데이터를 보관하는 BigQuery 테이블의 ID입니다.
    • data-schema: dataSchema 속성에 suggestions(기본값), allowlist, denylist 값을 사용합니다. Retail 자동 완성 스키마를 사용합니다.
    {
      "inputConfig":{
        "bigQuerySource": {
          "datasetId":"dataset-id",
          "tableId":"table-id",
          "dataSchema":"data-schema"
        }
      }
    }
    
  3. CompletionData:import REST 메서드에 대해 POST 요청을 수행하고 데이터 파일 이름(여기서는 input.json으로 표시됨)을 제공하여 자동 완성 정보를 Retail로 가져옵니다.

    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",
      }
    }
    

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

BigQuery 데이터 세트가 Retail 서비스와 다른 프로젝트에 있을 때 액세스를 설정하려면 다음 단계를 완료합니다.

  1. Cloud Console에서 IAM 페이지를 엽니다.

    IAM 페이지 열기

  2. Retail 프로젝트를 선택합니다.

  3. 이름이 Retail 서비스 계정인 서비스 계정을 찾습니다.

    이전에 Retail로 가져오기 작업을 시작한 적이 없다면 이 서비스 계정이 나열되지 않을 수 있습니다. 이 서비스 계정이 표시되지 않으면 가져오기 작업으로 돌아가서 가져오기를 시작합니다. 권한 오류로 인해 가져오기가 실패하면 여기로 돌아와 이 작업을 완료하세요.

  4. 이메일 주소와 비슷한 서비스 계정의 식별자를 복사합니다(예: cloud-retail-customer-data-access@system.gserviceaccount.com).

  5. IAM 및 관리자에서 추가를 클릭합니다.

  6. Retail 서비스 계정의 식별자를 입력하고 BigQuery > BigQuery 데이터 뷰어 역할을 선택합니다.

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

  7. 저장을 클릭합니다.

자동 완성 데이터 형식

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

추천 최소 필수 필드:

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

또는

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

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

BigQuery에서 일반적으로 한 번 가져오는 데 10시간 정도 걸립니다. 장기 실행 작업은 프로덕션을 제공할 수 있도록 데이터 세트를 푸시합니다. 데이터 세트를 제공할 수 있으면 작업 객체done 필드가 true로 표시됩니다. 작업이 done되기 전에는 가져오기 데이터 세트에서 최신 제안을 가져온다고 보장되지 않습니다.

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

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

일괄 업데이트

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

가져오기 상태 모니터링

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

Retail 자동 완성 스키마

BigQuery에서 자동 완성 데이터 세트를 가져올 때는 아래의 Retail 스키마를 사용하여 올바른 형식으로 BigQuery 테이블을 만들어 자동 완성 데이터와 함께 로드합니다.

추천 스키마

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

차단 목록 스키마

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

허용 목록 스키마

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