Documentation sur Oracle Cloud Infrastructure

Appeler des scripts Python avec WITH_CONTEXT sur une base de données d'intelligence artificielle autonome

Affiche les étapes pour appeler des scripts Python à l'aide de WITH_CONTEXT sur votre base de données.

Rubriques

Rubrique parent : Appeler des fonctions définies par l'utilisateur

À propos de l'appel de scripts Python avec WITH_CONTEXT sur une base de données d'intelligence artificielle autonome

Vous pouvez exécuter des scripts Python sur une instance de base de données d'intelligence artificielle autonome à l'aide de travaux Oracle Scheduler avec l'attribut WITH_CONTEXT.

Lorsque vous appelez des scripts Python avec WITH_CONTEXT sur Autonomous AI Database, un pointeur de contexte est transmis au script qui permet au script de revenir à la base de données. Le contexte fait référence à la session de base de données, à la connexion et à tout état ou donnée associé auquel le script doit accéder ou manipuler.

Vous ne pouvez pas exécuter un script Python directement sur une instance de base de données autonome avec intelligence artificielle. À la place, vous hébergez le script à distance sur une image de conteneur Extproc d'Oracle Autonomous AI Database s'exécutant dans un réseau en nuage virtuel (VCN) d'Oracle Cloud Infrastructure. L'image de conteneur est préconfigurée avec l'agent EXTPROC et comprend toutes les bibliothèques nécessaires, telles que utils, onnx et python-oracledb, pour exécuter le script.

Vous appelez des scripts Python à partir de votre base de données d'intelligence artificielle autonome à l'aide des travaux Oracle Scheduler. La tâche du programmateur que vous créez doit être une tâche exécutable qui est exécutée avec l'attribut WITH_CONTEXT. Les travaux exécutables peuvent exécuter des scripts d'interpréteur de commandes ou d'autres exécutables et l'attribut Oracle Scheduler WITH_CONTEXT permet à un script d'hériter des privilèges de session courants lors de l'appel d'une procédure, d'un programme ou d'un script externe. L'attribut WITH_CONTEXT permet aux sous-programmes externes d'accéder à des informations propres à la session telles que le schéma, les privilèges et d'autres variables de contexte.

Les scripts Python de votre base de données autonome d'IA ne sont pris en charge que lorsque votre base de données se trouve sur un point d'extrémité privé. Pour exécuter des scripts Python, vous devez obtenir, installer et configurer l'image de conteneur Oracle Autonomous AI Database EXTPROC avec l'agent EXTPROC installé. L'image de conteneur Autonomous AI Database EXTPROC vous permet d'appeler des procédures et des scripts externes écrits en BASH, C ou Python à partir de votre base de données Autonomous AI Database. L'instance d'agent EXTPROC est hébergée dans un sous-réseau privé et la base de données autonome d'IA accède à l'agent EXTPROC au moyen d'un point d'extrémité de connexion inverse (RCE).

Note

Cette fonction n'est prise en charge que pour la version de base de données Oracle 19c.

Vous déployez des scripts Python à l'aide des éléments suivants :

  • Une image de conteneur de base de données d'intelligence artificielle autonome fournie par Oracle avec l'agent EXTPROC installé. Oracle fournit l'image de conteneur sur les ensembles GitHub.

    Voir GitHub README pour obtenir et configurer l'image de conteneur EXTPROC :

    L'instance d'agent EXTPROC est hébergée à distance sur une image de conteneur s'exécutant dans un réseau en nuage virtuel (VCN) Oracle Cloud Infrastructure. La communication sécurisée entre votre base de données d'IA autonome et l'instance d'agent EXTPROC est sécurisée en définissant des règles de groupe de sécurité de réseau de sorte que le trafic soit autorisé entre votre instance de base de données d'IA autonome s'exécutant sur un point d'extrémité privé et l'instance d'agent EXTPROC. L'image de l'agent EXTPROC est préconfigurée pour héberger et exécuter des procédures externes sur le port 16000.

  • Procédures PL/SQL permettant d'enregistrer des environnements de point d'extrémité et de gérer les privilèges sur les points d'extrémité enregistrés. Pour plus d'informations, voir Ensemble DBMS_CLOUD_FUNCTION_ADMIN.

  • Procédures PL/SQL permettant de créer et de gérer des travaux et des programmes du planificateur pour appeler des scripts Python.

    Pour plus d'informations, voir DBMS_SCHEDULER.

