1. Présentation de l'API des Assistants OpenAI

1.1 Définition et Objectif de l'API des Assistants

L'API des Assistants permet aux développeurs de construire des assistants d'intelligence artificielle au sein de leurs propres applications. En définissant des commandes personnalisées et en sélectionnant des modèles, les assistants peuvent utiliser des outils, des modèles et des connaissances pour répondre aux requêtes des utilisateurs. Actuellement, l'API des Assistants prend en charge trois types d'outils : Interprétateur de Code, Récupération et Appel de Fonction.

1.2 Applications de l'API des Assistants

L'API des Assistants est adaptée à divers scénarios nécessitant un support interactif d'IA. Par exemple :

  • Support Client : Répondre automatiquement aux questions courantes pour réduire la charge de travail du service client humain.
  • Éducation en Ligne : Répondre aux questions des étudiants et fournir un soutien d'apprentissage personnalisé.
  • Analyse de Données : Analyser les fichiers de données téléchargés par les utilisateurs, générer des rapports et visualiser des graphiques.
  • Recommandations Personnalisées : Fournir des suggestions et des services personnalisés en fonction des interactions historiques des utilisateurs.

1.3 Concepts Fondamentaux des Assistants

Les objets fondamentaux de l'API des Assistants comprennent Assistant, Thread et Message. Voici des présentations détaillées de ces objets et de leurs fonctions :

Assistant

L'objet Assistant est construit sur la base des modèles OpenAI et peut appeler les outils des assistants IA. Vous pouvez personnaliser les instructions de l'Assistant pour adapter sa personnalité et sa fonctionnalité. Par exemple, vous pouvez créer un Assistant appelé "Analyste de Données" qui analyse les données et génère des graphiques en utilisant l'outil "code_interpreter".

Thread

L'objet Thread représente la session de conversation entre l'utilisateur et l'Assistant. Vous pouvez créer un Thread pour chaque utilisateur et y ajouter des messages lorsque l'utilisateur interagit avec l'Assistant. L'objet Thread stocke efficacement l'historique des messages et tronque les messages au besoin pour se conformer à la limite de longueur contextuelle du modèle.

Message

L'objet Message peut être créé par l'utilisateur ou l'Assistant. Les messages peuvent contenir du texte, des images et d'autres fichiers. Les messages sont stockés sous forme de liste sur le Thread. Dans l'utilisation effective de l'API, les développeurs peuvent ajouter des messages d'utilisateur au Thread et déclencher la réponse de l'Assistant au besoin.

Exécution

L'objet Run représente l'exécution d'une requête d'assistant, appelant l'assistant en fonction du contenu du message dans le Thread. L'assistant utilise sa configuration et les messages du Thread pour exécuter des tâches en appelant des modèles et des outils. Dans le cadre de l'exécution, l'assistant ajoute des messages au thread.

2. Processus de Développement de l'API des Assistants

2.1 Créer votre Assistant

Pour créer un Assistant, vous devez envoyer une requête à l'API avec des instructions, le nom du modèle et la configuration de l'outil. Voici un exemple simple de création d'un assistant tuteur en mathématiques personnel :

curl "https://api.openai.com/v1/assistants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer VOTRE_CLE_API_OPENAI" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Vous êtes un tuteur en mathématiques personnel. Écrivez et exécutez du code pour répondre aux questions de mathématiques.",
    "name": "Tuteur en Mathématiques",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4"
  }'

Paramètres de l'API :

  • instructions : instructions système indiquant à l'assistant quoi faire.
  • name : le nom de l'assistant.
  • tools : définit quels outils l'assistant peut utiliser. Chaque assistant peut avoir jusqu'à 128 outils. Les types d'outil actuels peuvent être code_interpreter, retrieval ou function.
  • model : quel modèle l'assistant doit-il utiliser ?

Après avoir créé avec succès l'Assistant, vous recevrez un ID d'Assistant.

2.2 Créer un Thread de Session

Un Thread représente une conversation, et nous recommandons de créer un Thread de session pour chaque utilisateur lorsqu'il démarre une conversation. Vous pouvez créer un Thread comme suit :

curl https://api.openai.com/v1/threads \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CLE_API_OPENAI" \
  -H "OpenAI-Beta: assistants=v1" \
  -d ''

Après avoir créé le Thread, vous recevrez un ID de Thread.

2.3 Ajouter des messages au fil de discussion

Vous pouvez ajouter des messages à un fil de discussion spécifique, qui contiennent du texte et éventuellement permettent des fichiers téléchargeables par l'utilisateur. Par exemple:

curl https://api.openai.com/v1/threads/{thread_id}/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
      "role": "user",
      "content": "J'ai besoin de résoudre cette équation `3x + 11 = 14`. Pouvez-vous m'aider ?"
    }'

Paramètres de l'API :

  • thread_id - représente l'identifiant du fil de conversation, que vous pouvez obtenir lors de la création du fil.

Le corps de la requête API est un message utilisateur, représentant généralement la question de l'utilisateur, similaire à la structure de message du modèle de conversation.

2.4 Exécuter l'Assistant pour Générer une Réponse

Pour que l'assistant réponde aux messages de l'utilisateur, vous devez créer un Exécution. Cela permet à l'assistant de lire le fil et de décider s'il faut utiliser des outils (si activés) ou simplement utiliser le modèle pour répondre au mieux à la requête.

Remarque : Jusqu'à présent, l'assistant n'a pas répondu à la question de l'utilisateur. Ce n'est que lorsque vous appelez l'API Exécution que l'assistant IA répondra à la question de l'utilisateur.

curl https://api.openai.com/v1/threads/{thread_id}/runs \
  -H "Authorization: Bearer YOUR_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "assistant_id": "assistant_id",
    "instructions": "Adressez-vous à l'utilisateur comme si c'était Jane Doe. L'utilisateur possède un compte premium."
  }'

Paramètres de l'API :

  • thread_id - représente l'identifiant du fil de conversation, que vous pouvez obtenir lors de la création du fil.
  • assistant_id - représente l'identifiant de l'assistant, que vous pouvez obtenir lors de la création de l'Assistant.
  • instructions - instructions de l'assistant qui peuvent remplacer les instructions définies lors de la création de l'Assistant.

Une API réussie renverra un identifiant d'exécution.

2.5 Vérifier le Statut d'Exécution de l'Assistant

Après avoir lancé une tâche (Exécution) dans l'Assistant, l'exécution de la tâche est asynchrone. Cela signifie que nous devons vérifier régulièrement le statut de l'Exécution pour déterminer si elle a été terminée. Pour vérifier le statut de l'Exécution, une requête HTTP peut être effectuée à l'aide de CURL. Voici une introduction spécifique à ce processus.

Exemple de Requête CURL:

curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

Explication des Paramètres de l'API :

  • https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 : Il s'agit de l'URL de requête de l'API, où thread_abc123 est l'identifiant unique du fil (Thread), et run_abc123 est l'identifiant unique de l'Exécution.

Exemple de Corps de Réponse :

{
  "id": "run_abc123",
  "object": "thread.run",
  "status": "completed",
  "created_at": 1699073585,
  ...
}

Explication des Paramètres de Réponse de l'API :

  • id : L'identifiant unique de l'Exécution.
  • object : Indique le type d'objet renvoyé, qui est thread.run ici.
  • status : Le statut de l'Exécution, les valeurs possibles incluent en attente, en cours, terminé, nécessite une action, échec, etc.
  • created_at : L'horodatage de la création de l'Exécution.

2.6 Obtenir les Résultats de Réponse de l'Assistant

Après la fin de l'Exécution de l'Assistant, nous pouvons lire les résultats de réponse de l'Assistant en vérifiant les messages ajoutés au fil (Thread). Voici une démonstration de comment faire la demande via CURL et une explication détaillée des paramètres de l'API.

Astuce : Similaire à une conversation avec un Assistant, lorsque l'Assistant a fini de traiter la requête de l'utilisateur, l'Assistant ajoutera un message au fil de conversation (Thread). Par conséquent, nous devons simplement interroger le dernier message dans le fil de conversation (Thread) pour obtenir la réponse de l'Assistant.

Exemple de Requête CURL :

curl https://api.openai.com/v1/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

Explication des paramètres de l'API:

  • https://api.openai.com/v1/threads/thread_abc123/messages: L'URL de requête de l'API, où thread_abc123 est l'identifiant unique du fil de discussion (thread).
  • Identique aux en-têtes de requête utilisés pour vérifier l'état d'exécution précédemment, y compris les informations d'authentification et les informations de version de l'API.

Exemple de résultats de réponse de l'Assistant:

Dans cet exemple, l'utilisateur a posé une question mathématique à l'Assistant, et l'Assistant a ajouté un message de réponse au fil de discussion après l'avoir traité.

Utilisateur: J'ai besoin de résoudre l'équation `3x + 11 = 14`. Pouvez-vous m'aider?
Assistant: Bien sûr, Jane Doe. Pour résoudre l'équation `(3x + 11 = 14)`, vous devez isoler `(x)` d'un côté de l'équation. Laissez-moi calculer la valeur de `(x)` pour vous.
Assistant: La solution de l'équation `(3x + 11 = 14)` est `(x = 1)`.

