Esta página foi traduzida pela API Cloud Translation.

Avaliar a qualidade da pesquisa

Como parte da sua experiência de pesquisa com a Vertex AI para Pesquisa, é possível avaliar a qualidade dos resultados da pesquisa para apps de pesquisa genérica usando conjuntos de consultas de amostra.

É possível avaliar a performance de apps de pesquisa genéricos que contêm dados estruturados, não estruturados e de sites. Não é possível avaliar o desempenho de apps com vários repositórios de dados.

Esta página explica por que, quando e como avaliar a qualidade da pesquisa usando o método de avaliação.

Visão geral

Esta seção descreve por que e quando fazer uma avaliação de qualidade da pesquisa. Para saber como realizar a avaliação de qualidade da pesquisa, consulte Processo para avaliar a qualidade da pesquisa.

Motivos para realizar a avaliação

A avaliação da qualidade da pesquisa fornece métricas que ajudam a realizar tarefas como estas:

Avalie a performance do seu mecanismo de pesquisa em nível agregado
No nível da consulta, localize padrões para entender possíveis vieses ou falhas nos algoritmos de classificação.
Compare os resultados históricos de avaliação para entender o impacto das mudanças na configuração da pesquisa.

Para uma lista de métricas, consulte Entender os resultados.

Quando realizar a avaliação

A Vertex AI para Pesquisa estende várias configurações de pesquisa para melhorar sua experiência de pesquisa. É possível realizar a avaliação de qualidade da pesquisa depois de fazer as seguintes alterações:

Também é possível executar testes de avaliação regularmente, porque o comportamento de pesquisa é atualizado periodicamente.

Sobre os conjuntos de consultas de exemplo

Os conjuntos de consultas de amostra são usados para avaliação da qualidade. A amostra do conjunto de consultas precisa devem seguir o formato prescrito e conter entradas de consulta com o seguintes campos aninhados:

Consultas: a consulta cujos resultados são usados para gerar as métricas de avaliação e determinar a qualidade da pesquisa. O Google recomenda usar um conjunto diversificado de consultas que reflete o padrão de pesquisa do seu usuário e do seu modelo.
Destino: o URI do documento esperado como resultado da pesquisa da consulta de exemplo. Para entender a definição de documento para estruturado, não estruturados e de pesquisa em sites, consulte Documentos.

Quando os documentos de destino são comparados aos documentos recuperados na resposta da pesquisa, as métricas de performance são geradas. As métricas são geradas usando estas duas técnicas:
- Correspondência de documento: os URIs dos documentos de destino são comparados com os URIs dos documentos recuperados. Isso determina se os documentos esperados estão presentes nos resultados da pesquisa. Durante a comparação, a API de avaliação tenta extrair os campos a seguir na seguinte ordem e usar o primeiro valor disponível para corresponder ao destino com o documento recuperado:
  - cdoc_url no campo structData da definição do documento
  - uri no campo structData da definição do documento
  - link no campo derivedStructData da definição do documento
  - url no campo derivedStructData da definição do documento
- Correspondência de página: quando você inclui números de página na sua amostra a API de avaliação compara os resultados no nível da página. Isso determina se as páginas mencionadas nos destinos também são citadas na resposta da pesquisa. Ative as respostas extrativas para habilitar a correspondência em nível de página. A API de avaliação corresponde à página da primeira extrativa no resultado da pesquisa.

Finalidade dos conjuntos de consultas de amostra

Usar o mesmo conjunto de consultas de amostra para todas as avaliações de qualidade da pesquisa em um determinado repositório de dados garante uma maneira consistente e confiável de medir os resultados da qualidade da pesquisa. Isso também estabelece um sistema justo e repetível.

Os resultados de cada avaliação são comparados aos resultados desejados para cada amostra para calcular diferentes métricas, como recall, precisão e ganho cumulativo descontado normalizado (NDCG, na sigla em inglês). Essas métricas quantitativas são usadas para classificar os resultados de diferentes pesquisas personalizadas.

Cotas e limites

O limite a seguir se aplica aos exemplos de conjuntos de consultas:

Cada conjunto de consultas de amostra pode conter no máximo 20 mil consultas.

A cota a seguir se aplica aos exemplos de conjuntos de consultas:

É possível criar no máximo 100 conjuntos de consultas de amostra por projeto e 500 conjuntos de consultas de amostra por organização.

Para mais informações, consulte Cotas e limites.

Exemplo de formato do conjunto de consultas

O conjunto de consultas precisa seguir este esquema quando construídos no formato JSON. O conjunto de consultas pode conter várias entradas de consulta, cada uma com uma consulta. Quando apresentado em JSON delimitado por nova linha NDJSON), cada entrada de consulta deve estar em uma nova linha.

Importar do BigQuery e do Cloud Storage

A seção a seguir fornece os modelos de conjuntos de consultas para importação do BigQuery e do Cloud Storage.

Dados não estruturados

Use o modelo a seguir para criar um exemplo de arquivo de consulta no formato JSON para avaliar dados não estruturados com metadados.

{
  "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"
      }
    ]
  }
}

Substitua:

SAMPLE_QUERY: a consulta usada para testar e avaliar a qualidade da pesquisa
PATH/TO/CLOUD/STORAGE/LOCATION: o caminho para o local do Cloud Storage em que o resultado esperado reside. Esse é o valor do campo link na derivedStructData da definição do documento.
PAGE_NUMBER_1: um campo opcional para indicar. os números de página no arquivo PDF em que a resposta esperada para a consulta é localizado. Isso é útil quando o arquivo tem várias páginas.
CDOC_URL: um campo opcional para indicar o campo ID do documento personalizado cdoc_url nos metadados do documento no esquema do repositório de dados da Vertex AI para Pesquisa.

Dados estruturados

Use o modelo a seguir para elaborar um arquivo de consulta de exemplo no formato JSON para avaliar dados estruturados do BigQuery.

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

Substitua:

SAMPLE_QUERY: a consulta usada para testar a qualidade da pesquisa.
CDOC_URL: um campo obrigatório para indicar a personalização cdoc_url para o campo de dados estruturados na Esquema do repositório de dados da Vertex AI para Pesquisa.

Dados do site

Use o modelo a seguir para criar um exemplo de arquivo de consulta no formato JSON para avaliar o conteúdo do site.

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

Substitua:

SAMPLE_QUERY: a consulta usada para testar e avaliar a qualidade da pesquisa
WEBSITE_URL: o site de destino da consulta.

Confira um exemplo de conjunto de consultas em formatos 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"}]}}

Importar do sistema de arquivos local

A seção a seguir fornece os exemplos de modelos de conjuntos de consultas para importação a partir do sistema de arquivos local.

Dados não estruturados

Use o modelo a seguir para criar um exemplo de arquivo de consulta no formato JSON para avaliar dados não estruturados com metadados.

{
  "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"
            }
          ]
        }
      }
    ]
  }
}

Substitua:

SAMPLE_QUERY: a consulta usada para testar e avaliar a qualidade da pesquisa
PATH/TO/CLOUD/STORAGE/LOCATION: o caminho para o local do Cloud Storage em que o arquivo de dados não estruturados a ser consultado está armazenado. Esse é o valor do campo link na derivedStructData da definição do documento.
PAGE_NUMBER_1: um campo opcional para indicar os números de página em que a resposta necessária para a consulta pode ser localizada no arquivo PDF. Isso é útil se o arquivo tiver várias páginas.
CDOC_URL: um campo opcional para indicar o campo ID do documento personalizado cdoc_url nos metadados do documento no esquema do repositório de dados da Vertex AI para Pesquisa.

Dados estruturados

Use o modelo a seguir para elaborar um arquivo de consulta de exemplo no formato JSON para avaliar dados estruturados do BigQuery.

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

Substitua:

SAMPLE_QUERY: a consulta usada para testar a qualidade da pesquisa.
CDOC_URL: um campo obrigatório para indicar a personalização cdoc_url para o campo de dados estruturados na Esquema do repositório de dados da Vertex AI para Pesquisa.

Dados do site

