Partage via

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

  • Article

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 un assistant

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

Créez un assistant avec un modèle et des instructions.

Corps de la demande

Nom Type Requise Description
modèle string Requis Nom du modèle de déploiement du modèle à utiliser.
name chaîne ou null Facultatif Nom de l’assistant. La longueur maximale est de 256 caractères.
description chaîne ou null Facultatif Description de l’assistant. La longueur maximale est de 512 caractères.
détaillées chaîne ou null Facultatif Instructions système utilisées par l’assistant. La longueur maximale est de 256 000 caractères.
tools tableau Facultatif La valeur par défaut est []. Liste des outils activés sur l’assistant. Il peut y avoir jusqu’à 128 outils par assistant. Les outils peuvent actuellement être de types code_interpreter ou function. Une description function peut comporter au maximum 1 024 caractères.
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.
température entier ou nul Facultatif La valeur par défaut est de 1. Détermine la température d’échantillonnage à utiliser, entre 0 et 2. Des valeurs plus élevées telles que 0,8 rendent la sortie plus aléatoire, tandis que des valeurs inférieures telles que 0,2 la rendent plus ciblée et déterministe.
top_p entier ou nul Facultatif La valeur par défaut est de 1. Alternative à l’échantillonnage avec la température, appelée échantillonnage de noyau, où le modèle considère les résultats des jetons avec la masse de probabilité top_p. Par conséquent, 0,1 signifie que seuls les jetons comprenant la masse de probabilité supérieure de 10 % sont considérés. Nous vous recommandons généralement de modifier this ou température, mais pas les deux.
response_format chaîne ou objet Facultatif Spécifie le format de sortie du modèle. Compatible avec GPT-4 Turbo et tous les modèles GPT-3.5 Turbo depuis gpt-3.5-turbo-1106. La définition de ce paramètre sur { "type": "json_object" } active le mode JSON qui assure que le message généré par le modèle est un JSON valide. Avant tout, lorsque vous utilisez le mode JSON, vous devez également demander au modèle de produire JSON vous-même en utilisant un message utilisateur ou système. Sans cette instruction, le modèle peut générer un flux sans fin d’espaces blancs jusqu’à ce que la génération atteigne la limite de jetons et entraîner une requête apparemment « bloquée ». En outre, le contenu du message peut être partiellement coupé si vous utilisez finish_reason="length", ce qui indique que la génération a dépassé max_tokens ou que la conversation a dépassé la longueur maximale de contexte.
tool_resources object Facultatif Un ensemble de ressources utilisées par les outils de l’Assistant. Les ressources sont spécifiques au type d’outil. Par exemple, l’outil code_interpreter nécessite une liste d’ID de fichiers, tandis que l’outil file_search nécessite une liste d’ID de magasins de vecteurs.

Retours

Un objet assistant.

Exemple de requête de création d’assistant

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

assistant = client.beta.assistants.create(
  instructions="You are an AI assistant that can write code to help answer math questions",
  model="<REPLACE WITH MODEL DEPLOYMENT NAME>", # replace with model deployment name. 
  tools=[{"type": "code_interpreter"}]
)

Répertorier les assistants

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview

Retourne une liste de tous les assistants.

Paramètres de requête

Paramètre Type Requise Description
limit entier Facultatif 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 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 before=obj_foo afin d’extraire la page précédente de la liste.

Retours

Liste des objets d’assistant

Exemples de liste d’assistants

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

my_assistants = client.beta.assistants.list(
    order="desc",
    limit="20",
)
print(my_assistants.data)

Récupérer l’assistant

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview

Récupère un assistant.

Paramètres de chemin d’accès

Paramètre Type Requise Description
assistant_id string Requis ID de l’assistant à récupérer.

Renvoie

Objet assistant correspondant à l’ID spécifié.

Exemple de récupération d’assistant

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

my_assistant = client.beta.assistants.retrieve("asst_abc123")
print(my_assistant)

Modifier l’assistant

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview

Modifie un assistant.

Paramètres de chemin d’accès

Paramètre Type Requise Description
assistant_id string Requis ID de l’assistant auquel appartient le fichier.

Corps de la demande

