Adicionar uma Interface de Linguagem Natural ao Aplicativo Oracle APEX

Introdução

Operamos o site Database Expert Resources (DBExpert Toolkit), que fornece informações comparativas e ferramentas interativas, ajudando os usuários a identificar o melhor Oracle Database Cloud Service para seus casos de uso. Recentemente, adicionamos uma interface de linguagem natural ao nosso site para que os usuários também possam fazer perguntas sobre os serviços de nuvem.

Nosso site é uma instância do Oracle Application Express (Oracle APEX) em execução em um banco de dados Oracle Autonomous Transaction Processing Serverless e vimos que o novo Oracle Autonomous Database Select AI estava disponível para permitir interações de linguagem natural com nossos dados.

Para lidar normalmente não apenas com perguntas relacionadas ao conteúdo, mas também com solicitações de ajuda e aceitar feedback do usuário, escolhemos o Oracle Digital Assistant para o frontend das consultas de linguagem natural.

Este tutorial descreve as tarefas que realizamos para adicionar a interface de linguagem natural.

AskDBExpert em oracle.com/dbexpert

Objetivos

Pré-requisitos

Tarefa 1: Conectar o Oracle Autonomous Database Select AI ao seu LLM

No espaço de trabalho do APEX, em SQL Workshop -> SQL Commands, execute o código abaixo para criar um perfil de Inteligência Artificial (AI) para especificar esquemas e objetos de banco de dados que serão usados com Select AI. O perfil será usado na Tarefa 2.

Para este tutorial, usamos OpenAI como LLM.

BEGIN
DBMS_CLOUD.CREATE_CREDENTIAL(
credential_name => 'OPENAI_CRED',
username => 'OPENAI',
password => '...' );
END;

BEGIN
    DBMS_CLOUD_AI.CREATE_PROFILE(
        profile_name => 'OPENAI_PROFILE',
        attributes => '{ "provider": "openai",
                        "credential_name": "OPENAI_CRED",
                        "comments":"true", 
                        "object_list": [{"owner": "DB_SCHEMA", "name":"OBJECT_NAME"}]
                    }',
        description => 'AI profile to use OpenAI for SQL translation'
    );
END;

Para verificar a configuração do Oracle Autonomous Database Select AI, execute

select dbms_cloud_ai.generate(
    prompt => 'How many employees work at Oracle?',
    action => 'SHOWSQL',
    profile_name => 'OPENAI_PROFILE'
)
FROM DUAL;

A partir disso, você deve receber uma consulta SQL como saída, verificando a configuração.

Tarefa 2: Integrar a API REST

Depois de ter o Oracle Autonomous Database Select AI trabalhando com seus objetos de banco de dados, crie um ponto final REST POST que será integrado ao Oracle Digital Assistant. Para criar isso no Oracle APEX, abra SQL Workshop -> RESTful Data Services e crie um Módulo com um handler POST. O nome do módulo e o nome do handler POST são usados na Tarefa 3 para configurar o Oracle Digital Assistant.

O handler POST recebe as perguntas de linguagem natural do Oracle Digital Assistant e recupera uma consulta SQL. A consulta SQL resultante é executada e a saída é retornada ao assistente digital para exibição. Cole o seguinte código no handler POST do módulo criado:

Dica: Consulte Ativando o Intercâmbio de Dados com os Serviços RESTful para obter mais detalhes sobre os Serviços RESTful com o Oracle APEX.

DECLARE
    l_response       CLOB;
    l_sql            CLOB;
    l_prompt         VARCHAR2 (4000);
    l_cursor         NUMBER := DBMS_SQL.open_cursor;
    l_profile_name   user_cloud_ai_profiles.profile_name%TYPE :=  'YOUR_PROFILE'; -- the LLM profile you created per (link to Select AI setup)
    p_refcursor      SYS_REFCURSOR;
    l_result         CLOB;
BEGIN