Suivez ces étapes pour exécuter un script Python avec WITH_CONTEXT sur une instance de base de données d'IA autonome :

Créer un script Python

Affiche un exemple de création d'un script Python

  • Exemple : Script Python pour créer une table dans votre base de données.

    #!/usr/bin/env python1

import oracledb
import utils
 def gsf_main(argc, argv):
    table_name = argv[0]
    table_pk = argv[1]
    print(f"Total number of args: {argc}")
    print(f"Arg1: {table_name}")
    print(f"Arg2: {table_pk}")
    print(f"Arg3: {argv[2]}")
    print(f"Arg4: {argv[3]}")
    print(f"Arg5: {argv[4]}")
     
    # Step 1: Get connection object
    con = utils.getconnection()
    if con is None:
        print("Failed to establish database connection.")
        return -1
      try:
        # Step 2: Create a table
        cur = con.cursor()
        create_table_query = f"""
            CREATE TABLE {table_name} (
                employee_id NUMBER GENERATED ALWAYS AS IDENTITY (START WITH 1 INCREMENT BY 1),
                employee_name VARCHAR2(4000),
                employee_age NUMBER,
                CONSTRAINT {table_pk} PRIMARY KEY (employee_id)
            )
            """
        cur.execute(create_table_query)
    except Exception as e:
        print(f"Error performing operations: {e}")
        return -1
    finally:
        if cur:
            cur.close()

    Cet exemple crée le script python1.py. Le script définit une fonction Python gsf_main(argc, argv) qui accepte les arguments d'un travail du planificateur, crée une table dans la base de données avec les attributs fournis et gère les exceptions.

    Le pilote oracledb permet au script de se connecter à la base de données.

    L'ensemble utils fournit une fonction d'aide getconnection() pour obtenir une connexion à la base de données.

Pour plus d'informations, voir la documentation sur Python.

Configurer l'image de conteneur EXTPROC d'Oracle Autonomous AI Database

Décrit les étapes pour obtenir et configurer l'image de conteneur EXTPROC d'Oracle Autonomous AI Database.

Une image de conteneur de base de données Autonomous AI Database fournie par Oracle avec l'agent EXTPROC installé est hébergée sur les ensembles GitHub. Voir GitHub README pour obtenir et configurer l'image de conteneur EXTPROC.

Charger le portefeuille pour créer une connexion sécurisée à l'instance d'agent EXTPROC

Un portefeuille auto-signé est créé dans le cadre de la création de l'application d'agent Autonomous AI Database EXTPROC. Ce portefeuille vous permet d'accéder à l'instance d'agent Extrpoc.

Pour exécuter des scripts Python dans l'instance d'agent EXTPROC, la base de données d'intelligence artificielle autonome et l'agent EXTPROC se connectent à l'aide du protocole mTLS (mutual Transport Layer Security). Lors de l'utilisation de la sécurité de la couche de transport mutuel (mTLS), les clients se connectent au moyen d'une connexion TCPS (TCP sécurisé) à la base de données à l'aide de la norme TLS 1.2 avec un certificat de client approuvé d'une autorité de certification (CA). Pour plus d'informations, voir À propos de la connexion à une instance de base de données du service d'intelligence artificielle autonome.
Note

Vous pouvez également obtenir et utiliser un certificat public émis par une autorité de certification.

Vous devez d'abord exporter le portefeuille vers le stockage d'objets à partir du répertoire /u01/app/oracle/extproc_wallet sur la machine virtuelle où EXTPROC s'exécute.

