lundi, juin 09, 2025

Partie 2: Oracle APEX avec Ollama

Dans cette seconde partie nous explorons l'utilisation du service Ollama dans Oracle APEX en développant une page qui accepte en entrée une requête en langage naturel et qui la traduit vers une requête SQL pour afficher le résultat de celle-ci dans un tableau.

NL2SQL

La conversion du langage naturel vers SQL suivi de l'affichage du résultat présente deux challenges techniques principaux:

1. Le choix du modèle 
La contrainte du matériel, dans mon cas un ordinateur qui n'est pas équipé d'une carte graphique NVidia et avec 16Go de mémoire vive, impose le choix d'un modèle adapté à celui-ci, performant mais qui retourne un résultat plutôt fiable.
Après quelques tests sur le modèle initialement installé dans le conteneur Ollama (sqlcoder), il s'avère que les résultats et la performance de celui-ci ne répondent pas au besoin du cas d'utilisation.
2. L'affichage d'un tableau dynamique
Le résultat de la requête retournera un nombre indéfini de colonnes.  Plusieurs approches ici sont possibles, mais pour rester dans l'esprit APEX, on utilisera simplement un Interactive Report en faisant quelques ajustements.

qwen2.5-coder:7b

Compte-tenu des contraintes, nous installons et configurons le modèle qwen-coder qui s'avère plus approprié pour cet exemple sur mon matériel.  
Via un shell:
> docker exec -it ollama /bin/bash
> ollama pull qwen2.5-coder:7b

 Et on peut aussi profiter pour changer la dernière ligne du script run-ollama.sh 
#!/bin/bash

echo "Starting Ollama..."
ollama serve &

echo "Waiting for Ollama to be active..."
while [ "$(ollama list | grep 'NAME')" == "" ]; do
  sleep 1
done

ollama pull qwen2.5-coder:7b

Ne pas oublier de mettre à jour App Builder > Workspace Utilities > Generative AI Services > AI Model pour pointer sur le nouveau modèle: qwen2.5-coder:7b

Le prompt

La construction du prompt à envoyer au LLM se fait en deux temps.  Premièrement on construit le System Prompt qui aura pour objectif de définir la tâche du LLM, de lui fournir le modèle de données comme contexte avec lequel générer la requête SQL, mais aussi préciser les éléments à exclure de sa réponse tels que le raisonnement, mise en forme ou les commentaires.
Dans un processus Before Header sur la page APEX on utilise le code PL/SQL suivant pour générer le System Prompt et le stocker dans l'item P1_SYSTEM_PROMPT.
declare 
    l_system_prompt                 clob;
    l_owner                         varchar2(100) := 'DEFAULT_SCHEMA';
    l_ddl                           clob;
    l_relationships_comment         clob;
begin   
    :P1_QUERY_OK_YN := 'N';
    
    l_system_prompt := 
    '
    Your task is to convert a question into an SQL SELECT query.
    This query will run on the following database tables:
    {{sql_ddl_statement}}    
    DO NOT GENERATE REASONING. 
    DO NOT FORMAT CODE.  
    DO NOT COMMENT THE CODE.   
    ';
 
    dbms_metadata.set_transform_param(dbms_metadata.session_transform, 'STORAGE', false);
    dbms_metadata.set_transform_param(dbms_metadata.session_transform, 'TABLESPACE', false);
    dbms_metadata.set_transform_param(dbms_metadata.session_transform, 'CONSTRAINTS', false);
    dbms_metadata.set_transform_param(dbms_metadata.session_transform, 'REF_CONSTRAINTS', true);
    dbms_metadata.set_transform_param(dbms_metadata.session_transform, 'SEGMENT_ATTRIBUTES', false);
    dbms_metadata.set_transform_param(dbms_metadata.session_transform, 'EMIT_SCHEMA', false);
    dbms_metadata.set_transform_param(dbms_metadata.session_transform, 'SQLTERMINATOR', true);
    
    for t in (
        select
            ata.table_name,
            dbms_metadata.get_ddl('TABLE', ata.table_name, l_owner) as create_statement
        from 
            all_tables ata
            left join user_tab_comments utc on utc.table_name = ata.table_name
        where
            ata.owner = l_owner
    )
    loop
        l_ddl := l_ddl || t.create_statement;        
    end loop;

    :P1_SYSTEM_PROMPT := replace(l_system_prompt, '{{sql_ddl_statement}}', l_ddl);
