Inspecione e chame um agente de dados

Este documento descreve como inspecionar um agente e atualizar o ficheiro de contexto do agente. Pode inspecionar um agente para testar a respetiva capacidade de gerar consultas SQL a partir de perguntas em linguagem natural. Se uma consulta gerada não for precisa, pode atualizar o contexto do agente.

Para saber mais sobre os agentes de dados, consulte o artigo Vista geral dos agentes de dados.

Antes de começar

Certifique-se de que já foi criado um agente de dados e que o contexto do agente foi carregado para o agente de dados. Para mais informações, consulte o artigo Faça a gestão de agentes de dados no Spanner Studio.

Inspeccione um agente de dados

Para inspecionar um agente de dados, siga estes passos:

  1. Na Google Cloud consola, aceda à página do Spanner.

    Aceda ao Spanner

  2. Selecione uma instância na lista e, de seguida, selecione uma base de dados.

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

  4. No painel do explorador, junto a Agentes de dados, clique em Ver ações.

  5. Clique em Inspecionar agente.

  6. No editor de consultas, clique em Gerar SQL para abrir o painel Ajuda-me a programar.

  7. Introduza uma pergunta em linguagem natural para gerar uma consulta SQL e clique em Gerar.

  8. Reveja a consulta SQL para verificar a precisão.

Transfira e atualize o contexto de um agente de dados

Se não estiver satisfeito com a consulta SQL gerada para uma pergunta em linguagem natural, transfira o ficheiro de contexto do agente existente. Em seguida, pode rever e atualizar o modelo de consulta e voltar a carregar o ficheiro de contexto atualizado para o agente.

Para transferir e atualizar o contexto de um agente de dados, siga estes passos:

  1. No painel do explorador, junto a Agentes de dados, clique em Ver ações.
  2. Clique em Transferir ficheiro de contexto do agente.
  3. Siga os passos em Crie contextos com a Gemini CLI para atualizar o contexto com pares de consultas adicionais.
  4. No painel do explorador, junto ao agente de dados, clique em Ver ações.
  5. Clique em Editar agente.
  6. Clique em Procurar na secção Carregar ficheiro de contexto do agente e selecione o ficheiro de contexto do agente atualizado.
  7. Clique em Guardar para atualizar o contexto do agente.

Depois de se certificar da precisão das suas respostas, pode usar o ponto final QueryData para ligar a sua aplicação ao agente de dados.

Encontre o ID do contexto do agente

Para associar uma aplicação de dados ao agente de dados, precisa do ID do contexto do agente.

  1. Na Google Cloud consola, aceda à página do Spanner.

    Aceda ao Spanner

  2. Selecione uma instância na lista e, de seguida, selecione uma base de dados.

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

  4. No painel do explorador, junto a Agentes de dados, clique em Ver ações.

  5. Clique em Editar agente.

  6. Tome nota do ID do contexto em ID do contexto do agente. O formato do ID do contexto do agente é semelhante a projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_pg_all_templates.

Associe o agente de dados à aplicação

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

Depois de inspecionar o agente de dados, pode fazer referência à origem de dados da base de dados na sua chamada QueryData.

Exemplo de pedido QueryData com contexto criado

O exemplo seguinte mostra um pedido QueryData que usa a origem de dados da base de dados spanner_reference. O campo agent_context_reference.context_set_id é usado para criar um link para o contexto pré-criado armazenado na base de dados.

{
  "parent": "projects/cloud-db-nl2sql/locations/us-central1",
  "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.",
  "context": {
    "datasource_references": [
      {
        "spanner_reference" {
          "database_reference" {
            "engine": "GOOGLE_SQL"
            "project_id": "cloud-db-nl2sql"
            "region": "us-central1"
            "instance_id": "evalbench"
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/cloud-db-nl2sql/locations/us-east1/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 do pedido contém os seguintes campos:

  • prompt: a pergunta em linguagem natural do utilizador final.
  • context: contém informações sobre as origens de dados.
    • datasource_references: especifica o tipo de origem de dados.
      • spanner_reference: obrigatório ao consultar a base de dados. Este campo muda com base na base de dados que está a consultar.
        • database_reference: especifica informações relacionadas com a sua instância da base de dados.
          • engine: O dialeto SQL da base de dados. Definido como GOOGLE_SQL para bases de dados do Spanner.
          • project_id: o ID do projeto da instância da base de dados.
          • region: a região da instância do Spanner.
          • instance_id: o ID da instância do Spanner.
          • database_id: o ID da base de dados.
        • agent_context_reference: links para o contexto criado na base de dados.
          • context_set_id: o ID do contexto do agente completo do contexto armazenado na base de dados. Por exemplo, projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_gsql_gemini_all_templates.
  • generationOptions: configura o tipo de resultado a gerar.
    • generate_query_result: definido como verdadeiro para gerar e devolver os resultados da consulta.
    • generate_natural_language_answer: opcional. Se estiver definida como verdadeira, gera uma resposta em linguagem natural.
    • generate_explanation: opcional. Se for definida como verdadeira, gera uma explicação da consulta SQL.
    • generate_disambiguation_question: opcional. Se estiver definida como verdadeira, gera perguntas de desambiguação se a consulta for ambígua.

Exemplo de resposta QueryData

Segue-se um exemplo de uma resposta bem-sucedida de uma chamada QueryData:

{
  "generated_query": "-- Count the number of accounts in Prague that are eligible for loans\nSELECT\n  COUNT(DISTINCT \"loans\".\"account_id\")\nFROM \"loans\"\nJOIN \"district\" -- Join based on district ID\n  ON \"loans\".\"district_id\" = \"district\".\"district_id\"\nWHERE\n  \"district\".\"A3\" = 'Prague'; -- Filter for the Prague region",
  "intent_explanation": "The question asks for the number of accounts eligible for loans in the Prague region. I need to join the `district` table with the `loans` table to filter by region and count the distinct accounts. The `A3` column in the `district` table contains the region information, and I'll filter for 'Prague'. The `loans` table contains information about loans, including the `account_id` and `district_id`. I will join these two tables on their respective district IDs.",
  "query_result": {
    "columns": [
      {
        "name": "count"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "2"
          }
        ]
      }
    ],
    "total_row_count": 1
  },
  "natural_language_answer": "There are 2 accounts in Prague that are eligible for loans."
}

O que se segue?