Questa pagina è stata tradotta dall'API Cloud Translation.

Valutare la qualità della ricerca

Nell'ambito della tua esperienza di ricerca con Vertex AI Search, puoi valutare la qualità dei risultati di ricerca per le app di ricerca generica utilizzando insiemi di query di esempio.

Puoi valutare il rendimento di app di ricerca generiche che contengono dati strutturati, non strutturati e di siti web. Non puoi valutare il rendimento delle app con più datastore.

Questa pagina spiega perché, quando e come valutare la qualità della ricerca utilizzando il metodo di valutazione.

Panoramica

Questa sezione descrive perché e quando eseguire la valutazione della qualità della ricerca. Per informazioni su come eseguire la valutazione della qualità della Ricerca, consulta la procedura per la valutazione della qualità della Ricerca.

Motivi per eseguire la valutazione

La valutazione della qualità della ricerca fornisce metriche che ti aiutano a svolgere attività come:

A livello aggregato, valuta il rendimento del tuo motore di ricerca
A livello di query, individua i pattern per comprendere potenziali bias o carenze negli algoritmi di ranking
Confrontare i risultati delle valutazioni storiche per comprendere l'impatto delle modifiche alla configurazione della ricerca

Per un elenco delle metriche, consulta Interpretazione dei risultati.

Quando eseguire la valutazione

Vertex AI Search estende diverse configurazioni di ricerca per migliorare la tua esperienza di ricerca. Puoi eseguire la valutazione della qualità della ricerca dopo aver apportato le seguenti modifiche:

Puoi anche eseguire regolarmente i test di valutazione perché il comportamento di ricerca viene aggiornato periodicamente.

Informazioni sugli insiemi di query di esempio

Gli insiemi di query di esempio vengono utilizzati per la valutazione della qualità. L'insieme di query di esempio deve essere conforme al formato prescritto e deve contenere voci di query con i seguenti campi nidificati:

Query: la query i cui risultati di ricerca vengono utilizzati per generare le metriche di valutazione e determinare la qualità della ricerca. Google consiglia di utilizzare una serie diversificata di query che rifletta il comportamento e il pattern di ricerca degli utenti.
Target: l'URI del documento previsto come risultato di ricerca della query di esempio. Per comprendere la definizione di documento per le app di ricerca di siti web, strutturati e non strutturati, consulta Documenti.

Quando i documenti target vengono confrontati con i documenti recuperati nella risposta alla ricerca, vengono generate le metriche sul rendimento. Le metriche vengono generate utilizzando queste due tecniche:
- Corrispondenza dei documenti: gli URI dei documenti di destinazione vengono confrontati con gli URI dei documenti recuperati. Questo determina se i documenti previsti sono presenti nei risultati di ricerca. Durante il confronto, l'API di valutazione tenta di estrarre i seguenti campi nell'ordine seguente e utilizza il primo valore disponibile per abbinare il target al documento recuperato:
  - cdoc_url nel campo structData della definizione del documento
  - uri nel campo structData della definizione del documento
  - link nel campo derivedStructData della definizione del documento
  - url nel campo derivedStructData della definizione del documento
- Corrispondenza delle pagine: quando includi i numeri di pagina nei target di esempio, l'API di valutazione confronta i risultati a livello di pagina. Questo determina se le pagine menzionate nei target sono citate anche nella risposta di ricerca. Per attivare la corrispondenza a livello di pagina, devi attivare le risposte estrattive. L'API di valutazione abbina la pagina della prima risposta estratta nel risultato di ricerca.

Scopo degli insiemi di query di esempio

L'utilizzo dello stesso insieme di query di esempio per tutte le valutazioni della qualità della ricerca per un determinato datastore garantisce un modo coerente e affidabile per misurare i risultati della qualità della ricerca. Viene inoltre stabilito un sistema equo e ripetibile.

I risultati di ogni valutazione vengono confrontati con i risultati target per ogni query di esempio per calcolare metriche diverse, come il recupero, la precisione e il guadagno cumulativo scontato normalizzato (NDCG). Queste metriche quantitative vengono utilizzate per classificare i risultati di diverse configurazioni di ricerca.

Quote e limiti

Ai set di query di esempio si applica il seguente limite:

Ogni insieme di query di esempio può contenere un massimo di 20.000 query.

