소매업의 이름이 소매업용 Vertex AI Search로 변경됩니다. 새로운 브랜딩이 반영되도록 콘텐츠를 업데이트하는 중입니다.

추천 필터

이 페이지에서는 제품 속성을 사용하여 Recommendations의 필터링 결과에 대해 설명합니다.

예측 요청에 필터 표현식을 지정하여 예측 결과를 필터링할 수 있습니다. 필터 표현식은 각 제품에 대해 평가되는 논리 표현식입니다. 응답의 제품 목록은 표현식이 true로 평가되는 제품으로 범위가 제한됩니다.

Recommendations 필터링에는 두 가지 버전이 있습니다.

버전 2를 사용하는 것을 권장합니다.
버전 1은 지원 중단되었지만 여전히 사용 중일 수 있습니다.

이 안내 가이드의 섹션은 제품 속성을 사용하여 추천을 필터링하는 버전 2에만 적용됩니다.

Recommendations 필터링, 버전 2

버전 2는 제품 속성을 사용합니다. 필터 표현식은 제품 속성을 기반으로 합니다. categories나 colors 같은 사전 정의된 시스템 속성이거나 attributes.styles 같이 사용자가 정의한 커스텀 속성일 수 있습니다. 제품 속성을 필터링 가능으로 설정하면 Recommendations가 필터 태그를 수동으로 추가할 필요 없이 해당 속성을 Recommendations 필터링 태그로 자동으로 사용할 수 있습니다.

속성을 사용하여 제품을 필터링할 때 예측 응답은 필터 표현식과 일치하는 속성 값이 포함된 하나 이상의 기본 또는 옵션이 있는 제품을 포함하는 기본 제품을 반환합니다. 기본 및 옵션이 있는 제품에 대한 자세한 내용은 제품 수준을 참조하세요.

다음 필터 표현식 예시는 "New-Arrival"로 설정되고 프로모션용으로 설정되지 않은 모든 Red 또는 Blue 제품을 필터링합니다.

colors: ANY("red", "blue") AND attributes.status: ANY("New-Arrival") AND NOT attributes.is_promotional: ANY("true")

Recommendations에 대한 필터링 버전 2를 사용하려면 다음 절차를 따르세요. 각 절차는 이 페이지의 뒷부분에서 설명합니다.

필터링된 추천을 서빙할 모델의 Recommendations 필터링을 사용 설정합니다.
필터링할 제품 속성에 대한 Recommendations 필터링을 사용 설정합니다.
예측 요청에 필터링 가능한 제품 속성을 사용합니다.

Recommendations 필터링, 버전 1(지원 중단됨)

버전 1은 수동으로 생성된 필터 태그를 사용합니다. 필터 표현식은 필터 태그를 기반으로 하며 필터링할 카탈로그의 제품에 수동으로 추가해야 합니다.

다음 필터 표현식 예시에서는 필터 태그를 사용하여 'Red' 또는 'Blue'와 'New-Arrival'로 태그되지만 'promotional'로 태그되지 않은 제품을 지정합니다.

tag=("Red" OR "Blue") tag="New-Arrival" tag=(NOT "promotional")

Product.tags[] 필드는 API 참고 문서를 참조하세요.

태그 표현식에는 부울 연산자 OR 또는 NOT이 포함될 수 있으며, 이는 1개 이상의 공백을 사용하여 태그 값과 구분되어야 합니다. 태그 값 바로 앞에 NOT 연산자와 같은 대시(-)를 추가할 수도 있습니다. 부울 연산자를 사용하는 태그 표현식은 괄호로 묶어야 합니다.

태그 외에도 filterOutOfStockItems로 필터링할 수 있습니다. filterOutOfStockItems 플래그는 stockState가 OUT_OF_STOCK인 모든 제품을 필터링합니다.

태그 필터와 재고 없음 필터를 조합하여 지정된 모든 필터 표현식을 충족하는 항목만 반환되도록 할 수 있습니다.

필터 문자열의 예시는 다음과 같습니다.

