Gerar consultas SQL com perguntas em linguagem natural

Esta página descreve como configurar, configurar e gerar declarações SQL usando a linguagem natural da IA do AlloyDB. A linguagem natural permite-lhe criar aplicações de IA generativa viradas para o utilizador através da linguagem natural para consultar bases de dados.

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

  1. Instale a extensão alloydb_ai_nl.
  2. Defina uma configuração de linguagem natural para a sua aplicação.
  3. Registe um esquema.
  4. Adicione contexto.
  5. Adicione modelos de consultas.
  6. Defina tipos de conceitos e crie um índice de valores.
  7. Gerar declarações SQL através de uma interface de linguagem natural.

Antes de começar

  • Compreenda como estabelecer ligação à base de dados do AlloyDB e executar comandos do PostgreSQL. Para mais informações, consulte o artigo Vista geral da ligação.
  • Preencha a base de dados com os dados e o esquema aos quais o utilizador final quer aceder.

Ative a extensão necessária

Antes de poder instalar e usar a linguagem natural do AlloyDB AI, tem de ativar a extensão adicionando a flag alloydb_ai_nl.enabled. Para mais informações, consulte o artigo Configure as flags da base de dados de uma instância.

Crie um cluster e ative a integração do Vertex AI

  1. Crie um cluster e uma instância do AlloyDB. Usa a instância do AlloyDB para criar a base de dados da aplicação e o esquema.
  2. Ativar a integração do Vertex AI. Para mais informações, consulte o artigo Integre com o Vertex AI.

Funções necessárias

Para instalar a extensão alloydb_ai_nl e conceder acesso a outros utilizadores, tem de ter a seguinte função de gestão de identidade e de acesso (IAM) no projeto que está a usar: Google Cloud

Para mais informações, consulte o artigo Faça a gestão dos utilizadores do PostgreSQL com a autenticação padrão.

Prepare o seu ambiente

Para se preparar para gerar consultas de linguagem natural, tem de instalar a extensão necessária, criar uma configuração e registar um esquema.

Instale a extensão alloydb_ai_nl

A extensão alloydb_ai_nl usa a extensão google_ml_integration, que interage com modelos de linguagem (conteúdo extenso) (MDL/CE), incluindo modelos Gemini no Vertex AI.

Para instalar a extensão alloydb_ai_nl, ligue-se à base de dados e execute o seguinte comando:

CREATE EXTENSION alloydb_ai_nl cascade;

Atualize a extensão alloydb_ai_nl

Certifique-se de que tem a versão mais recente da extensão alloydb_ai_nl. Se já tiver instalado a extensão, verifique se existe uma nova versão da extensão disponível e atualize a extensão se não estiver a usar a versão mais recente. Para mais informações sobre a extensão alloydb_ai_nl, consulte a vista geral da linguagem natural da IA do AlloyDB.

  1. Determine se precisa de atualizar a extensão. Se a default_version for posterior à installed_version, atualize a extensão.

    SELECT * FROM pg_available_extensions where name = 'alloydb_ai_nl';

  2. Atualize a extensão.

    ALTER EXTENSION alloydb_ai_nl UPDATE;

Crie uma configuração de linguagem natural e registe um esquema

A linguagem natural da IA do AlloyDB usa o nl_config para associar aplicações a determinados esquemas, modelos de consultas e pontos finais de modelos. nl_config é uma configuração que associa uma aplicação a esquemas, modelos e outros contextos. Uma aplicação grande também pode usar diferentes configurações para diferentes partes da aplicação, desde que especifique a configuração correta quando uma pergunta é enviada a partir dessa parte da aplicação. Pode registar um esquema completo ou registar objetos de esquema específicos, como tabelas, vistas e colunas.

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

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

    gemini-2.0-flash:generateContent é o ponto final do modelo.

  2. Registe um esquema para uma configuração especificada através do 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 possa usar para responder a uma pergunta do utilizador final, como o seguinte:

  • Estrutura e relações do esquema
  • Resumos e descrições das colunas
  • Valores das colunas e respetiva semântica
  • Regras ou declarações de lógica de negócio específicas da aplicação ou do domínio