La seguente quota si applica agli insiemi di query di esempio:

Puoi creare un massimo di 100 set di query di esempio per progetto e 500 set di query di esempio per organizzazione.

Per ulteriori informazioni, consulta Quote e limiti.

Formato dell'insieme di query di esempio

Il set di query deve essere conforme allo schema riportato di seguito quando viene costituito in formato JSON. L'insieme di query può contenere più voci di query con una query in ogni voce. Se presentato in formato JSON delimitato da nuova riga (NDJSON), ogni voce della query deve trovarsi su una nuova riga.

Importa da BigQuery e Cloud Storage

La sezione seguente fornisce i modelli di set di query di esempio per l'importazione da BigQuery e Cloud Storage.

Dati non strutturati

Utilizza il seguente modello per creare la bozza di un file di query di esempio in formato JSON per valutare i dati non strutturati con metadati.

{
  "queryEntry": {
    "query": "SAMPLE_QUERY",
    "targets": [
      {
        "uri": "gs://PATH/TO/CLOUD/STORAGE/LOCATION_1.docx"
      },
      {
        "uri": "gs://PATH/TO/CLOUD/STORAGE/LOCATION_2.pdf",
        "pageNumbers": [
        PAGE_NUMBER_1,
        PAGE_NUMBER_2
        ]
      },
      {
        "uri": "CDOC_URL"
      }
    ]
  }
}

Sostituisci quanto segue:

SAMPLE_QUERY: la query utilizzata per valutare la qualità della ricerca
PATH/TO/CLOUD/STORAGE/LOCATION: il percorso della posizione Cloud Storage in cui si trova il risultato previsto. Si tratta del valore del campo link nel campo derivedStructData della definizione del documento.
PAGE_NUMBER_1: un campo facoltativo per indicare i numeri di pagina nel file PDF in cui si trova la risposta prevista per la query. Questa opzione è utile quando il file ha più pagine.
CDOC_URL: un campo facoltativo per indicare il campo ID documento personalizzato cdoc_url nei metadati del documento nello schema dell'datastore di Vertex AI Search.

Dati strutturati

Utilizza il seguente modello per creare la bozza di un file di query di esempio in formato JSON per valutare i dati strutturati di BigQuery.

{
  "queryEntry": {
    "query": "SAMPLE_QUERY",
    "targets": [
      {
        "uri": "CDOC_URL"
      }
    ]
  }
}

Sostituisci quanto segue:

SAMPLE_QUERY: la query utilizzata per valutare la qualità della ricerca
CDOC_URL: un campo obbligatorio per indicare il campo personalizzatocdoc_url per il campo dei dati strutturati nello schema del datastore di Vertex AI Search.

Dati sui siti web

Utilizza il seguente modello per creare la bozza di un file di query di esempio in formato JSON per valutare i contenuti del sito web.

{
  "queryEntry": {
    "query": "SAMPLE_QUERY",
    "targets": [
      {
        "uri": "WEBSITE_URL"
      }
    ]
  }
}

Sostituisci quanto segue:

SAMPLE_QUERY: la query utilizzata per valutare la qualità della ricerca
WEBSITE_URL: il sito web di destinazione della query.

Ecco un esempio di set di query di esempio nei formati JSON e NDJSON:

JSON

[
  {
    "queryEntry": {
      "query": "2018 Q4 Google revenue",
      "targets": [
        {
          "uri": "gs://cloud-samples-data/gen-app-builder/search/alphabet-investor-pdfs/2018Q4_alphabet_earnings_release.pdf"
        },
        {
          "uri": "gs://cloud-samples-data/gen-app-builder/search/alphabet-investor-pdfs/201802024_alphabet_10K.pdf"
        }
      ]
    }
  },
  {
    "queryEntry": {
      "query": "2019 Q4 Google revenue",
      "targets": [
        {
          "uri": "gs://cloud-samples-data/gen-app-builder/search/alphabet-investor-pdfs/2019Q4_alphabet_earnings_release.pdf"
        }
      ]
    }
  }
]

NDJSON