"filter": "tag=\"spring-sale\""

"filter": "filterOutOfStockItems"

"filter": "tag=\"spring-sale\" tag=\"exclusive\" filterOutOfStockItems"

다음 예시는 spring-sale 또는 exclusive 태그(또는 둘 다)가 있고 items-to-exclude 태그도 없는 재고 항목만 반환합니다.

"filter": "tag=(\"spring-sale\" OR \"exclusive\") tag=(-\"items-to-exclude\") filterOutOfStockItems"

속성 필터 및 태그 필터 호환성

모델에 수동으로 생성된 태그와 필터링 가능한 제품 속성이 모두 있는 경우 필터링 버전 중 하나를 사용하여 예측 요청을 제공할 수 있습니다. 그러나 동일한 예측 요청에 v1 필터링과 v2 필터링 표현식을 모두 포함할 수는 없습니다.

Recommendations 필터링 한도

각 필터링 가능 속성은 각 모델의 일부 메모리를 사용합니다. 다음 한도는 서빙 성능에 부정적인 영향을 미치는 것을 막는 데 도움이 됩니다.

카탈로그에서 최대 10개의 커스텀 속성을 필터링 가능으로 설정할 수 있습니다.
카탈로그에 필터링 가능 속성 값이 최대 100,000,000개까지 존재할 수 있습니다.

카탈로그의 총 속성 값 수는 카탈로그의 제품 수에 필터링 가능 속성 수를 곱해 추정할 수 있습니다.

예를 들어 제품 1,000개 및 속성 3개가 필터링 가능으로 설정된 카탈로그가 있는 경우 총 속성 값 수는 3*1000=3,000개로 추정될 수 있습니다.

버전 2와 함께 버전 1 Recommendations 필터링을 사용하는 경우 필터 태그 수는 할당량에 반영됩니다. 총 속성 값 수에 추가된 필터 태그 수가 100,000,000개 미만이어야 합니다.

이 한도를 초과하면 추가 속성을 필터링 가능으로 설정할 수 없습니다. 이 한도를 초과해야 하는 경우 할당량 상향을 요청합니다.

총 태그 수는 모델 학습 중에 계산됩니다. 총 개수가 한도를 초과하면 모델 학습이 실패합니다. 모델 학습 중에 필터링 가능한 커스텀 속성이 10개 넘게 발견되면 10개만 사용됩니다.

Recommendations 필터 표현식 구문

Search 및 Recommendations의 필터 표현식 구문은 비슷합니다. 하지만 Recommendations에는 몇 가지 제한사항이 있습니다.

