Gerar consultas SQL usando perguntas em linguagem natural

Nesta página, descrevemos como configurar, configurar e gerar instruções SQL usando a linguagem natural da IA do AlloyDB. Com a linguagem natural, é possível criar aplicativos de IA generativa voltados ao usuário usando linguagem natural para consultar bancos de dados.

Para ativar a extensão alloydb_ai_nl, que é a API de suporte a linguagem natural do AlloyDB para PostgreSQL, siga estas etapas gerais:

  1. Instale a extensão alloydb_ai_nl.
  2. Defina uma configuração de linguagem natural para seu aplicativo.
  3. Registre um esquema.
  4. Adicione contexto.
  5. Adicione modelos de consulta.
  6. Defina tipos de conceito e crie um índice de valor.
  7. Gerar instruções SQL usando uma interface de linguagem natural.

Antes de começar

  • Solicite acesso à linguagem natural da IA do AlloyDB e aguarde até receber a confirmação de ativação antes de seguir as instruções nesta página.
  • Entenda como se conectar ao banco de dados do AlloyDB e executar comandos do PostgreSQL. Para mais informações, consulte Visão geral da conexão.
  • Preencha o banco de dados com os dados e o esquema que o usuário final quer acessar.

Criar um cluster e ativar a integração com a Vertex AI

  1. Crie um cluster e uma instância do AlloyDB. Use a instância do AlloyDB para criar o banco de dados e o esquema do aplicativo.
  2. Ative a integração com a Vertex AI. Para mais informações, consulte Integração com a Vertex AI.

Funções exigidas

Para instalar a extensão alloydb_ai_nl e conceder acesso a outros usuários, você precisa ter o seguinte papel do gerenciamento de identidade e acesso (IAM) no projeto Google Cloud que está usando:

Para mais informações, consulte Gerenciar usuários do PostgreSQL com a autenticação integrada.

Preparar o ambiente

Para se preparar para gerar consultas em linguagem natural, instale a extensão necessária, crie uma configuração e registre um esquema.

Instalar a extensão alloydb_nl_ai

A extensão alloydb_ai_nl usa a extensão google_ml_integration, que interage com modelos de linguagem grandes (LLMs), incluindo modelos do Gemini na Vertex AI.

Para instalar a extensão alloydb_ai_nl, conecte-se ao banco de dados e execute o seguinte comando:

CREATE EXTENSION alloydb_ai_nl cascade;

Criar uma configuração de linguagem natural e registrar um esquema

A linguagem natural da IA do AlloyDB usa o nl_config para associar aplicativos a determinados esquemas, modelos de consulta e endpoints de modelo. nl_config é uma configuração que associa um aplicativo a esquemas, modelos e outros contextos. Um aplicativo grande também pode usar configurações diferentes para diferentes partes dele, desde que você especifique a configuração certa quando uma pergunta for enviada dessa parte do aplicativo. É possível registrar um esquema inteiro ou objetos específicos, como tabelas, visualizações e colunas.

  1. Para criar uma configuração de linguagem natural, use o exemplo a seguir:

    SELECT
  alloydb_ai_nl.g_create_configuration(
    'my_app_config'        -- configuration_id
  );

    gemini-2.0-flash:generateContent é o endpoint do modelo.

  2. Para registrar um esquema para uma configuração especificada, use o seguinte exemplo:

    SELECT
  alloydb_ai_nl.g_manage_configuration(
    operation => 'register_schema',
    configuration_id_in => 'my_app_config',
    schema_names_in => '{my_schema}'
  );

Adicione contexto

O contexto inclui qualquer tipo de informação que você pode usar para responder a uma pergunta do usuário final. O contexto inclui estrutura e relacionamentos de esquema, resumos e descrições de colunas, valores de coluna e semântica, além de regras ou declarações de lógica de negócios específicas do aplicativo ou domínio.

Adicionar contexto geral para regras específicas do aplicativo

