Partager via


Informations de référence sur l’API Assistants (préversion)

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 paramètre tool_choice qui peut être utilisé pour forcer l'utilisation d'un outil spécifique (comme la recherche de fichiers, un interpréteur de code ou une fonction) dans une exécution particulière.

Cet article fournit une documentation de référence pour Python et REST pour la nouvelle API Assistants (préversion). Des conseils plus détaillés, étape par étape, sont fournis dans le guide de démarrage.

Créer une exécution

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs?api-version=2024-05-01-preview

Créer une exécution.

Paramètre de chemin

Paramètre Type Requise Description
thread_id string Requis ID du thread pour lequel créer un message.

Corps de la demande

Nom Type Requise Description
assistant_id string Requis ID de l’assistant à utiliser pour cette exécution.
model chaîne ou null Facultatif Nom du modèle de déploiement à utiliser pour cette exécution. Si une valeur est fournie ici, elle remplace le nom du modèle de déploiement associé à l’assistant. Si ce n’est pas le cas, le nom du modèle de déploiement associé à l’assistant est utilisé.
instructions chaîne ou null Facultatif Remplace les instructions de l’assistant. Cela est utile pour modifier le comportement lors de chaque exécution.
tools tableau ou null Facultatif Remplacez les outils que l’assistant peut utiliser pour cette exécution. Cela est utile pour modifier le comportement lors de chaque exécution.
metadata map Facultatif Ensemble de 16 paires clé-valeur pouvant être attachées à un objet. Cela peut être utile pour stocker des informations supplémentaires sur l'objet dans un format structuré. Les clés peuvent contenir au maximum 64 caractères et les valeurs peuvent contenir au maximum 512 caractères.

Retours

Objet d’exécution.

Exemple de création d’une requête d’exécution

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

run = client.beta.threads.runs.create(
  thread_id="thread_abc123",
  assistant_id="asst_abc123"
)
print(run)

Créer un thread et l’exécuter

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/runs?api-version=2024-05-01-preview

Créer un thread et l’exécuter dans une seule requête.

Corps de la demande

Nom Type Requise Description
assistant_id string Requis ID de l’assistant à utiliser pour cette exécution.
thread object Facultatif
model chaîne ou null Facultatif ID du nom du modèle de déploiement à utiliser pour cette exécution. Si une valeur est fournie ici, elle remplace le nom du modèle de déploiement associé à l’assistant. Si ce n’est pas le cas, le nom du modèle de déploiement associé à l’assistant est utilisé.
instructions chaîne ou null Facultatif Remplacez le message système par défaut de l’assistant. Cela est utile pour modifier le comportement lors de chaque exécution.
tools tableau ou null Facultatif Remplacez les outils que l’assistant peut utiliser pour cette exécution. Cela est utile pour modifier le comportement lors de chaque exécution.
metadata map Facultatif Ensemble de 16 paires clé-valeur pouvant être attachées à un objet. Cela peut être utile pour stocker des informations supplémentaires sur l'objet dans un format structuré. Les clés peuvent contenir au maximum 64 caractères et les valeurs peuvent contenir au maximum 512 caractères.

Retours

Objet d’exécution.

Exemple de création d’un thread et d’exécution d’une requête

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

run = client.beta.threads.create_and_run(
  assistant_id="asst_abc123",
  thread={
    "messages": [
      {"role": "user", "content": "Explain deep learning to a 5 year old."}
    ]
  }
)

Listes d’exécutions

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs?api-version=2024-05-01-preview

Retourne une liste d’exécutions appartenant à un thread.

Paramètre de chemin

Paramètre Type Requise Description
thread_id string Requis ID du thread auquel appartient l’exécution.

Paramètres de requête

