Tutoriel : Utiliser les sessions d’interpréteur de code dans Semantic Kernel sur Azure Container Apps

Semantic Kernel est un framework IA open source créée par Microsoft pour les développeurs .NET, Python et Java travaillant avec de grands modèles de langage (LLM). Quand vous créez un agent IA avec Semantic Kernel, un LLM interprète l’entrée utilisateur et génère une réponse. L’agent IA rencontre souvent des difficultés quand il doit effectuer un raisonnement mathématique et symbolique pour produire une réponse. En intégrant des sessions dynamiques Azure Container Apps à Semantic Kernel, vous donnez à l’agent un interpréteur de code à utiliser pour effectuer des tâches spécialisées.

Dans ce tutoriel, vous découvrez comment exécuter un agent IA Semantic Kernel dans une API web. L’API accepte une entrée utilisateur et retourne une réponse générée par l’agent IA. L’agent utilise un interpréteur de code dans des sessions dynamiques pour effectuer des calculs.

Prérequis

• Compte Azure avec un abonnement actif.
  • Si vous n’en avez pas, vous pouvez en créer un gratuitement.
• Installez Azure CLI.
• Git.
• Python 3.10 ou ultérieur.

Créer des ressources Azure

L’exemple d’application de ce guide de démarrage rapide utilise un LLM d’Azure OpenAI. Il utilise également des sessions Azure Container Apps pour exécuter le code généré par le LLM.

1. Mettez à jour Azure CLI vers la dernière version.

    az upgrade
   

2. Supprimez l’extension Azure Container Apps si elle est déjà installée et installez une préversion de l’extension Azure Container Apps contenant des commandes pour les sessions :

   az extension remove --name containerapp
   az extension add \
       --name containerapp \
       --allow-preview true -y
   

3. Connectez-vous à Azure :

   az login
   

4. Définissez les variables utilisées dans ce guide de démarrage rapide :

   RESOURCE_GROUP_NAME=aca-sessions-tutorial
   AZURE_OPENAI_LOCATION=swedencentral
   AZURE_OPENAI_NAME=<UNIQUE_OPEN_AI_NAME>
   SESSION_POOL_LOCATION=eastasia
   SESSION_POOL_NAME=code-interpreter-pool
   

   Remplacez <UNIQUE_OPEN_AI_NAME> par un nom unique pour créer votre compte Azure OpenAI.

5. Créez un groupe de ressources :

   az group create --name $RESOURCE_GROUP_NAME --location $SESSION_POOL_LOCATION
   

6. Créez un compte Azure OpenAI :

   az cognitiveservices account create \
       --name $AZURE_OPENAI_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --location $AZURE_OPENAI_LOCATION \
       --kind OpenAI \
       --sku s0 \
       --custom-domain $AZURE_OPENAI_NAME
   

7. Créez un modèle de déploiement GPT 3.5 Turbo nommé gpt-35-turbo dans le compte Azure OpenAI :

   az cognitiveservices account deployment create \
       --resource-group $RESOURCE_GROUP_NAME \
       --name $AZURE_OPENAI_NAME \
       --deployment-name gpt-35-turbo \
       --model-name gpt-35-turbo \
       --model-version "1106" \
       --model-format OpenAI \
       --sku-capacity "100" \
       --sku-name "Standard"
   

8. Créez un pool de sessions d’interpréteur de code :

   az containerapp sessionpool create \
       --name $SESSION_POOL_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --location $SESSION_POOL_LOCATION \
       --max-sessions 100 \
       --container-type PythonLTS \
       --cooldown-period 300
   

Exécuter l’exemple d’application localement

Avant de déployer l’application sur Azure Container Apps, vous pouvez l’exécuter localement pour la tester.

Cloner l’application

1. Clonez le référentiel d’exemples de sessions Azure Container Apps.

   git clone https://github.com/Azure-Samples/container-apps-dynamic-sessions-samples.git
   

2. Accédez au répertoire qui contient l’exemple d’application :

   cd container-apps-dynamic-sessions-samples/semantic-kernel-python-webapi
   

Configurer l’application

1. Créez un environnement virtuel Python et activez-le :

   python3.11 -m venv .venv
   source .venv/bin/activate
   

   Changez la version de Python dans la commande si vous utilisez une autre version. Il est recommandé d’utiliser Python 3.10 ou ultérieur.

   Remarque

   Si vous utilisez Windows, remplacez .venv/bin/activate par .venv\Scripts\activate.

2. Installez les packages Python requis :

   python -m pip install -r requirements.txt
   

