Esta página foi traduzida pela API Cloud Translation.

Avaliar a qualidade da pesquisa

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

É 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 realizar a avaliação da 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 Como 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 os testes de avaliação regularmente, porque o comportamento de pesquisa é atualizado periodicamente.

Sobre os conjuntos de consultas de amostra

Os conjuntos de consultas de exemplo são usados para avaliação de qualidade. O conjunto de consultas de exemplo precisa seguir o formato prescrito e conter entradas de consulta com os 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 reflita o padrão de pesquisa e o comportamento do usuário.
Targets: o URI do documento esperado como resultado da pesquisa da consulta de exemplo. Para entender a definição de documento para apps de pesquisa estruturados, não estruturados e de 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 documentos: 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 o destino ao 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 nos destinos de 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. É necessário ativar as respostas de extração para ativar a correspondência no nível da página. A API de avaliação corresponde à página da primeira resposta 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 de destino de cada consulta de amostra para calcular diferentes métricas, como recall, precisão e ganho cumulativo normalizado (NDCG, na sigla em inglês). Essas métricas quantitativas são usadas para classificar os resultados de diferentes configurações de pesquisa.

Cotas e limites

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

Cada conjunto de consultas de exemplo pode conter no máximo 20.000 consultas.

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

É 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 de conjunto de consultas

O conjunto de consultas precisa estar em conformidade com o esquema abaixo quando construído no formato JSON. O conjunto de consultas pode conter várias entradas de consulta, com uma consulta em cada entrada. Quando apresentado no formato JSON delimitado por nova linha (NDJSON, na sigla em inglês), cada entrada de consulta precisa estar em uma nova linha.

Importar do BigQuery e do Cloud Storage

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

Dados não estruturados

Use o modelo a seguir para elaborar um arquivo de consulta de exemplo 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 a qualidade da pesquisa
PATH/TO/CLOUD/STORAGE/LOCATION: o caminho para o local do Cloud Storage em que o resultado esperado está armazenado. Esse é o valor do campo link no campo 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 está localizada. 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 o campo cdoc_url personalizado para o campo de dados estruturados no esquema do repositório de dados da Vertex AI para Pesquisa.

Dados do site

Use o modelo a seguir para criar um arquivo de consulta de exemplo 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 modelos de conjuntos de consultas de exemplo para importação do sistema de arquivos local.

Dados não estruturados

Use o modelo a seguir para elaborar um arquivo de consulta de exemplo 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 no campo 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 o campo cdoc_url personalizado para o campo de dados estruturados no esquema do repositório de dados da Vertex AI para Pesquisa.

Dados do site

Use o modelo a seguir para criar um arquivo de consulta de exemplo 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 da consulta.

Confira um exemplo de conjunto de consultas:

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 de avaliação da qualidade da pesquisa

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

Crie um conjunto de consultas de exemplo.
Importe uma consulta de exemplo que esteja em conformidade com o formato JSON prescrito.
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

O limite a seguir se aplica:
- Em um determinado momento, você só pode ter uma 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 e por 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 das respostas de pesquisa de um determinado repositório de dados. Para criar um conjunto de consultas de amostra, faça o seguinte.

REST

O exemplo a seguir mostra como criar o conjunto de consultas de amostra 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 de consulta de exemplo, faça o seguinte:

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 sistema de arquivos local: crie e importe o conjunto de consultas de exemplo no sistema de arquivos local.

Cloud Storage

Crie conjuntos de consultas de exemplo que estejam em conformidade com o formato de conjunto de consultas de exemplo.
Importe o arquivo JSON que contém o conjunto de consultas de exemplo de um local do Cloud Storage 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.
- 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 um local temporário automaticamente.
Resposta

Você receberá uma resposta JSON semelhante a seguinte. Observe 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) usando o método 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 os conjuntos de consultas de exemplo que estão em conformidade com o formato de conjunto de consultas de exemplo.
Importe o arquivo JSON que contém o conjunto de consultas de amostra de um local do BigQuery 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.
- DATASET_ID: o ID do conjunto de dados do BigQuery que contém o conjunto de consultas de exemplo.
- TABLE_ID: o ID da tabela do BigQuery que contém 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. Observe 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) usando o método 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"
   }
 }
}

Sistemas de arquivos locais

Crie conjuntos de consultas de exemplo que estejam em conformidade com o formato de conjunto 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. Observe 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) usando o método 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 da 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. Observe o valor de EVALUATION_ID. Você vai precisar desse valor na próxima etapa para consultar 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"
 }
}

Monitore 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 da avaliação é mostrado como PENDING até que a avaliação seja concluída.

{
"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 da avaliação é mostrado como PENDING até que ela seja concluída.

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

Extrair 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 de 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 primeiros, o `docRecall` poderá ser calculado como 3/5 ou 0,6.	A consulta de exemplo precisa conter o campo URI.
`pageRecall`	Recall por página, em vários níveis de corte de 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 exemplo 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, 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. O NDCG mede a qualidade da classificação, 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 da performance do seu mecanismo de pesquisa.
Analise os resultados no nível da consulta:
- Detalhar 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 falhas 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 das mudanças feitas no seu mecanismo de pesquisa.

A seguir

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