Paramètre Type Requise Description
model Facultatif Nom du modèle de déploiement à utiliser.
name chaîne ou null Facultatif Nom de l’assistant. La longueur maximale est de 256 caractères.
description chaîne ou null Facultatif Description de l’assistant. La longueur maximale est de 512 caractères.
instructions chaîne ou null Facultatif Instructions système utilisées par l’assistant. La longueur maximale est de 32 768 caractères.
tools tableau Facultatif La valeur par défaut est []. Liste des outils activés sur l’assistant. Il peut y avoir jusqu’à 128 outils par assistant. Les outils peuvent être de types code_interpreter ou fonction. Une description function peut comporter au maximum 1 024 caractères.
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.
temperature entier ou nul Facultatif La valeur par défaut est de 1. Détermine la température d’échantillonnage à utiliser, entre 0 et 2. Des valeurs plus élevées telles que 0,8 rendent la sortie plus aléatoire, tandis que des valeurs inférieures telles que 0,2 la rendent plus ciblée et déterministe.
top_p entier ou nul Facultatif La valeur par défaut est de 1. Alternative à l’échantillonnage avec la température, appelée échantillonnage de noyau, où le modèle considère les résultats des jetons avec la masse de probabilité top_p. Par conséquent, 0,1 signifie que seuls les jetons comprenant la masse de probabilité supérieure de 10 % sont considérés. Nous vous recommandons généralement de modifier this ou température, mais pas les deux.
response_format chaîne ou objet Facultatif Spécifie le format de sortie du modèle. Compatible avec GPT-4 Turbo et tous les modèles GPT-3.5 Turbo depuis gpt-3.5-turbo-1106. La définition de ce paramètre sur { "type": "json_object" } active le mode JSON qui assure que le message généré par le modèle est un JSON valide. Avant tout, lorsque vous utilisez le mode JSON, vous devez également demander au modèle de produire JSON vous-même en utilisant un message utilisateur ou système. Sans cette instruction, le modèle peut générer un flux sans fin d’espaces blancs jusqu’à ce que la génération atteigne la limite de jetons et entraîner une requête apparemment « bloquée ». En outre, le contenu du message peut être partiellement coupé si vous utilisez finish_reason="length", ce qui indique que la génération a dépassé max_tokens ou que la conversation a dépassé la longueur maximale de contexte.
tool_resources object Facultatif Un ensemble de ressources utilisées par les outils de l’Assistant. Les ressources sont spécifiques au type d’outil. Par exemple, l’outil code_interpreter nécessite une liste d’ID de fichiers, tandis que l’outil file_search nécessite une liste d’ID de magasins de vecteurs.

Renvoie

L’objet assistant modifié.

Exemple de modification de l’assistant

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

my_updated_assistant = client.beta.assistants.update(
  "asst_abc123",
  instructions="You are an HR bot, and you have access to files to answer employee questions about company policies. Always respond with info from either of the files.",
  name="HR Helper",
  tools=[{"type": "code-interpreter"}],
  model="gpt-4", #model = model deployment name
)

print(my_updated_assistant)

Supprimer l’assistant

DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview

Supprimez un assistant.

Paramètres de chemin d’accès

Paramètre Type Requise Description
assistant_id string Requis ID de l’assistant auquel appartient le fichier.

Renvoie

État de suppression.

Exemple de suppression de l’assistant

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

response = client.beta.assistants.delete("asst_abc123")
print(response)

Références sur l’API de chargement de fichiers

Les assistants utilisent la même API pour le chargement de fichiers et la précision du réglage. Lors du chargement d’un fichier, vous devez spécifier une valeur appropriée pour le paramètre d’objectif.

Objet assistant

Champ Type Description
id string Identificateur, qui peut être référencé dans les points de terminaison d’API.
object string Type d’objet, qui est toujours assistant.
created_at entier Horodatage Unix (en secondes) de la création de l’assistant.
name chaîne ou null Nom de l’assistant. La longueur maximale est de 256 caractères.
description chaîne ou null Description de l’assistant. La longueur maximale est de 512 caractères.
model string Nom du nom du modèle de déploiement à utiliser.
instructions chaîne ou null Instructions système utilisées par l’assistant. La longueur maximale est de 32 768 caractères.
tools tableau Liste des outils activés sur l’assistant. Il peut y avoir jusqu’à 128 outils par assistant. Les outils peuvent être de types code_interpreter ou fonction. Une description function peut comporter au maximum 1 024 caractères.
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.
temperature entier ou nul La valeur par défaut est de 1. Détermine la température d’échantillonnage à utiliser, entre 0 et 2. Des valeurs plus élevées telles que 0,8 rendent la sortie plus aléatoire, tandis que des valeurs inférieures telles que 0,2 la rendent plus ciblée et déterministe.
top_p entier ou nul La valeur par défaut est de 1. Alternative à l’échantillonnage avec la température, appelée échantillonnage de noyau, où le modèle considère les résultats des jetons avec la masse de probabilité top_p. Par conséquent, 0,1 signifie que seuls les jetons comprenant la masse de probabilité supérieure de 10 % sont considérés. Nous vous recommandons généralement de modifier this ou température, mais pas les deux.
response_format chaîne ou objet Spécifie le format de sortie du modèle. Compatible avec GPT-4 Turbo et tous les modèles GPT-3.5 Turbo depuis gpt-3.5-turbo-1106. La définition de ce paramètre sur { "type": "json_object" } active le mode JSON qui assure que le message généré par le modèle est un JSON valide. Avant tout, lorsque vous utilisez le mode JSON, vous devez également demander au modèle de produire JSON vous-même en utilisant un message utilisateur ou système. Sans cette instruction, le modèle peut générer un flux sans fin d’espaces blancs jusqu’à ce que la génération atteigne la limite de jetons et entraîner une requête apparemment « bloquée ». En outre, le contenu du message peut être partiellement coupé si vous utilisez finish_reason="length", ce qui indique que la génération a dépassé max_tokens ou que la conversation a dépassé la longueur maximale de contexte.
tool_resources object Un ensemble de ressources utilisées par les outils de l’Assistant. Les ressources sont spécifiques au type d’outil. Par exemple, l’outil code_interpreter nécessite une liste d’ID de fichiers, tandis que l’outil file_search nécessite une liste d’ID de magasins de vecteurs.