Test QueryData

Neste documento, descrevemos como testar o QueryData para o Spanner Graph chamando o método QueryData da API Análise conversacional e como atualizar o arquivo de conjunto de contexto. É possível testar a capacidade do QueryData de gerar consultas em linguagem GraphQL (GQL) com base em perguntas em linguagem natural. Se uma consulta GQL gerada não for precisa, atualize o arquivo de conjunto de contexto.

Para aprender mais sobre os conjuntos de contexto do Spanner Graph, consulte Visão geral dos conjuntos de contexto.

Antes de começar

Encontrar o ID do conjunto de contexto atual

Para testar o QueryData com seu conjunto de contexto ou conectar um aplicativo de dados ao QueryData, você precisa do ID do conjunto de contexto.

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

    Acessar o Spanner

  2. Selecione uma instância na lista e, em seguida, um banco de dados.

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

  4. No painel Explorador, 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 conjunto de contextos em ID do conjunto de contextos. O formato do ID do conjunto de contexto é semelhante a projects/my-project/locations/us-central1/contextSets/fingraph-assistant.

Testar QueryData usando HTTP POST

Para testar o QueryData para o Spanner Graph, envie uma solicitação POST HTTP QueryData que inclua o campo graph_ids e o ID do conjunto de contexto:

  1. Crie um arquivo chamado request.json com o conteúdo a seguir:

    {
      "prompt": "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts.",
      "context": {
        "datasource_references": {
          "spanner_reference": {
            "database_reference": {
              "engine": "GOOGLE_SQL",
              "project_id": "PROJECT_ID",
              "instance_id": "INSTANCE_ID",
              "database_id": "DATABASE_ID",
              "graph_ids": ["FinGraph"]
            },
            "agent_context_reference": {
              "context_set_id": "CONTEXT_SET_ID"
            }
          }
        }
      },
      "generation_options": {
        "generate_query_result": true,
        "generate_natural_language_answer": true,
        "generate_explanation": true
      }
    }

    Substitua:

    • PROJECT_ID: o ID do projeto Google Cloud .
    • INSTANCE_ID: o ID da instância do Spanner.
    • DATABASE_ID: o ID do banco de dados do Spanner.
    • CONTEXT_SET_ID: o ID completo do conjunto de contexto que você anotou em Encontrar o ID do conjunto de contexto.
  2. Envie a solicitação:

    curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -H "x-goog-user-project: PROJECT_ID" \
      "https://geminidataanalytics.googleapis.com/v1beta/projects/PROJECT_ID/locations/global:queryData" \
      -d @request.json
    
  3. Na resposta, verifique se o campo generatedQuery (GRAPH FinGraph MATCH ...) está correto e confira o campo queryResult para ver as linhas retornadas.

Para testar outras perguntas, mude o valor de prompt em request.json e envie a solicitação novamente. Para ver como o QueryData se comporta sem o contexto criado, remova o objeto agent_context_reference.

Para verificar se o QueryData usa o conjunto de contexto, faça uma pergunta que dependa dele (como "Quem é o proprietário da conta de reserva de emergência?") e compare as respostas com e sem o objeto agent_context_reference. Sem o contexto definido, QueryData pode filtrar em 'rainy day' e não retornar linhas. Com o contexto definido, ele filtra em 'Rainy Day Fund' e retorna Dana.

Baixar e atualizar o conjunto de contexto atual

Se as respostas do teste mostrarem que a consulta GQL gerada para uma pergunta em linguagem natural precisa ser melhorada, faça o download do arquivo de conjunto de contexto atual. Em seguida, revise e atualize os modelos de consulta GQL, as facetas ou as pesquisas de valor e faça upload do arquivo de conjunto de contexto atualizado para o conjunto de contexto.

Para baixar e atualizar um conjunto de contexto, siga estas etapas:

  1. No painel Explorer, clique em Ver ações ao lado do conjunto de contexto.
  2. Clique em Baixar arquivo de contexto.
  3. Siga as etapas em Criar conjuntos de contexto usando o agente de engenharia de contexto para atualizar o conjunto de contexto com mais pares de consulta de linguagem natural para GQL.
  4. No painel Explorador, 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 do conjunto de contexto e selecione o arquivo atualizado.
  7. Clique em Salvar para atualizar o conjunto de contexto.
  8. Teste QueryData novamente para verificar a consulta GQL gerada.

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

Conectar o QueryData ao seu aplicativo

Defina o ID do conjunto de contexto e o graph_ids de destino na chamada do método QueryData para fornecer o contexto criado e ativar a geração de consultas GQL para o Spanner Graph. Para mais informações sobre como usar QueryData com fontes de dados de banco de dados, consulte Definir o contexto do agente de dados para fontes de dados de banco de dados. Para ver um exemplo que conecta um aplicativo de agente ao QueryData usando uma ferramenta HTTP personalizada que chama a API REST do QueryData, consulte Integrar o QueryData a um aplicativo.

