Partager via

Démarrage rapide : Prise en main des Assistants Azure OpenAI (préversion)

  • Article

Les Assistants Azure OpenAI (préversion) vous permettent de créer des assistants IA adaptés à vos besoins par le biais d’instructions personnalisées et augmentées par des outils avancés tels que l’interpréteur de code et les fonctions personnalisées.

Important

Les éléments marqués (préversion) dans cet article sont actuellement en préversion publique. Cette préversion est fournie sans contrat de niveau de service, nous la déconseillons dans des charges de travail de production. Certaines fonctionnalités peuvent être limitées ou non prises en charge. Pour plus d’informations, consultez Conditions d’Utilisation Supplémentaires relatives aux Évaluations Microsoft Azure.

Prérequis

Accédez à Azure AI Studio (préversion)

Azure AI Studio vous permet d’utiliser Assistants v2, qui fournit plusieurs mises à niveau telles que l’outil de recherche de fichiers qui est plus rapide et prend en charge davantage de fichiers.

  1. Connectez-vous à Azure AI Studio.

  2. Accédez à votre projet ou créez un projet dans Azure AI Studio.

  3. Dans la vue d’ensemble de votre projet, sélectionnez Assistants, qui se trouve sous Terrain de jeu du projet.

    Le terrain de jeu Assistants vous permet d’explorer, de prototyper et de tester des assistants IA sans exécuter de code. À partir de cette page, vous pouvez rapidement itérer et expérimenter les nouvelles idées.

    Le terrain de jeu propose plusieurs options pour configurer votre Assistant. Dans les étapes suivantes, vous allez utiliser le volet d’installation de l’Assistant pour créer un assistant IA.

    Nom Description
    Nom de l’Assistant Votre nom de déploiement associé à un modèle spécifique.
    Instructions Les instructions sont similaires aux messages système, c’est là que vous fournissez des instructions sur le comportement du modèle et tout contexte qu’il doit référencer lorsqu’il génère une réponse. Vous pouvez décrire la personnalité de l’assistant, lui dire ce qu’il doit et ne doit pas répondre, et lui indiquer comment formater les réponses. Vous pouvez également fournir des exemples des mesures à prendre lorsqu’il répond aux réponses.
    Déploiement C’est là que vous définissez le modèle de déploiement à utiliser avec votre assistant.
    Fonctions Créer des définitions de fonction personnalisées pour les modèles afin de formuler des appels d’API et des sorties de données de structure en fonction de vos spécifications. Non utilisé dans ce guide de démarrage rapide.
    Interpréteur de code L’interpréteur de code fournit un accès à un environnement Python en bac à sable qui peut être utilisé pour permettre au modèle de tester et d’exécuter du code.
    Fichiers Vous pouvez charger jusqu’à 10 000 fichiers d’une taille de fichier maximale de 512 Mo à utiliser avec des outils. Non utilisé dans ce guide de démarrage rapide.

    Capture d’écran de l’écran de configuration de l’Assistant sans toutes les valeurs renseignées.

Créez votre premier assistant

  1. Sélectionnez votre déploiement dans la liste déroulante Déploiements.

  2. Dans le menu déroulant Configuration de l’Assistant, sélectionnez Nouveau.

  3. Nommez votre Assistant.

  4. Entrez les instructions suivantes : « Vous êtes un assistant IA capable d’écrire du code pour répondre aux questions mathématiques ».

  5. Sélectionnez un modèle de déploiement. Nous vous recommandons de tester avec l’un des derniers modèles gpt-4.

  6. Sélectionnez le bouton bascule qui active l’interpréteur de code.

  7. Sélectionnez Enregistrer.

    Capture d’écran de l’Assistant avec les détails de configuration entrés.

  8. Entrez une question à laquelle l’assistant doit répondre : « J’ai besoin de résoudre l’équation 3x + 11 = 14. Pouvez-vous m’aider ? ».

  9. Sélectionnez le bouton Ajouter et exécuter 

    The solution to the equation (3x + 11 = 14) is (x = 1).

    Bien que nous puissions voir que cette réponse est correcte, nous poserons une autre question dans le but de confirmer que le modèle a utilisé l’interpréteur de code pour accéder à cette réponse et que le code qu’il a écrit est valide, au lieu de répéter une réponse provenant des données de formation du modèle.

  10. Entrez la question de suivi : « Montrez-moi le code que vous avez exécuté pour obtenir cette réponse. ».

    Sure. The code is very straightforward

    # calculation
x = (14 - 11) / 3
x


    First, we subtract 11 from 14, then divide the result by 3. This gives us the value of x which is 1.0.

    Capture d’écran de la session de conversation dans le terrain de jeu Assistant.