{"queryEntry":{"query":"2018 Q4 Google revenue","targets":[{"uri":"gs://cloud-samples-data/gen-app-builder/search/alphabet-investor-pdfs/2018Q4_alphabet_earnings_release.pdf"},{"uri":"gs://cloud-samples-data/gen-app-builder/search/alphabet-investor-pdfs/201802024_alphabet_10K.pdf"}]}}
{"queryEntry":{"query":"2019 Q4 Google revenue","targets":[{"uri":"gs://cloud-samples-data/gen-app-builder/search/alphabet-investor-pdfs/2019Q4_alphabet_earnings_release.pdf"}]}}

Importa dal file system locale

La sezione seguente fornisce i modelli di set di query di esempio per l'importazione dal file system locale.

Dati non strutturati

Utilizza il seguente modello per creare la bozza di un file di query di esempio in formato JSON per valutare i dati non strutturati con metadati.

{
  "inlineSource": {
    "sampleQueries": [
      {
        "queryEntry": {
          "query": "SAMPLE_QUERY",
          "targets": [
            {
              "uri": "gs://PATH/TO/CLOUD/STORAGE/LOCATION_1.docx"
            },
            {
              "uri": "gs://PATH/TO/CLOUD/STORAGE/LOCATION_2.pdf",
              "pageNumbers": [
                PAGE_NUMBER_1,
                PAGE_NUMBER_2
              ]
            },
            {
              "uri": "CDOC_URL"
            }
          ]
        }
      }
    ]
  }
}

Sostituisci quanto segue:

SAMPLE_QUERY: la query utilizzata per valutare la qualità della ricerca
PATH/TO/CLOUD/STORAGE/LOCATION: il percorso della posizione di Cloud Storage in cui si trova il file di dati non strutturati su cui eseguire la query. Si tratta del valore del campo link nel campo derivedStructData della definizione del documento.
PAGE_NUMBER_1: un campo facoltativo per indicare i numeri di pagina in cui è possibile trovare la risposta richiesta per la query nel file PDF. Questa opzione è utile se il file ha più pagine.
CDOC_URL: un campo facoltativo per indicare il campo ID documento personalizzato cdoc_url nei metadati del documento nello schema dell'datastore di Vertex AI Search.

Dati strutturati

Utilizza il seguente modello per creare la bozza di un file di query di esempio in formato JSON per valutare i dati strutturati di BigQuery.

{
  "inlineSource": {
    "sampleQueries": [
      {
        "queryEntry": {
          "query": "SAMPLE_QUERY",
          "targets": [
            {
              "uri": "CDOC_URL"
            }
          ]
        }
      }
    ]
  }
}

Sostituisci quanto segue:

SAMPLE_QUERY: la query utilizzata per valutare la qualità della ricerca
CDOC_URL: un campo obbligatorio per indicare il campo personalizzatocdoc_url per il campo dei dati strutturati nello schema del datastore di Vertex AI Search.

Dati sui siti web

Utilizza il seguente modello per creare la bozza di un file di query di esempio in formato JSON per valutare i contenuti del sito web.

{
  "inlineSource": {
    "sampleQueries": [
      {
        "queryEntry": {
          "query": "SAMPLE_QUERY",
          "targets": [
            {
              "uri": "WEBSITE_URL"
            }
          ]
        }
      }
    ]
  }
}

Sostituisci quanto segue:

SAMPLE_QUERY: la query utilizzata per valutare la qualità della ricerca
WEBSITE_URL: il sito web di destinazione della query.

Di seguito è riportato un esempio di un insieme di query di esempio:

JSON

{
  "inlineSource": {
    "sampleQueries": [
      {
        "queryEntry": {
          "query": "2018 Q4 Google revenue",
          "targets": [
            {
              "uri": "gs://cloud-samples-data/gen-app-builder/search/alphabet-investor-pdfs/2018Q4_alphabet_earnings_release.pdf"
            },
            {
              "uri": "gs://cloud-samples-data/gen-app-builder/search/alphabet-investor-pdfs/201802024_alphabet_10K.pdf"
            }
          ]
        }
      },
      {
        "queryEntry": {
          "query": "2019 Q4 Google revenue",
          "targets": [
            {
              "uri": "gs://cloud-samples-data/gen-app-builder/search/alphabet-investor-pdfs/2019Q4_alphabet_earnings_release.pdf"
            }
          ]
        }
      }
    ]
  }
}

Procedura per la valutazione della qualità della Ricerca

La procedura di valutazione della qualità della Ricerca è la seguente:

Crea un insieme di query di esempio.
Importa una query di esempio conforme al formato JSON prescritto.
Esegui la valutazione della qualità della ricerca.
Comprendere i risultati.

Le sezioni seguenti forniscono le istruzioni per eseguire questi passaggi utilizzando i metodi dell'API REST.

Prima di iniziare

Si applica il seguente limite:
- In un determinato momento, puoi avere una sola valutazione attiva per progetto.
Si applica la seguente quota:
- Puoi avviare un massimo di cinque richieste di valutazione al giorno per progetto. Per ulteriori informazioni, consulta Quote e limiti.
Per ottenere le metriche a livello di pagina, devi attivare le risposte estrattive.

Crea un set di query di esempio

Puoi creare un set di query di esempio e utilizzarlo per valutare la qualità delle risposte di ricerca per un determinato datastore. Per creare un insieme di query di esempio:

REST

L'esempio seguente mostra come creare l'insieme di query di esempio utilizzando il metodo sampleQuerySets.create.

Crea l'insieme di query di esempio.

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/v1beta/projects/PROJECT_ID/locations/global/sampleQuerySets?sampleQuerySetId=SAMPLE_QUERY_SET_ID" \
    -d '{
  "displayName": "SAMPLE_QUERY_SET_DISPLAY_NAME"
}'

Sostituisci quanto segue:

PROJECT_ID: l'ID del tuo progetto Google Cloud.
SAMPLE_QUERY_SET_ID: un ID personalizzato per il tuo insieme di query di esempio.
SAMPLE_QUERY_SET_DISPLAY_NAME: un nome personalizzato per il set di query di esempio.

Risposta

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "name": "projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID",
  "displayName": "SAMPLE_QUERY_SET_DISPLAY_NAME",
  "createTime": "CREATION_DATETIME"
}

Importa i dati delle query di esempio

Dopo aver creato l'insieme di query di esempio, importa i dati della query di esempio. Per importare i dati di query di esempio, puoi procedere in uno dei seguenti modi:

Importa da Cloud Storage: importa un file NDJSON da una posizione Cloud Storage.
Importa da BigQuery: importa i dati di BigQuery da una tabella BigQuery. Per creare la tabella BigQuery dal file NDJSON, consulta Caricare i dati JSON da Cloud Storage.
Importa dal file system locale: crea l'insieme di query di esempio nel file system locale e importalo.

Cloud Storage

Crea gli insiemi di query di esempio conformi al formato dell'insieme di query di esempio.
Importa il file JSON contenente l'insieme di query di esempio da una posizione Cloud Storage utilizzando il metodo sampleQueries.import.
```
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/v1beta/projects/PROJECT_ID/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/sampleQueries:import" \
-d '{
  "gcsSource": {
    "inputUris": ["INPUT_FILE_PATH"],
  },
  "errorConfig": {
    "gcsPrefix": "ERROR_DIRECTORY"
  }
}'
```
Sostituisci quanto segue:
- PROJECT_ID: l'ID del tuo progetto Google Cloud.
- SAMPLE_QUERY_SET_ID: l'ID personalizzato per il set di query di esempio che hai definito durante la creazione del set di query di esempio.
- INPUT_FILE_PATH: il percorso della posizione Cloud Storage per l'insieme di query di esempio.
- ERROR_DIRECTORY: un campo facoltativo per specificare il percorso della posizione di Cloud Storage in cui vengono registrati i file di errore quando si verificano errori di importazione. Google consiglia di lasciare vuoto questo campo o di rimuoverlo errorConfig in modo che Vertex AI Search possa creare automaticamente una posizione temporanea.
Risposta

Dovresti ricevere una risposta JSON simile alla seguente. Prendi nota del valore di OPERATION_ID. Ti servirà questo valore nel passaggio successivo per eseguire il polling dello stato di questa operazione a lunga esecuzione (LRO).
```
{
  "name": "projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.discoveryengine.v1beta.ImportSampleQueriesMetadata"
  }
}
```

Recupera lo stato dell'operazione a lunga esecuzione (LRO) utilizzando il metodo operations.get.

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/operations/OPERATION_ID"

Risposta

Dovresti ricevere una risposta JSON simile alla seguente. Se si verificano errori e l'importazione non va a buon fine, la risposta mostra un campo failureCount per indicare il numero di query di esempio di cui non è stata eseguita l'importazione.

