Partager 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.

Types de formats de réponse (response_format)

string

auto est la valeur par défaut.

object

Valeurs possibles de type : text, json_object, json_schema.

json_schema

Nom Type Description Default Obligatoire ou facultatif
description string Description du rôle du format de réponse, qui permet au modèle de déterminer comment répondre dans le format. Facultatif
name string Nom du format de réponse. Doit être a-z, A-Z, 0-9 ou contenir des traits de soulignement et des tirets, avec une longueur maximale de 64. Requis
schema object Schéma du format de réponse, décrit en tant qu’objet de schéma JSON. Facultatif
strict booléen ou null Indique s’il faut activer l’adhésion stricte au schéma lors de la génération de la sortie. Si la valeur est true, le modèle suit toujours le schéma exact défini dans le champ schema. Seul un sous-ensemble de schéma JSON est pris en charge lorsque strict est true. false Facultatif

Propriétés tool_resources

code_interpreter

Nom Type Description Default
file_ids tableau Une liste d’ID de fichiers mis à la disposition de l’outil code_interpreter. Il peut y avoir un maximum de 20 fichiers associés à l’outil. []

file_search

Nom Type Description Obligatoire ou facultatif
vector_store_ids tableau Le magasin de vecteurs attaché à ce thread. Il peut y avoir un maximum d’un magasin de vecteurs attaché au thread. Facultatif
vector_stores tableau Un Assistant pour créer un magasin de vecteurs avec file_ids et l’attacher à ce thread. Il peut y avoir un maximum d’un magasin de vecteurs attaché au thread. Facultatif

vector_stores

Nom Type Description Obligatoire ou facultatif
file_ids tableau Une liste d’ID de fichier à ajouter au magasin de vecteurs. Il peut y avoir un maximum de 10 000 fichiers dans un magasin de vecteurs. Facultatif
chunking_strategy object Stratégie de segmentation utilisée pour segmenter un ou plusieurs fichiers. Si elle n’est pas définie, la stratégie automatique est utilisée. Facultatif
metadata map Ensemble de 16 paires clé-valeur pouvant être attachées à un magasin de vecteurs. Ceci peut être utile pour stocker des informations supplémentaires sur le magasin de vecteurs dans un format structuré. Les clés peuvent contenir au maximum 64 caractères et les valeurs peuvent contenir au maximum 512 caractères. Facultatif

chunking_strategy

Nom Type Description Obligatoire ou facultatif
Auto Chunking Strategy object Stratégie par défaut. Cette stratégie utilise actuellement un max_chunk_size_tokens de 800 et chunk_overlap_tokens de 400. type a toujours la valeur auto Requis
Static Chunking Strategy object type toujours static Requis

Stratégie de segmentation statique

Nom Type Description Obligatoire ou facultatif
max_chunk_size_tokens entier Nombre maximal de jetons dans chaque segmentation. La valeur par défaut est 800. La valeur minimale est 100, alors que la valeur maximale est 4096. Requis
chunk_overlap_tokens entier Nombre de jetons qui se chevauchent entre segmentations. La valeur par défaut est 400. Notez que le chevauchement ne doit pas excéder la moitié de max_chunk_size_tokens. Requis

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.