/* 
    The variable name for the 'prompt' parameter below must match the variable used in the 
    Oracle Digital Assistant Flow, in the State that calls the REST endpoint
*/

    l_sql :=
        dbms_cloud_ai.generate (prompt         =>  :l_prompt, 
                                action         => 'showsql',
                                profile_name   => l_profile_name);

    -- check if SQL could be generated.
    BEGIN
        DBMS_SQL.PARSE (l_cursor, l_sql, DBMS_SQL.native);
        l_response := l_sql;
        parse_cursor (l_sql, p_refcursor, l_result);
        if l_result is not null then
            :status := 200;
        else
            raise_application_error(-20987,'No records found');
        end if;
    EXCEPTION
        WHEN OTHERS
        THEN
            :status := 400;
            l_result := 'Something went wrong while processing...'; 
    END;

    APEX_UTIL.PRN (l_result, FALSE);
END;

Execute o seguinte no Oracle APEX SQL Workshop -> SQL Commands para criar o procedimento que executa a consulta SQL recebida do Oracle Autonomous Database Select AI:

CREATE OR REPLACE PROCEDURE parse_cursor (p_query    IN     VARCHAR2,
                                          cur        IN OUT SYS_REFCURSOR,
                                          p_result   OUT CLOB)
AS
    curs          INT;
    cols          INT;
    d             DBMS_SQL.desc_tab2;
    val           VARCHAR2 (32767);
    l_row_count   INTEGER := 0;
BEGIN
    OPEN cur FOR p_query;
    curs := DBMS_SQL.to_cursor_number (cur);
    DBMS_SQL.describe_columns2 (curs, cols, d);
    p_result := p_result || '<table> <tr>';
    FOR i IN 1 .. cols
    LOOP
        DBMS_SQL.define_column (curs,
                                i,
                                val,
                                32767);
        p_result := p_result || '<th>' || d (i).col_name || '</th>';
    END LOOP;
    p_result := p_result ||'</tr>';
    WHILE DBMS_SQL.fetch_rows (curs) > 0
    LOOP
        p_result := p_result ||'<tr>';

        FOR i IN 1 .. cols
        LOOP
            DBMS_SQL.COLUMN_VALUE (curs, i, val);
            p_result := p_result ||'<td>' || val || '</td>';
        END LOOP;

        p_result := p_result ||'</tr>';
        l_row_count := l_row_count + 1;
    END LOOP;
    p_result := p_result ||'</table>';
    IF l_row_count = 0
    THEN
        p_result := NULL;
    END IF;

    DBMS_SQL.close_cursor (curs);
END;
/

A saída é formatada em uma tabela para uso com o Oracle Digital Assistant; a saída JSON seria outra opção para diferentes aplicativos.

Observação: esse ponto final pode ser usado em vários Assistentes Digitais da Oracle (ou aplicativos semelhantes) para aproveitar os dados e o processamento executados pelo Oracle Autonomous Database Select AI.

Tarefa 3: Configurar um Oracle Digital Assistant

Em nossa instância do Oracle Digital Assistant, criamos um fluxo para lidar com perguntas sobre nossos dados. Fluxos adicionais lidam com solicitações de ajuda, conversa fiada e feedback. As capturas de tela abaixo mostram os lugares no Oracle Digital Assistant em que usamos as informações sobre o ponto final REST que criamos na Tarefa 2 para conectar o chatbot ao serviço REST.

Dica: Este tutorial não abrange a criação e a configuração de um Oracle Digital Assistant. Para obter mais informações, consulte Oracle Digital Assistant.

Este fluxo passa a entrada do usuário para o ponto final REST para processamento.

Configurando Serviços de API do Oracle Digital Assistant

Oracle Digital Assistant - Definindo Variável para Chamar o Serviço REST

Oracle Digital Assistant - Definindo Detalhes da Variável

Oracle Digital Assistant - Chamar Serviço REST

Oracle Digital Assistant - Capturar Resposta do Serviço REST

Tarefa 4: Preparar Dados para o Oracle Autonomous Database Select AI

Nosso esquema inclui várias tabelas associadas a tabelas de mapeamento. Em vez de passar tudo isso para o LLM, criamos uma view que une as tabelas relevantes, usando nosso conhecimento de domínio para enviar uma tabela com todos (e apenas) os dados necessários. Esta exibição é atualizada periodicamente das tabelas de origem para permanecer atualizada.

Polonês a experiência com Geração Aumentada de Recuperação (RAG)