Use o modelo a seguir para criar um exemplo de arquivo de consulta no formato JSON para avaliar o conteúdo do site.

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

Substitua:

SAMPLE_QUERY: a consulta usada para testar e avaliar a qualidade da pesquisa
WEBSITE_URL: o site de destino para a consulta.

Veja um exemplo de um conjunto de consultas de amostra:

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"
            }
          ]
        }
      }
    ]
  }
}

Processo para avaliar a qualidade da pesquisa

O processo de avaliação da qualidade da pesquisa é o seguinte:

Crie um conjunto de consultas de exemplo.
Importe uma amostra de consulta que esteja em conformidade com as diretrizes Formato JSON.
Execute a avaliação da qualidade da pesquisa.
Entenda os resultados.

As seções a seguir mostram as instruções para realizar essas etapas usando métodos da API REST.

Antes de começar

Aplicam-se os seguintes limites:
- Em um determinado momento, só é possível ter uma única avaliação ativa por projeto.
A cota a seguir se aplica:
- Você pode iniciar no máximo cinco solicitações de avaliação por dia em cada projeto. Para mais informações, consulte Cotas e limites.
Para receber métricas no nível da página, ative as respostas extrativas.

Criar um conjunto de consultas de exemplo

Você pode criar um conjunto de consultas de amostra e usá-lo para avaliar a qualidade da respostas de pesquisa para um determinado repositório de dados. Para criar um conjunto de consultas de amostra, siga as etapas a seguir.

REST

O exemplo a seguir mostra como criar o conjunto de consultas de exemplo usando o método sampleQuerySets.create.

Crie o conjunto de consultas de exemplo.

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"
}'

Substitua:

PROJECT_ID: o ID do seu projeto do Google Cloud.
SAMPLE_QUERY_SET_ID: um ID personalizado para seu conjunto de consultas de exemplo.
SAMPLE_QUERY_SET_DISPLAY_NAME: um nome personalizado para o conjunto de consultas de amostra.

Resposta

Você receberá uma resposta JSON semelhante a esta:

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

Importar dados de consulta de amostra

Depois de criar o conjunto de consultas de amostra, importe os dados de consulta de amostra. Para importar os dados da consulta de amostra, siga um destes procedimentos:

Importar do Cloud Storage: importe um arquivo NDJSON de um local do Cloud Storage.
Importar do BigQuery: importe dados do BigQuery de uma tabela do BigQuery. Para criar a tabela do BigQuery com base no arquivo NDJSON, consulte Como carregar dados JSON do Cloud Storage.
Importar do seu sistema de arquivos local: crie o conjunto de consultas de amostra no seu sistema de arquivos e importá-lo.

Cloud Storage

Crie os conjuntos de consultas de amostra que estejam em conformidade com o formato correspondente.
Importe o arquivo JSON que contém o conjunto de consultas de amostra de um Cloud Storage local usando o método 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"
  }
}'
```
Substitua:
- PROJECT_ID: o ID do seu projeto do Google Cloud.
- SAMPLE_QUERY_SET_ID: o ID personalizado do conjunto de consultas de amostra que você definiu durante a criação do conjunto de consultas de amostra.
- INPUT_FILE_PATH: o caminho para o local do Cloud Storage para o conjunto de consultas de exemplo.
- ERROR_DIRECTORY: um campo opcional para especificar o caminho para o local do Cloud Storage em que os arquivos de erro são registrados quando ocorrem erros de importação. O Google recomenda deixar esse campo em branco ou remover o campo errorConfig para que a Vertex AI para Pesquisa possa criar automaticamente um local temporário.
Resposta

Você receberá uma resposta JSON semelhante a seguinte. Anote o valor de OPERATION_ID. Você vai precisar desse valor na próxima etapa para consultar o status dessa operação de longa duração (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"
  }
}
```

Confira o status da operação de longa duração (LRO, na sigla em inglês) usando o 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"

Resposta

Você receberá uma resposta JSON semelhante a seguinte. Se houver erros e a importação falhar, a resposta vai mostrar um campo failureCount para indicar o número de consultas de amostra que não foram importadas.