Exemplo de solicitação QueryData com contexto criado

O exemplo a seguir mostra uma solicitação QueryData que usa a fonte de dados do banco de dados spanner_reference para o gráfico de propriedades FinGraph. É necessário fornecer graph_ids dentro de spanner_reference.database_reference para que o QueryData segmente seu gráfico de propriedades e gere consultas GQL. O campo agent_context_reference.context_set_id se vincula ao contexto pré-criado armazenado no banco de dados:

{
  "parent": "projects/my-project/locations/global",
  "prompt": "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts.",
  "context": {
    "datasource_references": {
      "spanner_reference": {
        "database_reference": {
          "engine": "GOOGLE_SQL",
          "project_id": "my-project",
          "instance_id": "my-instance",
          "database_id": "fin-graph-db",
          "graph_ids": [
            "FinGraph"
          ]
        },
        "agent_context_reference": {
          "context_set_id": "projects/my-project/locations/us-central1/contextSets/fingraph-assistant"
        }
      }
    }
  },
  "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:

  • parent: opcional. O projeto e o local da solicitação, no formato projects/PROJECT_ID/locations/LOCATION. Use o mesmo projeto e local do URL da solicitação.
  • prompt: a pergunta em linguagem natural do usuário final.
  • context: contém informações sobre as fontes de dados.
    • datasource_references: especifica a fonte de dados. Este campo é um objeto, não uma lista.
      • spanner_reference: obrigatório ao consultar um banco de dados do Spanner.
        • database_reference: especifica informações relacionadas ao banco de dados do Spanner e aos gráficos de propriedades.
          • engine: o dialeto do banco de dados. Defina como GOOGLE_SQL para bancos de dados do Spanner Graph.
          • project_id: o ID do projeto da instância do Spanner.
          • instance_id: o ID da instância do Spanner.
          • database_id: o ID do banco de dados do Spanner.
          • graph_ids: obrigatório para o Spanner Graph. Uma lista de nomes de gráficos de propriedades no banco de dados para consulta (por exemplo, ["FinGraph"]). Fornecer graph_ids instrui o QueryData a gerar consultas GQL nos gráficos de propriedades especificados. Se você omitir graph_ids, o QueryData vai gerar apenas consultas SQL relacionais nas tabelas subjacentes.
        • agent_context_reference: links para o contexto criado no banco de dados.
          • context_set_id: o ID completo do conjunto de contexto armazenado no banco de dados, como projects/my-project/locations/us-central1/contextSets/fingraph-assistant.
  • generation_options: configura o tipo de saída a ser gerada.
    • generate_query_result: defina como true para executar a consulta GQL gerada e retornar os resultados.
    • generate_natural_language_answer: opcional. Se definido como true, gera uma resposta em linguagem natural que resume os resultados da consulta.
    • generate_explanation: opcional. Se definido como true, gera uma explicação da consulta GQL.
    • generate_disambiguation_question: opcional. Se definido como true, gera perguntas de desambiguação se o comando em linguagem natural for ambíguo.

Exemplo de resposta QueryData

O exemplo a seguir mostra uma resposta bem-sucedida de uma chamada QueryData no gráfico de propriedades FinGraph. A API REST retorna nomes de campo em camelCase, como generatedQuery e queryResult. Como a geração de GQL não é determinista, a consulta gerada, os nomes das colunas e o texto da resposta podem variar entre as chamadas.

{
  "generatedQuery": "GRAPH `FinGraph` MATCH (p:`Person` {`name`: 'Dana'})-[:`Owns`]->(src:`Account`)-[t:`Transfers`]->(dst:`Account`) MATCH (p_recipient:`Person`)-[:`Owns`]->(dst) RETURN DISTINCT p_recipient.`name` AS recipient_name, dst.`id` AS recipient_account_id, t.`amount` AS transfer_amount",
  "intentExplanation": "To find everyone Dana transferred money to, we identify the person named Dana and locate the accounts they own. We trace the transfer relationships from Dana's accounts to any destination accounts, identifying the specific amounts sent and the IDs of those receiving accounts. Finally, we find the individuals who own those receiving accounts to present their names along with the account details and transfer amounts.",
  "queryResult": {
    "columns": [
      {
        "name": "recipient_name",
        "type": "STRING"
      },
      {
        "name": "recipient_account_id",
        "type": "INT64"
      },
      {
        "name": "transfer_amount",
        "type": "FLOAT64"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "Alex"
          },
          {
            "value": "7"
          },
          {
            "value": "500"
          }
        ]
      },
      {
        "values": [
          {
            "value": "Lee"
          },
          {
            "value": "16"
          },
          {
            "value": "200"
          }
        ]
      }
    ],
    "totalRowCount": "2"
  },
  "naturalLanguageAnswer": "Based on the transaction records, Dana transferred money to the following recipients:\n\n*   **Alex**: Account ID **7**, with a transfer amount of **500**\n*   **Lee**: Account ID **16**, with a transfer amount of **200**"
}

A seguir