Gerar consultas SQL usando perguntas em linguagem natural

Esta página descreve como definir, configurar e gerar instruções SQL usando a linguagem natural da IA do AlloyDB. A linguagem natural permite 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 ao idioma 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. Adicionar 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 AlloyDB AI e aguarde a confirmação de ativação antes de seguir as instruções desta 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 do aplicativo e o esquema.
  2. Ative a integração com a Vertex AI. Para mais informações, consulte Integrar 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 de Identity and Access Management (IAM) no projeto do Google Cloud que está usando:

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

Preparar o ambiente

Para se preparar para gerar consultas de 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 comando abaixo, que ativa as extensões google_ml_integration e alloydb_ai_nl.

CREATE EXTENSION google_ml_integration;
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 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 diferentes configurações para diferentes partes do aplicativo, 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 de esquema, 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. Registre um esquema para uma configuração especificada usando o exemplo a seguir:

    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 possa ser usada para responder a uma pergunta do usuário final. O contexto inclui estrutura e relacionamentos do esquema, resumos e descrições de colunas, valores de colunas e semântica, além de regras ou instruçõ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, instruçõ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 do domínio, siga estas etapas:

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

    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 linguagem natural da IA do AlloyDB a fornecer respostas de maior qualidade para as perguntas em linguagem natural dos usuários.

  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 APIs a seguir. Para obter 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. Para conferir os contextos de esquema gerados, execute 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: atualize os contextos de esquema gerados.

    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.

    -- 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: defina manualmente o contexto do esquema.

    -- 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 de linguagem natural comuns ou representativas, com consultas SQL correspondentes, além de 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 ser 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 de linguagem natural feita, identifica a instrução SQL parametrizada correspondente e sintetiza uma instrução SQL instanciando parâmetros com valores da pergunta de 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 compor 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 intent 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 tabelas, recomendamos que você execute consultas SQL que correspondam às perguntas comuns que os usuários finais provavelmente vão fazer. É importante garantir que as consultas tenham bons planos de consulta e que elas tenham bom desempenho.

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

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

  • SELECT instruções
  • Executáveis: a consulta pode ser processada pelo comando EXPLAIN.
  • Sem duplicação: a consulta não foi usada anteriormente para gerar modelos.
  • Todas as tabelas e visualizações mencionadas 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 a seguir 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

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

    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 a linguagem natural

Para configurar a segurança da linguagem natural da IA do AlloyDB, consulte Gerenciar a segurança do aplicativo 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. Um tipo de conceito é uma categoria ou classe de entidades que identifica o significado semântico de palavras e frases, em vez de apenas a forma literal delas.

Por exemplo, dois nomes de país podem ser iguais, mesmo que um esteja em maiúsculas, por exemplo, USA, e o outro em minúsculas, por exemplo, usa. Nesse caso, o nome do país é o tipo de conceito. Outros exemplos de tipos de conceito 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 consulta a seguir:

    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.

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

  4. Para ativar a linguagem natural da IA do AlloyDB para corresponder a sinônimos de um valor, execute o exemplo de instrução a seguir:

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

    Embora os dados nas 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 de linguagem natural, a linguagem natural da AlloyDB AI vai corresponder os sinônimos aos valores nas tabelas.

  5. Realize uma pesquisa de valor para encontrar os valores corretos do banco de dados, considerando uma matriz de frases de valor.

    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?" que usa a consulta get_sql a seguir, a linguagem natural da IA do AlloyDB usa a função get_concept_and_value com a frase de valor United States para realizar uma pesquisa aproximada nos índices de valor. Uma pesquisa aproximada é uma técnica de pesquisa 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) próximo à consulta de pesquisa e usa esse resultado 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';

    Os tipos de conceito integrados definidos pela linguagem natural da AlloyDB AI estão listados na tabela a seguir.

    Nome do conceito Descrição
    generic_entity_name Uma única coluna do tipo string pode ser usada para um nome de entidade genérica. 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 do tipo de conceito generic_entity_name.
    full_person_name Nome da pessoa, que consiste no primeiro, segundo e último nome. Até três colunas do tipo string podem ser usadas 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 coluna de string única que contém um CPF. 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 AlloyDB AI 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 a linguagem natural e extrair resultados do seu 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 saída JSON a seguir é 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, adicione um contexto melhor, modelos de consulta e índices de valor, depois itere até alcançar os resultados desejados.

A seguir