Riorganizzare i risultati di ricerca con VertexRanker

Agent Retrieval (in precedenza Vector Search 2.0) fornisce VertexRanker per la riclassificazione semantica, che è basata sull'API Ranking.

Dopo che Agent Retrieval recupera e unisce i risultati candidati (utilizzando Reciprocal Rank Fusion (RRF)), VertexRanker ricalcola i 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. La riclassificazione avviene lato server con chiamate a BatchSearchDataObjects. Non sono necessari collegamenti aggiuntivi lato client o round trip aggiuntivi.

VertexRanker

VertexRanker è configurato come riclassificatore per il campo combine.ranker dell'oggetto BatchSearchDataObjectsRequest. Devi configurare un classificatore principale (è supportato solo RRF). Il riclassificatore viene eseguito dopo il passaggio di unione RRF e sostituisce l'output con l'elenco riclassificato semanticamente.

La tabella seguente elenca i campi di configurazione del classificatore.

Campo Obbligatorio Descrizione
combine.ranker.rrf.weights Sì I pesi per l'unione RRF dei risultati di ricerca sottostanti.
combine.ranker.vertex_ranker.model Sì Il nome del modello di classificazione. Valori supportati: semantic-ranker-fast@latest, semantic-ranker-default@latest, semantic-ranker-fast-004, semantic-ranker-default-004. Per i dettagli su ciascuno, consulta i modelli dell'API Ranking.
combine.ranker.vertex_ranker.top_n Sì Il numero massimo di candidati dall'elenco unito da inviare al classificatore. I valori validi vanno da 1 a 1000.
combine.ranker.vertex_ranker.text_record_spec.query Sì La query in linguaggio naturale utilizzata dal classificatore 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 dati.
combine.ranker.vertex_ranker.text_record_spec.content_template Sì La stringa del modello, ad esempio {body.text}, che specifica come estrarre (costruire) il contenuto principale per ogni record. Utilizza i percorsi con punti per specificare i campi dati.
combine.top_k Facoltativo Il numero finale di risultati da restituire dopo la riclassificazione. Questo 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 percorsi con punti per i campi 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 a 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 in Agent Retrieval utilizza un livello senza costi con fatturazione dell'eccedenza basata sull'utilizzo. Ogni progetto riceve una quota senza costi di utilizzo della classificazione per un periodo di 30 giorni. L'utilizzo entro questa quota non comporta costi. Al progetto consumer vengono applicati i prezzi standard dell'API Ranking per qualsiasi utilizzo oltre questa quota.

La tabella seguente elenca i valori di quota.

Elemento Valore
Quota del livello senza costi 80.000 unità di classificazione per progetto consumer per un periodo di 30 giorni.
Eccedenza Fatturata in base ai prezzi standard dell'API Ranking sul progetto consumer.
Numero massimo di record per chiamata di riclassificazione 1000 (top_n deve essere nell'intervallo [1, 1000] e top_k <= top_n).

Il raggiungimento della quota del livello senza costi non comporta l'esito negativo delle richieste. Dopo aver consumato la quota di 80.000 unità di classificazione, l'utilizzo successivo di VertexRanker continua ad avere esito positivo e viene fatturato come eccedenza. La quota viene reimpostata 30 giorni dopo il primo utilizzo.

Le unità di classificazione vengono calcolate in base al numero di record inviati al classificatore e alle dimensioni dei relativi modelli di titolo e contenuti, utilizzando la stessa contabilità dell'API Ranking autonoma. Per tutti i dettagli, consulta i prezzi dell'API Ranking.

Prima di poter utilizzare VertexRanker, devi abilitare Discovery Engine nel progetto consumer. Per ulteriori informazioni, consulta le condizioni di errore.

Gestione degli errori e avvisi

VertexRanker è un riclassificatore "best effort". Se la chiamata di classificazione non riesce, l'RPC BatchSearchDataObjects ha comunque esito positivo e restituisce i risultati uniti 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 mantenuto. 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'intero RPC BatchSearchDataObjects non riesce con FAILED_PRECONDITION (nessun fallback a RRF) nei seguenti casi.

  • API Discovery Engine non abilitata : l'API Ranking restituisce FAILED_PRECONDITION con il messaggio Discovery Engine API is not enabled for the consumer project /<N/>. Please enable the API and try again." Soluzione: abilita l'API Discovery Engine nel progetto consumer.

Il cliente deve abilitare Discovery Engine per il progetto consumer affinché venga eseguita la riclassificazione.

La tabella seguente elenca i codici di avviso, le cause tipiche che generano gli avvisi e il messaggio che spiega l'avviso.

Codice di avviso 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 classificazione non causa questo avviso; viene invece fatturata l'eccedenza. <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 oppure ha restituito 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 della riclassificazione. <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>