Adicione contexto geral para regras específicas da aplicação

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

Para adicionar contexto geral para regras específicas da aplicação e terminologia específica da aplicação ou do domínio, siga estes passos:

  1. Para adicionar um item de contexto geral para a 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 linguagem natural da IA do AlloyDB a fornecer respostas de maior qualidade às perguntas em linguagem natural dos utilizadores.

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

    SELECT alloydb_ai_nl.list_general_context(nl_config TEXT);

Gere e reveja o contexto do esquema

O contexto do esquema descreve objetos de esquema, incluindo tabelas, vistas, vistas materializadas e colunas. Este contexto é armazenado como o COMMENT de cada objeto de esquema.

  1. Para gerar contextos para objetos de esquemas, chame as seguintes APIs. Para melhores resultados, certifique-se de que as tabelas da base 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. Reveja os contextos de esquemas gerados executando a seguinte consulta:

    SELECT schema_object, object_context
FROM alloydb_ai_nl.generated_schema_context_view;

    Os contextos de esquemas gerados são armazenados na vista anterior.

  3. Opcional: atualize os contextos do 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 aplica o contexto, este entra em vigor imediatamente e é eliminado da vista 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: valide o contexto gerado. A API seguinte permite-lhe verificar os contextos de esquemas, que são usados quando gera declaraçõ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"}'
  );

Crie modelos de consultas

Para melhorar a qualidade das aplicações de IA generativa criadas com MDIs, pode adicionar modelos. Um modelo de consulta é um conjunto organizado de perguntas de linguagem natural representativas ou comuns, com consultas SQL correspondentes, bem como explicações para fornecer uma justificação declarativa para a geração de linguagem natural para SQL (NL2SQL). Os modelos destinam-se principalmente a ser especificados pela aplicação, mas também podem ser gerados automaticamente pela extensão alloydb_ai_nl com base em consultas SQL usadas com frequência. Cada modelo tem de 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 declaração SQL para responder à pergunta do utilizador final. O template_store faz o seguinte:

  • Identifica modelos com intenções semelhantes à pergunta em linguagem natural que o utilizador final fez.
  • Identifica a declaração SQL parametrizada correspondente.
  • Sintetiza uma declaração SQL ao instanciar parâmetros com valores da pergunta em linguagem natural.

Se não existir um modelo com a mesma intenção que a pergunta feita pelo utilizador final, o alloydb_ai_nl usa todos os modelos e o contexto relevantes para compor uma declaração SQL.

Adicione um modelo à loja de modelos

Adiciona modelos especificando a pergunta, usando um parâmetro denominado intent, e a consulta SQL.

Para adicionar um modelo à loja de modelos, 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 faz uma verificação semântica para confirmar se a intenção fornecida corresponde à declaração SQL transmitida. Se a intenção não corresponder à declaração SQL, o modelo não é adicionado.

O SQL e a intenção são parametrizados por alloydb_ai_nl. A vista alloydb_ai_nl.template_store_view expõe as declarações SQL parametrizadas e as respetivas intenções.

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

Esta declaração devolve 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 declaração SQL através da interface manual da função add_template, execute a declaração no seguinte exemplo:

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, é fornecida a parametrização da declaração SQL. Os parâmetros são $1 e $2, respetivamente, para Slokolov e 1950. É fornecido um manifesto como uma versão generalizada da intenção, em que os valores dos literais são substituídos por descrições genéricas dos valores.

Neste exemplo, o valor de 1950 na intenção é substituído por a given date, e o valor de Slokolov é substituído no manifesto por a given city. Quando é fornecido um valor TRUE para o argumento opcional check_intent , é realizada uma validação de intenção baseada em MDIs durante a add_template. Durante esta verificação, quando a declaração SQL fornecida não capta a finalidade e o objetivo da declaração de intenção fornecida, a add_template falha e o motivo é fornecido como resultado.

