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

  • 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.

Ativar a extensão necessária

Antes de instalar e usar a linguagem natural da IA do AlloyDB, é necessário ativar a extensão adicionando a flag alloydb_ai_nl.enabled. Para mais informações, consulte Configurar flags de banco de dados de uma instância.

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 Identity and Access Management (IAM) no projeto 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 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;

Fazer upgrade da extensão alloydb_ai_nl

Verifique se você tem a versão mais recente da extensão alloydb_ai_nl. Se você já instalou a extensão, verifique se há uma nova versão disponível e atualize se não estiver usando a mais recente. Para mais informações sobre a extensão alloydb_ai_nl, consulte a Visão geral da linguagem natural da IA do AlloyDB.

  1. Determine se é necessário fazer upgrade da extensão. Se o default_version for posterior ao installed_version, faça upgrade da extensão.

    SELECT * FROM pg_available_extensions where name = 'alloydb_ai_nl';

  2. Faça upgrade da extensão.

    ALTER EXTENSION alloydb_ai_nl UPDATE;

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. 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

Contexto inclui qualquer tipo de informação que você pode usar para responder a uma pergunta do usuário final, como:

  • Estrutura e relacionamentos do esquema
  • Resumos e descrições de colunas
  • Valores de coluna e semântica
  • 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, 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, execute a seguinte consulta:

    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 ver os contextos gerais da configuração especificada, execute a seguinte consulta:

    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 consulta:

    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 da visualização 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 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 que responda à pergunta do usuário final. O template_store faz o seguinte:

  • Identifica modelos com intenções semelhantes à pergunta em linguagem natural feita pelo usuário final.
  • Identifica a instrução SQL parametrizada correspondente.
  • Sintetiza uma instrução SQL ao instanciar parâmetros com valores da pergunta em linguagem natural.

Se não houver um modelo com a mesma intenção da pergunta feita pelo usuário final, o alloydb_ai_nl usará todos os modelos e contextos relevantes para criar uma instrução SQL.

Adicionar um modelo à loja de modelos

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

Para adicionar um modelo à loja, execute a seguinte consulta:

SELECT
  alloydb_ai_nl.add_template(
    nl_config_id => '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.

O SQL e a intent são parametrizados por alloydb_ai_nl. A visualização alloydb_ai_nl.template_store_view expõe as instruções SQL parametrizadas e as intents delas.

SELECT psql
FROM alloydb_ai_nl.template_store_view
WHERE intent = 'How many accounts associated with loans are located in the Prague region?';

Essa instrução retorna o seguinte:

SELECT COUNT(T1.account_id)
FROM account AS T1 INNER JOIN loan AS T2
  ON T1.account_id = T2.account_id
INNER JOIN district AS T3
  ON T1.district_id = T3.district_id WHERE T3."A3" = $1

Fornecer uma parametrização personalizada

Para fornecer uma parametrização personalizada para uma instrução SQL usando a interface manual da função add_template, execute a instrução no exemplo a seguir:

SELECT
  alloydb_ai_nl.add_template(
     nl_config_id => 'my_app_config',
     intent => 'Among the accounts opened, how many customers born before 1950 resided in Slokolov at the time of account opening?',
     sql => $$SELECT COUNT(DISTINCT T2.client_id)
              FROM district AS T1 INNER JOIN client AS T2
                ON T1.district_id = T2.district_id
             INNER JOIN account AS T3 ON T2.client_id IN (
                   SELECT client_id FROM disp WHERE account_id = T3.account_id)
             WHERE to_char(T2.birth_date::timestamp, 'YYYY') < '1950'
               AND T1."A2" = 'Slokolov'$$,
  parameterized_sql => $$SELECT COUNT(DISTINCT T2.client_id)
                         FROM district AS T1 INNER JOIN client AS T2
                           ON T1.district_id = T2.district_id
                   INNER JOIN account AS T3 ON T2.client_id IN (
                         SELECT client_id FROM disp WHERE account_id = T3.account_id)
                   WHERE to_char(T2.birth_date::timestamp, 'YYYY') < $2
                     AND T1."A2" = $1$$,
  parameterized_intent => $$Among the accounts opened, how many customers born before $2 resided in $1 at the time of account opening?$$,
  manifest => $$Among the accounts opened, how many customers born before a given date resided in a given city at the time of account opening?$$,
  check_intent => TRUE);

Na definição anterior, a parametrização da instrução SQL é fornecida. Os parâmetros são $1 e $2, respectivamente, para Slokolov e 1950. Um manifesto é fornecido como uma versão generalizada da intent, em que os valores de literais são substituídos por descrições genéricas dos valores.

Neste exemplo, o valor de 1950 na intent é substituído por a given date, e o valor de Slokolov é substituído no manifesto por a given city. Quando um valor TRUE é fornecido para o argumento opcional check_intent , uma verificação de intent baseada em LLM é realizada durante add_template. Durante essa verificação, quando a instrução SQL fornecida não captura a finalidade e o objetivo da instrução de intent, add_template falha e o motivo é fornecido como saída.

No exemplo a seguir, a finalidade do modelo, conforme indicado na intenção, é recuperar o ID das contas associadas ao carregamento e localizadas em uma região. A instrução SQL fornecida retorna o número de contas, e não a lista de IDs de conta, como mostrado no exemplo a seguir.

SELECT
  alloydb_ai_nl.add_template(
    nl_config_id => 'my_app_config',
    intent => 'List the account id for all accounts that associated with loans and are located in the Prague region.',
    sql => 'SELECT COUNT(T1.account_id)
            FROM account AS T1 INNER JOIN loan AS T2
              ON T1.account_id = T2.account_id
            INNER JOIN district AS T3
              ON T1.district_id = T3.district_id
            WHERE T3."A3" = ''Prague''',
    check_intent => TRUE
  );

Quando check_intent está definido como TRUE, não é possível adicionar o modelo anterior à biblioteca de modelos. Se você executar a instrução anterior, um erro semelhante ao seguinte será retornado:

ERROR:  Checking intent failed, for nl_question:List the account id for all accounts that associated with loans and are located in the Prague region...reason:The SQL query only counts the number of account IDs, but the question asks for a list of the account IDs.

Gerenciar modelos

É possível gerenciar modelos na loja de modelos usando as seguintes APIs:

-- To disable a template:
SELECT alloydb_ai_nl.disable_template(INPUT template_id);

-- To enable a template which has been disabled:
SELECT alloydb_ai_nl.enable_template(INPUT template_id);

-- To permanently remove a template:
SELECT alloydb_ai_nl.drop_template(INPUT template_id);

Quando você cria um modelo, ele é ativado por padrão. Um modelo desativado permanece na loja de modelos, mas não é usado pelo alloydb_ai_nl para sintetizar consultas. É possível ativar um modelo desativado usando alloydb_ai_nl.enable_template. Executar alloydb_ai_nl.drop_template remove permanentemente o modelo da loja de modelos.

Você pode usar alloydb_ai_nl.template_store_view para extrair o template_id de um modelo, considerando o conteúdo dele. Por exemplo, para encontrar o identificador de modelos com a intenção accounts that associated with loans, execute a seguinte consulta, que retorna um identificador de modelo e identifica se o modelo está ativado em alloydb_ai_nl.template_store_view:

SELECT id, enabled
FROM alloydb_ai_nl.template_store_view
WHERE intent ILIKE '%accounts that associated with loans%';

Atualizar um modelo

Ao usar os modelos em alloydb_ai_nl.template_store_view, verifique se a intenção de cada modelo é consistente com o seguinte:

  • A instrução SQL
  • A instrução SQL parametrizada
  • A intent parametrizada
  • O manifesto do modelo

O alloydb_ai_nl pode recuperar modelos relevantes se o embedding mantido para modelos corresponder ao conteúdo deles.

Para atualizar um modelo, siga estas etapas:

  1. Identifique o template_id usando alloydb_ai_nl.template_store_view.
  2. Remova o modelo.
  3. Redefina o novo modelo com a modificação necessária usando a função alloydb_ai_nl.add_template.

Criar fragmentos de consulta

É possível especializar modelos no momento da consulta usando fragmentos, que ajudam os modelos de consulta a realizar pesquisas de atributos, como perguntas em linguagem natural. Um fragmento é um conjunto selecionado de condições representativas ou comuns de linguagem natural com predicados SQL correspondentes. Os fragmentos devem ser especificados pelo aplicativo.

Cada fragmento precisa estar associado a um nl_config_id e a uma matriz de tabelas e visualizações com aliases a que o predicado do fragmento se aplica. É possível verificar a finalidade de um fragmento quando o argumento check_intent está definido como TRUE. A extensão alloydb_ai_nl pode usar um modelo com uma combinação de fragmentos para sintetizar a resposta a uma consulta em linguagem natural.

A extensão alloydb_ai_nl usa fragment_store para incorporar dinamicamente as condições em fragmentos relevantes no processo de geração de uma instrução SQL para responder à pergunta do usuário final. Primeiro, o template_store identifica modelos com intenções semelhantes à pergunta em linguagem natural feita pelo usuário final. Em seguida, os fragmentos que podem fornecer especialização aos modelos identificados são recuperados. A substituição de parâmetros é aplicada a modelos e fragmentos para sintetizar uma instrução SQL.

Os valores de parâmetro são extraídos da pergunta em linguagem natural e substituídos pelo LLM usando os padrões implícitos de modelos e fragmentos relevantes. No entanto, se a combinação de modelos e fragmentos não tiver a mesma finalidade da pergunta feita pelo usuário final, o alloydb_ai_nl usará todos os modelos e contextos relevantes para compor uma instrução SQL.

Adicionar um fragmento

Para adicionar um fragmento, execute as seguintes consultas de exemplo usando a função alloydb_ai_nl.add_fragment. Cada fragmento precisa ser associado a um identificador nl_config_id do aplicativo.

-- A fragment that cannot be parameterized.
SELECT alloydb_ai_nl.add_fragment(
  nl_config_id => 'my_app_config',
  table_aliases => ARRAY['account AS T'],
  intent => 'Accounts with issuance after transaction',
  fragment => 'T.frequency = ''POPLATEK PO OBRATU''',
  check_intent => True);

-- A fragment that can be parameterized.
SELECT alloydb_ai_nl.add_fragment(
  nl_config_id => 'my_app_config',
  table_aliases => ARRAY['district AS T'],
  intent => 'Average salary between 6000 and 10000',
  fragment => 'T."A11" BETWEEN 6000 AND 10000',
  check_intent => True);

Quando o alloydb_ai_nl.add_fragment é executado, a extensão alloydb_ai_nl extrai um manifesto da intent fornecida, e a extensão parametriza a intent e a condição do fragmento, se possível. Os fragmentos disponíveis são expostos por visualizações como alloydb_ai_nl.fragment_store_view, conforme mostrado no exemplo a seguir:

SELECT manifest, scope, fragment, intent, pfragment, pintent
FROM alloydb_ai_nl.fragment_store_view
WHERE intent = 'Average salary between 6000 and 10000';

A consulta retorna um conjunto de resultados semelhante a este:

manifest  | Average salary between a given number and a given number
scope     | district AS T
fragment  | T."A11" BETWEEN 6000 AND 10000
intent    | Average salary between 6000 and 10000
pfragment | T."A11" BETWEEN $2 AND $1
pintent   | Average salary between $2 and $1

Um manifesto em um fragmento é gerado automaticamente com base na intent e representa uma versão generalizada dela. Por exemplo, os números 6000 e 10000 na intent são substituídos por a given number no manifesto. Os números são substituídos, respectivamente, por $2 e $1 nas colunas pfragment e pintent. As colunas pfragment e pintent em alloydb_ai_nl.fragment_store_view são, respectivamente, a representação parametrizada de fragment e intent.

Para fornecer uma parametrização personalizada de um fragmento, use a versão manual de alloydb_ai_nl.add_fragment, conforme mostrado no exemplo a seguir:

SELECT alloydb_ai_nl.add_fragment(
  nl_config_id => 'my_app_config',
  table_aliases => ARRAY['bird_dev_financial.district AS T'],
  intent => $$districts in 'Prague'$$,
  parameterized_intent => $$districts in $1$$,
  fragment => $$T."A3" = 'Prague'$$,
  parameterized_fragment => $$T."A3" = $1$$,
  manifest => $$districts in a given city$$,
  check_intent => TRUE);

Gerenciar fragmentos

Para gerenciar fragmentos, use as seguintes APIs:

-- To disable a fragment:
SELECT alloydb_ai_nl.disable_fragment(INPUT fragment_id);

-- To enable a fragment which has been disabled:
SELECT alloydb_ai_nl.enable_fragment(INPUT fragment_id);

-- To permanently remove a fragment:
SELECT alloydb_ai_nl.drop_fragment(INPUT fragment_id);

Você pode usar a visualização alloydb_ai_nl.fragment_store_view para extrair o fragment_id de um fragmento, considerando o conteúdo dele. Por exemplo, para encontrar o identificador de um fragmento com a intent Average salary between 6000 and 10000, execute a seguinte consulta de exemplo:

SELECT id
FROM alloydb_ai_nl.fragment_store_view
WHERE intent = "Average salary between 6000 and 10000";

Atualizar um fragmento

Ao atualizar um fragmento, verifique se a intent dele é consistente com o seguinte:

  • O manifesto do fragmento e a instrução SQL
  • A instrução SQL parametrizada
  • A intent parametrizada

Para estabelecer consistência ao atualizar um fragmento, siga estas etapas:

  1. Remova o fragmento que você quer modificar usando a função alloydb_ai_nl.drop_fragment.
  2. Insira o fragmento atualizado usando a função alloydb_ai_nl.add_fragment.

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. Verifique se as consultas têm planos completos e se elas têm um bom desempenho.

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: a consulta pode ser processada com sucesso pelo comando EXPLAIN.
  • 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 índices 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 dos 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.

    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 associar os sinônimos aos valores nas suas tabelas.

  5. Realiza 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 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';

    Os tipos de conceitos integrados definidos pela linguagem natural da IA do AlloyDB estão listados na tabela a seguir.

    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 associações de tipo de conceito automaticamente

Para associar automaticamente colunas a tipos de conceitos, use o recurso de associação automatizada de tipos de conceitos da API Natural Language da IA do AlloyDB. Uma associação de tipo de conceito define a relação entre um tipo de conceito e uma ou mais colunas de banco de dados, o que é um pré-requisito para criar índices de valor.

Para gerar automaticamente associações de tipo de conceito, siga estas etapas:

  1. Para gerar associações, chame as seguintes APIs.

    -- To cover all relations within the scope of a provided nl_config.
SELECT alloydb_ai_nl.generate_concept_type_associations(
  nl_config => 'my_app_config'
);

-- To cover a specific relation.
SELECT alloydb_ai_nl.generate_concept_type_associations(
  nl_config => 'my_app_config',
  relation_name => 'my_app_table'
);

  2. Revise as associações geradas executando a consulta a seguir.

    SELECT * FROM alloydb_ai_nl.generated_value_index_columns_view;

  3. Opcional: atualize as associações geradas.

    -- NULL means keeping the original value.
SELECT alloydb_ai_nl.update_generated_concept_type_associations(
  id => 1,
  column_names => NULL,
  concept_type => 'generic_entity_name',
  additional_info => NULL
);

  4. Opcional: remova uma associação gerada.

    SELECT alloydb_ai_nl.drop_generated_concept_type_association(id => 1);

  5. Aplique as associações geradas.

    -- To apply all associations under a nl config.
SELECT alloydb_ai_nl.apply_generated_concept_type_associations(
  nl_config => 'my_app_config'
);

-- To apply a specific association by id.
SELECT alloydb_ai_nl.apply_generated_concept_type_association(
  id => 1
);

  6. Atualize o índice de valor para refletir as mudanças.

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

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.

Gerar resumos de resultados com base em entradas de linguagem natural

Você pode usar a linguagem natural da IA do AlloyDB para gerar resumos de resultados com base em entradas de linguagem natural. A função alloydb_ai_nl.get_sql_summary executa com segurança a pergunta em linguagem natural na tabela subjacente, resume uma amostra do conjunto de resultados e retorna o resumo em linguagem natural.

Para gerar um resumo dos resultados de uma pergunta em linguagem natural no seu banco de dados, use a função alloydb_ai_nl.get_sql_summary, conforme mostrado no exemplo a seguir:

SELECT
  alloydb_ai_nl.get_sql_summary(
    nl_config_id => 'my_app_config',
    nl_question => 'Give me the total number of accounts and the earliest opening date and other information for accounts who choose issuance after transaction are staying in east Bohemia region?');

Chamar a instrução anterior produz o seguinte objeto JSON de exemplo:

{
  "answer": "The result set indicates that there are 13 accounts that chose issuance after a transaction and are located in the East Bohemia region. The earliest opening date among these accounts is August 21, 1993. Other information about these accounts is not provided in the result set."
}

É possível proteger as tabelas e visualizações acessadas por uma consulta em alloydb_ai_nl.get_sql_summary usando uma ou mais visualizações seguras parametrizadas. Os nomes dos parâmetros e os valores deles estão disponíveis para um aplicativo e são obrigatórios para alloydb_ai_nl.get_sql_summary.

Por exemplo, o aplicativo pode querer fornecer o parâmetro user_id para um usuário autenticado com um ID de usuário 123. Para isso, forneça entradas param_names e param_values, conforme mostrado no exemplo a seguir:

SELECT
  alloydb_ai_nl.get_sql_summary(
    nl_config_id => 'my_app_config',
    nl_question => 'Give me the total number of accounts and the earliest opening date and other information for accounts who choose issuance after transaction are staying in east Bohemia region?',
    param_names => ARRAY ['user_id'],
    param_values => ARRAY ['123']
);

Ao fornecer argumentos param_names e param_values, você garante que, quando a nl_question puder ser respondida por uma instrução SQL aplicada por visualizações seguras parametrizadas, os filtros de segurança designados serão aplicados quando o conjunto de resultados for produzido e o resumo for gerado.

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