Questa pagina è stata tradotta dall'API Cloud Translation.

Valutare la qualità della ricerca

Nell'ambito dell'esperienza di ricerca con Vertex AI Search, puoi valutare la qualità dei risultati di ricerca per le app di ricerca personalizzate utilizzando set di query di esempio.

Puoi valutare il rendimento delle app di ricerca personalizzate 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, vedi Procedura per la valutazione della qualità della ricerca.

Motivi per eseguire la valutazione

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

Valutare il rendimento del motore di ricerca a livello aggregato
A livello di query, individua i pattern per comprendere potenziali pregiudizi o carenze negli algoritmi di ranking
Confrontare i risultati della valutazione storica per comprendere l'impatto delle modifiche alla configurazione della ricerca

Per un elenco delle metriche, consulta Comprendere i 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 sui set di query di esempio

I set di query di esempio vengono utilizzati per la valutazione della qualità. Il set di query di esempio deve rispettare il formato prescritto e 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 un insieme diversificato 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 strutturata, non strutturata e di siti web, consulta Documenti.

Quando i documenti di destinazione vengono confrontati con i documenti recuperati nella risposta alla ricerca, vengono generate 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 nel seguente ordine 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 vengono citate anche nella risposta di ricerca. Devi attivare le risposte estrattive per attivare la corrispondenza a livello di pagina. L'API di valutazione corrisponde alla pagina della prima risposta estrattiva nel risultato di ricerca.

Scopo dei set 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. In questo modo viene creato anche un sistema equo e ripetibile.

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

Quote e limiti

Al 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 ai set 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 del set di query di esempio

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

Importare 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 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. Questo è il 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 una 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 cdoc_url personalizzato per il campo di dati strutturati nello schema del datastore di Vertex AI Search.

Dati sui siti web

Utilizza il seguente modello per creare 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 per la query.

Ecco un esempio di un insieme 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 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 Cloud Storage in cui si trova il file di dati non strutturati da interrogare. Questo è il 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 si trova 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 una 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 cdoc_url personalizzato per il campo di dati strutturati nello schema del datastore di Vertex AI Search.

Dati sui siti web

Utilizza il seguente modello per creare 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 per la query.

Ecco 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 valutare la 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 metriche a livello di pagina, devi attivare le risposte estrattive.

Crea un insieme di query di esempio

Puoi creare un insieme 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 il set di query di esempio utilizzando il metodo sampleQuerySets.create.

Crea il set 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 Google Cloud progetto.
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 dati di query di esempio

Dopo aver creato il set di query di esempio, importa i dati delle query di esempio. Per importare i dati di esempio della query, 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 BigQuery da una tabella BigQuery. Per creare la tabella BigQuery dal file NDJSON, consulta Caricamento di dati JSON da Cloud Storage.
Importa dal file system locale: crea il set di query di esempio nel file system locale e importalo.

Cloud Storage

Crea i set di query di esempio conformi al formato del set di query di esempio.
Importa il file JSON contenente il set 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 Google Cloud progetto.
- 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 il set di query di esempio.
- ERROR_DIRECTORY: un campo facoltativo per specificare il percorso della posizione 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 rimuovere il campo 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 è riuscita, la risposta mostra un campo failureCount per indicare il numero di query di esempio che non è stato possibile importare.

{
 "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 i set di query di esempio conformi al formato del set di query di esempio.
Importa il file JSON contenente il set 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 Google Cloud progetto.
- 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 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 rimuovere il campo `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

{
 "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 i set di query di esempio conformi al formato del set 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 Google Cloud progetto.
- 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 il set 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"
   }
 }
}

Esegui 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 Google Cloud progetto.
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à della 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 Google Cloud progetto.
EVALUATION_ID: l'ID del job di valutazione 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 finché la valutazione non è completa.

{
"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 Google Cloud progetto.
EVALUATION_ID: l'ID del job di valutazione 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 finché la valutazione non è completa.

{
 "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 Google Cloud progetto.
EVALUATION_ID: l'ID del job di valutazione 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 finché la valutazione non è completa.

{
 "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 cutoff top-k. Il richiamo è la frazione di documenti pertinenti recuperati su tutti i documenti pertinenti. Ad esempio, il valore `top5` indica quanto segue: Per una singola query, se vengono recuperati 3 documenti pertinenti su 5 nei primi 5 risultati, la `docRecall` può essere calcolata come 3/5 o 0,6.	La query di esempio deve contenere il campo URI.
`pageRecall`	Richiamo per pagina, a vari livelli di cutoff 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 vengono recuperate 3 pagine pertinenti su 5 nelle prime 5 posizioni, la `pageRecall` può essere calcolata 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 cutoff top-k. NDCG misura la qualità del ranking, dando maggiore pertinenza ai risultati migliori. 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 interruzione top-k. NDCG misura la qualità del ranking, dando maggiore pertinenza ai risultati migliori. 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 cutoff 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 nei primi 5 sono pertinenti, il valore di `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 richiamo medio, precisione e 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:
- Visualizza in dettaglio le singole query per identificare le aree specifiche in cui il motore di ricerca ha un buon o scarso rendimento.
- Cerca pattern nei risultati per comprendere potenziali pregiudizi o carenze negli algoritmi di ranking.
Confronta i risultati nel tempo:
- Esegui regolarmente 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 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.

Valutare la qualità della ricerca Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Panoramica

Motivi per eseguire la valutazione

Quando eseguire la valutazione

Informazioni sui set di query di esempio

Scopo dei set di query di esempio

Quote e limiti

Formato del set di query di esempio

Importare da BigQuery e Cloud Storage

Dati non strutturati

Dati strutturati

Dati sui siti web

JSON

NDJSON

Importa dal file system locale

Dati non strutturati

Dati strutturati

Dati sui siti web

JSON

Procedura per valutare la qualità della Ricerca

Prima di iniziare

Crea un insieme di query di esempio

REST

Risposta

Importa dati di query di esempio

Cloud Storage

Risposta

Risposta

BigQuery

Risposta

Risposta

File system locale

Risposta

Risposta

Esegui la valutazione della qualità della Ricerca

REST

Risposta

Risposta

Risposta

Risposta

Comprendere i risultati

Passaggi successivi

Valutare la qualità della ricerca