Suivez ces étapes pour charger le portefeuille dans votre base de données d'intelligence artificielle autonome :

  1. Importez le portefeuille, cwallet.sso, contenant les certificats de l'instance d'agent EXTPROC dans votre base de données d'IA autonome à partir du stockage d'objets. Notez ce qui suit pour le fichier de portefeuille :

    • Le fichier de portefeuille, ainsi que l'ID utilisateur et le mot de passe de la base de données, permettent d'accéder à l'instance d'agent EXTPROC. Stockez les fichiers de portefeuille dans un emplacement sécurisé et partagez-les uniquement avec les utilisateurs autorisés.

    • Ne renommez pas le fichier de portefeuille. Le fichier de portefeuille dans le stockage d'objets doit être nommé cwallet.sso.

  2. Créez des données d'identification pour accéder au stockage d'objets où vous stockez le fichier de portefeuille cwallet.sso. Voir Procédure CREATE_CREDENTIAL pour plus d'informations sur les paramètres de nom d'utilisateur et de mot de passe pour différents services de stockage d'objets.
    La création de données d'identification pour accéder au magasin d'objets Oracle Cloud Infrastructure n'est pas requise si vous activez les données d'identification du principal de ressource. Pour plus d'informations, voir À propos de l'utilisation d'un principal de ressource pour accéder aux ressources Oracle Cloud Infrastructure.
  3. Créez un répertoire dans Autonomous AI Database pour le fichier de portefeuille cwallet.sso.
    CREATE DIRECTORY wallet_dir AS 'directory_location';

    Voir Créer un répertoire dans Autonomous AI Database pour plus d'informations sur la création de répertoires.

  4. Utilisez DBMS_CLOUD.GET_OBJECT pour charger le portefeuille. Exemple :
    BEGIN
  DBMS_CLOUD.GET_OBJECT (
    credential_name     => 'DEF_CRED_NAME',
    object_uri          => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/cwallet.sso',
    directory_name      => 'WALLET_DIR'
);
END;
/

    Dans cet exemple, namespace-string est l'espace de noms du service de stockage d'objets pour Oracle Cloud Infrastructure Object Storage et bucketname est le nom du seau. Pour plus d'informations, voir Espaces de noms du stockage d'objets.

    Le portefeuille est copié dans le répertoire créé à l'étape précédente, WALLET_DIR. Le portefeuille qui vous permet de vous connecter à l'instance d'agent EXTPROC est maintenant disponible dans votre instance de base de données du service d'intelligence artificielle autonome.

Etapes d'appel des scripts Python

Affiche les étapes permettant d'appeler des scripts Python sur une base de données autonome avec intelligence artificielle.

Après avoir configuré l'instance d'agent EXTPROC pour exécuter des scripts Python, vous enregistrez un point d'extrémité distant et créez des tâches du programmateur pour appeler les scripts.

Voici les conditions requises pour appeler des scripts Python sur une base de données autonome avec intelligence artificielle :

  • Les scripts Python doivent être copiés dans l'instance d'agent EXTPROC.

  • Pour créer et gérer des travaux du planificateur afin d'appeler des scripts Python avec un utilisateur autre qu'ADMIN, vous devez disposer des privilèges suivants :

    • MANAGE SCHEDULER

    • CREATE JOB

    • Privilège sur le point d'extrémité distant enregistré

Rubriques

Rubrique parent : Appeler des scripts Python avec WITH_CONTEXT sur une base de données d'intelligence artificielle autonome

Enregistrer et gérer un point d'extrémité distant dans une base de données autonome avec intelligence artificielle

En tant qu'utilisateur ADMIN, effectuez les étapes suivantes pour enregistrer et gérer des points d'extrémité distants dans votre base de données du service d'intelligence artificielle autonome.

Enregistrer un point d'extrémité distant

Utilisez DBMS_CLOUD_FUNCTION_ADMIN.REGISTER_REMOTE_EXECUTION_ENV pour enregistrer un point d'extrémité distant.

Exemple :

