이 페이지에서는 부스트 서빙 컨트롤(컨트롤이라고도 함)을 사용하여 모델에서 반환된 미디어 추천의 순위 위치를 변경하는 방법을 설명합니다.
부스트 컨트롤은 모델에서 추천이 반환된 후 추천의 순서를 변경합니다. 필터 표현식을 결과에 적용하여 부스팅하거나 숨길 추천을 식별한 다음 -1과 +1 사이의 부스트 값을 적용합니다. 부스트 값이 +1이면 추천에 가장 큰 부스트가 적용되어 해당 추천이 반환된 추천의 맨 위에 배치됩니다. -1 값은 반환된 추천 목록의 하단으로 추천을 숨깁니다.
부스트는 서빙 시간 컨트롤입니다. 먼저 추천 모델이 추천 목록을 반환합니다. 그런 다음 서빙 구성을 사용해 부스트 컨트롤을 해당 목록에 적용하여 추천의 순위를 조정합니다. 부스트 컨트롤은 추천을 추가하거나 삭제하지는 않지만 추천이 사용자에게 표시되는 순서를 제어합니다.
추천 부스트와 필터링 비교
부스트는 소프트 필터입니다. 반면 추천 필터링에 설명된 추천의 일반 필터는 하드 필터입니다.
추천에 하드 필터를 적용하면 필터링된 문서는 표시되지 않습니다. 반면 소프트 필터를 사용하면 추천 목록에서 문서가 삭제되지 않습니다. 대신 소프트 필터는 반환된 추천 목록에서 어떤 문서가 더 높게 혹은 낮게 표시되어야 하는지 결정하는 데 사용됩니다.
추천 모델 과부하 방지
부스트 또는 숨기기 필터를 적용할 때는 0에 가까운 작은 값을 사용하는 것이 좋습니다. +1 또는 -1에 가까운 값은 추천 모델에 과부하를 일으킬 수 있으므로 모델에서 적용한 추천 순위가 사용자에게 표시되는 추천 순위에 반영되지 않습니다.
예를 들어 애니메이션 영화를 +1로 부스팅하면 추천 목록 상단에 애니메이션 영화만 표시됩니다. 이로 인해 모델에서 추천도가 높은 비애니메이션 영화가 목록 하단으로 밀려 사용자가 보지 못할 수도 있습니다.
순위 내리기와 숨기기 비교
순위 내리기와 숨기기는 적용되지 않았더라면 표시되었을 추천을 반환된 추천 목록에서 더 낮은 위치로 이동시킵니다.
하지만 순위 내리기는 콘텐츠의 연도나 사용자가 이미 콘텐츠의 일부를 시청했는지 여부를 기반으로 합니다. 순위 내리기에 관한 자세한 내용은 미디어 추천 순위 내리기를 참조하세요.
숨기기는 필터로 식별된 콘텐츠에 적용됩니다. 필터는 스키마에서 필터링 가능으로 표시된 데이터 필드일 수 있습니다. 필드를 필터링 가능으로 표시하는 방법을 비롯한 추천 필터에 관한 일반적인 내용은 추천 필터링을 참조하세요.
부스트 컨트롤 및 서빙 구성 정보
각 부스트 서빙 컨트롤은 필터와 부스트 값으로 구성됩니다. 예를 들어 한 부스트 컨트롤은 제목에 크리스마스가 포함된 영화를 0.1 값으로 부스트하고 다른 부스트 컨트롤은 공포 영화를 -0.2 값으로 숨깁니다.
하나 이상의 부스트 컨트롤을 만든 후 컨트롤을 서빙 구성에 연결합니다. Vertex AI Search 앱이 생성되면 기본 서빙 구성도 자동으로 생성됩니다. 서빙 시 서빙 구성을 참조하여 앱에서 생성할 결과를 결정합니다. 서빙 구성에는 부스트 컨트롤 외에 다양화 및 순위 내리기 컨트롤과 같은 다른 유형의 컨트롤이 포함될 수 있습니다.
서빙 구성은 recommend 메서드를 호출할 때 적용할 수 있습니다. 그런 다음 서빙 구성의 모든 컨트롤이 메서드 호출에서 반환된 추천에 적용됩니다.
또한 앱과 연결된 서빙 구성을 여러 개 사용할 수 있습니다. 이를 통해 다양한 상황에서 서로 다른 컨트롤 모음을 적용할 수 있습니다. 예를 들어 추천 요청이 어린이의 계정에서 오는 경우 어린이에게 적합한 카테고리의 영화를 부스팅하고 부적합한 영화는 숨깁니다. 마찬가지로 요청이 성인으로 표시된 계정에서 오는 경우 성인에게 인기 있는 작품이나 카테고리를 부스팅합니다. 또는 지리적 위치별로 서빙 구성을 다르게 하여 지역별로 인기 있는 콘텐츠에 따라 콘텐츠를 부스트할 수도 있습니다. 서빙 구성에 대한 자세한 내용은 미디어 서빙 구성 만들기 및 관리를 참조하세요.
부스트 값은 가산됨
서빙 구성에 여러 서빙 컨트롤을 연결한 경우 부스트와 숨기기가 가산됩니다.
예를 들어 애니메이션 어린이 영화를 0.3만큼 부스팅하고 애니메이션 어드벤처 영화를 0.4만큼 부스팅하면 어린이 애니메이션 어드벤처로 분류된 영화는 0.7만큼 부스팅됩니다.
마찬가지로 공포 영화가 동일한 서빙 구성에서 한 컨트롤에 의해 0.2만큼 부스팅되고 다른 컨트롤에 의해 -0.3만큼 숨겨지면 최종적으로 영화가 -0.1만큼 숨겨지게 됩니다.
부스트의 합계는 +1을 초과할 수 있습니다. 예를 들어 컨트롤이 애니메이션 어린이 영화를 0.6만큼 부스팅하고 애니메이션 어드벤처 영화를 0.5만큼 부스팅하는 경우 어린이 애니메이션 어드벤처 영화는 +1.1만큼 부스팅됩니다.
필터 예시
다음은 미디어 추천 필터의 몇 가지 예시입니다.
일반적인 키 속성에 대한 필터
일반 키 문자열 속성(category, image_name, image_uri, language, title, uri)의 필터 예시입니다.
어린이용 애니메이션:
"filter": "categories: ANY(\"animation\") AND categories: ANY(\"children\")"무서운 미디어:
"filter": "categories: ANY(\"horror\", \"thriller\", \"crime\")제목이 '크리스마스'인 미디어:
"filter": "title: ANY(\"Christmas\")"images배열의 첫 번째 항목에name'비치볼'이 있는 미디어:
"filter": "images[0].name: ANY(\"beach ball\")"
미디어 키 속성에 대한 필터
미디어 키 속성에 대한 필터 예시입니다. 미디어 키 속성은 media_로 시작하고 필터 문법에서 필드 이름은 media_key_properties.로 시작합니다. 미디어 키 속성 목록은 Google 사전 정의 스키마와 커스텀 스키마 비교를 참조하세요.
유형이
audio인 미디어:
"filter": "media_key_properties.media_type: ANY(\"audio\")"hash_tags 배열에 문자열(
#winter)이 포함된 미디어:
"filter": "media_key_properties.hash_tags: ANY(\"#winter\")"hash_tags 배열의 첫 번째 요소가 문자열(
#winter)인 미디어:
"filter": "media_key_properties.hash_tags[0]: ANY(\"#winter\")"
커스텀 필드
커스텀 필드의 필터 예시입니다. 커스텀 속성의 경우 필드 이름은 attributes.로 시작합니다.
스키마에 영화가 처음 상영된 영화제를 나타내는 커스텀 문자열 필드
festival이 있습니다. 칸에서 처음 상영한 영화만 필터링하려면 다음과 같이 작성합니다.
"filter": "attributes.festival: ANY(\"Cannes\")시각장애인 시청자를 위한 오디오 설명이 미디어에 포함된 경우 true인 커스텀 불리언 필드
audio_desc가 있습니다. 오디오 설명이 있는 미디어로 필터링하려면 다음과 같이 작성합니다.
"filter": "attributes.audio_desc: ANY(true)"
필터링 가능한 필드의 제한사항
다음과 같은 제한사항이 부스트 서빙 컨트롤에 적용됩니다.
부스트의 필터 표현식에는 문자열 및 불리언 유형의 속성 필드만 사용할 수 있습니다.
두 개 이상의 수준으로 중첩된 필드는 필터링할 수 없습니다. 예를 들어
persons.name을 기준으로 필터링할 수 있지만persons.name.stage필드가 있더라도 이 필드를 기준으로 필터링할 수는 없습니다.필터는 정확히 일치해야 합니다. 즉, 예시에서 '
Christmas Story' 또는 'CHRISTMAS'라는 영화는 부스팅되지 않습니다.
시작하기 전에
미디어 추천 앱과 데이터 스토어를 만들었는지 확인합니다. 자세한 내용은 미디어 추천 앱 및 데이터 스토어 만들기를 참조하세요.
선택사항: 기본 서빙 구성을 사용하지 않으려면 서빙 구성 만들기의 1~5단계와 7단계를 따라 새 서빙 구성을 만듭니다. 앱이 프로덕션에 있는 경우 프로덕션 서빙 구성에 컨트롤을 적용하기 전에 부스트 컨트롤 테스트를 위한 별도의 서빙 구성을 만드는 것이 좋습니다.
부스트 컨트롤에 사용할 필드가 스키마에서 필터링 가능으로 표시되어 있는지 확인합니다. 자세한 내용은 필드 설정 구성을 참조하세요. 필터링 한도도 참조하세요.
추천 부스트 또는 숨기기
이 절차에서는 부스트 컨트롤을 만들고 서빙 구성에 컨트롤을 연결하는 방법을 설명합니다.
컨트롤이 서빙 구성에 연결되면 servingConfigs.recommend 메서드를 호출할 때 서빙 구성을 지정할 수 있으며 부스트 컨트롤이 반환된 추천의 순위에 영향을 미치는 데 사용됩니다.
REST
부스트 서빙 컨트롤을 만들고 서빙 구성에 연결하려면 다음 단계를 따르세요.
앱 ID를 찾습니다. 앱 ID를 이미 알고 있는 경우 다음 단계로 건너뜁니다.
Google Cloud 콘솔에서 AI 애플리케이션 페이지로 이동합니다.
앱 페이지에서 앱 이름을 찾고 ID 열에서 앱 ID를 가져옵니다.
데이터 스토어 ID를 찾습니다. 데이터 스토어 ID를 이미 알고 있는 경우 다음 단계로 건너뜁니다.
Google Cloud 콘솔에서 AI 애플리케이션 페이지로 이동하고 탐색 메뉴에서 데이터 스토어를 클릭합니다.
데이터 스토어 이름을 클릭합니다.
데이터 스토어의 데이터 페이지에서 데이터 스토어 ID를 가져옵니다.
부스트 컨트롤을 만듭니다.
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ -H "X-Goog-User-Project: PROJECT_NUMBER" \ "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \ -d '{ "displayName": "CONTROL_DISPLAY_NAME", "solutionType": "SOLUTION_TYPE_RECOMMENDATION", "boostAction": { "dataStore": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/dataStores/DATA_STORE_ID", "boost" : BOOST_VALUE, "filter": "FILTER" } }'다음을 바꿉니다.
PROJECT_NUMBER: Google Cloud 프로젝트 수입니다.CONTROL_DISPLAY_NAME: 컨트롤을 식별하는 인간이 읽을 수 있는 이름입니다. 최대 길이가 128자(영문 기준)인 UTF-8 문자열이어야 합니다.CONTROL_ID: 컨트롤의 고유 식별자(데이터 스토어 내)입니다. ID에는 소문자, 숫자, 하이픈, 밑줄을 포함할 수 있습니다.APP_ID: Vertex AI Search 앱의 ID입니다.DATA_STORE_ID: Vertex AI Search 데이터 스토어의 ID입니다.BOOST_VALUE: [-1,1] 범위의 부동 소수점 숫자입니다. 값이 음수이면 추천이 결과 하단에 표시됩니다. 값이 양수이면 추천의 순위가 올라 결과 상단에 표시됩니다.FILTER: 부스팅하거나 숨길 문서를 설명하는 필터 표현식입니다. 필터 표현식을 작성하는 방법에 대한 자세한 내용은 필터 표현식을 참조하세요.
추천에 적용할 각 부스트 컨트롤에 대해 3단계를 반복합니다. 예를 들어 어린이용 영화를 부스트하는 부스트 컨트롤
boost-kids와 공포 영화를 숨기는 두 번째 컨트롤bury-horror를 적용하고자 할 수 있습니다.서빙 구성의 ID를 찾습니다. 서빙 구성 ID를 이미 알고 있는 경우 다음 단계로 건너뜁니다.
Google Cloud 콘솔에서 AI 애플리케이션 페이지로 이동합니다.
앱 페이지에서 앱 이름을 클릭합니다.
구성 페이지로 이동하여 서빙 탭을 클릭합니다.
ID 열에서 서빙 구성 ID를 가져옵니다.
engines.servingConfigs.patch메서드를 사용하여 업데이트 요청과 함께 새 부스트 서빙 컨트롤을 서빙 구성에 연결합니다.curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/CONFIG_ID?update_mask=boost_control_ids" \ -d '{ "boostControlIds": ["CONTROL_ID"] }'다음을 바꿉니다.
CONFIG_ID: 부스트 컨트롤을 연결하려는 서빙 구성의 ID입니다(예:my_app-1234567_id). 이전 단계를 참조하세요.CONTROL_ID: 서빙 구성에 연결할 하나 이상의 부스트 서빙 컨트롤 ID를 포함합니다(예:"boost-kids", "bury-horror"). 문자열 배열입니다. ID가 두 개 이상인 경우 구분 따옴표와 쉼표를 사용해야 합니다.
결과가 적용될 때까지 몇 분 정도 기다립니다.
부스트 컨트롤의 효과를 미리 봅니다. 미디어 추천 가져오기를 참조하세요.
부스트 컨트롤 업데이트
이 절차에서는 기존 부스트 컨트롤을 업데이트하여 부스트 또는 필터 값을 변경하는 방법을 설명합니다.
부스트 컨트롤을 테스트한 후 부스트를 더 강하게 또는 더 약하게 만들고 싶을 수 있습니다. 또는 필터 문자열을 변경하고자 할 수 있습니다.
부스트 값 또는 필터를 업데이트할 때는 engines.controls.patch 메서드를 호출합니다.
패치 메서드는 boost 및 filter 값을 제공된 새 값으로 바꿉니다. 이 절차에서는 boost 값(3단계)과 filter 값(4단계)을 수정하는 방법을 각각 보여줍니다. 하지만 두 항목을 모두 수정하려는 경우 단일 curl 명령어에서 수정할 수 있습니다.
REST
기존 컨트롤의 필터에 대한 부스트 값을 수정하려면 다음 단계를 따르세요.
앱 ID를 찾습니다. 앱 ID를 이미 알고 있는 경우 다음 단계로 건너뜁니다.
Google Cloud 콘솔에서 AI 애플리케이션 페이지로 이동합니다.
앱 페이지에서 앱 이름을 찾고 ID 열에서 앱 ID를 가져옵니다.
engines.servingConfigs.get메서드를 사용하여 업데이트할 부스트 컨트롤의 ID를 찾습니다. ID를 이미 알고 있는 경우 다음 단계로 건너뜁니다.curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls"다음을 바꿉니다.
PROJECT_ID: Google Cloud 프로젝트의 ID입니다.APP_ID: Vertex AI Search 앱의 ID입니다.
컨트롤의 부스트 값을 수정합니다.
curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls/CONTROL_ID?update_mask=boost_action.boost" \ -d '{ "name": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls/CONTROL_ID", "boostAction": { "boost": BOOST_VALUE } }'다음을 바꿉니다.
PROJECT_ID: Google Cloud 프로젝트의 ID입니다.APP_ID: Vertex AI Search 앱의 ID입니다.CONTROL_ID: 수정하려는 부스트 컨트롤의 고유 식별자입니다. 2단계에서GET명령어로 출력된name필드의 마지막 부분입니다. 예를 들면boost-kids입니다.BOOST_VALUE: [-1,1] 범위의 부동 소수점 숫자입니다. 값이 음수이면 추천이 결과 하단에 표시됩니다. 값이 양수이면 추천의 순위가 올라 결과 상단에 표시됩니다.
부스트 컨트롤의 필터를 수정합니다.
curl -X PATCH \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls/CONTROL_ID?update_mask=boost_action.filter" \ -d '{ "name": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls/CONTROL_ID", "boostAction": { "filter": "FILTER" } }'다음을 바꿉니다.
PROJECT_ID: Google Cloud 프로젝트의 ID입니다.APP_ID: Vertex AI Search 앱의 ID입니다.CONTROL_ID: 수정하려는 부스트 컨트롤의 고유 식별자입니다. 2단계에서GET명령어로 출력된name필드의 마지막 부분입니다.FILTER: 부스팅하거나 숨길 문서를 설명하는 필터 표현식입니다. 필터 표현식을 작성하는 방법에 대한 자세한 내용은 필터 표현식을 참조하세요.
부스트 컨트롤 삭제
이 절차에서는 부스트 컨트롤을 삭제하는 방법을 설명합니다. 부스트 컨트롤을 사용하지 않는 경우 허용되는 컨트롤 수의 할당량에 도달하거나 이를 초과하지 않도록 삭제하는 것이 좋습니다.
부스트 컨트롤을 삭제할 때는 engines.controls.delete 메서드를 호출합니다.
서빙 구성에 연결된 부스트 컨트롤은 삭제할 수 없습니다. 부스트 컨트롤을 삭제하려고 하면 오류 메시지에 서빙 구성의 이름이 표시됩니다. 그러면 해당 서빙 구성을 삭제하거나 서빙 구성에서 해당 컨트롤을 분리해야 합니다.
REST
부스트 컨트롤을 삭제하려면 다음 단계를 따르세요.
앱 ID를 찾습니다. 앱 ID를 이미 알고 있는 경우 다음 단계로 건너뜁니다.
Google Cloud 콘솔에서 AI 애플리케이션 페이지로 이동합니다.
앱 페이지에서 앱 이름을 찾고 ID 열에서 앱 ID를 가져옵니다.
engines.servingConfigs.get메서드를 사용하여 삭제하려는 부스트 컨트롤의 ID를 찾습니다. ID를 이미 알고 있는 경우 다음 단계로 건너뜁니다.curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls"다음을 바꿉니다.
PROJECT_ID: Google Cloud 프로젝트의 ID입니다.APP_ID: Vertex AI Search 앱의 ID입니다.
출력을 검토합니다. 서빙 구성에 연결된 부스트 컨트롤이 있는 경우 서빙 구성을 업데이트하여 삭제하려는 컨트롤을 삭제합니다. 서빙 구성을 업데이트하여 부스트 컨트롤 삭제를 참조하세요.
다음 curl 명령어를 실행하여 부스트 컨트롤을 삭제합니다.
curl -X DELETE \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls/CONTROL_ID"다음을 바꿉니다.
PROJECT_ID: Google Cloud 프로젝트의 ID입니다.APP_ID: Vertex AI Search 앱의 ID입니다.CONTROL_ID: 삭제하려는 부스트 컨트롤의 고유 식별자입니다. 2단계에서GET명령어로 출력된name필드의 마지막 부분입니다.
하나 이상의 서빙 구성에서 현재 컨트롤을 참조하고 있다는 오류 메시지가 표시되면 서빙 구성을 업데이트하여 부스트 컨트롤 삭제를 참조하세요.
서빙 구성을 업데이트하여 부스트 컨트롤 삭제
부스트 컨트롤을 삭제하려면 먼저 모든 서빙 컨트롤에서 분리해야 합니다. 서빙 컨트롤을 패치하여 부스트 컨트롤의 ID를 삭제합니다.
서빙 구성에서 부스트 컨트롤을 분리하려면 다음 단계를 따르세요.
engines.servingConfigs.get요청을 전송하고 응답의boostControlIds필드를 확인하여 서빙 구성에 연결된 부스트 컨트롤을 살펴봅니다.curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/CONFIG_ID"다음을 바꿉니다.
PROJECT_ID: Google Cloud 프로젝트의 ID입니다.APP_ID: Vertex AI Search 앱의 ID입니다.CONFIG_ID: 자세히 알아보고자 하는 서빙 구성의 ID입니다.
서빙 구성을 업데이트하여 부스트 컨트롤 하나를 삭제하려면
engines.servingConfigs.patch메서드를 사용합니다.curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/CONFIG_ID?update_mask=boost_control_ids" \ -d '{ "boostControlIds": ["CONTROL_ID"] }'다음을 바꿉니다.
CONFIG_ID: 부스트 컨트롤을 연결하려는 서빙 구성의 ID입니다(예:my_app-1234567_id). 이전 단계를 참조하세요.CONTROL_ID: 서빙 구성에 포함할 하나 이상의 부스트 컨트롤 ID를 포함합니다. 삭제하려는 부스트 컨트롤은 생략해야 합니다. 문자열 배열입니다. ID가 두 개 이상인 경우 구분 따옴표와 쉼표를 사용해야 합니다(예:boost-1", "boost-2).