Vous pouvez également consulter les journaux d’activité dans le volet de droite pour vérifier que l’interpréteur de code a été utilisé et pour valider le code exécuté pour générer la réponse. Il est important de ne pas oublier que si l’interpréteur de code donne au modèle la possibilité de répondre à des questions mathématiques plus complexes en convertissant les questions en code et en s’exécutant dans un environnement Python en bac à sable, vous devez toujours valider la réponse pour confirmer que le modèle a correctement traduit votre question en une représentation valide dans le code.

Concepts clés

Tout en utilisant le terrain de jeu Assistants, gardez à l’esprit les concepts suivants.

outils

Un assistant individuel peut accéder à jusqu’à 128 outils, notamment code interpreter, ainsi qu’à n’importe quel outil personnalisé que vous créez par le biais de fonctions.

Session de conversation instantanée

La session de conversation, également appelée thread, dans l’API de l’Assistant est l’endroit où la conversation entre l’utilisateur et l’Assistant a lieu. Contrairement aux appels de saisie semi-automatique de conversation traditionnels, il n’existe aucune limite au nombre de messages dans un thread. L’assistant compresse automatiquement les demandes pour qu’elles correspondent à la limite du jeton d’entrée du modèle.

Cela signifie également que vous ne contrôlez pas le nombre de jetons passés au modèle pendant chaque tour de la conversation. La gestion des jetons est abstraite et entièrement gérée par l’API Assistants.

Sélectionnez le bouton Effacer la conversation pour supprimer l’historique actuel des conversations.

Vous trouverez deux boutons sous la zone de saisie du texte :

  • Ajouter un message sans exécution.
  • Ajouter et exécuter.

Journaux d’activité

Les journaux fournissent un cliché instantané détaillé de l’activité de l’API Assistant.

Afficher les panneaux

Par défaut, il y a trois panneaux : configuration de l’assistant, session de conversation et journaux d’activité. La fonctionnalité Afficher les panneaux vous permet d’ajouter, de supprimer et de réorganiser les panneaux. Si jamais vous fermez un panneau et que vous avez besoin de le récupérer, utilisez Afficher les panneaux pour restaurer le panneau perdu.

Nettoyer les ressources

Si vous voulez nettoyer et supprimer une ressource Azure OpenAI, vous pouvez supprimer la ressource ou le groupe de ressources. La suppression du groupe de ressources efface également les autres ressources qui y sont associées.

Vous pouvez également supprimer l’Assistant ou thread via l’API de l’Assistant.

Voir aussi

Documentation de référence | Code source de la bibliothèque | Package (PyPi) |

Prérequis

Pour l’authentification sans mot de passe, il vous faut

  1. Utilisez le package azure-identity.
  2. Attribuez le rôle Cognitive Services User à votre compte d’utilisateur. Cela peut être effectué dans le Portail Azure sous Contrôle d’accès (IAM)>Ajouter une attribution de rôle.
  3. Connectez-vous à l’aide de l’interface Azure CLI, par exemple az login.

Configurer

  1. Installez la bibliothèque de client Python OpenAI avec :
pip install openai
  1. Pour l’authentification sans mot de passe recommandée :
pip install azure-identity

Remarque

  • La recherche de fichiers peut ingérer jusqu’à 10 000 fichiers par assistant, soit 500 fois plus qu’auparavant. Elle est rapide, prend en charge les requêtes parallèles par le biais de recherches multithread, et propose des fonctionnalités améliorées de reclassement et de réécriture des requêtes.
    • Le magasin de vecteurs est un nouvel objet dans l’API. Une fois qu’un fichier est ajouté à un magasin vectoriel, il est automatiquement analysé, découpé en morceaux et incorporé, prêt à être recherché. Les magasins vectoriels peuvent être utilisés par tous les assistants et threads, ce qui simplifie la gestion des fichiers et la facturation.
  • Nous avons ajouté la prise en charge du tool_choice paramètre qui peut être utilisé pour forcer l’utilisation d’un outil spécifique (comme la recherche de fichiers, l’interpréteur de code ou une fonction) dans une exécution particulière.

Remarque

Cette bibliothèque est gérée par OpenAI. Reportez-vous à l’historique des versions pour suivre les dernières mises à jour de la bibliothèque.

Récupérer la clé et le point de terminaison

Pour effectuer un appel sur le service Azure OpenAI, vous aurez besoin des éléments suivants :

