Migliorare la qualità della ricerca e della RAG con l'API di ranking

Nell'ambito dell'esperienza di generazione aumentata dal recupero (RAG) in Agent Search, puoi classificare un insieme di documenti in base a una query.

L'API Ranking accetta un elenco di documenti e li riclassifica in base alla loro pertinenza rispetto a una query. Rispetto agli embedding, che esaminano solo la similarità semantica di un documento e di una query, l'API Ranking può fornire punteggi precisi sull'efficacia con cui un documento risponde a una determinata query. L'API Ranking può essere utilizzata per migliorare la qualità dei risultati di ricerca dopo aver recuperato un insieme iniziale di documenti candidati.

L'API Ranking è senza stato, quindi non è necessario indicizzare i documenti prima di chiamarla. Devi solo passare la query e i documenti. Ciò rende l'API adatta alla riclassificazione dei documenti da Vector Search e altre soluzioni di ricerca.

Questa pagina descrive come utilizzare l'API Ranking per classificare un insieme di documenti in base a una query.

Casi d'uso

Il caso d'uso principale dell'API Ranking è migliorare la qualità dei risultati di ricerca.

Tuttavia, l'API Ranking può essere utile in qualsiasi scenario in cui devi trovare i contenuti più pertinenti per la query di un utente. Ad esempio, l'API Ranking può aiutarti a:

• Trovare i contenuti giusti da fornire a un LLM per la grounding

• Migliorare la pertinenza di un'esperienza di ricerca esistente

• Identificare le sezioni pertinenti di un documento

Il seguente flusso descrive come utilizzare l'API Ranking per migliorare la qualità dei risultati per i documenti suddivisi in blocchi:

1. Utilizza l'API Document AI Layout Parser per suddividere un insieme di documenti in blocchi.

2. Utilizza un'API di embedding per creare embedding per ciascun blocco.

3. Carica gli embedding in Vector Search o in un'altra soluzione di ricerca.

4. Esegui una query sull'indice di ricerca e recupera i blocchi più pertinenti.

5. Riclassifica i blocchi pertinenti utilizzando l'API Ranking.

Dati di input

Termine chiave: l'API Ranking utilizza il termine record per indicare un documento. Un record è composto da un ID, un titolo e il contenuto di un documento. A differenza dei documenti contenuti nei datastore di Agent Search, i record di input dell'API Ranking sono in formato JSON e non sono stati indicizzati da Agent Search.

L'API Ranking richiede i seguenti input:

• La query per cui stai classificando i record.

  Ad esempio:

  "query": "Why is the sky blue?"
  

• Un insieme di record pertinenti alla query. I record vengono forniti come array di oggetti. Ogni record può includere un ID univoco, un titolo e il contenuto del documento. Per ogni record includi un titolo, un contenuto o entrambi. Il numero massimo di token supportati per record dipende dalla versione del modello in uso. Ad esempio, i modelli fino alla versione 003 supportano 512 token, mentre la versione 004 supporta 1024 token. Se la lunghezza combinata del titolo e del contenuto supera il limite di token del modello, il contenuto aggiuntivo viene troncato. Puoi includere fino a 200 record per richiesta.

  Ad esempio, un array di record ha un aspetto simile a questo. In realtà, l'array includerebbe molti più record e il contenuto sarebbe molto più lungo:

  "records": [
     {
         "id": "1",
         "title": "The Color of the Sky: A Poem",
         "content": "A canvas stretched across the day,\nWhere sunlight learns to dance and play.\nBlue, a hue of scattered light,\nA gentle whisper, soft and bright."
     },
     {
         "id": "2",
         "title": "The Science of a Blue Sky",
         "content": "The sky appears blue due to a phenomenon called Rayleigh scattering. Sunlight is comprised of all the colors of the rainbow. Blue light has shorter wavelengths than other colors, and is thus scattered more easily."
     }
  ]
  

