이 페이지에서는 게재 컨트롤 (컨트롤이라고도 함)을 사용하여 모델에서 반환된 미디어 추천의 순위 위치를 변경하는 방법을 설명합니다.
부스트 제어는 모델에서 추천을 반환한 후 추천 순서를 변경합니다. 결과에 필터 표현식을 적용하여 추천을 올리거나 내릴 추천을 식별한 다음 -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 콘솔에서 Agent Builder 페이지로 이동합니다.
앱 페이지에서 앱 이름을 찾고 ID 열에서 앱 ID를 가져옵니다.
데이터 스토어 ID를 찾습니다. 데이터 스토어 ID가 이미 있는 경우 다음 단계로 건너뜁니다.
Google Cloud 콘솔에서 Agent Builder 페이지로 이동하고 탐색 메뉴에서 데이터 스토어를 클릭합니다.
데이터 스토어 이름을 클릭합니다.
데이터 스토어의 데이터 페이지에서 데이터 스토어 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 콘솔에서 Agent Builder 페이지로 이동합니다.
앱 페이지에서 앱 이름을 클릭합니다.
구성 페이지로 이동하여 서빙 탭을 클릭합니다.
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가 2개 이상인 경우 구분 따옴표와 쉼표를 사용해야 합니다.
결과가 적용될 때까지 몇 분 정도 기다립니다.
부스트 제어의 효과를 미리 봅니다. 미디어 추천 가져오기를 참고하세요.
부스트 컨트롤 업데이트
이 절차에서는 기존 부스트 컨트롤을 업데이트하여 부스트 또는 필터의 값을 변경하는 방법을 설명합니다.
부스트 제어를 테스트한 후 부스트를 더 강하게 또는 더 약하게 설정해야 할 수도 있습니다. 또는 필터 문자열을 변경할 수 있습니다.
최적화 값 또는 필터를 업데이트할 때는 engines.controls.patch 메서드를 호출합니다.
패치 메서드는 boost 및 filter 값을 제공된 새 값으로 바꿉니다. 이 절차에서는 boost 값 (3단계)과 filter 값 (4단계)을 별도로 수정하는 방법을 보여줍니다. 하지만 둘 다 수정하려면 단일 curl 명령어로 실행하면 됩니다.
REST
기존 컨트롤의 필터 부스트 값을 수정하려면 다음 단계를 따르세요.
앱 ID를 찾습니다. 앱 ID를 이미 알고 있는 경우 다음 단계로 건너뜁니다.
Google Cloud 콘솔에서 Agent Builder 페이지로 이동합니다.
앱 페이지에서 앱 이름을 찾고 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 콘솔에서 Agent Builder 페이지로 이동합니다.
앱 페이지에서 앱 이름을 찾고 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).