Nom de la variable Valeur
ENDPOINT Cette valeur se trouve dans la section Clés et point de terminaison quand vous examinez votre ressource à partir du portail Azure. Vous pouvez également trouver le point de terminaison via la page Déploiements dans Azure AI Studio. Voici un exemple de point de terminaison : https://docs-test-001.openai.azure.com/.
API-KEY Cette valeur se trouve dans la section Clés et point de terminaison quand vous examinez votre ressource à partir du portail Azure. Vous pouvez utiliser soit KEY1, soit KEY2.
DEPLOYMENT-NAME Cette valeur correspond au nom personnalisé que vous avez choisi pour votre déploiement lorsque vous avez déployé un modèle. Cette valeur se trouve sousGestion des ressources>Déploiements de modèles dans le portail Azure, ou dans la page Déploiements d’Azure AI Studio.

Accédez à votre ressource sur le portail Azure. Le point de terminaison et les clés se trouvent dans la section Gestion des ressources. Copiez votre point de terminaison et votre clé d’accès, car vous aurez besoin de l’authentification de vos appels d’API. Vous pouvez utiliser soit KEY1, soit KEY2. Avoir toujours deux clés vous permet de faire pivoter et de régénérer en toute sécurité les clés sans provoquer d’interruption de service.

Capture d’écran du panneau de vue d’ensemble d’une ressource Azure OpenAI dans le Portail Azure avec l’emplacement des clés d’accès et du point de terminaison encerclés en rouge.

Variables d'environnement

Créez et affectez des variables d’environnement persistantes pour votre clé et votre point de terminaison.

Important

Si vous utilisez une clé API, stockez-la en toute sécurité dans un autre emplacement, par exemple dans Azure Key Vault. N'incluez pas la clé API directement dans votre code et ne la diffusez jamais publiquement.

Pour plus d’informations sur la sécurité des services IA, consultez Authentifier les requêtes auprès d’Azure AI services.

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"

Créer un assistant

Dans notre code, nous allons spécifier les valeurs suivantes :

Nom Description
Nom de l’Assistant Votre nom de déploiement associé à un modèle spécifique.
Instructions Les instructions sont similaires aux messages système, c’est là que vous fournissez des instructions sur le comportement du modèle et tout contexte qu’il doit référencer lorsqu’il génère une réponse. Vous pouvez décrire la personnalité de l’assistant, lui dire ce qu’il doit et ne doit pas répondre, et lui indiquer comment formater les réponses. Vous pouvez également fournir des exemples des mesures à prendre lorsqu’il répond aux réponses.
Modèle C’est là que vous définissez le nom du modèle de déploiement à utiliser avec votre Assistant. L’outil de récupération nécessite le modèle gpt-35-turbo (1106) ou gpt-4 (1106-preview). Définissez cette valeur sur le nom de votre déploiement, et non sur le nom du modèle, sauf s’ils portent le même nom.
Interpréteur de code L’interpréteur de code fournit un accès à un environnement Python en bac à sable qui peut être utilisé pour permettre au modèle de tester et d’exécuter du code.

Outils

Un assistant individuel peut accéder à jusqu’à 128 outils, notamment code interpreter, ainsi qu’à n’importe quel outil personnalisé que vous créez par le biais de fonctions.

Créer l’application Python

Connectez-vous à Azure avec az login puis créez et exécutez un assistant avec l'exemple Python sans mot de passe recommandé ci-dessous :

import os
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from openai import AzureOpenAI

token_provider = get_bearer_token_provider(DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default")

client = AzureOpenAI(
    azure_ad_token_provider=token_provider,
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version="2024-05-01-preview",
)

# Create an assistant
assistant = client.beta.assistants.create(
    name="Math Assist",
    instructions="You are an AI assistant that can write code to help answer math questions.",
    tools=[{"type": "code_interpreter"}],
    model="gpt-4-1106-preview" # You must replace this value with the deployment name for your model.
)

# Create a thread
thread = client.beta.threads.create()

# Add a user question to the thread
message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="I need to solve the equation `3x + 11 = 14`. Can you help me?"
)

# Run the thread and poll for the result
run = client.beta.threads.runs.create_and_poll(
    thread_id=thread.id,
    assistant_id=assistant.id,
    instructions="Please address the user as Jane Doe. The user has a premium account.",
)

print("Run completed with status: " + run.status)

if run.status == "completed":
    messages = client.beta.threads.messages.list(thread_id=thread.id)
    print(messages.to_json(indent=2))

Pour utiliser la clé API de service pour l’authentification, vous pouvez créer et exécuter un assistant avec l’exemple Python suivant :

import os
from openai import AzureOpenAI

client = AzureOpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version="2024-05-01-preview",
)

# Create an assistant
assistant = client.beta.assistants.create(
    name="Math Assist",
    instructions="You are an AI assistant that can write code to help answer math questions.",
    tools=[{"type": "code_interpreter"}],
    model="gpt-4-1106-preview" # You must replace this value with the deployment name for your model.
)

# Create a thread
thread = client.beta.threads.create()