BEGIN
 DBMS_CLOUD_FUNCTION_ADMIN.REGISTER_REMOTE_EXECUTION_ENV (
        remote_endpoint_name => 'rem_executable',
        remote_endpoint_url  => 'remote_extproc_hostname:16000',
        wallet_dir           => 'WALLET_DIR',
        remote_cert_dn       => 'CN=MACHINENAME'
);
END;
/

Cet exemple crée la bibliothèque rem_executable et enregistre l'instance d'agent EXTPROC spécifiée dans le paramètre remote_endpoint_url de votre base de données d'intelligence artificielle autonome. L'instance d'agent EXTPROC est préconfigurée pour héberger les scripts Python sur le port 16000.

Pour plus d'informations, voir ProcédureREGISTER_REMOTE_EXECUTION_ENV.

Gérer les privilèges sur un point d'extrémité enregistré

Cette étape est facultative et n'est requise que lorsqu'un utilisateur autre qu'ADMIN doit appeler des scripts Python à partir de la base de données autonome avec intelligence artificielle.

Utilisez DBMS_CLOUD_FUNCTION_ADMIN.GRANT_REMOTE_EXECUTION_ENV pour accorder le privilège sur le point d'extrémité enregistré à un utilisateur autre que l'administrateur.

Exemple :

BEGIN
 DBMS_CLOUD_FUNCTION_ADMIN.GRANT_REMOTE_EXECUTION_ENV (   
    remote_endpoint_name => 'REM_EXECUTABLE',
    user_name            => 'username');
END;
/

Cet exemple accorde le privilège sur REM_EXECUTABLE à l'utilisateur spécifié. Pour plus d'informations, voir ProcédureGRANT_REMOTE_EXECUTION_ENV.

Après avoir accordé le privilège sur le point d'extrémité enregistré, vous pouvez utiliser DBMS_CLOUD_FUNCTION_ADMIN.REVOKE_REMOTE_EXECUTION_ENV pour révoquer le privilège sur le point d'extrémité enregistré d'un utilisateur.

Exemple :

BEGIN
 DBMS_CLOUD_FUNCTION_ADMIN.REVOKE_REMOTE_EXECUTION_ENV (   
    remote_endpoint_name => 'REM_EXECUTABLE',
    user_name            => 'username');
END;
/

Cet exemple révoque le privilège sur REM_EXECUTABLE de l'utilisateur spécifié. Pour plus d'informations, voir ProcédureREVOKE_REMOTE_EXECUTION_ENV.

Vous pouvez interroger DBA_CLOUD_FUNCTION_REMOTE_EXECUTION_GRANT pour lister les autorisations accordées pour tous les points d'extrémité distants. Pour plus d'informations, voir Vue DBA_CLOUD_FUNCTION_REMOTE_EXECUTION_GRANT.

Supprimer un point d'extrémité enregistré

Utilisez DBMS_CLOUD_FUNCTION_ADMIN.DEREGISTER_REMOTE_EXECUTION_ENV pour supprimer un point d'extrémité distant enregistré.

Exemple :

BEGIN
 DBMS_CLOUD_FUNCTION_ADMIN.DEREGISTER_REMOTE_EXECUTION_ENV (   
    remote_endpoint_name => 'REM_EXECUTABLE');
END;
/

Cela supprime le point d'extrémité distant rem_executable de votre base de données d'intelligence artificielle autonome. Pour plus d'informations, voir ProcédureDEREGISTER_REMOTE_EXECUTION_ENV.

Créer et gérer des travaux du programmateur pour appeler des scripts Python

Affiche les étapes de création et de gestion des tâches de programmateur pour appeler des scripts Python à partir de la base de données d'intelligence artificielle autonome.

