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 personalizados usando conjuntos de consultas de amostra.

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

Nesta página, explicamos 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 fazer uma avaliação de qualidade da pesquisa, consulte Processo para avaliar a qualidade da pesquisa.

Motivos para realizar uma avaliação

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

Avalie a performance do seu mecanismo de pesquisa em um nível agregado
No nível da consulta, localize padrões para entender possíveis vieses ou deficiências nos algoritmos de classificação.
Compare os resultados da avaliação histórica para entender o impacto das mudanças na sua configuração de 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. É possível fazer uma avaliação da qualidade da pesquisa depois de fazer as seguintes mudanças:

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

Sobre conjuntos de consultas de amostra

Conjuntos de consultas de exemplo são usados para avaliação de qualidade. O conjunto de consultas de exemplo precisa obedecer ao formato prescrito e conter entradas de consulta com os seguintes campos aninhados:

Consultas: a consulta cujos resultados da pesquisa 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.
Destinos: 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 de 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 seguintes campos na ordem a seguir e usa 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 nas suas metas 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. É preciso ativar as respostas extrativas 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 exemplo

Usar o mesmo conjunto de consultas de amostra em todas as avaliações de qualidade da pesquisa para um repositório de dados específico 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 com desconto 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 por organização.

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

Formato de conjunto de consultas de exemplo

O conjunto de consultas precisa estar de acordo com o seguinte esquema quando construído no formato JSON. O conjunto pode conter várias entradas de consulta, cada uma com uma consulta. Quando apresentada no formato JSON delimitado por nova linha (NDJSON), 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 conjunto de consultas de amostra para importação do BigQuery e do Cloud Storage.

Dados não estruturados

Use o modelo a seguir para criar um arquivo de consulta de amostra 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 está. 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 das páginas 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 criar um arquivo de consulta de amostra em formato JSON e avaliar dados estruturados do BigQuery.

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

Substitua:

SAMPLE_QUERY: a consulta usada para testar e avaliar 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 de sites

Use o modelo a seguir para criar um arquivo de consulta de amostra 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 de amostra nos 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 conjunto de consultas de amostra para importar do sistema de arquivos local.

Dados não estruturados

Use o modelo a seguir para criar um arquivo de consulta de amostra 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á localizado. 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 das páginas em que a resposta necessária para a consulta pode ser encontrada 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 criar um arquivo de consulta de amostra em formato JSON e avaliar dados estruturados do BigQuery.

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

Substitua:

SAMPLE_QUERY: a consulta usada para testar e avaliar 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 de sites

Use o modelo a seguir para criar um arquivo de consulta de amostra 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 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 amostra.
Importe uma consulta de exemplo que esteja de acordo com o formato JSON prescrito.
Faça uma avaliação da qualidade da pesquisa.
Entenda os resultados.

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

Antes de começar

O seguinte limite se aplica:
- Em um determinado momento, só é possível ter uma avaliação ativa por projeto.
A seguinte cota se aplica:
- É possível 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 amostra

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 exemplo usando o método sampleQuerySets.create.

Crie o conjunto de consultas de amostra.

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 Google Cloud projeto.
SAMPLE_QUERY_SET_ID: um ID personalizado para seu conjunto de consultas de exemplo.
SAMPLE_QUERY_SET_DISPLAY_NAME: um nome personalizado para seu 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: importa dados 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 o conjunto de consultas de amostra no sistema de arquivos local e importe-o.

Cloud Storage