# Add a user question to the thread
message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="I need to solve the equation `3x + 11 = 14`. Can you help me?"
)

# Run the thread and poll for the result
run = client.beta.threads.runs.create_and_poll(
    thread_id=thread.id,
    assistant_id=assistant.id,
    instructions="Please address the user as Jane Doe. The user has a premium account.",
)

print("Run completed with status: " + run.status)

if run.status == "completed":
    messages = client.beta.threads.messages.list(thread_id=thread.id)
    print(messages.to_json(indent=2))

Sortie

Exécution terminée avec l’état : terminé

{
  "data": [
    {
      "id": "msg_4SuWxTubHsHpt5IlBTO5Hyw9",
      "assistant_id": "asst_cYqL1RuwLyFV3HU1gkaE2k0K",
      "attachments": [],
      "content": [
        {
          "text": {
            "annotations": [],
            "value": "The solution to the equation \\(3x + 11 = 14\\) is \\(x = 1\\)."
          },
          "type": "text"
        }
      ],
      "created_at": 1716397091,
      "metadata": {},
      "object": "thread.message",
      "role": "assistant",
      "run_id": "run_hFgBPbUtO8ZNTnNPC8PgpH1S",
      "thread_id": "thread_isb7spwRycI5ueT9E7357aOm"
    },
    {
      "id": "msg_Z32w2E7kY5wEWhZqQWxIbIUB",
      "assistant_id": null,
      "attachments": [],
      "content": [
        {
          "text": {
            "annotations": [],
            "value": "I need to solve the equation `3x + 11 = 14`. Can you help me?"
          },
          "type": "text"
        }
      ],
      "created_at": 1716397025,
      "metadata": {},
      "object": "thread.message",
      "role": "user",
      "run_id": null,
      "thread_id": "thread_isb7spwRycI5ueT9E7357aOm"
    }
  ],
  "object": "list",
  "first_id": "msg_4SuWxTubHsHpt5IlBTO5Hyw9",
  "last_id": "msg_Z32w2E7kY5wEWhZqQWxIbIUB",
  "has_more": false
}

Comprendre votre facture

Dans cet exemple, nous créons un assistant avec l’interpréteur de code activé. Lorsque nous posons une question mathématique à l’assistant, il traduit la question en code Python et l’exécute dans l’environnement en bac à sable afin de déterminer la réponse à la question. Le code que le modèle crée et teste pour trouver une réponse est :

from sympy import symbols, Eq, solve  
  
# Define the variable  
x = symbols('x')  
  
# Define the equation  
equation = Eq(3*x + 11, 14)  
  
# Solve the equation  
solution = solve(equation, x)  
solution

Il est important de ne pas oublier que si l’interpréteur de code donne au modèle la possibilité de répondre à des requêtes plus complexes en convertissant les questions en code et en exécutant ce code de manière itérative dans un environnement Python en bac à sable jusqu’à trouver une solution, vous devez toujours valider la réponse pour confirmer que le modèle a correctement traduit votre question en une représentation valide dans le code.

Nettoyer les ressources

Si vous voulez nettoyer et supprimer une ressource Azure OpenAI, vous pouvez supprimer la ressource ou le groupe de ressources. La suppression du groupe de ressources efface également les autres ressources qui y sont associées.

Voir aussi

Documentation de référence | Code source | Package (NuGet)

Prérequis

Configurer

Créez une application .NET Core

  1. Dans une fenêtre de console (par exemple cmd, PowerShell ou Bash), utilisez la commande dotnet new pour créer une application de console portant le nom azure-openai-quickstart :

    dotnet new console -n azure-openai-assistants-quickstart

  2. Accédez au répertoire du dossier d’application qui vient d’être créé, puis générez l’application avec la commande dotnet build :

    dotnet build

    La sortie de génération ne doit contenir aucun avertissement ni erreur.

    ...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

  3. Installez la bibliothèque de client .NET OpenAI avec la commande dotnet add package :

    dotnet add package Azure.AI.OpenAI --prerelease

Récupérer la clé et le point de terminaison

Pour effectuer correctement un appel sur Azure OpenAI, vous avez besoin d’un point de terminaison et d’une clé.

Nom de la variable Valeur
ENDPOINT Le point de terminaison de service se trouve dans la section Clés et point de terminaison quand vous examinerez votre ressource à partir du Portail Azure. Vous pouvez également trouver le point de terminaison via la page Déploiements dans Azure AI Studio. Voici un exemple de point de terminaison : https://docs-test-001.openai.azure.com/.
API-KEY Cette valeur se trouve dans la section Clés et point de terminaison quand vous examinez votre ressource à partir du portail Azure. Vous pouvez utiliser soit KEY1, soit KEY2.