Après avoir obtenu les résultats de réponse de l'Assistant, ils peuvent être présentés à l'utilisateur pour les aider à mieux comprendre et utiliser les services fournis par l'Assistant.

3. Outils: Outils intégrés fournis par OpenAI

3.1 Outil d'interprétation de code

L'outil d'interprétation de code permet à l'API des Assistants d'écrire et d'exécuter du code Python dans un environnement d'exécution isolé. Cet outil peut gérer divers formats de données et de fichiers, et générer des fichiers avec des données et des images graphiques. L'interpréteur de code permet à votre Assistant d'exécuter itérativement du code pour résoudre des problèmes de codage et mathématiques complexes. Lorsque le code écrit par l'Assistant ne parvient pas à s'exécuter, il peut itérer ce code en essayant différents codes jusqu'à ce que le code s'exécute avec succès.

Activation de l'interpréteur de code

Pour activer l'interpréteur de code, passez code_interpreter dans le paramètre tools lors de la création de l'objet Assistant:

curl https://api.openai.com/v1/assistants \
  -u :$OPENAI_API_KEY \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v1' \
  -d '{
    "instructions": "Vous êtes un tuteur de mathématiques personnel. Lorsqu'on vous pose une question mathématique, écrivez et exécutez du code pour y répondre.",
    "tools": [
      { "type": "code_interpreter" }
    ],
    "model": "gpt-4-turbo-preview"
  }'

Ensuite, le modèle décidera quand invoquer l'interpréteur de code à l'exécution en fonction de la nature de la demande de l'utilisateur. Vous pouvez faciliter ce comportement grâce aux instructions de l'Assistant (par exemple, "Écrivez du code pour résoudre ce problème").

Utilisation de l'interpréteur de code pour traiter des fichiers

L'interpréteur de code peut analyser des données à partir de fichiers. Cela est utile lorsque vous souhaitez fournir une grande quantité de données à l'Assistant ou permettre à vos utilisateurs de télécharger leurs propres fichiers pour analyse. Notez que les fichiers téléchargés pour l'interpréteur de code ne seront pas indexés pour la récupération. Pour des informations détaillées sur la manière d'indexer les fichiers pour la récupération, reportez-vous à la section Outil de Récupération ci-dessous.

Les fichiers passés au niveau de l'Assistant peuvent être accessibles par toutes les exécutions associées à cet Assistant:

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="assistants" \
  -F file="@/chemin/vers/mondata.csv"

curl https://api.openai.com/v1/assistants \
  -u :$OPENAI_API_KEY \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v1' \
  -d '{
    "instructions": "Vous êtes un tuteur de mathématiques personnel. Lorsqu'on vous pose une question mathématique, écrivez et exécutez du code pour y répondre.",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4-turbo-preview",
    "file_ids": ["file_123abc456"]
  }'

Lecture des Images et des Fichiers Générés par l'Interpréteur de Code

L'Interpréteur de Code peut également produire des fichiers dans l'API, tels que la génération de graphiques d'images, de fichiers CSV et PDF. Il existe deux types de fichiers générés : des images et des fichiers de données (par exemple, un fichier CSV avec des données générées par l'Assistant).

Lorsque l'Interpréteur de Code produit une image, vous pouvez trouver et télécharger ce fichier dans le champ file_id de la réponse du Message de l'Assistant :

{
    "id": "msg_abc123",
    "object": "thread.message",
    "created_at": 1698964262,
    "thread_id": "thread_abc123",
    "role": "assistant",
    "content": [
    {
      "type": "image_file",
      "image_file": {
        "file_id": "file-abc123"
      }
    }
  ]
  // ...
}

3.2 Outil de Récupération

L'Outil de Récupération améliore les capacités de l'Assistant en ajoutant des connaissances provenant de l'extérieur du modèle (telles que des informations sur des produits propriétaires ou des documents fournis par l'utilisateur). Une fois le fichier téléchargé et transmis à l'Assistant, OpenAI découpera automatiquement, indexera, stockera les embeddings de votre document, et mettra en œuvre une recherche vectorielle pour récupérer du contenu pertinent afin de répondre aux requêtes des utilisateurs.

Activer la Récupération

Pour activer la récupération dans le paramètre tools de l'Assistant, passez retrieval :

curl https://api.openai.com/v1/assistants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Vous êtes un chatbot de support client. Utilisez votre base de connaissances pour répondre efficacement aux demandes des clients.",
    "tools": [{"type": "retrieval"}],
    "model": "gpt-4-turbo-preview"
  }'

Téléverser des Fichiers pour la Récupération

