Agent Retrieval(旧称: Vector Search 2.0)は、セマンティック再ランキングに VertexRanker を提供します。これは Ranking API を利用しています。
Agent Retrieval が候補結果を取得して融合(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} など)を使用します。これらのフィールドはコレクション スキーマに存在する必要があります。存在しない場合、リクエストは検証中に拒否されます。データ オブジェクトに指定されたフィールドがない場合、サーバーはストレージから完全なレコードを透過的に再取得し、テンプレートにデータを入力できるようにします。
割り当てと料金
Agent Retrieval の VertexRanker は、従量課金制の超過料金が適用される無料枠を使用します。各プロジェクトには、30 日間のランキング使用量の無料枠が割り当てられます。この許容量内の使用量には費用はかかりません。この許容量を超える使用量については、標準の Ranking API の料金がコンシューマ プロジェクトに適用されます。
次の表に、割り当て値を示します。
| 項目 | 値 |
|---|---|
| 無料枠の割り当て | コンシューマ プロジェクトごとに 30 日あたり 80,000 ランキング ユニット。 |
| 超過料金 | コンシューマ プロジェクトの標準の Ranking API 料金で課金されます。 |
| rerank 呼び出しあたりの最大レコード数 | 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 は、
Discovery Engine API is not enabled for the consumer project /<N/>. Please enable the API and try again."というメッセージとともにFAILED_PRECONDITIONを返します。 修正: コンシューマー プロジェクトで 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 を返したか、保持されていないコード(INTERNAL など)を返したため、UNAVAILABLE に折りたたまれています。 |
基になるコードが 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> |