end;

Invocation du modèle

On construit la page suivante
P1_QUESTION est le champs de saisie qui accepte la requête en langage naturel de l'utilisateur et le bouton GENERATE_SQL utilise une Dynamic ActionGenerate Text With AI avec pour paramètres le system prompt, la question, le modèle et le paramètre de sortie pour la réponse qui sera stockée dans P1_GENERATED_SQL.
Page APEX

Interprétation des résultats

Le LLM retourne la requête SQL générée dans P1_GENERATE_SQL.
Créer une Dynamic Action: Change sur cet item pour analyser et lancer la requête via un Execute Server-side Code dans lequel on mettra le code suivant:
declare
    l_context                   apex_exec.t_context;
    l_columns                   apex_exec.t_columns;
    l_column                    apex_exec.t_column;
begin
    if :P1_GENERATED_SQL is null then
        return;
    end if;

    APEX_COLLECTION.CREATE_COLLECTION_FROM_QUERY (
        p_collection_name       => 'SEARCH_RESULTS_COLL',
        p_query                 => :P1_GENERATED_SQL,
        p_truncate_if_exists    => 'YES'
    );

    l_context := apex_exec.open_query_context(p_location => apex_exec.c_location_local_db, p_sql_query => :P1_GENERATED_SQL);
    l_columns := apex_exec.get_columns(p_context => l_context);
    :P1_QUERY_COLUMNS_NAMES := '';
    :P1_QUERY_COLUMNS_COUNT := apex_exec.get_column_count(p_context => l_context);
    
    for i in 1..apex_exec.get_column_count(p_context => l_context)
    loop
        l_column := apex_exec.get_column (p_context => l_context, p_column_idx => i);
        :P1_QUERY_COLUMNS_NAMES := :P1_QUERY_COLUMNS_NAMES || l_column.name || ',';
    end loop;
   
    :P1_QUERY_COLUMNS_NAMES := substr(:P1_QUERY_COLUMNS_NAMES, 1, length(:P1_QUERY_COLUMNS_NAMES) - 1);
    :P1_QUERY_OK_YN := 'Y';
    exception when others then
        --raise_application_error(-20001, sqlerrm);
        :P1_QUERY_OK_YN := 'N';
end;
Les données du résultat de la requête SQL sont mises dans une collection et afin de cacher les colonnes vides et renommer celles pertinentes, on garde le nombre total de colonnes dans P1_QUERY_COLUMNS_COUNT et leurs noms dans P1_QUERY_COLUMNS_NAMES.
Une Dynamic Action: Change sur P1_QUERY_OK_YN lorsque l'item prend la valeur 'Y' déclenchera l'affichage de la région Interactive Report.
 
Cette requête va retourner toutes les colonnes de APEX_COLLECTION, donc pour n'afficher que celles pertinentes à la requête SQL générée, on peut utiliser des Server-side Condition sur chacune des colonnes.  Par exemple sur la colonne C002 une expression PL/SQL: P1_QUERY_COLUMNS_COUNT > 1 sur la colonne suivante C003 une expression PL/SQL:P1_QUERY_COLUMNS_COUNT > 2 etc.  
Bien entendu on pourrait aussi définir une autre règle pour afficher ou cacher les colonnes.
Quant au renommage des colonnes le javascript sur le Dynamic Action: After Refresh de l'Interactive Report peut faire l'affaire.
const columns = $v('P1_QUERY_COLUMNS_NAMES').split(',');
const htmlTableId = $('#IR_RESULTS .a-IRR-table').attr('id');
$('a.a-IRR-headerLink').each( function(i, v) {
    $(this).text(columns[i]);
});

Conclusion

Vous pouvez télécharger l'exemple ici sous forme d'application APEX exportée.
Forcément le renommage dynamique des colonnes de l'Interactive Report ne se réalise que sur l'affichage du tableau et lors de manipulations des colonnes dans la barre d'outils, l'utilisateur verra le nom générique des colonnes C001, C002 etc.

Libellés : , , ,