Recommendations 필터 표현식 구문은 다음 EBNF로 요약될 수 있습니다.

  # A single expression or multiple expressions that are joined by "AND" or "OR".
  filter = expression, { " AND " | "OR", expression };

  # An expression can be prefixed with "-" or "NOT" to express a negation.
  expression = [ "-" | "NOT " ],
                    # A parenthesized expression
                    | "(", expression, ")"
                    # A simple expression applying to a textual field.
                    # Function "ANY" returns true if the field contains any of the literals.
                    ( textual_field, ":", "ANY", "(", literal, { ",", literal }, ")"

  # A literal is any double-quoted string. You must escape backslash (\) and
  # quote (") characters.
  literal = double-quoted string;

  textual_field = see the tables below;

필터 구문 제한사항

다음 제한사항이 적용됩니다.

괄호로 묶은 AND 및 OR 연산자를 삽입하는 깊이가 제한됩니다. 필터의 논리 표현식은 논리곱 정규형(CNF)이어야 합니다. 지원되는 가장 복잡한 논리 표현식은 (... OR ... OR ...) AND (... OR ...) AND (... OR ...)과 같이 OR 연산자만 포함하는 AND로 연결된 절 목록일 수 있습니다.
NOT 키워드 또는 -을 사용하여 표현식을 부정할 수 있습니다. 이는 인벤토리 관련 속성을 포함하지 않는 단일 인수가 있는 ANY() 표현식에서만 작동합니다.
availability 기반 제한은 최상위 수준에 적용해야 합니다. OR 절이나 부정(NOT)의 일부로 사용할 수 없습니다.
표준 Recommendations 필터링은 텍스트 필드만 지원하므로 보다 작음, 보다 큼, 범위 확인 연산은 표준 Recommendations 필터링에 지원되지 않습니다. 보다 작음 및 보다 큼 연산은 일부 숫자 필드를 지원하는 추천 부스트/하강 컨트롤 조건에서만 사용할 수 있습니다(부스트/하강 지원 필드 참조).
최상위 AND 절의 최대 조건 수는 20개입니다.
OR 절에는 ANY() 표현식에 포함된 인수가 최대 100개까지 포함될 수 있습니다. OR 절에 여러 개의 ANY() 표현식이 있는 경우 해당 인수는 모두 이 한도에 반영됩니다. 예를 들어 colors: ANY("red", "green") OR colors: ANY("blue")에는 세 개의 인수가 있습니다.

다음 표는 유효한 필터 표현식의 예시와 잘못된 예시 및 잘못된 이유를 보여줍니다.

표현식	유효성	참고
`colors: ANY("red", "green")`	예
`NOT colors: ANY("red")`	예
`NOT colors: ANY("red", green")`	아니요	인수가 2개 이상인 `ANY()` 를 부정합니다.
`colors: ANY("red", "green") OR categories: ANY(\"Phone > Android > Pixel\")`	예
`(colors: ANY("red") OR colors: ANY("green")) AND categories: ANY(\"Phone > Android > Pixel\")`	예
`(colors: ANY("red") AND colors: ANY("green")) OR categories: ANY(\"Phone > Android > Pixel\")`	아니요	논리곱 정규형이 아닙니다.
`(colors: ANY("red")) AND (availability: ANY("IN_STOCK")`	예
`(colors: ANY("red")) OR (availability: ANY("IN_STOCK"))`	아니요	`OR` 표현식의 `availability`를 다른 조건과 결합합니다.

인벤토리 관련 속성 필터링

인벤토리 관련 속성에 대한 필터링은 제품의 실시간 상태를 기준으로 처리됩니다.

IN_STOCK은 Recommendations 필터링 버전 2에서 지원되는 유일한 availability 속성 값입니다.

인벤토리 관련 속성은 AND 절에서 사용할 수 있지만 OR 절에서는 사용할 수 없습니다.

지원되는 필드

지원되는 텍스트 필드는 다음 표에 요약되어 있습니다.

Recommendations의 부스트/하강은 표준 Recommendations 필터링에서 지원하지 않는 추가 필드를 지원합니다. Recommendations의 부스트/하강으로 지원되는 추가 필드 목록은 부스트/하강 지원 필드를 참조하세요.

필드	설명
'productId'	제품 ID입니다(Product.name의 마지막 부분).
'brands'	Product.brands입니다.
'categories'	Product.categories입니다.
'genders'	Audience.genders입니다.
'ageGroups'	Audience.age_groups입니다.
'colorFamilies'	ColorInfo.color_families입니다.
'colors'	ColorInfo.colors입니다.
'sizes'	Product.sizes입니다.
'materials'	Product.materials입니다.
'patterns'	Product.patterns입니다.
'conditions'	Product.conditions입니다.
'attributes.key'	제품 객체의 텍스트 커스텀 속성입니다. 속성 값이 텍스트인 경우 키는 Product.attributes 맵의 임의 키일 수 있습니다.

부스트/하강 지원 필드

부스트/하강은 숫자 필드를 포함하여 표준 Recommendations 필터링에서 지원하지 않는 일부 추가 필드를 지원합니다.

지원되는 필드에 나열된 필드 외에도 추천의 부스트/하강은 다음 필드를 지원합니다.

텍스트 필드

필드	설명
'tags'	`Product.tags[]` 제품과 연결된 커스텀 태그입니다.

숫자 필드

필드	설명
'price'	`PriceInfo.price`. 제품의 가격입니다.
'discount'	제품 할인입니다. 이 필드는 `PriceInfo`의 원래 가격 및 가격 필드 값을 사용하여 계산됩니다.
'rating'	`Product.rating` 제품의 총 평점 개수입니다.
'ratingCount'	`rating.ratingCount` 제품의 총 평점 개수입니다.

모델의 Recommendations 필터링 설정

Search for Retail 콘솔 또는 Models API 리소스를 사용하여 Recommendations에 대한 필터링을 사용 설정할 수 있습니다.

콘솔에서 Recommendations 필터링이 사용 설정된 새 모델을 만들 수 있습니다. 기존 모델에 대해 이 옵션을 업데이트할 수도 있습니다.

Models API 리소스를 사용하면 Recommendations 필터링이 사용 설정된 새 모델을 만들거나 models.Patch를 사용하여 기존 모델의 이 설정을 업데이트할 수 있습니다.

예측을 반환하는 서빙 구성에 카테고리 일치가 사용 설정된 경우 응답으로 컨텍스트 제품과 카테고리를 공유하는 제품 결과만 반환되기 때문에 필터링에 'categories' 속성이 작동하지 않습니다.

콘솔을 사용한 모델의 필터링 설정

Search for Retail 콘솔을 사용하여 모델을 만드는 동안 태그 자동 생성 옵션을 선택하여 해당 모델의 추천 필터링을 허용합니다.

콘솔을 사용해 추천 모델을 만드는 방법은 추천 모델 만들기를 참조하세요.

콘솔에서는 기존 모델의 설정을 업데이트할 수 없습니다. 모델의 이 설정을 업데이트하려면 models.Patch API 메서드를 사용하세요.

API를 사용한 모델의 필터링 설정

새 모델을 만들 때 models.Create를 사용하거나 기존 모델을 업데이트할 때 models.Patch를 사용하여 모델에 Recommendations 필터링을 사용 설정할 수 있습니다.

필터링을 허용하려면 모델의 filteringOption 필드를 설정합니다. 이 필드에서 허용되는 값은 다음과 같습니다.

RECOMMENDATIONS_FILTERING_DISABLED(기본값): 모델에 대한 필터링이 사용 중지됩니다.
RECOMMENDATIONS_FILTERING_ENABLED: 기본 제품에 대한 필터링이 사용 설정됩니다.

다음 curl 예시에서는 Recommendations 필터링이 사용 설정된 새 모델을 만듭니다.

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
       'name': 'MODEL_NAME',
       'displayName': 'MODEL_DISPLAY_NAME',
       'type': 'home-page',
       'filteringOption': 'RECOMMENDATIONS_FILTERING_ENABLED',
     }" \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/models"