Nom Type Requise Description
limit entier Facultatif – La valeur par défaut est 20 Limite du nombre d’objets à retourner. La limite peut être comprise entre 1 et 100, et la valeur par défaut est 20.
order string Facultatif – La valeur par défaut est « desc » Trier les objets en fonction du timestamp created_at. « asc » pour l’ordre croissant et « desc » pour l’ordre décroissant.
after string Facultatif Curseur à utiliser dans la pagination. « after » est un ID d’objet qui définit votre place dans la liste. Par exemple, si vous faites une requête de liste et que vous recevez 100 objets qui se terminent par obj_foo, votre appel suivant peut inclure after=obj_foo afin d’extraire la page suivante de la liste.
before string Facultatif Curseur à utiliser dans la pagination. « before » est un identifiant d’objet qui définit votre place dans la liste. Par exemple, si vous faites une requête de liste et que vous recevez 100 objets qui se terminent par obj_foo, votre appel suivant peut inclure before=obj_foo afin d’extraire la page précédente de la liste.

Retours

Une liste des objets exécution.

Exemple de requête d’exécution de liste

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

runs = client.beta.threads.runs.list(
  "thread_abc123"
)
print(runs)

Lister les étapes d’exécution

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}/steps?api-version=2024-05-01-preview

Retourne une liste d’exécutions appartenant à une exécution.

Paramètres de chemin d’accès

Paramètre Type Requise Description
thread_id string Requis ID du thread auquel appartient l’exécution.
run_id string Requis ID de l’exécution associée aux étapes d’exécution à interroger.

Paramètres de requête

Nom Type Requise Description
limit entier Facultatif – La valeur par défaut est 20 Limite du nombre d’objets à retourner. La limite peut être comprise entre 1 et 100, et la valeur par défaut est 20.
order string Facultatif – La valeur par défaut est « desc » Trier les objets en fonction du timestamp created_at. « asc » pour l’ordre croissant et « desc » pour l’ordre décroissant.
after string Facultatif Curseur à utiliser dans la pagination. « after » est un ID d’objet qui définit votre place dans la liste. Par exemple, si vous faites une requête de liste et que vous recevez 100 objets qui se terminent par obj_foo, votre appel suivant peut inclure after=obj_foo afin d’extraire la page suivante de la liste.
before string Facultatif Curseur à utiliser dans la pagination. « before » est un identifiant d’objet qui définit votre place dans la liste. Par exemple, si vous faites une requête de liste et que vous recevez 100 objets qui se terminent par obj_foo, votre appel suivant peut inclure before=obj_foo afin d’extraire la page précédente de la liste.

Retours

Une liste des objets étape exécution.

Exemple de requête d’exécution de liste d’étapes

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

run_steps = client.beta.threads.runs.steps.list(
    thread_id="thread_abc123",
    run_id="run_abc123"
)
print(run_steps)

Récupérer l’exécution

from openai import OpenAI
client = OpenAI()

run = client.beta.threads.runs.retrieve(
  thread_id="thread_abc123",
  run_id="run_abc123"
)

print(run)

Récupère une exécution.

Paramètres de chemin d’accès

Paramètre Type Requise Description
thread_id string Requis ID du thread qui a été exécuté.
run_id string Requis ID de l’exécution à récupérer.

Retours

L’objet exécution correspondant à l’ID d’exécution spécifié.

Exemple de requête d’exécution de liste d’étapes

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

run = client.beta.threads.runs.retrieve(
  thread_id="thread_abc123",
  run_id="run_abc123"
)
print(run)

Récupérer l’étape d’exécution

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}/steps/{step_id}?api-version=2024-05-01-preview

Récupère une étape d’exécution.

Paramètres de chemin d’accès

Paramètre Type Requise Description
thread_id string Requis ID du thread auquel appartient l’exécution et l’étape d’exécution.
run_id string Requis ID de l’exécution à laquelle appartient l’étape d’exécution.
step_id string Requis ID de l’étape d’exécution à récupérer.

Retours

L’objet étape d’exécuter correspondant à l’ID spécifié.

Exemple de requête de récupération des étapes d’exécution

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

run_step = client.beta.threads.runs.steps.retrieve(
    thread_id="thread_abc123",
    run_id="run_abc123",
    step_id="step_abc123"
)
print(run_step)

Modifier l’exécution

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}?api-version=2024-05-01-preview

Modifie une exécution.

Paramètres de chemin d’accès

Paramètre Type Requise Description
thread_id string Requis ID du thread qui a été exécuté.
run_id string Requis ID de l’exécution à modifier.

Corps de la demande