Tout comme avec l'Interpréteur de Code, les fichiers peuvent être téléversés au niveau de l'Assistant ou au niveau des Messages individuels.

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="assistants" \
  -F file="@/path/to/knowledge.pdf"

curl "https://api.openai.com/v1/assistants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Vous êtes un chatbot de support client. Utilisez votre base de connaissance pour répondre efficacement aux demandes des clients.",
    "name": "Tuteur en Maths",
    "tools": [{"type": "retrieval"}],
    "model": "gpt-4-turbo-preview",
    "file_ids": ["file_123abc456"]
  }'

3.3 Outil d'Appel de Fonction

Tout comme l'API de Complétions de Chat, l'API des Assistants prend en charge l'appel de fonctions. L'appel de fonction vous permet de décrire des fonctions à l'Assistant et de renvoyer intelligemment la fonction à appeler ainsi que ses paramètres. Lorsqu'un appel de fonction est exécuté, l'API des Assistants mettra en pause l'exécution, et vous pourrez fournir le résultat de l'appel de fonction pour poursuivre l'exécution.

Définir des fonctions

Lors de la création d'un Assistant, vous pouvez définir un ensemble de fonctions que l'assistant peut appeler. Ces fonctions doivent être explicitement spécifiées lors de la création de l'objet assistant. Chaque fonction doit avoir un nom, une description et une spécification de paramètres uniques.

Le code suivant démontre comment définir deux fonctions en utilisant la commande curl lors de la création d'un assistant :

curl https://api.openai.com/v1/assistants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Vous êtes un bot de prévisions météorologiques. Utilisez les fonctions fournies pour répondre aux questions.",
    "tools": [{
      "type": "function",
      "function": {
        "name": "getCurrentWeather",
        "description": "Obtenir les conditions météorologiques pour un lieu spécifique",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "Ville et état, par exemple San Francisco, CA"},
            "unit": {"type": "string", "enum": ["c", "f"]}
          },
          "required": ["location"]
        }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "getNickname",
        "description": "Obtenir le surnom d'une ville",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "Ville et état, par exemple San Francisco, CA"}
          },
          "required": ["location"]
        }
      }
    }],
    "model": "gpt-4-turbo-preview"
  }'

Lecture des fonctions appelées par l'Assistant

Lorsqu'un utilisateur soumet un message à l'assistant et que le contenu du message déclenche un appel de fonction, vous devez lire les informations de cet appel de fonction. Pendant ce processus, l'assistant générera un run avec le statut requires_action. À ce stade, vous pouvez récupérer l'objet Run pour obtenir des informations détaillées sur l'appel de fonction.

Voici un exemple de récupération de l'objet Run, montrant comment obtenir les informations des appels de fonction :

{
  "id": "run_abc123",
  "object": "thread.run",
  "status": "requires_action",
  "required_action": {
    "type": "submit_tool_outputs",
    "submit_tool_outputs": {
      "tool_calls": [
        {
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "getCurrentWeather",
            "arguments": "{\"location\":\"San Francisco\"}"
          }
        },
        {
          "id": "call_abc456",
          "type": "function",
          "function": {
            "name": "getNickname",
            "arguments": "{\"location\":\"Los Angeles\"}"
          }
        }
      ]
    }
  },
  ...
}

Le paramètre tool_calls contient les informations d'appel de fonction, et il vous suffit d'appeler la fonction correspondante dans votre programme local.

Soumission des résultats des fonctions

Après avoir exécuté l'appel de fonction localement et obtenu les résultats, vous devez soumettre ces résultats à l'assistant Assistants afin que l'assistant puisse continuer le traitement de la demande de l'utilisateur. Lors de la soumission des résultats des fonctions, vous devez vous assurer que les sorties sont associées aux appels de fonction d'origine.

Voici un exemple de code montrant comment soumettre les résultats des sorties de fonction :

curl https://api.openai.com/v1/threads/thread_abc123/runs/run_123/submit_tool_outputs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "tool_outputs": [
      {
        "tool_call_id": "call_abc123",
        "output": "{\"temperature\": \"22\", \"unit\": \"celsius\"}"
      }, 
      {
        "tool_call_id": "call_abc456",
        "output": "{\"nickname\": \"LA\"}"
      }
    ]
  }'

Explication des paramètres :

  • thread_abc123 représente l'ID du thread de conversation
  • run_123 représente l'ID de l'objet Run
  • tool_call_id représente l'ID d'un appel de fonction spécifique, qui est obtenu à partir du paramètre tool_calls précédent.

Une fois tous les résultats des fonctions soumis avec succès, le statut de l'objet Run sera à nouveau mis à jour, et l'assistant continuera le traitement et renverra la réponse finale à l'utilisateur.