{
 "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

Crie conjuntos de consultas de exemplo que estejam de acordo com o formato de conjuntos de consultas de exemplo.
Importe o arquivo JSON que contém o conjunto de consultas de amostra de um local usando o método 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"
  }
}'
```
Substitua:
- PROJECT_ID: o ID do seu projeto do Google Cloud.
- SAMPLE_QUERY_SET_ID: o ID personalizado do conjunto de consultas de amostra que você definiu durante a criação do conjunto de consultas de amostra.
- DATASET_ID: o ID do BigQuery. que contém o conjunto de consultas de amostra.
- TABLE_ID: o ID do BigQuery. que contém o conjunto de consultas de amostra.
- ERROR_DIRECTORY: um campo opcional para especificar o caminho para o local do Cloud Storage em que os arquivos de erro são registrados quando ocorrem erros de importação. O Google recomenda deixar este campo em branco ou remover campo `errorConfig` para que a Vertex AI para Pesquisa possa criar um local temporário.
Resposta

Você receberá uma resposta JSON semelhante a seguinte. Anote o valor de OPERATION_ID. Você vai precisar desse valor na próxima etapa para consultar o status dessa operação de longa duração (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"
  }
}
```

Confira o status da operação de longa duração (LRO, na sigla em inglês) usando o 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"

Resposta

Você receberá uma resposta JSON semelhante a seguinte. Se houver erros e a importação falhou, a resposta mostra um campo failureCount para indicar o número de amostras de consultas que apresentaram falha na importação.

{
 "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"
   }
 }
}

Sistemas de arquivos locais

Crie conjuntos de consultas de exemplo que estejam de acordo com o formato de conjuntos de consultas de exemplo.
Importe o arquivo JSON que contém o conjunto de consultas de exemplo de um local do sistema de arquivos local usando o método 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
```
Substitua:
- PROJECT_ID: o ID do seu projeto do Google Cloud.
- SAMPLE_QUERY_SET_ID: o ID personalizado do conjunto de consultas de amostra que você definiu durante a criação do conjunto de consultas de amostra.
- PATH/TO/LOCAL/FILE.json: o caminho para o arquivo JSON que contém o conjunto de consultas de exemplo.
Resposta

Você receberá uma resposta JSON semelhante a seguinte. Anote o valor de OPERATION_ID. Você vai precisar desse valor na próxima etapa para consultar o status dessa operação de longa duração (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"
  }
}
```

Confira o status da operação de longa duração (LRO, na sigla em inglês) usando o 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"

Resposta

{
 "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"
   }
 }
}

Executar a avaliação de qualidade da pesquisa

Depois de importar os dados de consulta de amostra para os conjuntos de consulta de amostra, siga estas etapas para executar a avaliação da qualidade da pesquisa.

REST

Inicie uma avaliação de qualidade da pesquisa.

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"
   }
 }
}'

Substitua:

PROJECT_ID: o ID do seu projeto do Google Cloud.
SAMPLE_QUERY_SET_ID: o ID personalizado do conjunto de consultas de amostra que você definiu durante a criação do conjunto de consultas de amostra.
APP_ID: o ID do app da Vertex AI para Pesquisa cuja qualidade de pesquisa você quer avaliar.

Resposta

Você receberá uma resposta JSON semelhante a seguinte. Anote o valor de EVALUATION_ID. Você precisa desse valor no próximo para verificar o status da avaliação, que é uma operação de longa duração (LRO, na sigla em inglês).

{
 "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"
 }
}

Monitorar o progresso da avaliação.

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"

Substitua:

PROJECT_ID: o ID do seu projeto do Google Cloud.
EVALUATION_ID: o ID do job de avaliação que foi retornado na etapa anterior quando você iniciou a avaliação.

Resposta

Você receberá uma resposta JSON semelhante a seguinte. O status do a avaliação será mostrada como PENDING até que ela seja concluído.

{
"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"
}

Extraia os resultados agregados.

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"

Substitua:

PROJECT_ID: o ID do seu projeto do Google Cloud.
EVALUATION_ID: o ID do job de avaliação que foi retornado na etapa anterior quando você iniciou a avaliação.

Resposta

Você receberá uma resposta JSON semelhante a seguinte. O status do a avaliação será mostrada como PENDING até que ela seja concluído.

{
 "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"
}

Recuperar resultados no nível da consulta.

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"

Substitua:

PROJECT_ID: o ID do seu projeto do Google Cloud.
EVALUATION_ID: o ID do job de avaliação que foi retornado na etapa anterior quando você iniciou a avaliação.

Resposta

Você receberá uma resposta JSON semelhante a seguinte. O status da avaliação é mostrado como PENDING até que a avaliação seja concluída.

{
 "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
        }
      }
   }
 ]
}

Entender os resultados

A tabela a seguir descreve as métricas que são retornadas nos resultados da avaliação.

Nome	Descrição	Requisitos
`docRecall`	Recall por documento, em vários níveis de corte Top-K. O recall é a fração de documentos relevantes recuperados de todos os documentos relevantes. Por exemplo, o valor `top5` significa o seguinte: Para uma única consulta, se três dos cinco documentos relevantes forem recuperados entre os cinco principais, o `docRecall` poderá ser calculado como 3/5 ou 0,6.	A consulta de amostra precisa conter o campo "URI".
`pageRecall`	Recall por página, em vários níveis de corte Top-K. O recall é a fração de páginas relevantes recuperadas de todas as páginas relevantes. Por exemplo, o valor `top5` significa o seguinte: Para uma única consulta, se três das cinco páginas relevantes forem recuperadas entre as cinco primeiras, o `pageRecall` poderá ser calculado como 3/5 = 0,6.	A consulta de amostra precisa conter os campos URI e páginas. As respostas extrativas precisam estar ativadas.
`docNdcg`	Ganho cumulativo descontado normalizado (NDCG, na sigla em inglês) por documento, em vários níveis de corte de top-k. O NDCG mede a qualidade da classificação, dando maior relevância aos principais resultados. O valor do NDCG pode ser calculado para cada consulta de acordo com o CDG normalizado.	A consulta de exemplo precisa conter o campo URI.
`pageNdcg`	Ganho cumulativo descontado normalizado (NDCG, na sigla em inglês) por página, em vários níveis de corte de top-k. A NDCG avalia a qualidade da classificação, atribuindo maior relevância aos principais resultados. O valor do NDCG pode ser calculado para cada consulta de acordo com o CDG normalizado.	A consulta de exemplo precisa conter os campos URI e páginas. As respostas extrativas precisam estar ativadas.
`docPrecision`	Precisão por documento, em vários níveis de corte de top-k. A precisão é a fração de documentos recuperados que são relevantes. Por exemplo, o valor `top3` significa o seguinte: Para uma única consulta, se quatro dos cinco documentos recuperados entre os cinco primeiros forem relevantes, o valor de `docPrecision` poderá ser calculado como 4/5 ou 0,8.	A consulta de exemplo precisa conter o campo URI.

Com base nos valores dessas métricas compatíveis, é possível realizar as seguintes tarefas:

Analisar métricas agregadas:
- Examine métricas gerais, como recall médio, precisão e ganho cumulativo com desconto normalizado (NDCG, na sigla em inglês).
- Essas métricas fornecem uma visão geral do desempenho do seu mecanismo de pesquisa.
Analisar os resultados no nível da consulta:
- Aprofunde-se em consultas individuais para identificar áreas específicas em que o mecanismo de pesquisa tem bom ou mau desempenho.
- Procure padrões nos resultados para entender possíveis vieses ou deficiências nos algoritmos de classificação.
Compare os resultados ao longo do tempo:
- Faça avaliações regularmente para acompanhar as mudanças na qualidade da pesquisa ao longo do tempo.
- Use dados históricos para identificar tendências e avaliar o impacto de alterações feitas em seu mecanismo de pesquisa.

A seguir

Usar o Cloud Scheduler para configurar uma avaliação de qualidade programada. Para mais informações, consulte Usar autenticação com destinos HTTP.