다음 curl 예시에서는 기존 모델의 필터링 옵션 설정을 업데이트합니다.

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
       'filteringOption': 'RECOMMENDATIONS_FILTERING_ENABLED',
     }" \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/models/MODEL_ID?updateMask=filteringOption"

필터링 가능 속성 설정

추천 제품을 필터링하려면 필터 표현식에서 사용할 제품 속성에 대한 필터링을 사용 설정합니다. Search for Retail 콘솔 또는 Attributes API 리소스를 사용하여 이 설정을 업데이트할 수 있습니다.

필요 이상으로 많은 속성을 필터링 가능하게 설정하지 마세요. 필터링 가능 속성 수에는 한도가 적용됩니다.

콘솔을 사용하여 속성을 필터링 가능으로 설정

Search for Retail 콘솔의 컨트롤 페이지에서 속성을 필터링 가능으로 설정할 수 있습니다.

Search for Retail 콘솔의 컨트롤 페이지로 이동합니다.

컨트롤 페이지로 이동
속성 컨트롤 탭으로 이동합니다.

이 탭에는 사이트 전체 컨트롤을 설정할 수 있는 모든 제품 속성이 표 형식으로 표시됩니다.
컨트롤 수정을 클릭합니다.
제품 속성의 필터링 가능을 True로 설정합니다.
컨트롤 저장을 클릭합니다.

