소매업의 이름이 소매업용 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 case sensitive string. You must escape backslash (\) and
  # quote (") characters. We do not support textual values containing `/` characters, or partial string matches.

  # The literal must be an exact match for products in the catalog. The Predict
  # API returns empty results when no possible matches exist.

  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")`	아니요	두 개 이상의 인수로 `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`를 다른 조건과 결합합니다.

인벤토리 관련 속성 필터링

인벤토리 관련 속성에 대한 필터링은 제품의 실시간 상태를 기준으로 합니다. availability: ANY("IN_STOCK") 필터링의 경우 예측 응답은 기본 제품 또는 옵션이 있는 제품의 일치하는 값이 IN_STOCK인 기본 제품을 반환합니다. 기본 및 옵션이 있는 제품에 대한 자세한 내용은 제품 수준을 참조하세요. Primary only 또는 Variant only 필터링은 지원하지 않습니다.

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 콘솔을 사용하여 모델을 만드는 동안 태그 자동 생성 옵션을 선택하여 해당 모델의 추천 필터링을 허용합니다.

전체 효과가 결합되고 필터링이 마지막으로 발생하므로 diversity-level 및 category-match-level 등과 같은 다른 설정과의 호환성을 다시 확인합니다.

예를 들어 규칙 기반 diversity-level 및 category attribute filtering을 결합하면 빈 출력이 자주 발생합니다.
- diversity-level=high-diversity는 모델이 동일한 카테고리 문자열의 최대 결과를 제한하도록 강제합니다. 즉, 카테고리 1에 대한 결과 1개, 카테고리 2에 대한 결과 1개 등입니다.
- 카테고리 메타데이터(Product.categories = ANY ("category2"))를 사용한 속성 필터링을 사용하면 모델에서 일치하지 않는 항목을 삭제합니다.
- 최종 출력의 결과는 3개 미만입니다.
similar-items 모델의 경우 기본 category-match-level = relaxed-category-match를 사용하는 추가 카테고리 관련성 부스팅이 이미 포함되어 있습니다. 동작을 사용 중지하고 맞춤 필터링 규칙을 사용하려면 category-match-level=no-category-match로 전환하세요.

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

콘솔에서는 기존 모델의 설정을 업데이트할 수 없습니다. 모델의 이 설정을 업데이트하려면 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"

다음 모델 학습 주기가 완료된 후 필터링에 속성을 사용할 수 있습니다. 일반적으로 최소 8시간이 걸립니다.

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

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

요청 매개변수 값 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\")'
     }" \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/placements/SERVING_CONFIG:predict"

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