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.

O conjunto de contexto é 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. Os conjuntos de contexto podem incluir modelos, facetas e pesquisas de valor que ajudam o QueryData a entender o esquema do banco de dados e a lógica de negócios dos seus aplicativos.

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

• AlloyDB para PostgreSQL
• Cloud SQL para MySQL
• Cloud SQL para PostgreSQL
• Spanner
• Firestore com compatibilidade com o MongoDB
• Bigtable

O que são conjuntos de contexto

Para criar aplicativos agênticos eficazes, ferramentas como o QueryData precisam entender a organização dos dados e a lógica de negócios. Você fornece essas informações na forma de um conjunto de contexto.

Você define o contexto em arquivos que contêm objetos JSON para cada tipo de contexto. É possível criar esses arquivos de contexto com a ajuda do agente de engenharia de contexto. Em seguida, faça upload do arquivo de contexto para um conjunto de contexto criado no console do Google Cloud. 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 ao seguinte:

O arquivo de contexto do agente é semelhante ao seguinte:

{
  "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": "employee.\"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": "employee.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ]
}

Formato do arquivo do conjunto de contexto

Um arquivo de conjunto de contexto consiste em um conjunto selecionado de modelos, facetas e pesquisas de valor no formato JSON que orientam ferramentas como o QueryData na tradução de perguntas em linguagem natural em consultas para um banco de dados específico. Definir o 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 contexto é preciso e abrangente na cobertura das consultas de aplicativo esperadas.

Os conjuntos de contexto podem ser criados nas regiões us-central1, us-east1, europe-west4 e asia-southeast1. É preciso selecionar uma região ao criar o primeiro conjunto de contexto em um projeto. Os conjuntos de contexto posteriores usam a mesma região.

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 QueryData processam.
• sql: a consulta SQL para a consulta em linguagem natural.
• intent: o objetivo ou propósito da consulta em linguagem natural. Se não for definido, esse valor será padronizado para a consulta em linguagem natural.
• manifest: uma forma generalizada e gerada automaticamente da intent.
• parameterized_intent: um formulário de intent gerado automaticamente com base em um modelo, 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. Os atributos gerenciam filtros e condições, o que permite que os modelos de consulta realizem pesquisas de atributos.

Um objeto de atributo de consulta é semelhante a este:

{
...
"facets": [
    {
      "sql_snippet": "employee.\"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": "employee.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ]
}

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

• sql_snippet: um snippet SQL. Para evitar ambiguidade, qualifique os nomes das colunas com os nomes das tabelas (por exemplo, table_name.column_name).
• intent: uma explicação do predicado SQL.
• manifest: uma forma generalizada e gerada automaticamente da intent.
• parameterized_intent: um formulário de intent gerado automaticamente com base em um modelo, 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.

Valorizar as consultas de pesquisa

Consultas de pesquisa de valor 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 linguagem natural em SQL com mais precisão. Ao usar consultas de pesquisa de valor, a API pode corrigir erros de ortografia e resolver tipos de valor 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 em 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 pode filtrar por WHERE name = 'Heathrow' e não retornar resultados. As consultas de pesquisa de valor 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.

Veja um exemplo de consulta de pesquisa de valor:

{
  ...
  "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"
    },
    {
      "query": "WITH SemanticMetrics AS ( SELECT T.\"city\" AS original_value, ( (google_ml.embedding('gemini-embedding-001', $value)::vector <=> google_ml.embedding('gemini-embedding-001', T.\"city\")::vector) / 2.0 ) AS normalized_dist FROM \"airports\" T WHERE T.\"city\" IS NOT NULL ) SELECT original_value AS value, 'airports.city' AS columns, 'Airport City' AS concept_type, normalized_dist AS distance, '{}'::text AS context FROM SemanticMetrics",
      "concept_type": "Airport City",
      "description": "Semantic search on string values for airport city names"
    }
  ]
}

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

• query: uma instrução SQL parametrizada que define a lógica para comparar uma frase de valor com os valores armazenados 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, district ou loan_status. Esse rótulo ajuda a vincular 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 contexto têm as seguintes limitações:

• O Cloud SQL para SQL Server não é compatível.
• Os conjuntos de contexto para bancos de dados só aceitam modelos, atributos e pesquisas de valor.
• Os conjuntos de contexto para bancos de dados são usados apenas pelo endpoint QueryData na API Conversational Analytics.

A seguir

• Saiba como criar ou excluir um conjunto de contexto no Cloud SQL Studio.
• Saiba como criar conjuntos de contextos usando o agente de engenharia de contexto.