• (Facoltativo) Il numero massimo di record che vuoi che l'API Ranking restituisca. Per impostazione predefinita, vengono restituiti tutti i record. Tuttavia, puoi utilizzare il campo topN per restituire meno record. Tutti i record vengono classificati indipendentemente dal valore impostato.

  Ad esempio, questo restituisce i primi 10 record classificati:

  "topN": 10,
  

• (Facoltativo) Un'impostazione che specifica se vuoi che l'API restituisca solo l'ID del record o anche il titolo e il contenuto del record. Per impostazione predefinita, viene restituito il record completo. Il motivo principale per impostare questa opzione è ridurre le dimensioni del payload della risposta.

  Ad esempio, se imposti true, viene restituito solo l'ID del record, non il titolo o il contenuto:

  "ignoreRecordDetailsInResponse": true,
  

• (Facoltativo) Il nome del modello. Specifica il modello da utilizzare per la classificazione dei documenti. Se non viene specificato alcun modello, viene utilizzato semantic-ranker-default@latest, che punta automaticamente all'ultimo modello disponibile. Per puntare a un modello specifico, specifica uno dei nomi dei modelli elencati in Modelli supportati, ad esempio semantic-ranker-512-003.

  Nell'esempio seguente, model è impostato su semantic-ranker-default@latest. Ciò significa che l'API Ranking utilizzerà sempre l'ultimo modello disponibile.

  "model": "semantic-ranker-default@latest"
  

Dati di output

L'API Ranking restituisce un elenco classificato di record con i seguenti output:

• Punteggio: un valore float compreso tra 0 e 1 che indica la pertinenza del record.

• ID: l'ID univoco del record.

• Se richiesto, l'oggetto completo: ID, titolo e contenuto.

  Ad esempio:

{
    "records": [
        {
            "id": "2",
            "score": 0.98,
            "title": "The Science of a Blue Sky",
            "content": "The sky appears blue due to a phenomenon called Rayleigh scattering. Sunlight is comprised of all the colors of the rainbow. Blue light has shorter wavelengths than other colors, and is thus scattered more easily."
        },
        {
            "id": "1",
            "score": 0.64,
            "title": "The Color of the Sky: A Poem",
            "content": "A canvas stretched across the day,\nWhere sunlight learns to dance and play.\nBlue, a hue of scattered light,\nA gentle whisper, soft and bright."
        }
    ]
}

Classificare (o riclassificare) un insieme di record in base a una query

In genere, fornisci all'API Ranking una query e un insieme di record pertinenti a quella query e che sono già stati classificati con un altro metodo, ad esempio una ricerca per parole chiave o una ricerca vettoriale. Poi, utilizzi l'API Ranking per migliorare la qualità della classificazione e determinare un punteggio che indica la pertinenza di ogni record rispetto alla query.

1. Ottieni la query e i record risultanti. Assicurati che ogni record abbia un ID e un titolo, un contenuto o entrambi.

   Il numero massimo di token supportati per record dipende dalla versione del modello. I modelli fino alla versione 003, come semantic-ranker-512-003, supportano 512 token per record. A partire dalla versione 004, questo limite aumenta a 1024 token. Se la lunghezza combinata del titolo e del contenuto supera il limite di token del modello, il contenuto aggiuntivo viene troncato.

2. Chiama il metodo rankingConfigs.rank utilizzando il seguente codice:

REST

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/rankingConfigs/default_ranking_config:rank" \
-d '{
"model": "semantic-ranker-default@latest",
"query": "QUERY",
"records": [
    {
        "id": "RECORD_ID_1",
        "title": "TITLE_1",
        "content": "CONTENT_1"
    },
    {
        "id": "RECORD_ID_2",
        "title": "TITLE_2",
        "content": "CONTENT_2"
    },
    {
        "id": "RECORD_ID_3",
        "title": "TITLE_3",
        "content": "CONTENT_3"
    }
]
}'

Sostituisci quanto segue:

• PROJECT_ID: l'ID del tuo Google Cloud progetto.
• QUERY: la query in base alla quale i record vengono classificati e valutati.
• RECORD_ID_n: una stringa univoca che identifica il record.
• TITLE_n: il titolo del record.
• CONTENT_n: il contenuto del record.

Nota: puoi testare l'API digitando i tuoi valori in questi segnaposto e incollando il comando in Cloud Shell. Tuttavia, in realtà, l'array records sarebbe più grande.

Per informazioni generali su questo metodo, consulta rankingConfigs.rank.

Fai clic per visualizzare un esempio di comando curl e risposta.

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: my-project-123" \
    "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/rankingConfigs/default_ranking_config:rank" \
    -d '{
        "model": "semantic-ranker-default@latest",
        "query": "what is Google gemini?",
        "records": [
            {
                "id": "1",
                "title": "Gemini",
                "content": "The Gemini zodiac symbol often depicts two figures standing side-by-side."
            },
            {
                "id": "2",
                "title": "Gemini",
                "content": "Gemini is a cutting edge large language model created by Google."
            },
            {
                "id": "3",
                "title": "Gemini Constellation",
                "content": "Gemini is a constellation that can be seen in the night sky."
            }
        ]
    }'
    

{
    "records": [
        {
            "id": "2",
            "title": "Gemini",
            "content": "Gemini is a cutting edge large language model created by Google.",
            "score": 0.97
        },
        {
            "id": "3",
            "title": "Gemini Constellation",
            "content": "Gemini is a constellation that can be seen in the night sky.",
            "score": 0.18
        },
        {
            "id": "1",
            "title": "Gemini",
            "content": "The Gemini zodiac symbol often depicts two figures standing side-by-side.",
            "score": 0.05
        }
    ]
}

Python

Per saperne di più, consulta la documentazione di riferimento dell' API Python di Agent Search.

Per eseguire l'autenticazione in Agent Search, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"

client = discoveryengine.RankServiceClient()

# The full resource name of the ranking config.
# Format: projects/{project_id}/locations/{location}/rankingConfigs/default_ranking_config
ranking_config = client.ranking_config_path(
    project=project_id,
    location="global",
    ranking_config="default_ranking_config",
)
request = discoveryengine.RankRequest(
    ranking_config=ranking_config,
    model="semantic-ranker-default@latest",
    top_n=10,
    query="What is Google Gemini?",
    records=[
        discoveryengine.RankingRecord(
            id="1",
            title="Gemini",
            content="The Gemini zodiac symbol often depicts two figures standing side-by-side.",
        ),
        discoveryengine.RankingRecord(
            id="2",
            title="Gemini",
            content="Gemini is a cutting edge large language model created by Google.",
        ),
        discoveryengine.RankingRecord(
            id="3",
            title="Gemini Constellation",
            content="Gemini is a constellation that can be seen in the night sky.",
        ),
    ],
)

response = client.rank(request=request)

# Handle the response
print(response)

Per visualizzare un esempio di API Ranking, esegui il notebook "Ranking API Beir evaluation" in uno dei seguenti ambienti:

Apri in Colab | Visualizza su GitHub

Modelli supportati

Sono disponibili i seguenti modelli.

Nome modello	Ultimo modello predefinito (semantic-ranker-default@latest)	Ultimo modello veloce (semantic-ranker-fast@latest)	Input	Finestra contestuale	Data di uscita	Data di interruzione
semantic-ranker-default-004	Sì	No	Testo (25 lingue)	1024	9 aprile 2025	Da stabilire
semantic-ranker-fast-004	No	Sì	Testo (25 lingue)	1024	9 aprile 2025	Da stabilire
semantic-ranker-default-003	No	No	Testo (25 lingue)	512	10 settembre 2024	Da stabilire
semantic-ranker-default-002	No	No	Testo (solo in inglese)	512	3 giugno 2024	Da stabilire

Passaggi successivi

Scopri come utilizzare il metodo di classificazione con altre API RAG per generare risposte basate su dati non strutturati.