No exemplo seguinte, o objetivo do modelo, conforme indicado na intenção, é obter o ID da conta das contas associadas ao carregamento e localizadas numa região. A declaração SQL fornecida devolve o número de contas, em vez da lista de IDs das contas, como mostrado no exemplo seguinte.

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 pode adicionar o modelo anterior à loja de modelos. Se executar a declaração anterior, é devolvido um erro semelhante ao seguinte:

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.

Faça a gestão de modelos

Pode gerir modelos na loja de modelos através das 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 cria um modelo, este é ativado por predefinição. Um modelo desativado permanece na loja de modelos, mas não é usado pelo alloydb_ai_nl para a síntese de consultas. Pode ativar um modelo desativado através do alloydb_ai_nl.enable_template. A execução alloydb_ai_nl.drop_template remove permanentemente o modelo da loja de modelos.

Pode usar alloydb_ai_nl.template_store_view para extrair o template_id de um modelo, dado o respetivo conteúdo. Por exemplo, para encontrar o identificador de modelos que têm a intenção accounts that associated with loans, execute a seguinte consulta, que devolve um identificador de modelo e identifica se o modelo está ativado a partir de alloydb_ai_nl.template_store_view:

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

Atualize um modelo

Quando usar os modelos no alloydb_ai_nl.template_store_view, certifique-se de que a intenção de cada modelo é consistente com o seguinte:

  • A declaração SQL
  • A declaração SQL parametrizada
  • A intenção parametrizada
  • O manifesto do modelo

alloydb_ai_nl pode obter modelos relevantes se a incorporação mantida para os modelos corresponder aos conteúdos dos modelos.

Para atualizar um modelo, siga estes passos:

  1. Identifique o template_id através de alloydb_ai_nl.template_store_view.
  2. Remova o modelo.
  3. Redefina o novo modelo com a modificação necessária através da função alloydb_ai_nl.add_template.

Crie fragmentos de consultas

Pode especializar modelos no momento da consulta através de fragmentos, que ajudam os modelos de consulta a realizar pesquisas filtradas, como perguntas em linguagem natural. Um fragmento é um conjunto organizado de condições de linguagem natural representativas ou comuns com predicados SQL correspondentes. Os fragmentos destinam-se a ser especificados pela aplicação.

Cada fragmento tem de estar associado a um nl_config_id e a uma matriz de tabelas e vistas aos quais se aplica o predicado do fragmento. Pode validar 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 de 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 declaração SQL para responder à pergunta do utilizador final. Primeiro, o template_store identifica modelos com intenções semelhantes à pergunta em linguagem natural que o utilizador final fez. Em seguida, são obtidos os fragmentos que podem fornecer especialização aos modelos identificados. A substituição de parâmetros é aplicada a modelos e fragmentos para sintetizar uma declaração SQL.

Os valores dos parâmetros são extraídos da pergunta em linguagem natural e substituídos pelo MDG através dos padrões implícitos dos modelos e fragmentos relevantes. No entanto, se a combinação de modelos e fragmentos não tiver o mesmo objetivo para a pergunta feita pelo utilizador final, o alloydb_ai_nl usa todos os modelos e o contexto relevantes para compor uma declaração SQL.

Adicione um fragmento

Para adicionar um fragmento, execute as consultas de exemplo seguintes com a função alloydb_ai_nl.add_fragment. Cada fragmento tem de estar associado a um nl_config_id identificador da aplicação.

-- 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 intenção fornecida e parametriza a intenção e a condição para o fragmento, se possível. Os fragmentos disponíveis são expostos por vistas como alloydb_ai_nl.fragment_store_view, conforme mostrado no exemplo seguinte:

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