Descobrimos rapidamente que, embora estivéssemos enviando nossos dados completos e confiáveis para o LLM, mais informações eram necessárias para que nossa aplicação produzisse bons resultados. (Aprendemos que engenharia rápida não significa codificar rapidamente!) Ao usar a geração aumentada de recuperação (RAG), conseguimos melhorar nossos resultados. Por exemplo, os pacotes de aplicativos da Oracle representados em nossos dados são conhecidos por várias abreviações e acrônimos, que agora fornecemos em comentários sobre as colunas relevantes. Você pode considerar esse tipo de ação para melhorar seus resultados.

Tarefa 5: Integrar um Oracle Digital Assistant ao Aplicativo Oracle APEX

O aplicativo é uma instância do Oracle APEX hospedada em uma instância do Oracle Autonomous Database. Integrar o Oracle Digital Assistant ao aplicativo.

  1. No aplicativo Oracle APEX, vá para Componentes Compartilhados e Arquivos de Aplicativos Estáticos.

    Esses arquivos de aplicativos estáticos são usados para configurar e chamar o chatbot.

    • settings.js
    • web-sdk.js
    • chatbot_style.css

    Observação: Faça download destes modelos do Oracle Digital Assistant aqui: Downloads do Oracle Digital Assistant (ODA) e do Oracle Mobile Cloud (OMC).

    • settings.js: Este arquivo destina-se à configuração do Oracle Digital Assistant. Atualize os seguintes valores.

      • URL: Informe o URL da sua instância do Oracle Digital Assistant.
      • Nome: Digite o nome do bot referenciado no evento Na Carga da Página do Aplicativo Oracle APEX na página 0.
      • ID do Canal: Informe o ID do canal copiado do aplicativo Oracle Digital Assistant.
      • Para vincular as sessões do usuário do aplicativo Oracle APEX a uma instância de bot mantida em diferentes páginas do aplicativo à medida que o usuário navega.
        • userId: document.getElementById("pInstance").value.

    • web-idk.js: Não são necessárias alterações neste arquivo, mas ele deve ser atualizado para cada nova versão da plataforma do Oracle Digital Assistant, para corresponder à versão do Oracle Digital Assistant.

    • chatbot_style.css: Crie um arquivo CSS do zero para personalizar o ícone do chatbot.

  2. Para configurar o aplicativo a ser usado, faça upload do arquivo em Arquivos de Aplicativo Estático. Vá para Componentes Compartilhados, Atributos da Interface do Usuário, JavaScript e informe os URLs para settings.js e web-sdk.js.

    Atualizar os Atributos da Interface do Usuário do aplicativo - JavaScript

  3. Vá para a guia CSS e digite o URL do arquivo CSS.

    Atualizar os Atributos da Interface do Usuário do aplicativo - CSS

  4. Na Página Global 0 do aplicativo, adicione um evento acionado no carregamento da página para chamar a função initSdk no arquivo settings.js.

    Evento do aplicativo APEX para inicialização de chatbot

    Código de evento do aplicativo APEX para inicialização de chatbot

Execute seu aplicativo Oracle APEX e ele deverá exibir o ícone do chatbot na parte inferior direita da tela. Está pronto para os usuários fazerem perguntas em linguagem natural!

Próximas Etapas

Ativar Consultas de Linguagem Natural para agregar Valor aos Seus Dados

Combinando três tecnologias estratégicas da Oracle, você introduziu rapidamente recursos de IA úteis e extensíveis em seu aplicativo com um novo chatbot que pode ser usado em outros aplicativos e sites. Você pode expandir o escopo dos dados tratados usando o Oracle Autonomous Database Select AI e integrar fontes adicionais de informações para novos fluxos do Oracle Digital Assistant a serem processados.

Vá para os Recursos Especializados de Banco de Dados e experimente a interface de linguagem natural e nos dê feedback.

AskDBExpert em oracle.com/dbexpert

Agradecimentos

Mais Recursos de Aprendizagem

Explore outros laboratórios em docs.oracle.com/learn ou acesse mais conteúdo de aprendizado gratuito no canal Oracle Learning YouTube. Além disso, visite education.oracle.com/learning-explorer para se tornar um Oracle Learning Explorer.

Para obter a documentação do produto, visite o Oracle Help Center.