Testar o QueryData no Firestore Studio

Este documento descreve como testar o QueryData e atualizar o arquivo do conjunto de contexto. É possível testar a capacidade do QueryData de gerar consultas da linguagem de consulta do MongoDB (MQL, na sigla em inglês) com base em perguntas em linguagem natural. Se uma consulta gerada não for precisa, atualize o arquivo do conjunto de contexto.

Para saber mais sobre conjuntos de contexto, consulte Visão geral dos conjuntos de contexto.

Antes de começar

Verifique se um conjunto de contexto já foi criado e se o arquivo do conjunto de contexto foi enviado ao agente do QueryData. Para mais informações, consulte Gerenciar conjuntos de contexto no Firestore Studio.

Para fazer o download, atualizar e enviar arquivos de conjunto de contexto, verifique se o usuário do IAM tem o papel de editor do Dataplex Catalog (roles/dataplex.catalogEditor) ou administrador do Dataplex Catalog (roles/dataplex.catalogAdmin) no projeto. Para mais informações, consulte Permissões de conjuntos de contexto.

Testar o QueryData

Para testar um QueryData, siga estas etapas:

  1. No Google Cloud console, acesse a página do Firestore.

    Vá para o Firestore

  2. Selecione um banco de dados ao qual você adicionou um conjunto de contexto. Somente o Firestore com compatibilidade com o MongoDB é aceito.

  3. No menu de navegação, clique em Firestore Studio.

  4. No painel Explorer, clique em Ver ações ao lado do conjunto de contexto que você está usando.

  5. Clique em Testar conjunto de contexto.

  6. No editor de consultas, clique em Gerar consulta para abrir o painel Me ajude com o código.

  7. Insira uma pergunta em linguagem natural no editor para gerar uma consulta MQL e clique em Gerar.

  8. Analise a precisão da consulta MQL.

Fazer o download e atualizar um conjunto de contexto

Se você não estiver satisfeito com a consulta MQL gerada para uma pergunta em linguagem natural, faça o download do arquivo do conjunto de contexto atual. Em seguida, revise e atualize o modelo de consulta e envie novamente o arquivo de contexto atualizado para o agente.

Para fazer o download e atualizar um conjunto de contexto, siga estas etapas:

  1. No painel Explorer, clique em Ver ações.
  2. Clique em Fazer o download do arquivo de contexto.
  3. Siga as etapas em Criar conjuntos de contexto usando o agente de engenharia de contexto para atualizar o contexto com outros pares de consultas.
  4. No painel Explorer, clique em Ver ações ao lado do conjunto de contexto que você está usando.
  5. Clique em Editar conjunto de contexto.
  6. Clique em Procurar na seção Fazer upload do arquivo de conjunto de contexto e selecione o arquivo atualizado.
  7. Clique em Salvar para atualizar o conjunto de contexto.

Depois de ficar satisfeito com a precisão das respostas, use o endpoint QueryData para conectar o aplicativo ao conjunto de contexto.

Encontrar o ID do conjunto de contexto

Para conectar um aplicativo de dados ao agente do QueryData, você precisa do ID do conjunto de contexto.

  1. No Google Cloud console, acesse a página do Firestore.

    Vá para o Firestore

  2. Selecione um banco de dados ao qual você adicionou um conjunto de contexto.

  3. No menu de navegação, clique em Firestore Studio.

  4. No painel Explorer, clique em Ver ações ao lado do conjunto de contexto que você está usando.

  5. Clique em Editar conjunto de contexto.

  6. Anote o ID do contexto em ID do conjunto de contexto. O formato do ID do conjunto de contexto é semelhante a projects/data-agents-project/locations/us-central1/contextSets/bdf_pg_all_templates.

Conectar o QueryData ao aplicativo

Defina o ID do conjunto de contexto na chamada de método QueryData para fornecer contexto criado para fontes de dados de banco de dados, como AlloyDB, Spanner, Cloud SQL, Cloud SQL para PostgreSQL e Firestore. Para mais informações, consulte Definir o contexto do agente de dados para fontes de dados de banco de dados.

Depois de testar o conjunto de contexto, você pode referenciar a fonte de dados do banco de dados na chamada QueryData.

Exemplo de solicitação QueryData com contexto criado

O exemplo a seguir mostra uma solicitação QueryData usando a fonte de dados firestore_reference (Firestore com compatibilidade com o MongoDB). O campo agent_context_reference.context_set_id é usado para criar um link para o contexto pré-criado armazenado no banco de dados.

{
  "parent": "projects/context-set-project/locations/us-central1",
  "prompt": "How many accounts in the Prague region are eligible for loans?",
  "context": {
    "datasource_references": [
      {
        "firestore_reference": {
          "database_reference": {
            "project_id": "context-set-project",
            "region": "us-central1",
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/context-set-project/locations/us-central1/contextSets/bdf_pg_all_templates"
          }
        }
      }
    ]
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}

O corpo da solicitação contém os seguintes campos:

  • prompt: a pergunta em linguagem natural do usuário final.
  • context: contém informações sobre as fontes de dados.
    • datasource_references: especifica o tipo de fonte de dados.
      • firestore_reference: obrigatório ao consultar o banco de dados. Esse campo muda com base no banco de dados que você está consultando.
        • database_reference: especifica informações relacionadas à instância do banco de dados.
          • project_id: o ID do projeto do banco de dados.
          • region: a região do banco de dados.
          • database_id: o ID do banco de dados.
        • agent_context_reference: cria um link para o contexto criado no banco de dados.
          • context_set_id: o ID completo do conjunto de contexto do contexto armazenado no banco de dados. Por exemplo, projects/context-set-project/locations/us-central1/contextSets/bdf_gsql_gemini_all_templates.
  • generationOptions: configura o tipo de saída a ser gerada.
    • generate_query_result: defina como verdadeiro para gerar e retornar os resultados da consulta.
    • generate_natural_language_answer: opcional. Se definido como verdadeiro, gera uma resposta em linguagem natural.
    • generate_explanation: opcional. Se definido como verdadeiro, gera uma explicação da consulta MQL.
    • generate_disambiguation_question: opcional. Se definido como verdadeiro, gera perguntas de desambiguação se a consulta for ambígua.

Exemplo de resposta QueryData

Confira a seguir um exemplo de resposta bem-sucedida de uma chamada QueryData:

{
  "generated_query": "// Count the number of accounts in Prague that are eligible for loans\ndb.loans.aggregate([\n  // 1. Filter loans in the Prague region\n  { \n    $match: { \"district.name\": \"Prague\" } \n  },\n  // 2. Group by account_id to get distinct values, and count them\n  { \n    $group: { \n      _id: null, \n      uniqueAccounts: { $addToSet: \"$account_id\" } \n    } \n  },\n  // 3. Project the size of the unique accounts array\n  { \n    $project: { \n      _id: 0,\n      distinct_account_count: { $size: \"$uniqueAccounts\" } \n    } \n  }\n]);",
  "intent_explanation": "The question asks for the number of accounts eligible for loans in the Prague region. I need to filter the documents in the loans collection to only give me those in the Prague region. Then I need to group the loans by account ID to get distinct values and count them. Finally, I need to project the size of the array of unique accounts.",
  "query_result": {
    "columns": [
      {
        "name": "distinct_account_count"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "2"
          }
        ]
      }
    ],
    "total_row_count": 1
  },
  "natural_language_answer": "There are 2 accounts in Prague that are eligible for loans."
}

A seguir