Os itens de contexto geral incluem regras específicas do aplicativo, declarações de lógica de negócios ou qualquer terminologia específica do aplicativo e do domínio que não esteja vinculada a um objeto de esquema específico.

Para adicionar contexto geral a regras específicas do aplicativo e terminologia específica do aplicativo ou domínio, siga estas etapas:

  1. Para adicionar um item de contexto geral à configuração especificada, use o exemplo a seguir:

    SELECT
  alloydb_ai_nl.g_manage_configuration(
    'add_general_context',
    'my_app_config',
    general_context_in => '{"If the user asks for a good seat, assume that means a window or aisle seat."}'
  );

    A declaração anterior ajuda a IA do AlloyDB a fornecer respostas de maior qualidade às perguntas dos usuários em linguagem natural.

  2. Para conferir os contextos gerais da configuração especificada, execute a seguinte instrução:

    SELECT alloydb_ai_nl.list_general_context(nl_config TEXT);

Gerar e revisar o contexto do esquema

O contexto do esquema descreve objetos de esquema, incluindo tabelas, visualizações, visualizações materializadas e colunas. Esse contexto é armazenado como o COMMENT de cada objeto de esquema.

  1. Para gerar contextos para objetos de esquema, chame as seguintes APIs. Para ter os melhores resultados, verifique se as tabelas do banco de dados contêm dados representativos.

    -- For all schema objects (tables, views, materialized views and columns)
-- within the scope of a provided nl_config.
SELECT
  alloydb_ai_nl.generate_schema_context(
    'my_app_config' -- nl_config
  );

  2. Analise os contextos de esquema gerados executando a seguinte instrução:

    SELECT schema_object, object_context
FROM alloydb_ai_nl.generated_schema_context_view;

    Os contextos de esquema gerados são armazenados na visualização anterior.

  3. Opcional: para atualizar os contextos de esquema gerados, execute a seguinte instrução:

    SELECT
  alloydb_ai_nl.update_generated_relation_context(
    'my_schema.my_table',
    'This table contains archival records, if you need latest records use records_new table.'
  );

SELECT
  alloydb_ai_nl.update_generated_column_context(
    'my_schema.my_table.column1',
    'The seat_class column takes single letters like "E" for economy, "P" for premium economy, "B" for business and "F" for First.'
  );

  4. Aplique o contexto. Quando você aplica o contexto, ele entra em vigor imediatamente e é excluído do generated_schema_context_view. Execute o comando a seguir:

    -- For all schema objects (tables, views, materialized views and columns)
-- within the scope of nl_config.
SELECT
  alloydb_ai_nl.apply_generated_schema_context(
    'my_app_config' --nl_config
  );

  5. Opcional: verifique o contexto gerado. A API a seguir permite verificar os contextos de esquema, que são usados ao gerar instruções SQL:

    -- For table, view or materialized view.
SELECT
  alloydb_ai_nl.get_relation_context(
    'my_schema.my_table'
  );

-- For column.
SELECT
  alloydb_ai_nl.get_column_context(
    'my_schema.my_table.column1'
  );

  6. Opcional: para definir manualmente o contexto do esquema, execute a seguinte instrução:

    -- For table, view or materialized view.
SELECT
  alloydb_ai_nl.set_relation_context(
    'my_schema.my_table',
    'One-to-many mapping from product to categories'
  );

-- For column.
SELECT
  alloydb_ai_nl.set_column_context(
    'my_schema.my_table.column1',
    'This column provides additional tagged info for the product in  Json format, e.g., additional color or size information of the product - tags: { "color": "red", "size": "XL"}'
  );

Criar modelos de consulta

Para melhorar a qualidade dos aplicativos de IA generativa criados com LLMs, adicione modelos. Um modelo de consulta é um conjunto selecionado de perguntas representativas ou comuns em linguagem natural, com consultas SQL correspondentes e explicações para fornecer uma justificativa declarativa para a geração de linguagem natural para SQL (NL2SQL). Os modelos são destinados principalmente a serem especificados pelo aplicativo, mas também podem ser gerados automaticamente pela extensão alloydb_ai_nl com base em consultas SQL usadas com frequência. Cada modelo precisa estar associado a um nl_config.