Nom Type Requise Description
metadata map Facultatif Ensemble de 16 paires clé-valeur pouvant être attachées à un objet. Cela peut être utile pour stocker des informations supplémentaires sur l'objet dans un format structuré. Les clés peuvent contenir au maximum 64 caractères et les valeurs peuvent contenir au maximum 512 caractères.

Retours

L’objet exécution modifié correspondant à l’ID spécifié.

Exemple de modification de la requête d’exécution

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

run = client.beta.threads.runs.update(
  thread_id="thread_abc123",
  run_id="run_abc123",
  metadata={"user_id": "user_abc123"},
)
print(run)

Envoyer des sorties d’outil à exécuter

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}/submit_tool_outputs?api-version=2024-05-01-preview

Lorsqu’une exécution a le statut : « requires_action » et que required_action.type est submit_tool_outputs, ce point de terminaison peut être utilisé pour envoyer les résultats des appels d’outils une fois qu’elles sont toutes terminées. Toutes les sorties doivent être envoyées dans une seule requête.

Paramètres de chemin d’accès

Paramètre Type Requise Description
thread_id string Requis ID du thread auquel appartient cette exécution.
run_id string Requis ID de l’exécution qui nécessite la soumission de sortie d’outil.

Corps de la demande

Nom Type Requise Description
tool_outputs tableau Requis Liste des outils pour lesquels les sorties sont envoyées.

Retours

L’objet exécution modifié correspondant à l’ID spécifié.

Exemple d’envoi de sorties d’outils pour exécuter une requête

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

run = client.beta.threads.runs.submit_tool_outputs(
  thread_id="thread_abc123",
  run_id="run_abc123",
  tool_outputs=[
    {
      "tool_call_id": "call_abc123",
      "output": "28C"
    }
  ]
)
print(run)

Annuler une exécution

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}/cancel?api-version=2024-05-01-preview

Annule une exécution in_progress.

Paramètres de chemin d’accès

Paramètre Type Requise Description
thread_id string Requis ID du thread auquel appartient cette exécution.
run_id string Requis ID de l’exécution à annuler.

Retours

L’objet exécution modifié correspondant à l’ID spécifié.

Exemple d’envoi de sorties d’outils pour exécuter une requête

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

run = client.beta.threads.runs.cancel(
  thread_id="thread_abc123",
  run_id="run_abc123"
)
print(run)

Objet d’exécution

Représente une exécution sur un thread.

Nom Type Description
id string Identificateur, qui peut être référencé dans les points de terminaison d’API.
object string Le type d’objet, qui est toujours thread.run.
created_at entier Horodatage Unix (en secondes) de la création de l’exécution.
thread_id string ID du thread qui a été exécuté dans le cadre de cette exécution.
assistant_id string ID de l’assistant utilisé pour cette exécution.
status string État de l’exécution, qui peut être queued, in_progress, requires_action, cancelling, cancelled, failed, completed ou expired.
required_action objet ou null Détails de l’action requise pour poursuivre l’exécution. Est null si aucune action n’est requise.
last_error objet ou null Dernière erreur associée à cette exécution. Est null s’il n’y a pas d’erreur.
expires_at entier Horodatage Unix (en secondes) de l’expiration de l’exécution.
started_at entier ou null Horodatage Unix (en secondes) du démarrage de l’exécution.
cancelled_at entier ou null Horodatage Unix (en secondes) de l’annulation de l’exécution.
failed_at entier ou null Horodatage Unix (en secondes) de l’échec de l’exécution.
completed_at entier ou null Horodatage Unix (en secondes) de la fin de l’exécution.
model string Nom du modèle de déploiement utilisé par l’assistant pour cette exécution.
instructions string Instructions utilisées par l’assistant pour cette exécution.
tools tableau Liste des outils utilisés par l’assistant pour cette exécution.
file_ids tableau Liste des ID de fichier utilisés par l’assistant pour cette exécution.
metadata map Ensemble de 16 paires clé-valeur pouvant être attachées à un objet. Cela peut être utile pour stocker des informations supplémentaires sur l'objet dans un format structuré. Les clés peuvent contenir au maximum 64 caractères et les valeurs peuvent contenir au maximum 512 caractères.
tool_choice chaîne ou objet Contrôle l’outil (le cas échéant) appelé par le modèle. none signifie que le modèle n’appelle pas d’outils et génère un message à la place. auto (valeur par défaut) signifie que le modèle peut choisir entre la génération d’un message et l’appel d’un outil. La spécification d’un outil particulier comme {"type": "file_search"} ou {"type": "function", "function": {"name": "my_function"}} force le modèle à appeler cet outil.
max_prompt_tokens entier ou null Nombre maximal de jetons de prompt spécifiés comme ayant été utilisés au cours de l’exécution.
max_completion_tokens entier ou null Nombre maximal de jetons de saisie semi-automatique spécifiés comme ayant été utilisés au cours de l’exécution.
usage objet ou null Statistiques d’utilisation relatives à l’exécution. Cette valeur est nul si l’exécution n’est pas dans un état terminal (par exemple in_progress, queued).

