에이전트 검색(이전의 벡터 검색 2.0)은 시맨틱 순위 조정을 위해 VertexRanker를 제공하며, 이는 Ranking API를 기반으로 합니다.
에이전트 검색이 Reciprocal Rank Fusion(RRF)을 사용하여 후보 결과를 검색하고 융합한 후 VertexRanker는 전용 시맨틱 모델을 사용하여 자연어 쿼리에 대해 병합된 후보의 점수를 다시 매깁니다.
이렇게 하면 특히 검색만으로는 뉘앙스를 놓치는 검색어의 경우 상위 k개 결과의 관련성이 향상됩니다. 재순위 지정은 BatchSearchDataObjects 호출을 통해 서버 측에서 발생합니다. 추가 클라이언트 측 연결이나 추가 왕복이 필요하지 않습니다.
VertexRanker
VertexRanker는 BatchSearchDataObjectsRequest 객체의 combine.ranker 필드에 대한 재랭커로 구성됩니다. 기본 순위 지정 도구를 구성해야 합니다(RRF만 지원됨). 리랭커는 RRF 융합 단계 후에 실행되며 출력을 시맨틱 점수가 다시 매겨진 목록으로 바꿉니다.
다음 표에는 순위 지정 도구 구성 필드가 나와 있습니다.
| 필드 | 필수 | 설명 |
|---|---|---|
combine.ranker.rrf.weights |
예 | 기본 검색 결과의 RRF 융합 가중치입니다. |
combine.ranker.vertex_ranker.model |
예 | 순위 모델 이름입니다. 지원되는 값: semantic-ranker-fast@latest, semantic-ranker-default@latest, semantic-ranker-fast-004, semantic-ranker-default-004 각 모델에 대한 자세한 내용은 Ranking API 모델을 참조하세요. |
combine.ranker.vertex_ranker.top_n |
예 | 순위 지정 도구로 전송할 병합된 목록의 최대 후보 수입니다. 유효한 값은 1부터 1000까지입니다. |
combine.ranker.vertex_ranker.text_record_spec.query |
예 | 순위 지정 도구에서 레코드 점수를 매기는 데 사용하는 자연어 쿼리입니다. |
combine.ranker.vertex_ranker.text_record_spec.title_template |
예 | 각 레코드의 제목을 추출(구성)하는 방법을 지정하는 템플릿 문자열입니다(예: {title}). 점 경로를 사용하여 데이터 필드를 지정합니다. |
combine.ranker.vertex_ranker.text_record_spec.content_template |
예 | 각 레코드의 기본 콘텐츠를 추출(구성)하는 방법을 지정하는 템플릿 문자열(예: {body.text})입니다. 점 경로를 사용하여 데이터 필드를 지정합니다. |
combine.top_k |
선택사항 | 순위 재지정 후 반환할 최종 결과 수입니다. vertex_ranker.top_n 이하여야 하며 1,000 이하여야 합니다. |
다음 예시는 요청 본문을 보여줍니다.
{
"searches": [
{ "semantic_search": { "search_text": "running shoes", "search_field": "embedding", "task_type": "RETRIEVAL_QUERY", "top_k": 50 } },
{ "text_search": { "search_text": "running shoes", "data_field_names": ["title"], "top_k": 50 } }
],
"combine": {
"top_k": 10,
"ranker": {
"rrf": { "weights": [1.0, 1.0] },
"vertex_ranker": {
"model": "semantic-ranker-fast@latest",
"top_n": 50,
"text_record_spec": {
"query": "running shoes",
"title_template": "{title}",
"content_template": "{body.text}"
}
}
}
}
}
템플릿은 데이터 객체 데이터 필드에 대한 점 경로를 사용합니다(예: {title} 또는 {nested.field}). 이러한 필드는 컬렉션 스키마에 있어야 합니다. 그렇지 않으면 검증 중에 요청이 거부됩니다. 데이터 객체에 제공된 필드가 누락된 경우 서버는 스토리지에서 전체 레코드를 투명하게 다시 가져와 템플릿을 채울 수 있습니다.
할당량 및 요금
에이전트 검색의 VertexRanker는 사용량 기반 초과분 청구와 함께 무료 등급 허용량을 사용합니다. 각 프로젝트에는 30일마다 무료 순위 사용량이 제공됩니다. 이 허용량 내에서 사용하면 비용이 발생하지 않습니다. 이 허용량을 초과하는 사용량에는 소비자 프로젝트에 표준 Ranking API 가격 책정이 적용됩니다.
다음 표에는 할당량 값이 나와 있습니다.
| 항목 | 값 |
|---|---|
| 무료 등급 허용량 | 소비자 프로젝트별 30일 기간당 순위 단위 80,000개 |
| 초과분 | 소비자 프로젝트의 표준 Ranking API 가격으로 청구됩니다. |
| 재순위 지정 호출당 최대 레코드 수 | 1000(top_n는 [1, 1000] 및 top_k <= top_n 범위 내에 있어야 함) |
무료 등급 한도에 도달해도 요청이 실패하지 않습니다. 80,000 순위 단위 허용량이 소진되면 후속 VertexRanker 사용량은 계속 성공하고 초과분으로 청구됩니다. 허용량은 처음 사용한 시점으로부터 30일 후에 재설정됩니다.
순위 단위는 순위 지정 도구로 전송된 레코드 수와 제목 및 콘텐츠 템플릿의 크기에서 계산되며, 독립형 Ranking API와 동일한 계산을 사용합니다. 자세한 내용은 Ranking API 가격 책정을 참조하세요.
VertexRanker를 사용하려면 먼저 소비자 프로젝트에서 Discovery Engine을 사용 설정해야 합니다. 자세한 내용은 실패 조건을 참조하세요.
실패 처리 및 경고
VertexRanker는 최선의 노력을 다하는 재순위 지정 도구입니다. 순위 호출이 실패하더라도 BatchSearchDataObjects RPC는 계속 성공하고 top_k로 잘린 RRF 융합 결과를 반환합니다. 실패는 응답의 search_response_metadata.warnings 필드에 보고됩니다. Ranking API의 전체 상태 코드가 보존됩니다. 예상치 못한 상태의 경고 코드는 UNAVAILABLE이며 경고 메시지는 "Reranking is temporarily unavailable. Returning fused (RRF) results without
semantic reranking."입니다.
실패 조건
다음과 같은 경우 전체 BatchSearchDataObjects RPC가 FAILED_PRECONDITION로 실패합니다(RRF로 대체되지 않음).
- Discovery Engine API가 사용 설정되지 않음 — Ranking API가
FAILED_PRECONDITION를 반환하고Discovery Engine API is not enabled for the consumer project /<N/>. Please enable the API and try again."메시지가 표시됩니다. 해결 방법: 소비자 프로젝트에서 Discovery Engine API를 사용 설정합니다.
재순위 지정을 수행하려면 고객이 소비자 프로젝트에 대해 Discovery Engine을 사용 설정해야 합니다.
다음 표에는 경고 코드, 경고를 생성하는 일반적인 원인, 경고를 설명하는 메시지가 나와 있습니다.
| 경고 코드 | 일반적인 원인 | 경고 메시지 |
|---|---|---|
RESOURCE_EXHAUSTED |
소비자 프로젝트에서 Ranking API 할당량을 초과했습니다. 참고: 순위 단위 허용량 80,000개를 초과해도 이 경고가 표시되지 않으며 초과분은 청구됩니다. | <Quota exceeded message>; RankService.Rank call failed for consumer project <N> with request query: <query> and <model>: semantic-ranker-fast@latest number of records: <N> |
DEADLINE_EXCEEDED |
Ranker.Rank이 요청 기한 내에 완료되지 않았습니다. |
<deadline-exceeded message from Ranker.Rank>; RankService.Rank call failed for consumer project <N> with request query: <query> and <model>: semantic-ranker-fast@latest number of records: <N> |
UNAVAILABLE |
Ranker.Rank가 UNAVAILABLE를 반환했거나 UNAVAILABLE로 축소된 보존되지 않은 코드(예: INTERNAL)를 반환했습니다. |
기본 코드가 UNAVAILABLE인 경우: "RankService.Rank call failed for consumer project... 그렇지 않은 경우: "Reranking is temporarily unavailable. Returning fused (RRF) results without semantic reranking." |
FAILED_PRECONDITION |
Ranking API에서 반환된 모든 FAILED_PRECONDITION입니다. |
RankService.Rank call failed for consumer project <N> with request query: <query> and <model>: semantic-ranker-fast@latest number of records: <N> |
CANCELLED |
재순위 지정이 완료되기 전에 호출자가 BatchSearchDataObjects RPC를 취소했습니다. |
<cancellation message from the cancelled RankService.Rank RPC>; RankService.Rank call failed for consumer project <N> with request query: <query> and <model>: semantic-ranker-fast@latest number of records: <N> |