Accédez à votre ressource sur le portail Azure. La section Point de terminaison et les clés se trouvent dans la section Gestion des ressources. Copiez votre point de terminaison et votre clé d’accès, car vous aurez besoin de l’authentification de vos appels d’API. Vous pouvez utiliser soit KEY1, soit KEY2. Avoir toujours deux clés vous permet de faire pivoter et de régénérer en toute sécurité les clés sans provoquer d’interruption de service.

Capture d’écran de l’interface utilisateur de vue d’ensemble d’une ressource Azure OpenAI dans le Portail Azure avec l’emplacement du point de terminaison et des clés d’accès entouré en rouge.

Variables d'environnement

Créez et affectez des variables d’environnement persistantes pour votre clé et votre point de terminaison.

Important

Si vous utilisez une clé API, stockez-la en toute sécurité dans un autre emplacement, par exemple dans Azure Key Vault. N'incluez pas la clé API directement dans votre code et ne la diffusez jamais publiquement.

Pour plus d’informations sur la sécurité des services IA, consultez Authentifier les requêtes auprès d’Azure AI services.

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"

L’authentification sans mot de passe est plus sécurisée que les alternatives basées sur une clé. Elle représente l’approche recommandée pour la connexion aux services Azure. Si vous choisissez l’authentification sans mot de passe, vous devez effectuer ce qui suit :

  1. Ajoutez le package Azure.Identity.

    dotnet add package Azure.Identity

  2. Attribuez le rôle Cognitive Services User à votre compte d’utilisateur. Vous pouvez effectuer cette opération dans le portail Azure sur votre ressource OpenAI sous Contrôle d’accès (IAM)>Ajouter une attribution de rôle.

  3. Connectez-vous à Azure à l’aide de Visual Studio ou d’Azure CLI via az login.

Créer l’assistant

Mettez à jour le fichier Program.cs avec le code suivant pour créer un assistant :

using Azure;
using Azure.AI.OpenAI.Assistants;

// Assistants is a beta API and subject to change
// Acknowledge its experimental status by suppressing the matching warning.
string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
string key = Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY");

var openAIClient = new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(key));

// Use for passwordless auth
//var openAIClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential()); 

FileClient fileClient = openAIClient.GetFileClient();
AssistantClient assistantClient = openAIClient.GetAssistantClient();

// First, let's contrive a document we'll use retrieval with and upload it.
using Stream document = BinaryData.FromString("""
            {
                "description": "This document contains the sale history data for Contoso products.",
                "sales": [
                    {
                        "month": "January",
                        "by_product": {
                            "113043": 15,
                            "113045": 12,
                            "113049": 2
                        }
                    },
                    {
                        "month": "February",
                        "by_product": {
                            "113045": 22
                        }
                    },
                    {
                        "month": "March",
                        "by_product": {
                            "113045": 16,
                            "113055": 5
                        }
                    }
                ]
            }
            """).ToStream();

OpenAIFileInfo salesFile = await fileClient.UploadFileAsync(
    document,
    "monthly_sales.json",
    FileUploadPurpose.Assistants);

// Now, we'll create a client intended to help with that data
AssistantCreationOptions assistantOptions = new()
{
    Name = "Example: Contoso sales RAG",
    Instructions =
        "You are an assistant that looks up sales data and helps visualize the information based"
        + " on user queries. When asked to generate a graph, chart, or other visualization, use"
        + " the code interpreter tool to do so.",
    Tools =
            {
                new FileSearchToolDefinition(),
                new CodeInterpreterToolDefinition(),
            },
    ToolResources = new()
    {
        FileSearch = new()
        {
            NewVectorStores =
                    {
                        new VectorStoreCreationHelper([salesFile.Id]),
                    }
        }
    },
};

Assistant assistant = await assistantClient.CreateAssistantAsync(deploymentName, assistantOptions);

// Create and run a thread with a user query about the data already associated with the assistant
ThreadCreationOptions threadOptions = new()
{
    InitialMessages = { "How well did product 113045 sell in February? Graph its trend over time." }
};

ThreadRun threadRun = await assistantClient.CreateThreadAndRunAsync(assistant.Id, threadOptions);

// Check back to see when the run is done
do
{
    Thread.Sleep(TimeSpan.FromSeconds(1));
    threadRun = assistantClient.GetRun(threadRun.ThreadId, threadRun.Id);
} while (!threadRun.Status.IsTerminal);

// Finally, we'll print out the full history for the thread that includes the augmented generation
AsyncCollectionResult<ThreadMessage> messages
    = assistantClient.GetMessagesAsync(
        threadRun.ThreadId,
        new MessageCollectionOptions() { Order = MessageCollectionOrder.Ascending });

