Method: projects.locations.collections.engines.servingConfigs.recommend

상황별 사용자 이벤트가 필요한 추천을 만듭니다.

HTTP 요청

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

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

경로 매개변수

매개변수
servingConfig

string

필수 항목입니다. ServingConfig의 전체 리소스 이름: projects/*/locations/global/collections/*/engines/*/servingConfigs/* 또는 projects/*/locations/global/collections/*/dataStores/*/servingConfigs/*

추천 엔진을 만들면 기본 서빙 구성이 하나 생성됩니다. 엔진 ID는 기본 서빙 구성의 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

자세한 내용은 Authentication Overview를 참조하세요.

IAM 권한

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

  • discoveryengine.servingConfigs.recommend

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