VertexRanker로 검색 결과 재순위 지정

이전의 벡터 검색 2.0인 에이전트 검색은 순위 지정 API를 기반으로 하는 시맨틱 재순위 지정을 위한 VertexRanker를 제공합니다.

에이전트 검색이 후보 결과를 검색하고 융합한 후(상호 순위 융합 (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. 각 모델에 관한 자세한 내용은 순위 지정 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보다 작거나 같고 1000보다 작거나 같아야 합니다.

다음 예에서는 요청의 본문을 보여줍니다.

{
  "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일 기간당 순위 지정 사용량의 무료 허용량이 제공됩니다. 이 허용량 내에서 사용하면 비용이 발생하지 않습니다. 이 허용량을 초과하는 사용량에 대해서는 소비자 프로젝트에 표준 순위 지정 API 가격 이 적용됩니다.

다음 표에는 할당량 값이 나와 있습니다.

항목 값
무료 등급 허용량 소비자 프로젝트당 30일 기간당 80,000개의 순위 지정 단위
초과분 소비자 프로젝트에서 표준 순위 지정 API 가격으로 청구됩니다.
재순위 지정 호출당 최대 레코드 수 1000 (top_n은 [1, 1000] 범위에 있어야 하며 top_k <= top_n이어야 함)

무료 등급 허용량에 도달해도 요청이 실패하지는 않습니다. 80,000개의 순위 지정 단위 허용량이 소진된 후에도 후속 VertexRanker 사용은 계속 성공하며 초과분으로 청구됩니다. 허용량은 첫 사용 시점으로부터 30일 후에 재설정됩니다.

순위 지정 단위는 독립형 순위 지정 API와 동일한 회계를 사용하여 순위 지정자로 전송된 레코드 수 와 제목 및 콘텐츠 템플릿의 크기로부터 계산됩니다. 자세한 내용은 순위 지정 API 가격 을 참고하세요.

VertexRanker를 사용하려면 소비자 프로젝트에서 Discovery Engine을 사용 설정해야 합니다. 자세한 내용은 실패 조건을 참고하세요.

실패 처리 및 경고

VertexRanker는 최선의 방식으로 재순위 지정을 시도합니다. 순위 지정 호출이 실패하더라도 BatchSearchDataObjects RPC는 계속 성공하고 RRF 융합 결과를 top_k로 자릅니다. 실패는 응답의 search_response_metadata.warnings 필드에 보고됩니다. 순위 지정 API의 전체 상태 코드가 유지됩니다. 예상치 못한 상태의 경고 코드는 UNAVAILABLE 경고 메시지가 "Reranking is temporarily unavailable. Returning fused (RRF) results without semantic reranking."입니다.

실패 조건

다음과 같은 경우 전체 BatchSearchDataObjects RPC가 FAILED_PRECONDITION(RRF로 대체되지 않음)으로 실패합니다.

  • Discovery Engine API가 사용 설정되지 않음 : 순위 지정 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 소비자 프로젝트에서 순위 지정 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을 반환했거나 유지되지 않는 코드 (예: INTERNAL)를 반환하여 UNAVAILABLE로 축소되었습니다. 기본 코드가 UNAVAILABLE인 경우: "RankService.Rank call failed for consumer project...

그 외의 경우: "Reranking is temporarily unavailable. Returning fused (RRF) results without semantic reranking."
FAILED_PRECONDITION 순위 지정 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>