await foreach (ThreadMessage message in messages)
{
    Console.Write($"[{message.Role.ToString().ToUpper()}]: ");
    foreach (MessageContent contentItem in message.Content)
    {
        if (!string.IsNullOrEmpty(contentItem.Text))
        {
            Console.WriteLine($"{contentItem.Text}");

            if (contentItem.TextAnnotations.Count > 0)
            {
                Console.WriteLine();
            }

            // Include annotations, if any.
            foreach (TextAnnotation annotation in contentItem.TextAnnotations)
            {
                if (!string.IsNullOrEmpty(annotation.InputFileId))
                {
                    Console.WriteLine($"* File citation, file ID: {annotation.InputFileId}");
                }
                if (!string.IsNullOrEmpty(annotation.OutputFileId))
                {
                    Console.WriteLine($"* File output, new file ID: {annotation.OutputFileId}");
                }
            }
        }
        if (!string.IsNullOrEmpty(contentItem.ImageFileId))
        {
            OpenAIFileInfo imageInfo = await fileClient.GetFileAsync(contentItem.ImageFileId);
            BinaryData imageBytes = await fileClient.DownloadFileAsync(contentItem.ImageFileId);
            using FileStream stream = File.OpenWrite($"{imageInfo.Filename}.png");
            imageBytes.ToStream().CopyTo(stream);

            Console.WriteLine($"<image: {imageInfo.Filename}.png>");
        }
    }
    Console.WriteLine();
}

Exécutez l’application à l’aide de la commande dotnet run :

dotnet run

La sortie de la console doit ressembler à ce qui suit :

[USER]: How well did product 113045 sell in February? Graph its trend over time.

[ASSISTANT]: Product 113045 sold 22 units in February. Let's visualize its sales trend over the given months (January through March).

I'll create a graph to depict this trend.

[ASSISTANT]: <image: 553380b7-fdb6-49cf-9df6-e8e6700d69f4.png>
The graph above visualizes the sales trend for product 113045 from January to March. As seen, the sales peaked in February with 22 units sold, and fluctuated over the period from January (12 units) to March (16 units).

If you need further analysis or more details, feel free to ask!

Nettoyer les ressources

Si vous voulez nettoyer et supprimer une ressource Azure OpenAI, vous pouvez supprimer la ressource ou le groupe de ressources. La suppression du groupe de ressources efface également les autres ressources qui y sont associées.

Voir aussi

Documentation de référence | Code source de la bibliothèque | Package (npm) |

Prérequis

Pour l’authentification sans mot de passe, il vous faut

  1. Utilisez le package @azure/identity.
  2. Attribuez le rôle Cognitive Services User à votre compte d’utilisateur. Cela peut être effectué dans le Portail Azure sous Contrôle d’accès (IAM)>Ajouter une attribution de rôle.
  3. Connectez-vous à l’aide de l’interface Azure CLI, par exemple az login.

Configurer

  1. Créez un dossier assistants-quickstart pour contenir l’application et ouvrez Visual Studio Code dans ce dossier avec la commande suivante :

    mkdir assistants-quickstart && code assistants-quickstart

  2. Créez le package.json avec la commande suivante :

    npm init -y

  3. Mettez à jour le package.json vers ECMAScript avec la commande suivante :

    npm pkg set type=module

  4. Installez la bibliothèque cliente Assistants OpenAI pour JavaScript avec :

    npm install openai

  5. Pour l’authentification sans mot de passe recommandée :

    npm install @azure/identity

Récupérer des informations sur les ressources

Attention

Pour utiliser l’authentification sans clé recommandée avec le kit de développement logiciel (SDK), vérifiez que la variable d’environnement AZURE_OPENAI_API_KEY n’est pas définie.

Nom de la variable Valeur
AZURE_OPENAI_ENDPOINT Cette valeur se trouve dans la section Clés et point de terminaison quand vous examinez votre ressource à partir du portail Azure.
AZURE_OPENAI_DEPLOYMENT_NAME Cette valeur correspond au nom personnalisé que vous avez choisi pour votre déploiement lorsque vous avez déployé un modèle. Cette valeur peut être trouvée dans le Portail Azure sous Gestion des ressources>Déploiements de modèles.
OPENAI_API_VERSION En savoir plus sur les versions d’API.

En savoir plus sur l’authentification sans clé et la définition de variables d’environnement.

Attention

Lors de l’utilisation de l’authentification sans clé, ne définissez pas AZURE_OPENAI_API_KEY.

Créer un assistant

Dans notre code, nous allons spécifier les valeurs suivantes :