다음 모델 학습 주기가 완료된 후에는 이 속성을 사용하여 필터링을 시작할 수 있습니다.

API를 사용하여 속성을 필터링 가능으로 설정

AttributesConfig는 카탈로그의 속성 목록을 나타냅니다.

CatalogAttribute의 AttributesConfig.filteringOption 필드를 설정합니다. 이 필드에서 허용되는 값은 다음과 같습니다.

RECOMMENDATIONS_FILTERING_DISABLED(기본값): 속성에 대한 필터링이 사용 중지됩니다.
RECOMMENDATIONS_FILTERING_ENABLED: 속성에 대한 필터링이 사용 설정됩니다.

다음 curl 예시에서는 기존 제품 속성을 쿼리합니다.

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \ "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/attributesConfig"

다음 curl 예시에서는 제품 속성 categories를 필터링 가능으로 설정합니다.

기존 속성을 업데이트할 때는 이전 단계에 표시된 대로 indexableOption, dynamicFacetableOption, searchableOption에 대한 속성의 원래 값을 유지합니다. 이전 예시와 같이 attributesConfig를 볼 때 선택한 속성이 표시되지 않으면 다음 예시와 같이 기본 설정을 사용합니다.

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
        'name': 'projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/attributesConfig',
        'catalogAttributes': {
          'categories': {
            'key': 'categories',
            'indexableOption': 'INDEXABLE_ENABLED',
            'dynamicFacetableOption': 'DYNAMIC_FACETABLE_DISABLED',
            'searchableOption': 'SEARCHABLE_DISABLED',
            'recommendationsFilteringOption': 'RECOMMENDATIONS_FILTERING_ENABLED'
          }
        },
        'attributeConfigLevel': 'CATALOG_LEVEL_ATTRIBUTE_CONFIG'
     }" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/attributesConfig"

다음 모델 학습 주기가 완료된 후에는 이 속성을 사용하여 필터링을 시작할 수 있습니다.

예측 요청에 필터링 가능 속성 사용

모델이 재학습한 후 예측 요청에 필터링 가능한 제품 속성을 사용할 수 있습니다.

요청 매개변수 값 filterSyntaxV2를 true로 설정하여 버전 2 Recommendations 필터링을 활성화합니다. 매개변수가 설정되지 않으면 버전 1 필터링은 활성 상태로 유지됩니다. 모델에 수동으로 생성된 태그와 필터링 가능한 제품 속성이 모두 있는 경우 필터링 버전 중 하나를 사용하여 예측 요청을 제공할 수 있습니다. 그러나 동일한 예측 요청에 v1 필터링과 v2 필터링 표현식을 모두 포함할 수는 없습니다.

다음 부분 curl 예시에서는 true로 설정된 filterSyntaxV2와 colors 및 categories 제품 속성을 사용하는 필터 표현식을 보여줍니다. 이 예시에서는 colors 및 categories를 필터링 가능으로 설정했다고 가정합니다.

"params": {
  "filterSyntaxV2": true
},
"filter": "(categories: ANY(\"Phone > Android > Pixel\") OR colors: ANY(\"red\", \"green\")) AND (availability: ANY(\"IN_STOCK\"))"

다음 curl 예시는 전체 예측 요청을 보여줍니다.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
        'userEvent': {
          'eventType': 'detail-page-view',
          'visitorId': 'VISITOR_ID',
          'productDetails': {
            'product': {
              'id': 'PRODUCT_ID'
            }
          }
        },
        'params': {
          'returnProduct': true,
          'filterSyntaxV2': true,
          'strictFiltering': true,
        },
        'filter': 'categories: ANY(\"xyz\")',
        useMostRecentServingConfig: true
     }" \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/placements/SERVING_CONFIG:predict"

필터 외에도 서빙 구성의 다각화 설정도 응답으로 반환되는 결과 수에 영향을 줄 수 있습니다.