A consulta devolve um conjunto de resultados semelhante ao seguinte:

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 num fragmento é gerado automaticamente a partir da intenção e representa uma versão generalizada da intenção. Por exemplo, os números 6000 e 10000 na intenção são substituídos por a given number no manifesto. Os números são substituídos, respetivamente, por $2 e $1 nas colunas pfragment e pintent. As colunas pfragment e pintent em alloydb_ai_nl.fragment_store_view são, respetivamente, 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 seguinte:

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);

Faça a gestão de fragmentos

Para gerir 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);

Pode usar a vista alloydb_ai_nl.fragment_store_view para extrair o fragment_id de um fragmento, dado o respetivo conteúdo. Por exemplo, para encontrar o identificador de um fragmento que tenha a intenção 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";

Atualize um fragmento

Quando atualiza um fragmento, certifique-se de que a intenção do fragmento é consistente com o seguinte:

  • O manifesto e a declaração SQL do fragmento
  • A declaração SQL parametrizada
  • A intenção parametrizada

Para estabelecer a consistência quando atualiza um fragmento, siga estes passos:

  1. Remova o fragmento que quer modificar através da função alloydb_ai_nl.drop_fragment.
  2. Insira o fragmento atualizado através da função alloydb_ai_nl.add_fragment.

Gere modelos automaticamente

Depois de ter um conjunto de dados representativo nas suas tabelas, recomendamos que execute consultas SQL que correspondam às perguntas comuns que os seus utilizadores finais provavelmente farão. Certifique-se de que as consultas têm planos de consultas completos e que têm um bom desempenho.

Depois de executar as consultas, a linguagem natural da IA do AlloyDB pode gerar automaticamente modelos com base no histórico de consultas. Pode chamar as seguintes APIs para gerar modelos. Tem de rever e aplicar os modelos gerados antes que entrem em vigor.

A geração automática de modelos baseia-se nas consultas usadas com maior frequência no registo de consultas, google_db_advisor_workload_statements. As consultas são filtradas com base nos seguintes critérios:

  • SELECT extratos
  • Executáveis: a consulta pode ser processada com êxito pelo comando EXPLAIN.
  • Sem duplicações: a consulta não foi usada anteriormente para gerar modelos.
  • Todas as tabelas e vistas referidas estão no âmbito do nl_config.

Para gerar automaticamente, rever e aplicar modelos, siga estes passos:

  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 vista fornecida, alloydb_ai_nl.generated_templates_view, para rever o generated_templates.

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

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

  2. Reveja os modelos gerados através da vista generated_templates_view.

    SELECT *