{
 "name": "projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/operations/OPERATION_ID",
 "metadata": {
   "@type": "type.googleapis.com/google.cloud.discoveryengine.v1beta.ImportSampleQueriesMetadata",
   "createTime": "CREATE_TIME",
   "updateTime": "UPDATE_TIME",
   "successCount": "SUCCESS_COUNT",
   "totalCount": "TOTAL_COUNT"
 },
 "done": true,
 "response": {
   "@type": "type.googleapis.com/google.cloud.discoveryengine.v1beta.ImportSampleQueriesResponse",
   "errorConfig": {
     "gcsPrefix": "gs://PROJECT_NUMBER_us_import/ERROR_CONFIG_FOLDER"
   }
 }
}

BigQuery

Crea gli insiemi di query di esempio conformi al formato dell'insieme di query di esempio.
Importa il file JSON contenente l'insieme di query di esempio da una posizione BigQuery utilizzando il metodo sampleQueries.import.
```
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/v1beta/projects/PROJECT_ID/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/sampleQueries:import" \
-d '{
  "bigquerySource": {
    "projectId": "PROJECT_ID",
    "datasetId":"DATASET_ID",
    "tableId": "TABLE_ID"
  },
  "errorConfig": {
    "gcsPrefix": "ERROR_DIRECTORY"
  }
}'
```
Sostituisci quanto segue:
- PROJECT_ID: l'ID del tuo progetto Google Cloud.
- SAMPLE_QUERY_SET_ID: l'ID personalizzato per il set di query di esempio che hai definito durante la creazione del set di query di esempio.
- DATASET_ID: l'ID del set di dati BigQuery che contiene il set di query di esempio.
- TABLE_ID: l'ID della tabella BigQuery che contiene il set di query di esempio.
- ERROR_DIRECTORY: un campo facoltativo per specificare il percorso della posizione di Cloud Storage in cui vengono registrati i file di errore quando si verificano errori di importazione. Google consiglia di lasciare vuoto questo campo o di rimuoverlo per consentire a Vertex AI Search di creare automaticamente una posizione temporanea.
Risposta

Dovresti ricevere una risposta JSON simile alla seguente. Prendi nota del valore di OPERATION_ID. Ti servirà questo valore nel passaggio successivo per eseguire il polling dello stato di questa operazione a lunga esecuzione (LRO).
```
{
  "name": "projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.discoveryengine.v1beta.ImportSampleQueriesMetadata"
  }
}
```

Recupera lo stato dell'operazione a lunga esecuzione (LRO) utilizzando il metodo operations.get.

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/operations/OPERATION_ID"

Risposta

{
 "name": "projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/operations/OPERATION_ID",
 "metadata": {
   "@type": "type.googleapis.com/google.cloud.discoveryengine.v1beta.ImportSampleQueriesMetadata",
   "createTime": "CREATE_TIME",
   "updateTime": "UPDATE_TIME",
   "successCount": "SUCCESS_COUNT",
   "totalCount": "TOTAL_COUNT"
 },
 "done": true,
 "response": {
   "@type": "type.googleapis.com/google.cloud.discoveryengine.v1beta.ImportSampleQueriesResponse",
   "errorConfig": {
     "gcsPrefix": "gs://PROJECT_ID_us_import/ERROR_CONFIG_FOLDER"
   }
 }
}

File system locale

Crea gli insiemi di query di esempio conformi al formato dell'insieme di query di esempio.
Importa il file JSON contenente il set di query di esempio da una posizione del file system locale utilizzando il metodo sampleQueries.import.
```
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/v1beta/projects/PROJECT_ID/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/sampleQueries:import" \
--data @PATH/TO/LOCAL/FILE.json
```
Sostituisci quanto segue:
- PROJECT_ID: l'ID del tuo progetto Google Cloud.
- SAMPLE_QUERY_SET_ID: l'ID personalizzato per il set di query di esempio che hai definito durante la creazione del set di query di esempio.
- PATH/TO/LOCAL/FILE.json: il percorso del file JSON contenente l'insieme di query di esempio.
Risposta

Dovresti ricevere una risposta JSON simile alla seguente. Prendi nota del valore di OPERATION_ID. Ti servirà questo valore nel passaggio successivo per eseguire il polling dello stato di questa operazione a lunga esecuzione (LRO).
```
{
  "name": "projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.discoveryengine.v1beta.ImportSampleQueriesMetadata"
  }
}
```