3. Pour exécuter l’application, vous devez configurer des variables d’environnement.

   1. Récupérez le point de terminaison du compte Azure OpenAI :

      az cognitiveservices account show \
          --name $AZURE_OPENAI_NAME \
          --resource-group $RESOURCE_GROUP_NAME \
          --query properties.endpoint \
          --output tsv
      

   2. Récupérez le point de terminaison de gestion du pool de sessions Azure Container Apps :

      az containerapp sessionpool show \
          --name $SESSION_POOL_NAME \
          --resource-group $RESOURCE_GROUP_NAME \
          --query properties.poolManagementEndpoint \
          --output tsv
      

   3. Créez un fichier .env à la racine du répertoire de l’exemple d’application (au même endroit que main.py). Ajoutez le contenu suivant au fichier :

      AZURE_OPENAI_ENDPOINT=<AZURE_OPENAI_ENDPOINT>
      POOL_MANAGEMENT_ENDPOINT=<SESSION_POOL_MANAGEMENT_ENDPOINT>
      

      Remplacez <AZURE_OPENAI_ENDPOINT> par le point de terminaison du compte Azure OpenAI et <SESSION_POOL_MANAGEMENT_ENDPOINT> par le point de terminaison de gestion du pool de sessions.

4. L’application utilise DefaultAzureCredential pour s’authentifier auprès des services Azure. Sur votre machine locale, elle utilise vos informations d’identification de connexion Azure CLI actuelles. Vous devez vous attribuer le rôle Utilisateur OpenAI Cognitive Services sur le compte Azure OpenAI pour que l’application puisse accéder aux points de terminaison du modèle, et le rôle Exécuteur de session Azure ContainerApps sur le pool de sessions pour que l’application puisse accéder au pool de sessions.

   1. Récupérez votre nom d’utilisateur d’Azure CLI :

      az account show --query user.name --output tsv
      

   2. Exécutez les commandes suivantes pour récupérer l’ID de ressource du compte Azure OpenAI :

      az cognitiveservices account show --name $AZURE_OPENAI_NAME --resource-group $RESOURCE_GROUP_NAME --query id --output tsv
      

   3. Attribuez le rôle Utilisateur OpenAI Cognitive Services à votre utilisateur Azure CLI sur le compte Azure OpenAI :

      az role assignment create --role "Cognitive Services OpenAI User" --assignee <CLI_USERNAME> --scope <AZURE_OPENAI_RESOURCE_ID>
      

      Remplacez <CLI_USERNAME> par votre nom d’utilisateur Azure CLI et <AZURE_OPENAI_RESOURCE_ID> par l’ID de ressource du compte Azure OpenAI.

   4. Exécutez les commandes suivantes pour récupérer l’ID de ressource du pool de sessions :

      az containerapp sessionpool show --name $SESSION_POOL_NAME --resource-group $RESOURCE_GROUP_NAME --query id --output tsv
      

   5. Attribuez le rôle Exécuteur de session Azure ContainerApps en utilisant son ID à votre utilisateur Azure CLI sur le pool de sessions :

      az role assignment create \
          --role "Azure ContainerApps Session Executor" \
          --assignee <CLI_USERNAME> \
          --scope <SESSION_POOL_RESOURCE_ID>
      

      Remplacez <CLI_USERNAME> par votre nom d’utilisateur Azure CLI et <SESSION_POOL_RESOURCE_ID> par l’ID de ressource du pool de sessions.

Exécuter l’application

Avant d’exécuter l’exemple d’application, ouvrez main.py dans un éditeur et examinez le code. L’application utilise FastAPI pour créer une API web qui accepte un message utilisateur dans la chaîne de requête.

Les lignes de code suivantes instancient un SessionsPythonTool et le fournissent à l’agent Semantic Kernel :

sessions_tool = SessionsPythonTool(
    pool_management_endpoint,
    auth_callback=auth_callback_factory("https://dynamicsessions.io/.default"),
)
kernel.add_plugin(sessions_tool, "SessionsTool")

Quand il doit effectuer des calculs, le noyau utilise l’interpréteur de code dans SessionsPythonTool pour exécuter le code. Le code est exécuté dans une session du pool de sessions. Par défaut, un identificateur de session aléatoire est généré quand vous instanciez l’outil. Si le noyau utilise l’outil pour exécuter plusieurs extraits de code Python, il utilise la même session. Pour garantir que chaque utilisateur final a une session unique, utilisez un noyau et un outil distincts pour chaque utilisateur.

SessionsPythonTool est disponible dans la version 0.9.8b1 ou ultérieure du package semantic-kernel.

1. Exécutez l’exemple d’application :

   fastapi dev main.py
   

2. Ouvrez un navigateur et accédez à http://localhost:8000/docs. Vous voyez l’interface utilisateur Swagger pour l’exemple d’application.

3. Développez le point de terminaison /chat, puis sélectionnez Faites un essai.

