Method: projects.locations.dataStores.servingConfigs.recommend

추천을 생성하며, 이를 위해서는 컨텍스트 기반 사용자 이벤트가 필요합니다.

HTTP 요청

POST https://discoveryengine.googleapis.com/v1beta/{servingConfig=projects/*/locations/*/dataStores/*/servingConfigs/*}:recommend

URL은 gRPC 트랜스코딩 문법을 사용합니다.

경로 매개변수

매개변수
servingConfig

string

필수 항목. 다음 형식의 ServingConfig 전체 리소스 이름을 입력해야 합니다(projects/*/locations/global/collections/*/engines/*/servingConfigs/* 또는 projects/*/locations/global/collections/*/dataStores/*/servingConfigs/*).

추천 엔진을 만들면 하나의 기본 서빙 구성이 함께 생성됩니다. 엔진 ID는 기본 ServingConfig의 ID로 사용됩니다. 예를 들어 엔진 projects/*/locations/global/collections/*/engines/my-engine의 경우 RecommendationService.Recommend 요청에 projects/*/locations/global/collections/*/engines/my-engine/servingConfigs/my-engine을 사용할 수 있습니다.

요청 본문

요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.

JSON 표현 
{
  "userEvent": {
    object (UserEvent)
  },
  "pageSize": integer,
  "filter": string,
  "validateOnly": boolean,
  "params": {
    string: value,
    ...
  },
  "userLabels": {
    string: string,
    ...
  }
}
필드
userEvent

object (UserEvent)

필수 항목. 사용자, 사용자가 보고 있는 항목, servingConfigs.recommend 요청을 트리거하기 위해 사용자가 취한 작업에 관한 컨텍스트입니다. 이 사용자 이벤트 세부정보는 userEvent 로그로 수집되지 않습니다. 따라서 이벤트 로깅을 위해서는 별도의 userEvent 쓰기 요청을 보내야 합니다.

여러 사용자에 대해 UserEvent.user_pseudo_id 또는 UserEvent.user_info.user_id를 동일한 고정 ID로 설정하지 마세요. 맞춤설정되지 않은 추천을 받으려면(권장되지 않음, 모델 성능에 부정적인 영향을 줄 수 있음) 대신 UserEvent.user_pseudo_id를 임의의 고유 ID로 설정하고 UserEvent.user_info.user_id를 설정하지 않은 상태로 두세요.
pageSize

integer

반환할 결과의 최대 수입니다. 이 속성을 필요한 추천 결과 수로 설정하세요. 0으로 설정하면 서비스가 적절한 기본값을 선택합니다. 허용되는 최댓값은 100입니다. 100을 초과하는 값은 100으로 설정됩니다.
filter

string

추천 결과를 제한하기 위한 필터 문자열입니다(최대 길이 5,000자). 현재는 filterTags 속성에 대한 필터 표현식만 지원됩니다.

예:

  • (filterTags: ANY("Red", "Blue") OR filterTags: ANY("Hot", "Cold"))
  • (filterTags: ANY("Red", "Blue")) AND NOT (filterTags: ANY("Green"))

params 필드에서 attributeFilteringSyntax가 true로 설정된 경우 위에서 설명한 태그 기반 구문 대신 속성 기반 표현식이 필요합니다. 예:

  • (language: ANY("en", "es")) AND NOT (categories: ANY("Movie"))
  • (available: true) AND (language: ANY("en", "es")) OR (categories: ANY("Movie"))

필터가 모든 결과를 차단하면 API는 일반적인(필터링되지 않은) 인기 문서를 반환합니다. 필터 조건에 정확히 일치하는 결과만 받고 싶다면, RecommendRequest.params에서 strictFiltering을 true로 설정하여 빈 결과를 받도록 하세요.

필터 선택과 관계없이 API는 storageStatus가 EXPIRED 또는 DELETED인 Document를 반환하지 않습니다.
validateOnly

boolean

이 추천 쿼리에 대해 검증 전용 모드를 사용합니다. true로 설정하면 임의의 문서 ID를 반환하는 가짜 모델이 사용됩니다. 검증 전용 모드는 API를 테스트하거나 모델이 준비되지 않은 경우에만 사용해야 합니다.
params

map (key: string, value: value (Value format))

추천을 위한 추가 도메인별 파라미터입니다.

허용되는 값:

  • returnDocument: 불리언. true로 설정하면 RecommendResponse.RecommendationResult.document에 연결된 문서 객체가 반환됩니다.
  • returnScore: 불리언. true로 설정하면 반환된 각 문서에 대응하는 추천 점수가 RecommendResponse.RecommendationResult.metadata에 포함됩니다. 이 점수는 사용자 컨텍스트 및 기록을 기반으로 해당 문서가 전환될 확률을 나타냅니다.
  • strictFiltering: 불리언. 기본적으로 true입니다. false로 설정된 경우 필터가 모든 추천 결과를 차단하더라도 서비스는 비어 있는 결과 대신 일반적인(필터링되지 않은) 인기 문서를 반환합니다.
  • diversityLevel: 문자열입니다. 기본값은 비어 있습니다. 비어 있지 않은 값으로 설정할 경우 다음 중 하나여야 합니다.
    • no-diversity
    • low-diversity
    • medium-diversity
    • high-diversity
    • auto-diversity 이 옵션을 선택하면 요청 단위에서 문서 카테고리를 기반으로 추천 결과를 제어 및 조정할 수 있습니다.
  • attributeFilteringSyntax: 불리언. 기본적으로 False입니다. true로 설정하면 filter 필드를 새로운 속성 기반 구문으로 해석합니다.
userLabels

map (key: string, value: string)

리소스에 적용된 사용자 라벨은 다음 요구사항을 충족해야 합니다.

  • 각 리소스는 여러 개의 라벨(최대 64개)을 가질 수 있습니다.
  • 각 라벨은 키-값 쌍이어야 합니다.
  • 키를 비워 둘 수 없으며 최소 길이는 1자(영문 기준)이고 최대 길이는 63자(영문 기준)입니다. 값을 비워 둘 수 있으며 최대 길이는 63자(영문 기준)입니다.
  • 키와 값에는 소문자, 숫자, 밑줄, 대시만 사용할 수 있습니다. 모든 문자는 UTF-8 인코딩을 사용해야 하며 국제 문자가 허용됩니다.
  • 라벨의 키 부분은 고유해야 합니다. 그러나 리소스 여러 개에 같은 키를 사용할 수 있습니다.
  • 키는 소문자나 국제 문자로 시작해야 합니다.

자세한 내용은 라벨 요구사항을 참고하세요.

응답 본문

성공한 경우 응답 본문에 RecommendResponse의 인스턴스가 포함됩니다.

승인 범위

다음 OAuth 범위 중 하나가 필요합니다.

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/discoveryengine.readwrite
  • https://www.googleapis.com/auth/discoveryengine.serving.readwrite

자세한 내용은 Authentication Overview에서 확인하세요.

IAM 권한

servingConfig 리소스에 대해서는 다음 IAM 권한이 필요합니다.

  • discoveryengine.servingConfigs.recommend

자세한 내용은 IAM 문서를 참조하세요.