Visão geral dos conjuntos de contexto

Visualizar

Este recurso está sujeito aos "Termos da Pré-GA" nos Termos Gerais de Serviço dos Termos Específicos de Serviço e aos Termos Adicionais para Produtos Pré-lançamento de IA Generativa. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições das fases de lançamento.

Interface PostgreSQL: Os exemplos neste tópico são destinados a bancos de dados de dialeto GoogleSQL. Esse recurso não oferece suporte à Interface PostgreSQL.

O conjunto de contextos é uma coleção de informações específicas do banco de dados que permite que ferramentas como o QueryData gerem consultas com alta precisão. O conjunto de contextos inclui modelos, facetas e pesquisas de valores que ajudam o QueryData a entender o esquema do banco de dados e a lógica de negócios dos aplicativos.

Os seguintes bancos de dados são compatíveis:

• AlloyDB para PostgreSQL
• Cloud SQL para MySQL
• Cloud SQL para PostgreSQL
• Spanner

O que são conjuntos de contextos

Para criar aplicativos de agentes eficazes, ferramentas como o QueryData precisam entender a organização de dados e a lógica de negócios. Essas informações são fornecidas na forma de um conjunto de contextos.

Você define o contexto em arquivos que contêm objetos JSON para cada tipo de contexto. Esses arquivos de contexto são criados com a ajuda da CLI do Gemini. Em seguida, faça upload do arquivo de contexto para um conjunto de contextos criado no Google Cloud console. Esse processo permite que ferramentas como o QueryData aprendam o esquema específico do banco de dados e a lógica de negócios do aplicativo.

O arquivo de contexto é semelhante a este:

{
  "templates": [
    {
      "nl_query": "Count Prague loan accounts",
      "sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" ='Prague'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = $1"
      }
    }
  ],
  "facets": [
    {
      "sql_snippet": "T.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "T.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ],
  "value_searches": [
    {
      "query": "SELECT $value as value, 'accounts.account_type' as columns, 'Account Type' as concept_type, 0 as distance, '{}'::text as context FROM \"accounts\" T WHERE T.\"account_type\" = $value",
      "concept_type": "Account Type",
      "description": "Exact match for account types"
    }
   ]
}

Formato do arquivo de conjunto de contextos

O arquivo de conjunto de contextos consiste em um conjunto selecionado de modelos e facetas no formato JSON que orientam ferramentas como o QueryData na tradução de perguntas em linguagem natural para consultas de um banco de dados específico. A definição de contexto garante a geração de SQL de alta precisão para padrões de consulta comuns.

Para maximizar a precisão, verifique se o conjunto de contextos é preciso e abrangente na cobertura das consultas de aplicativos esperadas.

Os conjuntos de contextos podem ser criados nas regiões us-central1, us-east1, europe-west4 e asia-southeast1.

Modelos de consulta

Os modelos de consulta são um conjunto selecionado de perguntas representativas em linguagem natural com consultas SQL correspondentes. Eles também incluem explicações para fornecer uma justificativa declarativa para a geração de linguagem natural para SQL.

Um objeto de modelo de consulta é semelhante a este:

{
  "templates": [
    {
      "nl_query": "Count prague loan accounts",
      "sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = 'Prague'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = $1"
      }
    }
  ]
},
...

Os principais componentes do objeto JSON do modelo de consulta são os seguintes:

• nl_query: um exemplo de consulta em linguagem natural que ferramentas como o QueryData processam.
• sql: a consulta SQL para a consulta em linguagem natural.
• intent: o objetivo ou finalidade da consulta em linguagem natural. Se não for definido, esse valor será padrão para a consulta em linguagem natural.
• manifest: uma forma generalizada e gerada automaticamente da intent.
• parameterized_intent: uma forma de modelo gerada automaticamente da intent, com valores de entidade substituídos por parâmetros.
• parameterized_sql: uma forma de modelo gerada automaticamente da consulta SQL que corresponde à intent parametrizada.

Facetas de consulta

As facetas de consulta são um conjunto selecionado de condições representativas de linguagem natural com predicados SQL correspondentes. As facetas gerenciam a filtragem e as condições, o que permite que os modelos de consulta realizem pesquisas facetadas.

Um objeto de faceta de consulta é semelhante a este:

{
...
"facets": [
    {
      "sql_snippet": "T.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "T.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ]
}

Os principais componentes do objeto JSON de faceta são os seguintes:

• sql_snippet: um snippet SQL.
• intent: uma explicação do predicado SQL.
• manifest: uma forma generalizada e gerada automaticamente da intent.
• parameterized_intent: uma forma de modelo gerada automaticamente da intent, com valores de entidade substituídos por parâmetros.
• parameterized_sql_snippet: uma forma de modelo gerada automaticamente do sql_snippet que corresponde à intent parametrizada.

Consultas de pesquisa de valores

As [consultas de pesquisa de valores](/spanner/docs/build-context-gemini-cli#generate-value-searches) são consultas definidas pelo desenvolvedor que usam funções de correspondência para encontrar valores e o contexto deles em um banco de dados. A vinculação de valores usa os resultados dessas consultas para identificar quais tabelas e colunas contêm um valor correspondente, entender o tipo de conceito do valor e corrigir erros de ortografia.

A API QueryData usa a vinculação de valores para converter a linguagem natural em SQL com mais precisão. Ao usar consultas de pesquisa de valores, a API pode corrigir erros de ortografia e resolver tipos de valores com base nos valores do banco de dados, melhorando a precisão da conversão.

A vinculação de valores melhora a precisão da conversão de linguagem natural para SQL. Por exemplo, se um usuário perguntar "Há voos saindo de Heathrow?", o banco de dados poderá armazenar o nome do aeroporto como "London Heathrow". Sem a vinculação de valores, o SQL gerado poderá filtrar por WHERE name = 'Heathrow' e não retornar resultados. As consultas de pesquisa de valores orientam o agente a mapear "Heathrow" para o valor correto do banco de dados "London Heathrow" e o local do esquema (airports.name), garantindo que o SQL gerado seja preciso.

Um exemplo de consulta de pesquisa de valores é:

{
  ...
  "value_searches": [
    {
      "query": "SELECT $value as value, 'airports.iata' as columns, 'Airport IATA Code' as concept_type, 0 as distance, '{}'::text as context FROM \"airports\" T WHERE T.\"iata\" = $value",
      "concept_type": "Airport IATA Code",
      "description": "Exact match (Standard SQL) for 3-letter airport codes"
    },
    {
      "query": "WITH TrigramMetrics AS ( SELECT T.\"name\" AS original_value, (T.\"name\" <-> $value::text) AS normalized_dist FROM \"airports\" T WHERE T.\"name\" % $value::text ) SELECT original_value AS value, 'airports.name' AS columns, 'Airport Name' AS concept_type, normalized_dist AS distance, '{}'::text AS context FROM TrigramMetrics",
      "concept_type": "Airport Name",
      "description": "Fuzzy match using standard trigram for partial airport names"
    }
  ]
}

Os principais componentes do objeto JSON de pesquisa de valores são os seguintes:

• query: uma instrução SQL parametrizada que define a lógica para corresponder uma frase de valor aos valores armazenados em uma coluna de uma tabela em um banco de dados. O conjunto de resultados normalmente projeta o valor correspondente, o local do esquema, o tipo de conceito e uma métrica de distância normalizada (entre 0 e 1).
• concept_type: um rótulo semântico atribuído ao valor, por exemplo, o district ou o loan_status. Esse rótulo ajuda a vinculação de valores e, por fim, as ferramentas, como a API QueryData, a entender o papel da frase de valor no esquema. Ele também ajuda a produzir uma instrução SQL que segmenta o conceito do valor, bem como a tabela e a coluna em que a frase de valor aparece.
• description: uma descrição da lógica de pesquisa.

Limitações

Os conjuntos de contextos têm as seguintes limitações:

• Os conjuntos de contextos para bancos de dados oferecem suporte apenas a modelos, facetas e pesquisas de valores.
• Os conjuntos de contextos para bancos de dados são usados apenas pelo endpoint QueryData na API Análises de conversação.

Aviso: todos os contextos de agente associados a um banco de dados podem ser visualizados por todos os usuários com acesso de leitura a esse banco de dados. Nos casos em que os usuários têm acesso mais restrito ao banco de dados, como o controle de acesso refinado do Spanner, eles podem descobrir outros campos e tabelas no contexto do agente.

A seguir

• Saiba como criar ou excluir um conjunto de contextos no Spanner Studio.