Exécuter l’objet de l’étape

Représenter une étape dans une exécution.

Nom Type Description
id string Identificateur de l’étape d’exécution qui peut être référencé dans les points de terminaison d’API.
object string Le type d’objet, qui est toujours thread.run.step.
created_at entier Horodatage Unix (en secondes) pour la création de l’étape d’exécution.
assistant_id string ID de l’assistant associé à l’étape d’exécution.
thread_id string ID du thread qui a été exécuté.
run_id string ID de l’exécution dont fait partie cette étape d’exécution.
type string Type d’étape d’exécution, qui peut être message_creation ou tool_calls.
status string État de l’étape d’exécution, qui peut être in_progress, cancelled, failed, completed ou expired.
step_details object Détails de l’étape d’exécution.
last_error objet ou null Dernière erreur associée à cette étape d’exécution. Est null s’il n’y a pas d’erreur.
expired_at entier ou null Horodatage Unix (en secondes) de l’expiration de l’étape d’exécution. Une étape est considérée comme expirée si l’exécution parente a expiré.
cancelled_at entier ou null Horodateur Unix (en secondes) de l’annulation de l’étape d’exécution.
failed_at entier ou null Horodatage Unix (en secondes) de l’échec de l’étape d’exécution.
completed_at entier ou null L’horodatage Unix (en secondes) de la réalisation de l’étape d’exécution.
metadata map Ensemble de 16 paires clé-valeur pouvant être attachées à un objet. Cela peut être utile pour stocker des informations supplémentaires sur l'objet dans un format structuré. Les clés peuvent contenir au maximum 64 caractères et les valeurs peuvent contenir au maximum 512 caractères.

Diffusion d'un résultat d'exécution (aperçu)

Stream le résultat de l'exécution d'un Run ou de la reprise d'un Run après avoir soumis les sorties de l'outil. Vous pouvez diffuser des événements après :

Pour diffuser en continu un résultat, passez "stream": true lors de la création d’une exécution. La réponse sera un flux d’événements envoyés par le serveur.

Exemple de streaming

from typing_extensions import override
from openai import AssistantEventHandler
 
# First, we create a EventHandler class to define
# how we want to handle the events in the response stream.
 
class EventHandler(AssistantEventHandler):    
  @override
  def on_text_created(self, text) -> None:
    print(f"\nassistant > ", end="", flush=True)
      
  @override
  def on_text_delta(self, delta, snapshot):
    print(delta.value, end="", flush=True)
      
  def on_tool_call_created(self, tool_call):
    print(f"\nassistant > {tool_call.type}\n", flush=True)
  
  def on_tool_call_delta(self, delta, snapshot):
    if delta.type == 'code_interpreter':
      if delta.code_interpreter.input:
        print(delta.code_interpreter.input, end="", flush=True)
      if delta.code_interpreter.outputs:
        print(f"\n\noutput >", flush=True)
        for output in delta.code_interpreter.outputs:
          if output.type == "logs":
            print(f"\n{output.logs}", flush=True)
 
# Then, we use the `create_and_stream` SDK helper 
# with the `EventHandler` class to create the Run 
# and stream the response.
 