Recupera lo stato dell'operazione a lunga esecuzione (LRO) utilizzando il metodo operations.get.

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/operations/OPERATION_ID"

Risposta

{
 "name": "projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/operations/OPERATION_ID",
 "metadata": {
   "@type": "type.googleapis.com/google.cloud.discoveryengine.v1beta.ImportSampleQueriesMetadata",
   "createTime": "CREATE_TIME",
   "updateTime": "UPDATE_TIME",
   "successCount": "SUCCESS_COUNT",
   "totalCount": "TOTAL_COUNT"
 },
 "done": true,
 "response": {
   "@type": "type.googleapis.com/google.cloud.discoveryengine.v1beta.ImportSampleQueriesResponse",
   "errorConfig": {
     "gcsPrefix": "gs://PROJECT_ID_us_import/ERROR_CONFIG_FOLDER"
   }
 }
}

Eseguire la valutazione della qualità della ricerca

Dopo aver importato i dati delle query di esempio nei set di query di esempio, segui questi passaggi per eseguire la valutazione della qualità della ricerca.

REST

Avvia una valutazione della qualità della ricerca.

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/v1beta/projects/PROJECT_ID/locations/global/evaluations" \
-d '{
 "evaluationSpec": {
   "querySetSpec": {
     "sampleQuerySet": "projects/PROJECT_ID/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID"
   },
   "searchRequest": {
     "servingConfig": "projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search"
   }
 }
}'

Sostituisci quanto segue:

PROJECT_ID: l'ID del tuo progetto Google Cloud.
SAMPLE_QUERY_SET_ID: l'ID personalizzato per il set di query di esempio che hai definito durante la creazione del set di query di esempio.
APP_ID: l'ID dell'app Vertex AI Search di cui vuoi valutare la qualità di ricerca.

Risposta

Dovresti ricevere una risposta JSON simile alla seguente. Prendi nota del valore di EVALUATION_ID. Ti servirà questo valore nel passaggio successivo per eseguire il polling dello stato della valutazione, che è un'operazione a lunga esecuzione (LRO).

{
 "name": "projects/PROJECT_NUMBER/locations/global/operations/OPERATION_ID",
 "done": true,
 "response": {
   "@type": "type.googleapis.com/google.cloud.discoveryengine.v1alpha.Evaluation",
   "name": "projects/PROJECT_NUMBER/locations/global/evaluations/EVALUATION_ID",
   "evaluationSpec": {
     "querySetSpec": {
       "sampleQuerySet": "projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID"
     },
     "searchRequest": {
       "servingConfig": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search"
     }
   },
   "state": "PENDING"
 }
}

Monitora l'avanzamento della valutazione.

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/evaluations/EVALUATION_ID"

Sostituisci quanto segue:

PROJECT_ID: l'ID del tuo progetto Google Cloud.
EVALUATION_ID: l'ID del job di valutazione che è stato restituito nel passaggio precedente quando hai avviato la valutazione.

Risposta

Dovresti ricevere una risposta JSON simile alla seguente. Lo stato della valutazione viene visualizzato come PENDING fino al suo completamento.

{
"name": "projects/PROJECT_NUMBER/locations/global/evaluations/EVALUATION_ID",
"evaluationSpec": {
  "querySetSpec": {
    "sampleQuerySet": "projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID"
  },
  "searchRequest": {
    "servingConfig": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search"
  }
},
"state": "PENDING"
"createTime": "CREATION_DATETIME"
}

Recupera i risultati aggregati.

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/evaluations/EVALUATION_ID"

Sostituisci quanto segue:

PROJECT_ID: l'ID del tuo progetto Google Cloud.
EVALUATION_ID: l'ID del job di valutazione che è stato restituito nel passaggio precedente quando hai avviato la valutazione.

Risposta

Dovresti ricevere una risposta JSON simile alla seguente. Lo stato della valutazione viene visualizzato come PENDING fino al suo completamento.