A extensão alloydb_ai_nl usa um template_store para incorporar dinamicamente modelos SQL relevantes no processo de geração de uma instrução SQL para responder à pergunta do usuário. O template_store identifica modelos com intenções semelhantes à pergunta em linguagem natural, identifica a instrução SQL parametrizada correspondente e sintetiza uma instrução SQL ao instanciar parâmetros com valores da pergunta em linguagem natural. No entanto, se não houver um modelo com a mesma intenção da pergunta feita pelo usuário, o alloydb_ai_nl vai usar todos os modelos e contextos relevantes para criar uma instrução SQL.

Para adicionar modelos, especifique a pergunta usando um parâmetro chamado intent e a consulta SQL.

Para adicionar um modelo à loja, execute a seguinte instrução:

SELECT
  alloydb_ai_nl.add_template(
    nl_config => 'my_app_config',
    intent => 'How many accounts associated with loans are located in the Prague region?',
    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''',
    check_intent => TRUE
  );

Quando check_intent é TRUE, alloydb_ai_nl realiza uma verificação semântica para confirmar se a intenção fornecida corresponde à instrução SQL transmitida. Se a intent não corresponder à instrução SQL, o modelo não será adicionado.

Gerar modelos automaticamente

Depois de ter um conjunto de dados representativo nas suas tabelas, recomendamos que você execute consultas SQL que correspondam às perguntas comuns que seus usuários finais provavelmente farão. É importante garantir que as consultas tenham bons planos e funcionem bem.

Depois de executar as consultas, a linguagem natural da IA do AlloyDB pode gerar modelos automaticamente com base no histórico de consultas. É possível chamar as seguintes APIs para gerar modelos. Você precisa revisar e aplicar os modelos gerados antes que eles entrem em vigor.

A geração automática de modelos se baseia nas consultas mais usadas no registro de consultas, google_db_advisor_workload_statements. As consultas são filtradas com base nos seguintes critérios:

  • SELECT instruções
  • Executáveis: o comando EXPLAIN processa a consulta com sucesso.
  • Sem duplicação: a consulta não foi usada antes para gerar modelos.
  • Todas as tabelas e visualizações referenciadas estão no escopo do nl_config.

Para gerar, revisar e aplicar modelos automaticamente, siga estas etapas:

  1. Peça ao AlloyDB para gerar modelos com base no seu histórico de consultas:

    SELECT
  alloydb_ai_nl.generate_templates(
    'my_app_config',
);

    Use a visualização fornecida, alloydb_ai_nl.generated_templates_view, para analisar o generated_templates.

    A saída a seguir mostra o número de modelos gerados:

    -[ RECORD 1 ]------+--
generate_templates | 1

  2. Revise os modelos gerados usando a visualização generated_templates_view.

    SELECT *
FROM alloydb_ai_nl.generated_templates_view;

    Confira abaixo um exemplo da saída retornada:

    -[ RECORD 1 ]----------------------------------------------------------------
id          | 1
config      | my_app_config
type        | Template
manifest    | How many clients have a birth year of a given number?
nl          | How many clients have a birth year of 1997?
sql         | select count(*) from public.client as T where
             to_char(T.birth_date::timestamp, 'YYYY') = '1997';
intent      | How many clients have a birth year of 1997?
psql        | select count(*) from public.client as T where
             to_char(T.birth_date::timestamp, 'YYYY') = $1;
pintent     | How many clients have a birth year of $1?
comment     |
explanation |
weight      | 1

    O manifest na saída retornada é um modelo geral ou uma descrição ampla do tipo de pergunta ou da operação que pode ser realizada. O pintent é uma versão parametrizada do intent, e generaliza intent substituindo o valor específico (1997) por um marcador de posição ($1).

  3. Para atualizar um modelo gerado, execute a seguinte instrução de exemplo:

    SELECT alloydb_ai_nl.update_generated_template(
  id => 1,
  manifest => 'How many clients are born in a given year?',
  nl => 'How many clients are born in 1997?',
  intent => 'How many clients are born in 1997?',
  pintent => 'How many clients are born in $1?'

);

  4. Aplique os modelos. Os modelos aplicados são adicionados imediatamente à loja de modelos e excluídos da visualização de revisão.

    -- For all templates generated under the nl config.
SELECT
  alloydb_ai_nl.apply_generated_templates('my_app_config');

Configurar a segurança para linguagem natural

Para configurar a segurança da linguagem natural da IA do AlloyDB, consulte Gerenciar a segurança de aplicativos de dados usando visualizações seguras parametrizadas.

Definir tipos de conceito e índice de valor

Você define tipos de conceito e índices de valor para entender melhor as perguntas feitas. Um tipo de conceito é uma categoria ou classe de entidades que identifica o significado semântico de palavras e frases, e não apenas a forma literal delas.

Por exemplo, dois nomes de países podem ser iguais, mesmo que um esteja em maiúsculas, como USA, e o outro em minúsculas, como usa. Nesse caso, o nome do país é o tipo de conceito. Outros exemplos de tipos de conceitos incluem nome de pessoa, nome de cidade e data.

Um índice de valor é um índice sobre os valores nas colunas que fazem parte da configuração de linguagem natural nl_config, com base nos tipos de conceito associados a cada coluna. Um índice de valor permite a correspondência eficiente de frases de valor para a pergunta feita e os valores no banco de dados.

Para definir tipos de conceito e um índice de valor, siga estas etapas usando os exemplos fornecidos. Os exemplos associam uma coluna a um tipo de conceito, criam e atualizam um índice de valor e usam um conjunto de sinônimos para realizar uma pesquisa de valor.

  1. Para associar uma coluna a um tipo de conceito, execute a seguinte consulta:

    SELECT
  alloydb_ai_nl.associate_concept_type(
    column_names_in => 'my_schema.country.country_name',
    concept_type_in => 'country_name',
    nl_config_id_in => 'my_app_config'
  );

  2. Para criar um índice de valor com base em todas as colunas que fazem parte de uma configuração de linguagem natural e estão associadas a um tipo de conceito, execute a seguinte instrução:

    SELECT
  alloydb_ai_nl.create_value_index(
    nl_config_id_in => 'my_app_config'
  );

  3. Ao associar tipos de conceito a novas colunas, atualize o índice de valor para refletir as mudanças. Use a seguinte instrução:

    SELECT
  alloydb_ai_nl.refresh_value_index(
    nl_config_id_in => 'my_app_config'
  );

  4. Para ativar a linguagem natural da IA do AlloyDB e fazer a correspondência de sinônimos de um valor, execute a seguinte instrução de exemplo:

    SELECT
  alloydb_ai_nl.insert_synonym_set(
    ARRAY [
      'USA',
      'US',
      'United States',
      'United States of America'
    ]
  );

    Embora os dados nas suas tabelas possam usar um valor específico, por exemplo, se United States for usado para identificar um país, você poderá definir um conjunto de sinônimos que contenha todos os sinônimos de United States. Se algum dos sinônimos aparecer na pergunta em linguagem natural, a IA do AlloyDB vai corresponder os sinônimos aos valores nas suas tabelas.

  5. Faça uma pesquisa de valor para encontrar os valores corretos do banco de dados, considerando uma matriz de frases de valor, usando a seguinte instrução:

    SELECT
  alloydb_ai_nl.get_concept_and_value(
    value_phrases_in => ARRAY['United States'],
    nl_config_id_in  => 'my_app_config'
  );

    Por exemplo, se um usuário fizer uma pergunta como "Qual é a população dos Estados Unidos?" usando a seguinte consulta get_sql, a linguagem natural da IA do AlloyDB usará a função get_concept_and_value com a frase de valor United States para realizar uma pesquisa difusa nos índices de valor. Uma pesquisa aproximada é uma técnica que encontra correspondências mesmo quando a consulta de pesquisa não corresponde exatamente aos dados correspondentes.

    A linguagem natural encontra um resultado (o valor USA) que é semelhante à consulta de pesquisa e o usa para gerar a consulta SQL.

    SELECT
  alloydb_ai_nl.get_sql(
    nl_config_id    => 'my_app_config',
    nl_question     => 'What is the population of the United States?',
    additional_info => json_build_object('enrich_nl_question', TRUE)
  ) ->> 'sql';

    A tabela a seguir lista os tipos de conceitos integrados definidos pela linguagem natural da AlloyDB AI:

    Nome do conceito Descrição
    generic_entity_name Uma única coluna de tipo de string pode ser usada para um nome de entidade genérico. Por exemplo:
      SELECT alloydb_ai_nl.associate_concept_type('public.item.item_name', 'generic_entity_name')
    country_name, city_name, region_name Nomes de países, cidades e regiões. O uso é exatamente o mesmo que o tipo de conceito generic_entity_name.
    full_person_name Nome da pessoa, composto pelo primeiro nome, sobrenome e nome do meio. É possível usar até três colunas do tipo string para um nome completo. Qualquer uma das colunas pode ser ignorada ao associar colunas de nome ao full_person_name. Por exemplo:
      SELECT alloydb_ai_nl.associate_concept_type('public.person.last_name,public.person.first_name,public.person.middle_name','full_person_name')
    ssn Uma única coluna de string que contém um CPF ou CNPJ. Por exemplo:
      SELECT alloydb_ai_nl.associate_concept_type('public.person.ssn','ssn')
    date Uma data ou um carimbo de data/hora. Por exemplo:
     SELECT alloydb_ai_nl.associate_concept_type('public.person.date_col','date')

Gerar instruções SQL com base em entradas de linguagem natural

Você pode usar a linguagem natural da IA do AlloyDB para gerar instruções SQL com base em entradas de linguagem natural. Quando você executa a instrução SQL gerada, ela fornece os dados do banco de dados necessários para responder à pergunta em linguagem natural.

  1. Para usar linguagem natural e receber resultados do banco de dados com a função alloydb_ai_nl.get_sql, use o exemplo a seguir:

    SELECT
  alloydb_ai_nl.get_sql(
    'my_app_config', -- nl_config
    'What is the sum that client number 4''s account has following transaction 851?' -- nl question
  );

    A seguinte saída JSON é retornada:

    {
  "sql": "SELECT T3.balance FROM public.client AS T1 INNER JOIN public.account AS T2 ON T1.district_id = T2.district_id INNER JOIN public.trans AS T3 ON T2.account_id = T3.account_id WHERE T1.client_id = 4 AND T3.trans_id = 851",
  "prompt": "",
  "retries": 0,
  "error_msg": "",
  "nl_question": "What is the sum that client number 4's account has following transaction 851?"
}

  2. Opcional: para extrair a consulta SQL gerada como uma string de texto, adicione ->>'sql':

    SELECT
  alloydb_ai_nl.get_sql(
    'my_app_config', -- nl_config
    'What is the sum that client number 4''s account has following transaction 851?' -- nl question
  ) ->> 'sql';

    O operador ->> é usado para extrair um valor JSON como texto. A função alloydb_ai_nl.get_sql retorna um objeto JSON, que é a parte da instrução que recupera o valor associado à chave sql. Esse valor é a consulta SQL gerada.

Testar e refinar

Para melhorar as consultas geradas automaticamente, modifique ou adicione um contexto melhor, modelos de consulta e índices de valor. Depois, repita o processo até alcançar os resultados desejados.

A seguir