Crie os conjuntos de consultas de amostra que estão de acordo com o formato de conjunto de consultas de amostra.
Importe o arquivo JSON que contém o conjunto de consultas de amostra 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 Google Cloud projeto.
- SAMPLE_QUERY_SET_ID: o ID personalizado do seu conjunto de consultas de amostra definido durante a criação dele.
- INPUT_FILE_PATH: o caminho para o local do Cloud Storage do 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 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 pesquisar 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 amostra que estão de acordo com o formato de conjunto de consultas de amostra.
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 Google Cloud projeto.
- SAMPLE_QUERY_SET_ID: o ID personalizado do seu conjunto de consultas de amostra definido durante a criação dele.
- DATASET_ID: o ID do conjunto de dados do BigQuery que contém o conjunto de consultas de amostra.
- TABLE_ID: o ID da sua tabela 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 esse campo vazio 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 pesquisar 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 os conjuntos de consultas de amostra que estão de acordo com o formato de conjunto de consultas de amostra.
Importe o arquivo JSON que contém o conjunto de consultas de amostra 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 Google Cloud projeto.
- SAMPLE_QUERY_SET_ID: o ID personalizado do seu conjunto de consultas de amostra definido durante a criação dele.
- 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 pesquisar 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 avaliação de qualidade da pesquisa

Depois de importar os dados de consulta de exemplo para os conjuntos de consultas de exemplo, 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 Google Cloud projeto.
SAMPLE_QUERY_SET_ID: o ID personalizado do seu conjunto de consultas de amostra que você definiu durante a criação dele.
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ê vai precisar desse valor na próxima etapa para pesquisar o status da avaliação, que é uma operação de longa duração (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"
 }
}

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 Google Cloud projeto.
EVALUATION_ID: o ID do seu trabalho 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"
  }
},
"state": "PENDING"
"createTime": "CREATION_DATETIME"
}

Recupere 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 Google Cloud projeto.
EVALUATION_ID: o ID do seu trabalho 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"
}

Recupera 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 Google Cloud projeto.
EVALUATION_ID: o ID do seu trabalho 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.

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

Entenda os resultados

A tabela a seguir descreve as métricas 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 em relação a todos os documentos relevantes. Por exemplo, o valor `top5` significa o seguinte: Para uma única consulta, se 3 de 5 documentos relevantes forem recuperados no top 5, 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 top-k. O recall é a fração de páginas relevantes recuperadas em relação a todas as páginas relevantes. Por exemplo, o valor `top5` significa o seguinte: Para uma única consulta, se 3 de 5 páginas relevantes forem recuperadas no top 5, 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 k superior. O NDCG mede a qualidade da classificação, mais relevância aos resultados principais. O valor de 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) por página, em vários níveis de corte top-k. O NDCG mede a qualidade da classificação, mais relevância aos resultados principais. O valor de 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 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 4 dos 5 documentos recuperados no top 5 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, você pode 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 oferecem uma visão geral do desempenho do seu mecanismo de pesquisa.
Analise os resultados no nível da consulta:
- Detalhe consultas individuais para identificar áreas específicas em que o mecanismo de pesquisa tem um bom ou mau desempenho.
- Procure padrões nos resultados para entender possíveis vieses ou deficiências nos algoritmos de classificação.
Comparar 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.

Avaliar a qualidade da pesquisa Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Visão geral

Motivos para realizar uma avaliação

Quando realizar a avaliação

Sobre conjuntos de consultas de amostra

Finalidade dos conjuntos de consultas de exemplo

Cotas e limites

Formato de conjunto de consultas de exemplo

Importar do BigQuery e do Cloud Storage

Dados não estruturados

Dados estruturados

Dados de sites

JSON

NDJSON

Importar do sistema de arquivos local

Dados não estruturados

Dados estruturados

Dados de sites

JSON

Processo para avaliar a qualidade da pesquisa

Antes de começar

Criar um conjunto de consultas de amostra

REST

Resposta

Importar dados de consulta de amostra

Cloud Storage

Resposta

Resposta

BigQuery

Resposta

Resposta

Sistemas de arquivos locais

Resposta

Resposta

Executar avaliação de qualidade da pesquisa

REST

Resposta

Resposta

Resposta

Resposta

Entenda os resultados

A seguir

Avaliar a qualidade da pesquisa