Nom Description
Nom de l’Assistant Votre nom de déploiement associé à un modèle spécifique.
Instructions Les instructions sont similaires aux messages système, c’est là que vous fournissez des instructions sur le comportement du modèle et tout contexte qu’il doit référencer lorsqu’il génère une réponse. Vous pouvez décrire la personnalité de l’assistant, lui dire ce qu’il doit et ne doit pas répondre, et lui indiquer comment formater les réponses. Vous pouvez également fournir des exemples des mesures à prendre lorsqu’il répond aux réponses.
Modèle Il s’agit du nom du déploiement.
Interpréteur de code L’interpréteur de code fournit un accès à un environnement Python en bac à sable qui peut être utilisé pour permettre au modèle de tester et d’exécuter du code.

Outils

Un assistant individuel peut avoir accès à un maximum de 128 outils, y compris code interpreter, ainsi qu’à tout outil personnalisé que vous créez via les fonctions.

  1. Remplacez le fichier index.ts avec le code suivant :

    import { AzureOpenAI } from "openai";
import {
  Assistant,
  AssistantCreateParams,
  AssistantTool,
} from "openai/resources/beta/assistants";
import { Message, MessagesPage } from "openai/resources/beta/threads/messages";
import { Run } from "openai/resources/beta/threads/runs/runs";
import { Thread } from "openai/resources/beta/threads/threads";

// Add `Cognitive Services User` to identity for Azure OpenAI resource
import {
  DefaultAzureCredential,
  getBearerTokenProvider,
} from "@azure/identity";

// Get environment variables
const azureOpenAIEndpoint = process.env.AZURE_OPENAI_ENDPOINT as string;
const azureOpenAIDeployment = process.env
  .AZURE_OPENAI_DEPLOYMENT_NAME as string;
const openAIVersion = process.env.OPENAI_API_VERSION as string;

// Check env variables
if (!azureOpenAIEndpoint || !azureOpenAIDeployment || !openAIVersion) {
  throw new Error(
    "Please ensure to set AZURE_OPENAI_DEPLOYMENT_NAME and AZURE_OPENAI_ENDPOINT in your environment variables."
  );
}

// Get Azure SDK client
const getClient = (): AzureOpenAI => {
  const credential = new DefaultAzureCredential();
  const scope = "https://cognitiveservices.azure.com/.default";
  const azureADTokenProvider = getBearerTokenProvider(credential, scope);
  const assistantsClient = new AzureOpenAI({
    endpoint: azureOpenAIEndpoint,
    apiVersion: openAIVersion,
    azureADTokenProvider,
  });
  return assistantsClient;
};

const assistantsClient = getClient();

const options: AssistantCreateParams = {
  model: azureOpenAIDeployment, // Deployment name seen in Azure AI Studio
  name: "Math Tutor",
  instructions:
    "You are a personal math tutor. Write and run JavaScript code to answer math questions.",
  tools: [{ type: "code_interpreter" } as AssistantTool],
};
const role = "user";
const message = "I need to solve the equation `3x + 11 = 14`. Can you help me?";

// Create an assistant
const assistantResponse: Assistant =
  await assistantsClient.beta.assistants.create(options);
console.log(`Assistant created: ${JSON.stringify(assistantResponse)}`);

// Create a thread
const assistantThread: Thread = await assistantsClient.beta.threads.create({});
console.log(`Thread created: ${JSON.stringify(assistantThread)}`);

// Add a user question to the thread
const threadResponse: Message =
  await assistantsClient.beta.threads.messages.create(assistantThread.id, {
    role,
    content: message,
  });
console.log(`Message created:  ${JSON.stringify(threadResponse)}`);

// Run the thread and poll it until it is in a terminal state
const runResponse: Run = await assistantsClient.beta.threads.runs.createAndPoll(
  assistantThread.id,
  {
    assistant_id: assistantResponse.id,
  },
  { pollIntervalMs: 500 }
);
console.log(`Run created:  ${JSON.stringify(runResponse)}`);

// Get the messages
const runMessages: MessagesPage =
  await assistantsClient.beta.threads.messages.list(assistantThread.id);
for await (const runMessageDatum of runMessages) {
  for (const item of runMessageDatum.content) {
    // types are: "image_file" or "text"
    if (item.type === "text") {
      console.log(`Message content: ${JSON.stringify(item.text?.value)}`);
    }
  }
}

  2. Créez le fichier tsconfig.json pour transpiler le code TypeScript et copiez le code suivant pour ECMAScript.

    {
    "compilerOptions": {
      "module": "NodeNext",
      "target": "ES2022", // Supports top-level await
      "moduleResolution": "NodeNext",
      "skipLibCheck": true, // Avoid type errors from node_modules
      "strict": true // Enable strict type-checking options
    },
    "include": ["*.ts"]
}

  3. Transpiler de TypeScript à JavaScript.

    tsc

  4. Connectez-vous à Azure à l’aide de la commande suivante :

    az login

  5. Exécutez le code avec la commande suivante :

    node index.js