with client.beta.threads.runs.stream(
  thread_id=thread.id,
  assistant_id=assistant.id,
  instructions="Please address the user as Jane Doe. The user has a premium account.",
  event_handler=EventHandler(),
) as stream:
  stream.until_done()

Objet delta du message

Représente un message delta. Par exemple, tout champ modifié dans un message pendant la diffusion.

Nom Type Description
id string Identificateur du message qui peut être référencé dans les points de terminaison d’API.
object string Le type d’objet, qui est toujours thread.message.delta.
delta object Le delta contenant les champs qui ont été modifiés dans le message.

Objet delta de l'étape d'exécution

Représente une exécution d’une étape delta. Par exemple, tout champ modifié dans une étape d’exécution pendant la diffusion.

Nom Type Description
id string Identificateur de l’étape d’exécution qui peut être référencé dans les points de terminaison d’API.
object string Le type d’objet, qui est toujours thread.run.step.delta.
delta object Le delta contenant les champs qui ont été modifiés dans l’étape d’exécution.

Événements du flux d'assistants

Représente un événement émis lors de la diffusion en continu d'une exécution. Chaque événement d’un flux d’événements envoyés par le serveur a une propriété d’événement et de données :

event: thread.created
data: {"id": "thread_123", "object": "thread", ...}

Des événements sont émis chaque fois qu'un nouvel objet est créé, qu'il passe à un nouvel état ou qu'il fait l'objet d'un flux partiel (deltas). Par exemple, thread.run.created est émis lorsqu’une nouvelle exécution est créée, thread.run.completed lorsqu’une exécution est terminée, et ainsi de suite. Lorsqu’un Assistant choisit de créer un message pendant une exécution, nous émettons un événement thread.message.created, un événement thread.message.in_progress, de nombreux threads.message.delta événements, et enfin un événement thread.message.completed.

Nom Type Description
thread.created data est un thread. Se produit quand une conversation est créée.
thread.run.created data est une exécution. Se produit quand une exécution est créée.
thread.run.queued data est une exécution. Se produit lorsqu'une exécution passe à l'état de file d'attente.
thread.run.in_progress data est une exécution. Se produit lorsqu'une exécution passe à l'état in_progress.
thread.run.requires_action data est une exécution. Se produit lorsqu'une exécution passe à l'état requires_action.
thread.run.completed data est une exécution. Se produit quand une exécution est terminée.
thread.run.failed data est une exécution. Se produit lorsqu'une exécution échoue.
thread.run.cancelling data est une exécution. Se produit lorsqu'une exécution passe à l'état cancelling.
thread.run.cancelled data est une exécution. Se produit quand une exécution est annulée.
thread.run.expired data est une exécution. Se produit lorsqu'une exécution expire.
thread.run.step.created data est une étape d’exécution. Se produit lors de la création d'une étape d'exécution.
thread.run.step.in_progress data est une étape d’exécution. Se produit lorsqu’une étape d’exécution passe à un état in_progress.
thread.run.step.delta data est un delta d’étape d’exécution. Se produit lorsque des parties d'une étape d'exécution sont diffusées en continu.
thread.run.step.completed data est une étape d’exécution. Se produit lors de la fin d'une étape d'exécution.
thread.run.step.failed data est une étape d’exécution. Se produit lors de l’échec d'une étape d'exécution.
thread.run.step.cancelled data est une étape d’exécution. Se produit quand une étape d’exécution est annulée.
thread.run.step.expired data est une étape d’exécution. Se produit lors de l’expiration d'une étape d'exécution.
thread.message.created data est un message. Se produit lorsqu'un message est créé.
thread.message.in_progress data est un message. Se produit lorsqu'un message passe à l'état in_progress.
thread.message.delta data est un message delta. Se produit lorsque des parties d'un message sont diffusées en continu.
thread.message.completed data est un message. Se produit lorsqu'un message est terminé.
thread.message.incomplete data est un message. Se produit lorsqu'un message se termine avant d'être achevé.
error data est une erreur. Se produit lorsqu'une erreur a lieu. Cela peut être dû à une erreur interne du serveur ou à un dépassement de délai.
done data est [DONE] Se produit lorsqu'un flux se termine.