{
 "name": "projects/PROJECT_NUMBER/locations/global/evaluations/EVALUATION_ID",
 "evaluationSpec": {
   "querySetSpec": {
     "sampleQuerySet": "projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID"
   },
   "searchRequest": {
     "servingConfig": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search"
   }
 },
 "qualityMetrics": {
   "docRecall": {
     "top1": DOC_RECALL_TOP_1,
     "top3": DOC_RECALL_TOP_3,
     "top5": DOC_RECALL_TOP_5,
     "top10": DOC_RECALL_TOP_10
   },
   "docPrecision": {
     "top1": DOC_PRECISION_TOP_1,
     "top3": DOC_PRECISION_TOP_3,
     "top5": DOC_PRECISION_TOP_5,
     "top10": DOC_PRECISION_TOP_10
   },
   "docNdcg": {
     "top1": DOC_NDCG_TOP_1,
     "top3": DOC_NDCG_TOP_3,
     "top5": DOC_NDCG_TOP_5,
     "top10": DOC_NDCG_TOP_10
   },
   "pageRecall": {
     "top1": PAGE_RECALL_TOP_1,
     "top3": PAGE_RECALL_TOP_3,
     "top5": PAGE_RECALL_TOP_5,
     "top10": PAGE_RECALL_TOP_10
   },
   "pageNdcg": {
     "top1": PAGE_NDCG_TOP_1,
     "top3": PAGE_NDCG_TOP_3,
     "top5": PAGE_NDCG_TOP_5,
     "top10": PAGE_NDCG_TOP_10
    }
  },
 "state": "SUCCEEDED",
 "error": {},
 "createTime": "CREATION_DATETIME",
 "endTime": "END_DATETIME"
}

Recupera i risultati a livello di query.

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/evaluations/EVALUATION_ID:listResults"

Sostituisci quanto segue:

PROJECT_ID: l'ID del tuo progetto Google Cloud.
EVALUATION_ID: l'ID del job di valutazione che è stato restituito nel passaggio precedente quando hai avviato la valutazione.

Risposta

Dovresti ricevere una risposta JSON simile alla seguente. Lo stato della valutazione viene visualizzato come PENDING fino al suo completamento.

{
 "evaluationResults": [
   {
     "sampleQuery": {
       "name": "projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/sampleQueries/QUERY_ID_1",
       "queryEntry": {
         "query": "SAMPLE_QUERY_1",
         "targets": [
           {
             "uri": "URI_1"
           }
         ]
       }
     },
     "qualityMetrics": {
       "docRecall": {
         "top1": DOC_RECALL_TOP_1,
         "top3": DOC_RECALL_TOP_3,
         "top5": DOC_RECALL_TOP_5,
         "top10": DOC_RECALL_TOP_10
       },
       "docPrecision": {
         "top1": DOC_PRECISION_TOP_1,
         "top3": DOC_PRECISION_TOP_3,
         "top5": DOC_PRECISION_TOP_5,
         "top10": DOC_PRECISION_TOP_10
       },
       "docNdcg": {
         "top1": DOC_NDCG_TOP_1,
         "top3": DOC_NDCG_TOP_3,
         "top5": DOC_NDCG_TOP_5,
         "top10": DOC_NDCG_TOP_10
       },
       "pageRecall": {
         "top1": PAGE_RECALL_TOP_1,
         "top3": PAGE_RECALL_TOP_3,
         "top5": PAGE_RECALL_TOP_5,
         "top10": PAGE_RECALL_TOP_10
       },
       "pageNdcg": {
         "top1": PAGE_NDCG_TOP_1,
         "top3": PAGE_NDCG_TOP_3,
         "top5": PAGE_NDCG_TOP_5,
         "top10": PAGE_NDCG_TOP_10
        }
      }
   },
   {
     "sampleQuery": {
       "name": "projects/PROJECT_NUMBER/locations/global/sampleQuerySets/SAMPLE_QUERY_SET_ID/sampleQueries/QUERY_ID_2",
       "queryEntry": {
         "query": "SAMPLE_QUERY_2",
         "targets": [
           {
             "uri": "URI_2"
           }
         ]
       }
     },
     "qualityMetrics": {
       "docRecall": {
         "top1": DOC_RECALL_TOP_1,
         "top3": DOC_RECALL_TOP_3,
         "top5": DOC_RECALL_TOP_5,
         "top10": DOC_RECALL_TOP_10
       },
       "docPrecision": {
         "top1": DOC_PRECISION_TOP_1,
         "top3": DOC_PRECISION_TOP_3,
         "top5": DOC_PRECISION_TOP_5,
         "top10": DOC_PRECISION_TOP_10
       },
       "docNdcg": {
         "top1": DOC_NDCG_TOP_1,
         "top3": DOC_NDCG_TOP_3,
         "top5": DOC_NDCG_TOP_5,
         "top10": DOC_NDCG_TOP_10
       },
       "pageRecall": {
         "top1": PAGE_RECALL_TOP_1,
         "top3": PAGE_RECALL_TOP_3,
         "top5": PAGE_RECALL_TOP_5,
         "top10": PAGE_RECALL_TOP_10
       },
       "pageNdcg": {
         "top1": PAGE_NDCG_TOP_1,
         "top3": PAGE_NDCG_TOP_3,
         "top5": PAGE_NDCG_TOP_5,
         "top10": PAGE_NDCG_TOP_10
        }
      }
   }
 ]
}