Nettoyer les ressources

Si vous voulez nettoyer et supprimer une ressource Azure OpenAI, vous pouvez supprimer la ressource ou le groupe de ressources. La suppression du groupe de ressources efface également les autres ressources qui y sont associées.

Exemple de code

Voir aussi

Prérequis

Configurer

Récupérer la clé et le point de terminaison

Pour effectuer un appel sur Azure OpenAI, vous aurez besoin des éléments suivants :

Nom de la variable Valeur
ENDPOINT Le point de terminaison de service se trouve dans la section Clés et point de terminaison quand vous examinerez votre ressource à partir du Portail Azure. Vous pouvez également trouver le point de terminaison via la page Déploiements dans Azure AI Studio. Voici un exemple de point de terminaison : https://docs-test-001.openai.azure.com/.
API-KEY Cette valeur se trouve dans la section Clés et point de terminaison quand vous examinez votre ressource à partir du portail Azure. Vous pouvez utiliser soit KEY1, soit KEY2.
DEPLOYMENT-NAME Cette valeur correspond au nom personnalisé que vous avez choisi pour votre déploiement lorsque vous avez déployé un modèle. Cette valeur se trouve sousGestion des ressources>Déploiements dans le portail Azure, ou dans la page Déploiements d’Azure AI Studio.

Accédez à votre ressource sur le portail Azure. Le Point de terminaison et les Clés se trouvent dans la section Gestion des ressources. Copiez votre point de terminaison et votre clé d’accès, car vous aurez besoin de l’authentification de vos appels d’API. Vous pouvez utiliser soit KEY1, soit KEY2. Avoir toujours deux clés vous permet de faire pivoter et de régénérer en toute sécurité les clés sans provoquer d’interruption de service.

Capture d’écran du panneau de vue d’ensemble d’une ressource Azure OpenAI dans le Portail Azure avec l’emplacement des clés d’accès et du point de terminaison encerclés en rouge.

Variables d'environnement

Créez et affectez des variables d’environnement persistantes pour votre clé et votre point de terminaison.

Important

Si vous utilisez une clé API, stockez-la en toute sécurité dans un autre emplacement, par exemple dans Azure Key Vault. N'incluez pas la clé API directement dans votre code et ne la diffusez jamais publiquement.

Pour plus d’informations sur la sécurité des services IA, consultez Authentifier les requêtes auprès d’Azure AI services.

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"

API REST

Créer un assistant

Remarque

Avec Azure OpenAI, le paramètre model nécessite un nom de modèle de déploiement. Si le nom de votre modèle de déploiement est différent du nom du modèle sous-jacent, vous devez ajuster votre code à "model": "{your-custom-model-deployment-name}".

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "You are an AI assistant that can write code to help answer math questions.",
    "name": "Math Assist",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4-1106-preview"
  }'

Outils

Un assistant individuel peut accéder à jusqu’à 128 outils, notamment code interpreter, ainsi qu’à n’importe quel outil personnalisé que vous créez par le biais de fonctions.

Créer un thread

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -d ''

Ajouter une question utilisateur au thread

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -d '{
      "role": "user",
      "content": "I need to solve the equation `3x + 11 = 14`. Can you help me?"
    }'

Exécuter le thread

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/runs \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "asst_abc123",
  }'

Récupérer l’état de l’exécution

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/runs/run_abc123 \
  -H "api-key: $AZURE_OPENAI_API_KEY" \

Réponse de l’Assistant

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \

Comprendre votre facture

Dans cet exemple, nous créons un assistant avec l’interpréteur de code activé. Lorsque nous posons une question mathématique à l’assistant, il traduit la question en code Python et l’exécute dans l’environnement en bac à sable afin de déterminer la réponse à la question. Le code que le modèle crée et teste pour trouver une réponse est :

    from sympy import symbols, Eq, solve  
      
    # Define the variable  
    x = symbols('x')  
      
    # Define the equation  
    equation = Eq(3*x + 11, 14)  
      
    # Solve the equation  
    solution = solve(equation, x)  
    solution

Il est important de ne pas oublier que si l’interpréteur de code donne au modèle la possibilité de répondre à des requêtes plus complexes en convertissant les questions en code et en exécutant ce code de manière itérative dans un environnement Python en bac à sable jusqu’à trouver une solution, vous devez toujours valider la réponse pour confirmer que le modèle a correctement traduit votre question en une représentation valide dans le code.

Nettoyer les ressources

Si vous voulez nettoyer et supprimer une ressource Azure OpenAI, vous pouvez supprimer la ressource ou le groupe de ressources. La suppression du groupe de ressources efface également les autres ressources qui y sont associées.

Voir aussi