Agent Retrieval (in precedenza Vector Search 2.0) fornisce VertexRanker per il reranking semantico, basato sull'API Ranking.
Dopo che Agent Retrieval ha recuperato e unito i risultati candidati (utilizzando Reciprocal Rank Fusion (RRF)), VertexRanker ricalcola il punteggio dei candidati uniti in base alla query in linguaggio naturale utilizzando un modello semantico dedicato.
In questo modo, la pertinenza dei risultati top-k migliora, soprattutto per le query in cui la ricerca da sola non coglie le sfumature. Il reranking avviene lato server con chiamate a BatchSearchDataObjects. Non sono necessari ulteriori collegamenti lato client o round trip aggiuntivi.
VertexRanker
VertexRanker è configurato come reranker per il campo combine.ranker dell'oggetto BatchSearchDataObjectsRequest. Devi configurare un ranker principale (è supportato solo RRF). Il reranker viene eseguito dopo il passaggio di fusione RRF e sostituisce l'output con l'elenco con un nuovo punteggio semantico.
La tabella seguente elenca i campi di configurazione del ranker.
| Campo | Obbligatorio | Descrizione |
|---|---|---|
combine.ranker.rrf.weights |
Sì | I pesi per la fusione RRF dei risultati di ricerca sottostanti. |
combine.ranker.vertex_ranker.model |
Sì | Il nome del modello di ranking. Valori supportati: semantic-ranker-fast@latest, semantic-ranker-default@latest, semantic-ranker-fast-004, semantic-ranker-default-004. Per informazioni dettagliate su ciascun modello, consulta Modelli dell'API Ranking. |
combine.ranker.vertex_ranker.top_n |
Sì | Il numero massimo di candidati dell'elenco unito da inviare al ranker. I valori validi sono compresi tra 1 e 1000. |
combine.ranker.vertex_ranker.text_record_spec.query |
Sì | La query in linguaggio naturale utilizzata dal ranker per assegnare un punteggio ai record. |
combine.ranker.vertex_ranker.text_record_spec.title_template |
Sì | La stringa del modello, ad esempio {title}, che specifica come estrarre (costruire) il titolo per ogni record. Utilizza i percorsi con punti per specificare i campi di dati. |
combine.ranker.vertex_ranker.text_record_spec.content_template |
Sì | La stringa del modello, ad esempio {body.text}, che specifica come estrarre (costruire) i contenuti principali per ogni record. Utilizza i percorsi con punti per specificare i campi di dati. |
combine.top_k |
Facoltativo | Il numero finale di risultati da restituire dopo il reranking. Il valore deve essere minore o uguale a vertex_ranker.top_n e minore o uguale a 1000. |
L'esempio seguente mostra il corpo di una richiesta.
{
"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}"
}
}
}
}
}
I modelli utilizzano i percorsi con punti per i campi di dati dell'oggetto dati, ad esempio {title}
o {nested.field}. Questi campi devono esistere nello schema della raccolta, altrimenti la richiesta viene rifiutata durante la convalida. Se in un oggetto dati manca il campo fornito, il server recupera in modo trasparente il record completo dallo spazio di archiviazione in modo che il modello possa comunque essere compilato.
Quota e prezzi
VertexRanker su Agent Retrieval utilizza un'allocazione del Livello senza costi con fatturazione per eccedenza basata sull'utilizzo. Ogni progetto riceve un'allocazione senza costi per l'utilizzo del ranking per un periodo di 30 giorni. L'utilizzo entro questa allocazione non comporta costi. Al progetto consumer vengono applicati i prezzi standard dell'API Ranking per qualsiasi utilizzo oltre questa soglia.
La tabella seguente elenca i valori delle quote.
| Elemento | Valore |
|---|---|
| Assegnazione del livello senza costi | 80.000 unità di ranking per progetto consumer per un periodo di 30 giorni. |
| Eccedenza | Fatturato in base ai prezzi standard dell'API Ranking sul progetto consumer. |
| Numero massimo di record per chiamata di reranking | 1000 (top_n deve essere compreso tra [1, 1000] e top_k <= top_n). |
Il raggiungimento dell'allocazione del Livello senza costi non comporta l'esito negativo delle richieste. Dopo aver consumato l'allocazione di 80.000 unità di ranking, l'utilizzo successivo di VertexRanker continua ad andare a buon fine e viene fatturato come eccedenza. La quota viene reimpostata 30 giorni dopo il primo utilizzo.
Le unità di ranking vengono calcolate in base al numero di record inviati al ranker e alle dimensioni dei relativi modelli di titolo e contenuto, utilizzando lo stesso conteggio dell'API Ranking autonoma. Per i dettagli completi, consulta i prezzi dell'API Ranking.
Prima di poter utilizzare VertexRanker, Discovery Engine deve essere abilitato nel progetto consumer. Per saperne di più, consulta Condizioni di errore.
Gestione degli errori e avvisi
VertexRanker è un reranker best-effort. Se la chiamata di ranking non va a buon fine, l'RPC BatchSearchDataObjects viene comunque eseguita correttamente e restituisce i risultati fusi con RRF troncati a top_k. L'errore viene segnalato nel campo search_response_metadata.warnings della risposta. Il codice di stato completo dell'API Ranking viene conservato. Il codice di avviso per gli stati imprevisti è UNAVAILABLE con il messaggio di avviso: "Reranking is temporarily unavailable. Returning fused (RRF) results without
semantic reranking."
Condizioni di errore
L'intera RPC BatchSearchDataObjects non riesce con FAILED_PRECONDITION
(nessun fallback a RRF) nei seguenti casi.
- API Discovery Engine non abilitata: l'API Ranking restituisce
FAILED_PRECONDITIONcon il messaggioDiscovery Engine API is not enabled for the consumer project /<N/>. Please enable the API and try again."Correzione: abilita l'API Discovery Engine nel progetto consumer.
Il cliente deve attivare Discovery Engine per il progetto consumer affinché venga eseguito il reranking.
La tabella seguente elenca i codici di avviso, le cause tipiche che li generano e il messaggio che spiega l'avviso.
| Warning Code | Causa tipica | Messaggio di avviso |
|---|---|---|
RESOURCE_EXHAUSTED |
È stata superata una quota dell'API Ranking nel progetto consumer. Nota: il superamento della quota di 80.000 unità di ranking non causa questo avviso; l'eccedenza viene invece fatturata. | <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 non è stato completato entro la scadenza della richiesta. |
<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 ha restituito UNAVAILABLE o un codice non conservato (ad esempio INTERNAL) che viene compresso in UNAVAILABLE. |
Se il codice sottostante è UNAVAILABLE: "RankService.Rank call failed for consumer project... Altrimenti: "Reranking is temporarily unavailable. Returning fused (RRF) results without semantic reranking." |
FAILED_PRECONDITION |
Qualsiasi FAILED_PRECONDITION restituito dall'API Ranking. |
RankService.Rank call failed for consumer project <N> with request query: <query> and <model>: semantic-ranker-fast@latest number of records: <N> |
CANCELLED |
Il chiamante ha annullato l'RPC BatchSearchDataObjects prima del completamento del reranking. |
<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> |