Comprendere i risultati

La seguente tabella descrive le metriche restituite nei risultati della valutazione.

Nome	Descrizione	Requisiti
`docRecall`	Recall per documento, a vari livelli di taglio top-k. Il richiamo è la frazione di documenti pertinenti recuperati rispetto a tutti i documenti pertinenti. Ad esempio, il valore `top5` indica quanto segue: Per una singola query, se 3 documenti pertinenti su 5 vengono recuperati tra i primi 5, il valore `docRecall` può essere calcolato come 3/5 o 0,6.	La query di esempio deve contenere il campo URI.
`pageRecall`	Recall per pagina, a vari livelli di taglio top-k. Il richiamo è la frazione di pagine pertinenti recuperate rispetto a tutte le pagine pertinenti. Ad esempio, il valore `top5` indica quanto segue: Per una singola query, se 3 pagine pertinenti su 5 vengono recuperate tra le prime 5, il valore `pageRecall` può essere calcolato come 3/5 = 0,6	La query di esempio deve contenere i campi URI e pagine. Le risposte estrattive devono essere attivate.
`docNdcg`	Guadagno cumulativo scontato normalizzato (NDCG) per documento, a vari livelli di taglio top-k. Il NDCG misura la qualità del ranking, assegnando una pertinenza maggiore ai risultati principali. Il valore NDCG può essere calcolato per ogni query in base al CDG normalizzato.	La query di esempio deve contenere il campo URI.
`pageNdcg`	Guadagno cumulativo scontato normalizzato (NDCG) per pagina, a vari livelli di taglio top-k. Il NDCG misura la qualità del ranking, assegnando una pertinenza maggiore ai risultati principali. Il valore NDCG può essere calcolato per ogni query in base al CDG normalizzato.	La query di esempio deve contenere i campi URI e pagine. Le risposte estrattive devono essere attivate.
`docPrecision`	Precisione per documento, a vari livelli di taglio top-k. La precisione è la frazione di documenti recuperati pertinenti. Ad esempio, il valore `top3` indica quanto segue: Per una singola query, se 4 dei 5 documenti recuperati tra i primi 5 sono pertinenti, il valore `docPrecision` può essere calcolato come 4/5 o 0,8.	La query di esempio deve contenere il campo URI.

In base ai valori di queste metriche supportate, puoi eseguire le seguenti operazioni:

Analizza le metriche aggregate:
- Esamina le metriche generali come il richiamo medio, la precisione e il guadagno cumulativo scontato normalizzato (NDCG).
- Queste metriche forniscono una visione generale del rendimento del tuo motore di ricerca.
Esamina i risultati a livello di query:
- Analizza in dettaglio le singole query per identificare aree specifiche in cui il motore di ricerca ha un buon rendimento o meno.
- Cerca schemi ripetuti nei risultati per comprendere potenziali bias o carenze negli algoritmi di ranking.
Confronta i risultati nel tempo:
- Esegui regolarmente le valutazioni per monitorare le variazioni della qualità della ricerca nel tempo.
- Utilizza i dati storici per identificare le tendenze e valutare l'impatto di eventuali modifiche apportate al tuo motore di ricerca.

Passaggi successivi

Utilizza Cloud Scheduler per configurare la valutazione della qualità pianificata. Per ulteriori informazioni, consulta Utilizzare l'autenticazione con target HTTP.