Pour exécuter les étapes suivantes en tant qu'utilisateur autre que ADMIN, vous devez disposer des privilèges requis. Pour plus d'informations, voir Étapes d'appel de scripts Python.
  1. Utilisez DBMS_SCHEDULER.CREATE_JOB pour créer une tâche de programmateur avec le type de tâche executable. Par exemple :
    BEGIN
 DBMS_SCHEDULER.CREATE_JOB (
    job_name             => 'rem_exec_job',
    job_type             => 'executable',
    job_action           => '/script_location_on_extproc_agent_image/python1.py',
    number_of_arguments  => 1,
    enabled              => false,
    auto_drop            => true);
 END;
/

    Cet exemple crée le travail du programmateur rem_exec_job de type exécutable.

    Le paramètre job_name spécifie le nom de la tâche.

    Le paramètre job_type spécifie le type d'action de tâche. Vous devez spécifier job_type comme exécutable pour appeler des scripts Python sur votre base de données d'intelligence artificielle autonome.

    Le paramètre job_action spécifie l'action insérée de la tâche. Il s'agit de l'emplacement du script sur le point d'extrémité distant que vous devez appeler. Cet exemple appelle le script python1.py, créé à l'étape précédente.

    Le paramètre number_of_arguments spécifie le nombre d'arguments de tâche.

    Le paramètre enabled indique si la tâche doit être activée immédiatement après sa création. Vous ne pouvez pas activer une tâche Oracle Scheduler qui appelle un script Python à la création. Utilisez DBMS_SCHEDULER.ENABLE pour activer la tâche une fois la tâche créée.

    Le paramètre auto_drop indique si la tâche doit être supprimée une fois terminée.

  2. Utilisez DBMS_SCHEDULER.SET_JOB_ARGUMENT_VALUE pour définir la valeur de l'argument de tâche.

    Exemple :

    BEGIN
 DBMS_SCHEDULER.SET_JOB_ARGUMENT_VALUE (
    job_name          => 'rem_exec_job',
    argument_position => 1,
    argument_value    => 'job_param');
 END;
/

    Cet exemple règle le premier argument de la tâche rem_exec_job à une valeur String job_param. Lors de l'exécution de la tâche, job_param est transmis comme valeur de son premier paramètre.

  3. Utilisez DBMS_SCHEDULER.SET_ATTRIBUTE pour modifier l'attribut destination de la tâche rem_exec_job. L'attribut destination spécifie la destination du point d'extrémité distant.

    Exemple :

    BEGIN
 DBMS_SCHEDULER.SET_ATTRIBUTE (
      name       => 'rem_exec_job',
      attribute  => 'destination',
      value      => 'REMOTE_EXTPROC:remote_endpoint_name:WITH_CONTEXT');
 END;
/

    Cet exemple modifie l'attribut destination de la tâche rem_exec_job pour spécifier le chemin d'accès à la bibliothèque distante.

    Le paramètre job_name spécifie le nom de la tâche.

    Le paramètre attribute spécifie l'attribut à modifier.

    Le paramètre value modifie l'attribut destination pour spécifier la destination du point d'extrémité distant.

    Le paramètre accepte une valeur de type chaîne au format REMOTE_EXTPROC:remote_endpoint_name:WITH_CONTEXT, où remote_endpoint_name est le nom du point d'extrémité distant enregistré. La clause WITH_CONTEXT permet à un script d'hériter des privilèges de session courants lors de l'appel d'une procédure, d'un programme ou d'un script externe.

    Une erreur est survenue si vous ne disposez pas des privilèges sur le point d'extrémité spécifié.

    Pour plus d'informations, voir Sous-programmes DBMS_SCHEDULER.

  4. Exécutez DBMS_SCHEDULER.ENABLE pour activer la tâche de programmateur.

    Exemple :

    BEGIN
 DBMS_SCHEDULER.ENABLE (
    name => 'rem_exec_job');
 END; 
/

    Cet exemple active la tâche rem_exec_job. Pour plus d'informations, voir DBMS_SCHEDULER.

    Une fois le travail activé, le planificateur commence à l'exécuter.

    Interrogez la vue USER_CLOUD_FUNCTION_RUN_DETAILS et la vue DBA_CLOUD_FUNCTION_RUN_DETAILS pour voir le statut des tâches du programmateur.