FROM alloydb_ai_nl.generated_templates_view;

    Segue-se um exemplo do resultado devolvido:

    -[ 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 no resultado devolvido é 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 o intent substituindo o valor específico (1997) por um marcador de posição ($1).

  3. Para atualizar um modelo gerado, execute a seguinte declaraçã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 que aplica são imediatamente adicionados à loja de modelos e eliminados da vista de revisão.

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

Configure a segurança para a linguagem natural

Para configurar a segurança da linguagem natural da IA do AlloyDB, consulte o artigo Faça a gestão da segurança das aplicações de dados através de vistas seguras parametrizadas.

Defina tipos de conceitos e índices de valores

Define tipos de conceitos e índices de valores para compreender melhor as perguntas feitas. Um tipo de conceito é uma categoria ou uma classe de entidades que identifica o significado semântico das palavras e das expressões, em vez de apenas a respetiva forma literal.

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

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

Para definir tipos de conceitos e um índice de valores, siga estes passos usando os exemplos fornecidos. Os exemplos associam uma coluna a um tipo de conceito, criam e atualizam um índice de valores e usam um conjunto de sinónimos para fazer uma pesquisa de valores.

  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 valores 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 declaração:

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

  3. Quando associa tipos de conceitos a novas colunas, atualize o índice de valores para refletir as alterações.

    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 a seguinte declaraçã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, pode 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 faz corresponder os sinónimos aos valores nas suas tabelas.

  5. Faça uma pesquisa de valores para encontrar os valores corretos da base de dados, tendo em conta uma matriz de expressões de valores.

    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 utilizador 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 usa a função get_concept_and_value com a expressão United States para fazer uma pesquisa aproximada em relação aos índices de valores. 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, que está próximo da 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 conceitos incorporados definidos pela linguagem natural da IA do AlloyDB estão listados na tabela seguinte.

    Nome do conceito Descrição
    generic_entity_name Pode usar uma única coluna do tipo string 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. A utilização é exatamente igual à do tipo de conceito generic_entity_name.
    full_person_name Nome da pessoa, composto pelo nome próprio, apelido e primeiro apelido. Podem ser usadas até três colunas do tipo string para um nome completo de uma pessoa. Pode ignorar qualquer uma das colunas ao associar colunas de nomes 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 número da segurança social. Por exemplo:
      SELECT alloydb_ai_nl.associate_concept_type('public.person.ssn','ssn')
    date Uma data ou uma indicação de tempo. Por exemplo:
     SELECT alloydb_ai_nl.associate_concept_type('public.person.date_col','date')

Gere automaticamente associações de tipos de conceitos

Para associar automaticamente colunas a tipos de conceitos, use a funcionalidade de associação de tipos de conceitos automatizada da API de linguagem natural do AlloyDB AI. Uma associação de tipo de conceito define a relação entre um tipo de conceito e uma ou mais colunas da base de dados, o que é um pré-requisito para criar índices de valores.

Para gerar automaticamente associações de tipos de conceitos, siga estes passos:

  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. Reveja as associações geradas executando a seguinte consulta.

    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 alterações.

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

Gerar declarações SQL a partir de entradas de linguagem natural

Pode usar a linguagem natural da IA do AlloyDB para gerar declarações SQL a partir de entradas de linguagem natural. Quando executa a declaração SQL gerada, esta fornece os dados da base de dados de que precisa para responder à pergunta em linguagem natural.

  1. Para usar a linguagem natural para obter resultados da sua base de dados através da função alloydb_ai_nl.get_sql, use o exemplo seguinte:

    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
  );

    É devolvida a seguinte saída JSON:

    {
  "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 devolve um objeto JSON, que é a parte da declaração que obtém o valor associado à chave sql. Este valor é a consulta SQL gerada.

Gerar resumos de resultados a partir de entradas de linguagem natural

Pode usar a linguagem natural da IA do AlloyDB para gerar resumos de resultados a partir de entradas de linguagem natural. A função alloydb_ai_nl.get_sql_summary executa de forma segura a pergunta em linguagem natural na tabela subjacente, resume um exemplo do conjunto de resultados e devolve o resumo em linguagem natural.

Para produzir um resumo dos resultados de uma pergunta em linguagem natural na sua base de dados, use a função alloydb_ai_nl.get_sql_summary, conforme mostrado no exemplo seguinte:

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?');

A chamada da declaraçã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."
}

Pode proteger as tabelas e as vistas acedidas por uma consulta em alloydb_ai_nl.get_sql_summary usando uma ou mais vistas seguras parametrizadas. Os nomes dos parâmetros e os respetivos valores estão disponíveis para uma aplicação e são obrigatórios para alloydb_ai_nl.get_sql_summary.

Por exemplo, a aplicação pode querer fornecer o parâmetro user_id para um utilizador autenticado com um ID do utilizador de 123. Pode fazê-lo fornecendo as entradas param_names e param_values, conforme mostrado no exemplo seguinte:

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']
);

A disponibilização de argumentos param_names e param_values garante que, quando a nl_question é respondível por uma declaração SQL aplicada por vistas seguras parametrizadas, os filtros de segurança designados são aplicados quando o conjunto de resultados é produzido e o resumo é gerado.

Teste e refine

Para obter consultas geradas automaticamente melhoradas, modifique ou adicione um contexto melhor, modelos de consultas e índices de valores. Em seguida, repita o processo até alcançar os resultados pretendidos.

O que se segue?