4. Entrez What time is it right now? dans le champ message, puis sélectionnez Exécuter.

   L’agent répond avec l’heure actuelle. Dans le terminal, vous voyez les journaux montrant le code Python généré par l’agent pour obtenir l’heure actuelle et son exécution dans une session d’interpréteur de code.

5. Pour arrêter l’application, entrez Ctrl+C dans le terminal.

Facultatif : Déployer l’exemple d’application sur Azure Container Apps

Pour déployer l’application FastAPI sur Azure Container Apps, vous devez créer une image conteneur et l’envoyer (push) à un registre de conteneurs. Vous pouvez ensuite déployer l’image sur Azure Container Apps. La commande az containerapp up combine ces étapes en une seule commande.

Vous devez ensuite configurer l’identité managée pour l’application et lui attribuer les rôles appropriés pour accéder à Azure OpenAI et au pool de sessions.

1. Définissez les variables pour l’environnement Container Apps et le nom de l’application :

   ENVIRONMENT_NAME=aca-sessions-tutorial-env
   CONTAINER_APP_NAME=chat-api
   

2. Générez et déployez l’application sur Azure Container Apps :

   az containerapp up \
       --name $CONTAINER_APP_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --location $SESSION_POOL_LOCATION \
       --environment $ENVIRONMENT_NAME \
       --env-vars "AZURE_OPENAI_ENDPOINT=<OPEN_AI_ENDPOINT>" "POOL_MANAGEMENT_ENDPOINT=<SESSION_POOL_MANAGMENT_ENDPOINT>" \
       --source .
   

   Remplacez <OPEN_AI_ENDPOINT> par le point de terminaison du compte Azure OpenAI et <SESSION_POOL_MANAGMENT_ENDPOINT> par le point de terminaison de gestion du pool de sessions.

3. Activez l’identité managée affectée par le système pour l’application :

   az containerapp identity assign \
       --name $CONTAINER_APP_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --system-assigned
   

4. Pour que l’application accède à Azure OpenAI et au pool de sessions, vous devez affecter l’identité managée aux rôles appropriés.

   1. Récupérez l’ID du principal de l’identité managée :

      az containerapp show \
          --name $CONTAINER_APP_NAME \
          --resource-group $RESOURCE_GROUP_NAME \
          --query identity.principalId \
          --output tsv
      

   2. Récupérez l’ID de ressource du pool de sessions :

      az containerapp sessionpool show \
          --name $SESSION_POOL_NAME \
          --resource-group $RESOURCE_GROUP_NAME \
          --query id \
          --output tsv
      

   3. Affectez l’identité managée aux rôles Azure ContainerApps Session Executor et Contributor sur le pool de sessions :

      Avant d’exécuter la commande suivante, remplacez <PRINCIPAL_ID> et <SESSION_POOL_RESOURCE_ID> par les valeurs que vous avez récupérées lors des étapes précédentes.

      az role assignment create \
          --role "Azure ContainerApps Session Executor" \
          --assignee <PRINCIPAL_ID> \
          --scope <SESSION_POOL_RESOURCE_ID>
      
      az role assignment create \
          --role "Contributor" \
          --assignee <PRINCIPAL_ID> \
          --scope <SESSION_POOL_RESOURCE_ID>
      

   4. Récupérez l’ID de ressource du compte Azure OpenAI :

      az cognitiveservices account show \
          --name $AZURE_OPENAI_NAME \
          --resource-group $RESOURCE_GROUP_NAME \
          --query id \
          --output tsv
      

   5. Attribuez l’identité managée au rôle Cognitive Services OpenAI User sur le compte Azure OpenAI :

      Avant d’exécuter la commande suivante, remplacez <PRINCIPAL_ID> et <AZURE_OPENAI_RESOURCE_ID> par les valeurs que vous avez récupérées lors des étapes précédentes.

      az role assignment create \
          --role "Cognitive Services OpenAI User" \
          --assignee <PRINCIPAL_ID> \
          --scope <AZURE_OPENAI_RESOURCE_ID>
      

5. Récupérez le nom de domaine complet (FQDN) de l’application :

   az containerapp show \
       --name $CONTAINER_APP_NAME \
       --resource-group $RESOURCE_GROUP_NAME \
       --query properties.configuration.ingress.fqdn \
       --output tsv
   

6. Ouvrez le navigateur sur https://<FQDN>/docs pour tester l’application déployée.

Nettoyer les ressources

Quand vous en avez terminé avec les ressources, vous pouvez les supprimer pour éviter d’entraîner des frais :

az group delete --name $RESOURCE_GROUP_NAME --yes --no-wait

Étapes suivantes

Sessions d’interpréteur de code