Référence de l'API REST d’Azure OpenAI Service

  • Article

Cet article fournit des détails sur les points de terminaison API REST d’inférence pour Azure OpenAI.

Authentification

Azure OpenAI offre deux méthodes d’authentification. Vous pouvez utiliser des clés API ou Microsoft Entra ID.

  • Authentification par clé API : pour ce type d’authentification, toutes les requêtes d’API doivent inclure la clé API dans l’en-tête HTTP api-key. Le Démarrage rapide fournit des conseils sur la façon d’effectuer des appels avec ce type d’authentification.

  • Authentification Microsoft Entra ID : Vous pouvez authentifier un appel d’API à l’aide d’un jeton Microsoft Entra. Les jetons d’authentification sont incluses dans une requête sous la forme de l’en-tête Authorization. Le jeton fourni doit être précédé de Bearer. Par exemple : Bearer YOUR_AUTH_TOKEN. Vous pouvez lire notre guide pratique sur Authentification avec Microsoft Entra ID.

Gestion des versions d’API

Les API de service sont versionnées à l’aide du paramètre de requête api-version. Toutes les versions suivent la structure de date AAAA-MM-JJ. Par exemple :

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/completions?api-version=2024-02-01

Saisies semi-automatiques

Avec l’opération Achèvements, le modèle génère un ou plusieurs achèvements prédits en fonction d’une invite fournie. Le service peut également retourner les probabilités de jetons alternatifs à chaque position.

Créer une exécution

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/completions?api-version={api-version}

Paramètres de chemin d’accès

Paramètre Type Requis ? Description
your-resource-name string Obligatoire Nom de votre ressource Azure OpenAI.
deployment-id string Obligatoire Nom de déploiement que vous avez choisi lors du déploiement du modèle.
api-version string Obligatoire Version de l’API à utiliser pour cette opération. Cela suit le format AAAA-MM-JJ.

Versions prises en charge

Corps de la demande

Paramètre Type Requis ? Default Description
prompt chaîne ou tableau Facultatif <\|endoftext\|> La ou les invites pour lesquelles il faut générer des complétions, encodées sous forme de chaîne ou de tableau de chaînes. <\|endoftext\|> est le séparateur de documents que le modèle voit lors de l’apprentissage : si aucune invite n’est spécifiée, le modèle est donc généré comme s’il s’agissait du début d’un nouveau document.
max_tokens entier Facultatif 16 Nombre maximal de jetons à générer dans la saisie semi-automatique. Le nombre de jetons de votre invite plus max_tokens ne peut pas dépasser la longueur du contexte du modèle. La plupart des modèles ont une longueur de contexte de 2 048 jetons (à l’exception des modèles les plus récents, qui prennent en charge 4 096 jetons).
temperature nombre Facultatif 1 Température d’échantillonnage à utiliser, entre 0 et 2. Des valeurs plus élevées signifient que le modèle prend plus de risques. Essayez 0,9 pour plus d’applications créatives, et 0 (argmax sampling) pour une réponse bien définie. Nous vous recommandons généralement de modifier this ou top_p, mais pas les deux.
top_p nombre Facultatif 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.
logit_bias carte Facultatif null Modifiez la probabilité que les jetons spécifiés apparaissent dans l’achèvement. Accepte un objet json qui mappe les jetons (spécifiés par leur ID de jeton dans le générateur de jetons GPT) avec une valeur de biais associée de -100 à 100. Vous pouvez utiliser cet outil de générateur de jetons (qui fonctionne pour GPT-2 et GPT-3) afin de convertir du texte en ID de jeton. Mathématiquement, le biais est ajouté aux logits générés par le modèle avant l’échantillonnage. L’effet exact varie selon le modèle, mais les valeurs comprises entre -1 et 1 doivent diminuer ou augmenter la probabilité de sélection; les valeurs telles que -100 ou 100 doivent entraîner une interdiction ou une sélection exclusive du jeton approprié. Par exemple, vous pouvez passer {"50256": -100} pour empêcher la génération du jeton <|endoftext|>.
user string Facultatif Identificateur unique représentant votre utilisateur final, qui peut vous aider à surveiller et à détecter des abus
n entier Facultatif 1 Nombre d’achèvements à générer pour chaque invite. Remarque : comme ce paramètre génère de nombreuses saisies semi-automatiques, il peut rapidement consommer votre quota de jetons. Utilisez-le avec précaution et assurez-vous que vous avez des paramètres raisonnables pour max_tokens et stop.
stream boolean Facultatif False Indique s’il faut renvoyer la progression partielle. Si cela est défini, les jetons sont envoyés en tant qu’événements envoyés par le serveur uniquement au fur et à mesure qu’ils deviennent disponibles, avec le flux arrêté par un message de données [DONE].
logprobs entier Facultatif null Incluez les probabilités de journal sur les jetons les plus probables, ainsi que les jetons choisis. Par exemple, si logprobs est égal à 10, l’API retourne une liste des 10 jetons les plus probables. L’API retourne toujours le logprob du jeton échantillonné. Il est donc possible qu’il y ait jusqu’à logprobs+1 éléments dans la réponse. Ce paramètre ne peut pas être employé avec gpt-35-turbo.
suffix string Facultatif null Suffixe qui vient après l’achèvement d’un texte inséré.
echo boolean Facultatif False Renvoyer l’invite en plus de l’achèvement. Ce paramètre ne peut pas être employé avec gpt-35-turbo.
stop chaîne ou tableau Facultatif null Jusqu’à quatre séquences dans lesquelles l’API cessera de générer d’autres jetons. Le texte retourné ne contient pas la séquence d’arrêt. Pour GPT-4 Turbo avec Vision, jusqu’à deux séquences sont prises en charge.
presence_penalty number Facultatif 0 Nombre compris entre -2.0 et 2.0. Les valeurs positives pénalisent les nouveaux tokens selon qu’ils apparaissent ou non dans le texte jusqu’à présent, ce qui augmente la probabilité que le modèle parle de nouveaux sujets.
frequency_penalty nombre Facultatif 0 Nombre compris entre -2.0 et 2.0. Les valeurs positives pénalisent les nouveaux jetons en fonction de leur fréquence existante dans le texte jusqu’à présent, ce qui réduit la probabilité que le modèle répète la même ligne mot pour mot.
best_of entier Facultatif 1 Génère des achèvements best_of côté serveur et retourne le « meilleur » d’entre eux (celui avec la probabilité de journal la plus faible par jeton). Les résultats ne peuvent pas être diffusés en continu. Lorsqu’il est utilisé avec n, best_of contrôle le nombre d’achèvements candidats et n spécifie le nombre de retours : best_of doit être supérieur à n. Remarque : comme ce paramètre génère de nombreuses saisies semi-automatiques, il peut rapidement consommer votre quota de jetons. Utilisez-le avec précaution et assurez-vous que vous avez des paramètres raisonnables pour max_tokens et stop. Ce paramètre ne peut pas être employé avec gpt-35-turbo.

Exemple de requête

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/completions?api-version=2024-02-01\
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d "{
  \"prompt\": \"Once upon a time\",
  \"max_tokens\": 5
}"

Exemple de réponse

{
    "id": "cmpl-4kGh7iXtjW4lc9eGhff6Hp8C7btdQ",
    "object": "text_completion",
    "created": 1646932609,
    "model": "ada",
    "choices": [
        {
            "text": ", a dark line crossed",
            "index": 0,
            "logprobs": null,
            "finish_reason": "length"
        }
    ]
}

Dans l’exemple de réponse, finish_reason est égal à stop. Si finish_reason est égal à content_filter, consultez notre guide de filtrage de contenu pour comprendre pourquoi cela se produit.

Incorporations

Obtenez une représentation vectorielle d’une entrée donnée qui peut être facilement consommée par des modèles Machine Learning et d’autres algorithmes.

Remarque

OpenAI autorise actuellement un plus grand nombre d’entrées de tableau avec text-embedding-ada-002. Azure OpenAI prend actuellement en charge jusqu’à 16 tableaux d’entrée pour text-embedding-ada-002 (Version 2). Les deux nécessitent que la limite maximale de jetons d’entrée par requête d’API reste inférieure à 8191 pour ce modèle.

Créer une incorporation

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/embeddings?api-version={api-version}

Paramètres de chemin d’accès

Paramètre Type Requis ? Description
your-resource-name string Obligatoire Nom de votre ressource Azure OpenAI.
deployment-id string Obligatoire Nom de votre modèle de déploiement. Vous devez d’abord déployer un modèle avant de pouvoir effectuer des appels.
api-version string Obligatoire Version de l’API à utiliser pour cette opération. Cela suit le format AAAA-MM-JJ.

Versions prises en charge

Corps de la demande

Paramètre Type Requis ? Default Description
input chaîne ou tableau Oui N/A Texte d’entrée pour lequel on veut obtenir des incorporations, encodé comme un tableau ou une chaîne. Le nombre de jetons d’entrée varie en fonction du modèle que vous utilisez. Uniquement text-embedding-ada-002 (Version 2) prend en charge l’entrée de tableau.
user string Non Null Identificateur unique représentant votre utilisateur final. Cela aidera Azure OpenAI à surveiller et à détecter les abus. Ne passez pas d’identificateurs d’informations personnelles à la place à l’aide de valeurs pseudo-anonymisées telles que les GUID
encoding_format string Non float Format dans lequel retourner les incorporations. La valeur peut être float ou base64. La valeur par défaut est float.

[Ajouté à 2024-03-01-preview].
dimensions entier Non Nombre de dimensions que les incorporations de sortie obtenues doivent avoir. Uniquement pris en charge dans les modèles text-embedding-3 et ultérieurs.

[Ajouté à 2024-03-01-preview]

Exemple de requête

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/embeddings?api-version=2024-02-01 \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d "{\"input\": \"The food was delicious and the waiter...\"}"

Exemple de réponse

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [
        0.018990106880664825,
        -0.0073809814639389515,
        .... (1024 floats total for ada)
        0.021276434883475304,
      ],
      "index": 0
    }
  ],
  "model": "text-similarity-babbage:001"
}

Complétions de conversation

Créez des saisies semi-automatiques aux messages de conversation avec les modèles GPT-35-Turbo et GPT-4.

Créer des complétions de conversation

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}

Paramètres de chemin d’accès

Paramètre Type Requis ? Description
your-resource-name string Obligatoire Nom de votre ressource Azure OpenAI.
deployment-id string Obligatoire Nom de votre modèle de déploiement. Vous devez d’abord déployer un modèle avant de pouvoir effectuer des appels.
api-version string Obligatoire Version de l’API à utiliser pour cette opération. Cela suit le format AAAA-MM-JJ ou AAAA-MM-JJ-préversion.

Versions prises en charge

Corps de la demande

Le corps de la requête se compose d’une série de messages. Le modèle génère une réponse au dernier message, en utilisant des messages antérieurs comme contexte.

Paramètre Type Requis ? Default Description
messages tableau Oui S/O Série de messages associés à cette demande de saisie semi-automatique de conversation. Il doit inclure les messages précédents dans la conversation. Chaque message a un role et content.
role string Oui S/O Indique qui donne le message actuel. Peut être system,user,assistant,toolou function.
content chaîne ou tableau Oui S/O Contenu du message. Il doit s’agir d’une chaîne, sauf dans un scénario activé par Vision. Si elle fait partie du message user, à l’aide du modèle GPT-4 Turbo avec Vision, avec la dernière version de l’API, alors content doit être un tableau de structures, où chaque élément représente du texte ou une image :
  • text : le texte d’entrée est représenté sous forme de structure avec les propriétés suivantes :
    • type = « text »
    • text = le texte d’entrée
  • images : une image d’entrée est représentée sous la forme d’une structure avec les propriétés suivantes :
    • type = « image_url »
    • image_url = une structure avec les propriétés suivantes :
      • url = l’URL de l’image
      • (facultatif) detail = high, low ou auto
contentPart object Non N/A Partie du message multimodal d’un utilisateur. Il peut s’agir d’un type de texte ou d’un type d’image. Si il y a du texte, il s’agit d’une chaîne de texte. Si c’est une image, il s’agit d’un contentPartImage objet.
contentPartImage object Non N/A Représente une image chargée par l’utilisateur. Il a une propriété url, qui est une URL de l’image ou les données d’image codées en base 64. Il a également une propriété detail qui peut être auto, lowou high.
enhancements object Non N/A Représente les fonctionnalités d’amélioration de vision demandées pour la conversation. Il a des propriétés grounding et ocr, chacune ayant une propriété enabled booléenne. Utilisez-les pour demander le service OCR et/ou le service de détection d’objets/de mise au sol [Ce paramètre en préversion n’est pas disponible dans l’API GA 2024-02-01].
dataSources object Non N/A Représente des données de ressources supplémentaires. Les données de ressources Vision par ordinateur sont nécessaires pour améliorer Vision. Il a une propriété type qui doit être "AzureComputerVision", et une propriété parameters, qui a une propriété endpoint et key. Ces chaînes doivent être définies sur l’URL du point de terminaison et la clé d’accès de votre ressource Vision par ordinateur.

Exemple de requête

Conversation en texte seule

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/chat/completions?api-version=2024-02-01 \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{"messages":[{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "Does Azure OpenAI support customer managed keys?"},{"role": "assistant", "content": "Yes, customer managed keys are supported by Azure OpenAI."},{"role": "user", "content": "Do other Azure AI services support this too?"}]}'

Conversation avec vision

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/chat/completions?api-version=2023-12-01-preview \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":[{"type":"text","text":"Describe this picture:"},{ "type": "image_url", "image_url": { "url": "https://learn.microsoft.com/azure/ai-services/computer-vision/media/quickstarts/presentation.png", "detail": "high" } }]}]}'

Conversation améliorée avec vision

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-12-01-preview \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{"enhancements":{"ocr":{"enabled":true},"grounding":{"enabled":true}},"dataSources":[{"type":"AzureComputerVision","parameters":{"endpoint":" <Computer Vision Resource Endpoint> ","key":"<Computer Vision Resource Key>"}}],"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":[{"type":"text","text":"Describe this picture:"},{"type":"image_url","image_url":"https://learn.microsoft.com/azure/ai-services/computer-vision/media/quickstarts/presentation.png"}]}]}'

Exemple de réponse

{
    "id": "chatcmpl-6v7mkQj980V1yBec6ETrKPRqFjNw9",
    "object": "chat.completion",
    "created": 1679072642,
    "model": "gpt-35-turbo",
    "usage":
    {
        "prompt_tokens": 58,
        "completion_tokens": 68,
        "total_tokens": 126
    },
    "choices":
    [
        {
            "message":
            {
                "role": "assistant",
                "content": "Yes, other Azure AI services also support customer managed keys.
                    Azure AI services offer multiple options for customers to manage keys, such as
                    using Azure Key Vault, customer-managed keys in Azure Key Vault or
                    customer-managed keys through Azure Storage service. This helps customers ensure
                    that their data is secure and access to their services is controlled."
            },
            "finish_reason": "stop",
            "index": 0
        }
    ]
}

Mise en forme de sortie ajustée pour faciliter la lecture. La sortie réelle est un seul bloc de texte sans saut de ligne.

Dans l’exemple de réponse, finish_reason est égal à stop. Si finish_reason est égal à content_filter, consultez notre guide de filtrage de contenu pour comprendre pourquoi cela se produit.

Important

Les paramètres functions et function_call ont été déconseillés avec la publication de la version 2023-12-01-preview de l’API. Le remplacement de functions est le paramètre tools. Le remplacement de function_call est le paramètre tool_choice. L’appel de fonction parallèle, qui a été introduit dans le cadre du 2023-12-01-preview, n’est pris en charge qu’avec gpt-35-turbo (1106) et gpt-4 (1106-preview), également connu sous le nom de Préversion de GPT-4 Turbo.

Paramètre Type Requis ? Default Description
messages tableau Requis Collection de messages de contexte associés à cette demande de complétion de conversation. L’utilisation classique commence par un message de conversation pour le rôle Système qui fournit des instructions pour le comportement de l’Assistant, suivi d’une alternance de messages entre les rôles Utilisateur et Assistant.
temperature number Facultatif 1 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. Nous vous recommandons généralement de modifier cela ou top_p mais pas les deux.
n entier Facultatif 1 Nombre d’options de complétion de conversation à générer pour chaque message d’entrée.
stream boolean Facultatif false Si cette option est définie, des deltas de message partiels sont envoyés, comme dans ChatGPT. Les jetons sont envoyés en tant qu’événements envoyés par le serveur de données uniquement au fur et à mesure qu’ils deviennent disponibles, avec le flux arrêté par un message data: [DONE]. »
stop chaîne ou tableau Facultatif null Jusqu’à 4 séquences dans lesquelles l’API cesse de générer d’autres jetons.
max_tokens entier Facultatif inf Nombre maximal de jetons autorisés pour la réponse générée. Par défaut, le nombre de jetons que le modèle peut retourner est (4 096 : jetons d’invite).
presence_penalty nombre Facultatif 0 Nombre compris entre -2.0 et 2.0. Les valeurs positives pénalisent les nouveaux tokens selon qu’ils apparaissent ou non dans le texte jusqu’à présent, ce qui augmente la probabilité que le modèle parle de nouveaux sujets.
frequency_penalty nombre Facultatif 0 Nombre compris entre -2.0 et 2.0. Les valeurs positives pénalisent les nouveaux jetons en fonction de leur fréquence existante dans le texte jusqu’à présent, ce qui réduit la probabilité que le modèle répète la même ligne mot pour mot.
logit_bias object Facultatif null Modifiez la probabilité que les jetons spécifiés apparaissent dans l’achèvement. Accepte un objet JSON qui mappe des jetons (spécifiés par leur ID de jeton dans le générateur de jetons) avec une valeur de biais associée de -100 à 100. Mathématiquement, le biais est ajouté aux logits générés par le modèle avant l’échantillonnage. L’effet exact varie selon le modèle, mais les valeurs comprises entre -1 et 1 doivent diminuer ou augmenter la probabilité de sélection; les valeurs telles que -100 ou 100 doivent entraîner une interdiction ou une sélection exclusive du jeton approprié.
user string Facultatif Identificateur unique représentant votre utilisateur final, qui peut aider Azure OpenAI à surveiller et à détecter des abus.
function_call Facultatif [Deprecated in 2023-12-01-preview replacement parameter is tools_choice]Contrôle la façon dont le modèle répond aux appels de fonction. « none » signifie que le modèle n’appelle pas de fonction et répond à l’utilisateur final. auto signifie que le modèle peut choisir entre un utilisateur final ou appeler une fonction. La spécification d’une fonction particulière via {"name": "my_function"} force le modèle à appeler cette fonction. « none » est la valeur par défaut lorsqu’aucune fonction n’est présente. auto est la valeur par défaut si des fonctions sont présentes. Ce paramètre nécessite la version 2023-07-01-preview de l’API
functions FunctionDefinition[] Facultatif [Deprecated in 2023-12-01-preview replacement paremeter is tools] Liste des fonctions pour lesquelles le modèle peut générer des entrées JSON. Ce paramètre nécessite la version 2023-07-01-preview de l’API
tools chaîne (Type de l’outil. Seul function est pris en charge.) Facultatif Liste d’outils que le modèle peut appeler. Actuellement, seules les fonctions sont prises en charge en tant qu’outil. Utilisez cette option afin de fournir une liste des fonctions pour lesquelles le modèle peut générer des entrées JSON. Ce paramètre nécessite la version 2023-12-01-preview de l’API
tool_choice chaîne ou objet Facultatif none est la valeur par défaut lorsqu’aucune fonction n’est présente. auto est la valeur par défaut si des fonctions sont présentes. Contrôle la fonction (le cas échéant) appelée par le modèle. None signifie que le modèle n’appelle pas de fonction et génère un message à la place. auto signifie que le modèle peut choisir entre générer un message ou appeler une fonction. La spécification d’une fonction particulière via {"type: "function", "function": {"name": "my_function"}} force le modèle à appeler cette fonction. Ce paramètre nécessite la version 2023-12-01-preview ou ultérieure de l’API.

ChatMessage

Message unique, attribué à un rôle dans une interaction de fin de conversation.

Nom Type Description
contenu string Texte associé à cette charge utile de message.
function_call FunctionCall Nom et arguments d’une fonction qui doit être appelée, comme généré par le modèle.
name chaîne Le name de l’auteur de ce message. Le name est requis si le rôle est function, et il doit s’agir du nom de la fonction dont la réponse se trouve dans le content. Peut contenir a-z, A-Z, 0-9 et des tirets bas, avec une longueur maximale de 64 caractères.
role ChatRole Rôle associé à cette charge utile de message

ChatRole

Description de l’objectif prévu d’un message dans une interaction de complétion de conversation.

Nom Type Description
assistant string Rôle qui fournit des réponses à une entrée indiquée par le système et à l’invite de l’utilisateur.
function string Rôle qui fournit des résultats de fonction pour les complétions de conversation.
système string Rôle qui indique ou définit le comportement de l’Assistant.
utilisateur string Rôle qui fournit une entrée pour les complétions de conversation.

Fonction

Cette option est utilisée avec le paramètre tools qui a été ajouté dans la version 2023-12-01-preview de l’API.

Nom Type Description
description string Description de l’utilité de la fonction, utilisée par le modèle pour choisir quand et comment appeler la fonction
name chaîne Nom de la fonction à appeler. Doit être a-z, A-Z, 0-9 ou contenir des traits de soulignement et des tirets, avec une longueur maximale de 64
parameters object Paramètres acceptés par les fonctions, décrits sous la forme d’un objet de schéma JSON. Consultez la référence de schéma JSON pour obtenir de la documentation sur le format. »

FunctionCall-Deprecated

Nom et arguments d’une fonction qui doit être appelée, comme généré par le modèle. Cela nécessite la version 2023-07-01-preview de l’API

Nom Type Description
arguments string Arguments à utiliser pour appeler la fonction, tels qu’ils sont générés par le modèle au format JSON. Le modèle ne génère pas toujours un JSON valide et peut fabriquer des paramètres non définis par votre schéma de fonction. Validez les arguments dans votre code avant d’appeler votre fonction.
name chaîne Nom de la fonction à appeler.

FunctionDefinition-Deprecated

Définition d’une fonction spécifiée par l’appelant que les complétions de conversation instantanée peuvent appeler en réponse à une entrée utilisateur correspondante. Cela nécessite la version 2023-07-01-preview de l’API

Nom Type Description
description string Description du rôle de la fonction. Le modèle utilise cette description lors de la sélection de la fonction et de l’interprétation de ses paramètres.
name chaîne Nom de la fonction à appeler.
parameters Paramètres acceptés par les fonctions, décrits sous la forme d’un objet de schéma JSON.

Extensions de saisie semi-automatique

Extensions pour les complétions de conversation, par exemple Azure OpenAI sur vos données.

Important

Les informations suivantes concernent la version 2023-12-01-preview de l’API. Il ne s’agit pas de la version actuelle de l’API. Pour trouver la dernière documentation de référence, consultez Informations de référence sur Azure OpenAI sur vos données.

Utiliser des extensions de saisie semi-automatique de conversation

POST {your-resource-name}/openai/deployments/{deployment-id}/extensions/chat/completions?api-version={api-version}

Paramètres de chemin d’accès

Paramètre Type Requis ? Description
your-resource-name string Obligatoire Nom de votre ressource Azure OpenAI.
deployment-id string Obligatoire Nom de votre modèle de déploiement. Vous devez d’abord déployer un modèle avant de pouvoir effectuer des appels.
api-version string Obligatoire Version de l’API à utiliser pour cette opération. Cela suit le format AAAA-MM-JJ.

Versions prises en charge

Exemple de requête

Vous pouvez faire des en utilisant Recherche Azure AI, Azure Cosmos DB for MongoDB vCore, Pinecone et Elasticsearch. Pour plus d’informations, consultez Azure OpenAI sur vos données.

curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-06-01-preview \
-H "Content-Type: application/json" \
-H "api-key: YOUR_API_KEY" \
-d \
'
{
    "temperature": 0,
    "max_tokens": 1000,
    "top_p": 1.0,
    "dataSources": [
        {
            "type": "AzureCognitiveSearch",
            "parameters": {
                "endpoint": "YOUR_AZURE_COGNITIVE_SEARCH_ENDPOINT",
                "key": "YOUR_AZURE_COGNITIVE_SEARCH_KEY",
                "indexName": "YOUR_AZURE_COGNITIVE_SEARCH_INDEX_NAME"
            }
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What are the differences between Azure Machine Learning and Azure AI services?"
        }
    ]
}
'
Azure Cosmos DB for MongoDB vCore
curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-06-01-preview \
-H "Content-Type: application/json" \
-H "api-key: YOUR_API_KEY" \
-d \
'
{
    "temperature": 0,
    "top_p": 1.0,
    "max_tokens": 800,
    "stream": false,
    "messages": [
        {
            "role": "user",
            "content": "What is the company insurance plan?"
        }
    ],
    "dataSources": [
        {
            "type": "AzureCosmosDB",
            "parameters": {
                "authentication": {
                    "type": "ConnectionString",
                    "connectionString": "mongodb+srv://onyourdatatest:{password}$@{cluster-name}.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000"
                },
                "databaseName": "vectordb",
                "containerName": "azuredocs",
                "indexName": "azuredocindex",
                "embeddingDependency": {
                    "type": "DeploymentName",
                    "deploymentName": "{embedding deployment name}"
                },
                "fieldsMapping": {
                    "vectorFields": [
                        "contentvector"
                    ]
                }
            }
        }
    ]
}
'
Elasticsearch
curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-12-01-preview \
-H "Content-Type: application/json" \
-H "api-key: YOUR_API_KEY" \
-d \
{
  "messages": [
    {
      "role": "system",
      "content": "you are a helpful assistant that talks like a pirate"
    },
    {
      "role": "user",
      "content": "can you tell me how to care for a parrot?"
    }
  ],
  "dataSources": [
    {
      "type": "Elasticsearch",
      "parameters": {
        "endpoint": "{search endpoint}",
        "indexName": "{index name}",
        "authentication": {
          "type": "KeyAndKeyId",
          "key": "{key}",
          "keyId": "{key id}"
        }
      }
    }
  ]
}
Azure Machine Learning
curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-12-01-preview \
-H "Content-Type: application/json" \
-H "api-key: YOUR_API_KEY" \
-d \
'
{
  "messages": [
    {
      "role": "system",
      "content": "you are a helpful assistant that talks like a pirate"
    },
    {
      "role": "user",
      "content": "can you tell me how to care for a parrot?"
    }
  ],
  "dataSources": [
    {
      "type": "AzureMLIndex",
      "parameters": {
        "projectResourceId": "/subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.MachineLearningServices/workspaces/{workspace-id}",
        "name": "my-project",
        "version": "5"
      }
    }
  ]
}
'
Pinecone
curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-12-01-preview \
-H "Content-Type: application/json" \
-H "api-key: YOUR_API_KEY" \
-d \
'
{
  "messages": [
    {
      "role": "system",
      "content": "you are a helpful assistant that talks like a pirate"
    },
    {
      "role": "user",
      "content": "can you tell me how to care for a parrot?"
    }
  ],
  "dataSources": [
    {
      "type": "Pinecone",
      "parameters": {
        "authentication": {
          "type": "APIKey",
          "apiKey": "{api key}"
        },
        "environment": "{environment name}",
        "indexName": "{index name}",
        "embeddingDependency": {
          "type": "DeploymentName",
          "deploymentName": "{embedding deployment name}"
        },
        "fieldsMapping": {
          "titleField": "title",
          "urlField": "url",
          "filepathField": "filepath",
          "contentFields": [
            "content"
          ],
          "contentFieldsSeparator": "\n"
        }
      }
    }
  ]
}
'

Exemple de réponse

{
    "id": "12345678-1a2b-3c4e5f-a123-12345678abcd",
    "model": "",
    "created": 1684304924,
    "object": "chat.completion",
    "choices": [
        {
            "index": 0,
            "messages": [
                {
                    "role": "tool",
                    "content": "{\"citations\": [{\"content\": \"\\nAzure AI services are cloud-based artificial intelligence (AI) services...\", \"id\": null, \"title\": \"What is Azure AI services\", \"filepath\": null, \"url\": null, \"metadata\": {\"chunking\": \"orignal document size=250. Scores=0.4314117431640625 and 1.72564697265625.Org Highlight count=4.\"}, \"chunk_id\": \"0\"}], \"intent\": \"[\\\"Learn about Azure AI services.\\\"]\"}",
                    "end_turn": false
                },
                {
                    "role": "assistant",
                    "content": " \nAzure AI services are cloud-based artificial intelligence (AI) services that help developers build cognitive intelligence into applications without having direct AI or data science skills or knowledge. [doc1]. Azure Machine Learning is a cloud service for accelerating and managing the machine learning project lifecycle. [doc1].",
                    "end_turn": true
                }
            ]
        }
    ]
}
Paramètres Type Requis ? Default Description
messages tableau Obligatoire null Messages pour générer des complétions de conversation, au format de conversation.
dataSources tableau Obligatoire Les sources de données à utiliser pour la fonctionnalité Azure OpenAI sur vos données.
temperature nombre Facultatif 0 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. Nous vous recommandons généralement de modifier cela ou top_p mais pas les deux.
top_p nombre Facultatif 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.
stream boolean Facultatif false Si cette option est définie, des deltas de message partiels sont envoyés, comme dans ChatGPT. Les jetons sont envoyés en tant qu’événements envoyés par le serveur de données uniquement au fur et à mesure qu’ils deviennent disponibles, avec le flux arrêté par un message "messages": [{"delta": {"content": "[DONE]"}, "index": 2, "end_turn": true}]
stop chaîne ou tableau Facultatif null Jusqu’à deux séquences dans lesquelles l’API cesse de générer d’autres jetons.
max_tokens entier Facultatif 1 000 Nombre maximal de jetons autorisés pour la réponse générée. Par défaut, le nombre de jetons que le modèle peut retourner est 4096 - prompt_tokens.

Les paramètres suivants peuvent être utilisés à l’intérieur du champ parameters à l’intérieur de dataSources.

Paramètres Type Requis ? Default Description
type string Obligatoire null La source de données à utiliser pour la fonctionnalité Azure OpenAI sur vos données. Pour Recherche Azure AI, la valeur est AzureCognitiveSearch. Pour Azure Cosmos DB for MongoDB vCore, la valeur est AzureCosmosDB. Pour Elasticsearch, la valeur est Elasticsearch. Pour Azure Machine Learning, la valeur est AzureMLIndex. Pour Pinecone, la valeur est Pinecone.
indexName string Obligatoire null Index de recherche à utiliser.
inScope booléen Facultatif true Si elle est définie, cette valeur limite les réponses spécifiques au contenu des données de base.
topNDocuments number Facultatif 5 Spécifie le nombre de documents au meilleur score à partir de votre index de données utilisé pour générer des réponses. Vous souhaiterez peut-être augmenter leur valeur lorsque vous avez des documents courts ou que souhaitez fournir davantage de contexte. Il s’agit du paramètre de documents récupérés dans Azure OpenAI Studio.
semanticConfiguration string Facultatif null Configuration de la recherche sémantique. Requis uniquement lorsque queryType est défini sur semantic ou vectorSemanticHybrid.
roleInformation string Facultatif null Fournit au modèle des instructions sur son comportement désiré et sur tout contexte qu’il doit référencer en générant une réponse. Correspond au « Message système » dans Azure OpenAI Studio. Consultez Utilisation de vos données pour plus d’informations. Il existe une limite de 100 jetons, qui compte pour la limite globale des jetons.
filter string Facultatif null Le modèle de filtre utilisé pour restreindre l’accès à des documents sensibles
embeddingEndpoint string Facultatif null L'URL du point de terminaison pour un modèle déploiement d'intégration Ada, généralement au format https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/embeddings?api-version=2023-05-15. À utiliser avec le paramètre embeddingKey dans une recherche vectorielle en dehors des réseaux privés et des points de terminaison privés.
embeddingKey string Facultatif null Clé API pour un modèle déploiement d'intégration Ada. À utiliser avec embeddingEndpoint dans une recherche vectorielle en dehors des réseaux privés et des points de terminaison privés.
embeddingDeploymentName string Facultatif null Nom de déploiement du modèle d’incorporation Ada dans la même ressource Azure OpenAI. Utilisé au lieu de embeddingEndpoint et de embeddingKey pour une recherche vectorielle. Doit être utilisé uniquement lorsque les paramètres embeddingEndpoint et embeddingKey sont définis. Quand ce paramètre est fourni, Azure OpenAI sur vos données utilise un appel interne pour évaluer le modèle d’incorporation Ada au lieu d’appeler le point de terminaison Azure OpenAI. Cela vous permet d’utiliser une recherche vectorielle dans des réseaux privés et des points de terminaison privés. La facturation reste la même que ce paramètre soit défini ou non. Disponible dans les régions où les modèles d’incorporation sont disponibles à partir des versions d’API 2023-06-01-preview et ultérieures.
strictness number Facultatif 3 Définit le seuil de catégorisation des documents en fonction de vos requêtes. Augmenter la valeur signifie un seuil de pertinence plus élevé et filtre les documents moins pertinents pour les réponses. Une valeur trop élevée peut entraîner l’échec de la génération de réponses par le modèle en raison d’un nombre limité de documents disponibles.

Paramètres de la Recherche Azure AI

Les paramètres suivants sont utilisés pour la Recherche Azure AI.

Paramètres Type Requis ? Default Description
endpoint string Obligatoire null Recherche Azure AI uniquement. Point de terminaison de la source de données.
key string Obligatoire null Recherche Azure AI uniquement. L’une des clés d’administration Recherche Azure AI pour votre service.
queryType string Facultatif simple Indique l’option de requête qui est utilisée pour le service Recherche Azure AI. Types disponibles : simple, semantic, vector, vectorSimpleHybrid, vectorSemanticHybrid.
fieldsMapping dictionnaire Facultatif pour Recherche Azure AI. null permet de définir les champs que vous souhaitez mapper lors de l’ajout de votre source de données.

Les paramètres suivants sont utilisés à l’intérieur du champ authentication, ce qui vous permet d’utiliser Azure OpenAI sans accès au réseau public.

Paramètres Type Requis ? Default Description
type string Obligatoire null Type d’authentification.
managedIdentityResourceId string Obligatoire null ID de ressource de l’identité managée affectée par l’utilisateur à utiliser pour l’authentification. 
"authentication": {
  "type": "UserAssignedManagedIdentity",
  "managedIdentityResourceId": "/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{resource-name}"
},

Vous utilisez les paramètres suivants à l’intérieur du champ fieldsMapping.

Paramètres Type Requis ? Default Description
titleField string Facultatif null Le champ de votre index qui contient le titre d’origine de chaque document.
urlField string Facultatif null Le champ de votre index qui contient l’URL d’origine de chaque document.
filepathField string Facultatif null Le champ de votre index qui contient le nom du fichier d’origine de chaque document.
contentFields dictionnaire Facultatif null Les champs de votre index qui contiennent le principal contenu du texte de chaque document.
contentFieldsSeparator string Facultatif null Le séparateur pour les champs de contenu. Utilisez \n par défaut. 
"fieldsMapping": {
  "titleField": "myTitleField",
  "urlField": "myUrlField",
  "filepathField": "myFilePathField",
  "contentFields": [
    "myContentField"
  ],
  "contentFieldsSeparator": "\n"
}

Les paramètres suivants sont utilisés à l’intérieur du paramètre facultatif embeddingDependency, qui contient les détails d’une source de vectorisation basée sur un nom de modèle de déploiement d’incorporation interne dans la même ressource Azure OpenAI.

Paramètres Type Requis ? Default Description
deploymentName string Facultatif null Type de source de vectorisation à utiliser.
type string Facultatif null Nom du modèle de déploiement d’incorporation situé dans la même ressource Azure OpenAI. Cela vous permet d’utiliser la recherche vectorielle sans clé API Azure OpenAI et sans accès au réseau public Azure OpenAI. 
"embeddingDependency": {
  "type": "DeploymentName",
  "deploymentName": "{embedding deployment name}"
},

Paramètres du cœur virtuel d'Azure Cosmos DB for MongoDB

Les paramètres suivants sont utilisés pour le vCore d’Azure Cosmos DB for MongoDB.

Paramètres Type Requis ? Default Description
type (trouvé à l’intérieur de authentication) string Obligatoire null Azure Cosmos DB for MongoDB vCore uniquement. Authentification à utiliser. Pour Azure Cosmos Mongo vCore, la valeur est ConnectionString
connectionString string Obligatoire null Azure Cosmos DB for MongoDB vCore uniquement. Chaîne de connexion à utiliser pour authentifier le compte Azure Cosmos Mongo vCore.
databaseName string Obligatoire null Azure Cosmos DB for MongoDB vCore uniquement. Nom de la base de données Azure Cosmos Mongo vCore.
containerName string Obligatoire null Azure Cosmos DB for MongoDB vCore uniquement. Nom du conteneur Azure Cosmos Mongo vCore dans la base de données.
type (trouvé à l’intérieur de embeddingDependencyType) string Obligatoire null Indique la dépendance du modèle d’incorporation.
deploymentName (trouvé à l’intérieur de embeddingDependencyType) string Obligatoire null Nom du déploiement du modèle incorporé.
fieldsMapping dictionnaire Obligatoire pour Azure Cosmos DB for MongoDB vCore. null Mappage de colonnes de données d’index. Lorsque vous utilisez le vCore d’Azure Cosmos DB for MongoDB, la valeur vectorFields, qui indique les champs qui stockent des vecteurs, est nécessaire.

Les paramètres suivants sont utilisés à l’intérieur du paramètre facultatif embeddingDependency, qui contient les détails d’une source de vectorisation basée sur un nom de modèle de déploiement d’incorporation interne dans la même ressource Azure OpenAI.

Paramètres Type Requis ? Default Description
deploymentName string Facultatif null Type de source de vectorisation à utiliser.
type string Facultatif null Nom du modèle de déploiement d’incorporation situé dans la même ressource Azure OpenAI. Cela vous permet d’utiliser la recherche vectorielle sans clé API Azure OpenAI et sans accès au réseau public Azure OpenAI. 
"embeddingDependency": {
  "type": "DeploymentName",
  "deploymentName": "{embedding deployment name}"
},

Paramètres d’Elasticsearch

Les paramètres suivants sont utilisés pour Elasticsearch.

Paramètres Type Requis ? Default Description
endpoint string Obligatoire null Point de terminaison pour la connexion à Elasticsearch.
indexName string Obligatoire null Nom de l’index Elasticsearch.
type (trouvé à l’intérieur de authentication) string Obligatoire null Authentification à utiliser. Pour Elasticsearch, la valeur est KeyAndKeyId.
key (trouvé à l’intérieur de authentication) string Obligatoire null Clé utilisée pour se connecter à Elasticsearch.
keyId (trouvé à l’intérieur de authentication) string Obligatoire null ID de clé à utiliser. Pour Elasticsearch.

Vous utilisez les paramètres suivants à l’intérieur du champ fieldsMapping.

Paramètres Type Requis ? Default Description
titleField string Facultatif null Le champ de votre index qui contient le titre d’origine de chaque document.
urlField string Facultatif null Le champ de votre index qui contient l’URL d’origine de chaque document.
filepathField string Facultatif null Le champ de votre index qui contient le nom du fichier d’origine de chaque document.
contentFields dictionnaire Facultatif null Les champs de votre index qui contiennent le principal contenu du texte de chaque document.
contentFieldsSeparator string Facultatif null Le séparateur pour les champs de contenu. Utilisez \n par défaut.
vectorFields dictionnaire Facultatif null Noms de champs qui représentent des données vectorielles 
"fieldsMapping": {
  "titleField": "myTitleField",
  "urlField": "myUrlField",
  "filepathField": "myFilePathField",
  "contentFields": [
    "myContentField"
  ],
  "contentFieldsSeparator": "\n",
  "vectorFields": [
    "myVectorField"
  ]
}

Les paramètres suivants sont utilisés à l’intérieur du paramètre facultatif embeddingDependency, qui contient les détails d’une source de vectorisation basée sur un nom de modèle de déploiement d’incorporation interne dans la même ressource Azure OpenAI.

Paramètres Type Requis ? Default Description
deploymentName string Facultatif null Type de source de vectorisation à utiliser.
type string Facultatif null Nom du modèle de déploiement d’incorporation situé dans la même ressource Azure OpenAI. Cela vous permet d’utiliser la recherche vectorielle sans clé API Azure OpenAI et sans accès au réseau public Azure OpenAI. 
"embeddingDependency": {
  "type": "DeploymentName",
  "deploymentName": "{embedding deployment name}"
},

Paramètres d’Azure Machine Learning

Les paramètres suivants sont utilisés pour Azure Machine Learning.

Paramètres Type Requis ? Default Description
projectResourceId string Obligatoire null ID de ressource du projet.
name string Obligatoire null Nom du projet Azure Machine Learning.
version (trouvé à l’intérieur de authentication) string Obligatoire null Version de l’index vectoriel Azure Machine Learning.

Les paramètres suivants sont utilisés à l’intérieur du paramètre facultatif embeddingDependency, qui contient les détails d’une source de vectorisation basée sur un nom de modèle de déploiement d’incorporation interne dans la même ressource Azure OpenAI.

Paramètres Type Requis ? Default Description
deploymentName string Facultatif null Type de source de vectorisation à utiliser.
type string Facultatif null Nom du modèle de déploiement d’incorporation situé dans la même ressource Azure OpenAI. Cela vous permet d’utiliser la recherche vectorielle sans clé API Azure OpenAI et sans accès au réseau public Azure OpenAI. 
"embeddingDependency": {
  "type": "DeploymentName",
  "deploymentName": "{embedding deployment name}"
},

Paramètres de Pinecone

Les paramètres suivants sont utilisés pour Pinecone.

Paramètres Type Requis ? Default Description
type (trouvé à l’intérieur de authentication) string Obligatoire null Authentification à utiliser. Pour Pinecone, la valeur est APIKey.
apiKey (trouvé à l’intérieur de authentication) string Obligatoire null Clé API pour Pinecone.
environment string Obligatoire null Nom de l’environnement Pinecone.
indexName string Obligatoire null Nom de l’index Pinecone.
embeddingDependency string Obligatoire null Dépendance d’incorporation pour la recherche vectorielle.
type (trouvé à l’intérieur de embeddingDependency) string Obligatoire null Type de dépendance. Pour Pinecone, la valeur est DeploymentName.
deploymentName (trouvé à l’intérieur de embeddingDependency) string Obligatoire null Le nom du déploiement.
titleField (trouvé à l’intérieur de fieldsMapping) string Obligatoire null Nom du champ d’index à utiliser comme titre.
urlField (trouvé à l’intérieur de fieldsMapping) string Obligatoire null Nom du champ d’index à utiliser comme URL.
filepathField (trouvé à l’intérieur de fieldsMapping) string Obligatoire null Nom du champ d’index à utiliser comme chemin d’accès au fichier.
contentFields (trouvé à l’intérieur de fieldsMapping) string Obligatoire null Nom des champs d’index qui doivent être traités comme du contenu.
vectorFields dictionnaire Facultatif null Noms de champs qui représentent des données vectorielles
contentFieldsSeparator (trouvé à l’intérieur de fieldsMapping) string Obligatoire null Le séparateur pour les champs de votre contenu. Utilisez \n par défaut.

Les paramètres suivants sont utilisés à l’intérieur du paramètre facultatif embeddingDependency, qui contient les détails d’une source de vectorisation basée sur un nom de modèle de déploiement d’incorporation interne dans la même ressource Azure OpenAI.

Paramètres Type Requis ? Default Description
deploymentName string Facultatif null Type de source de vectorisation à utiliser.
type string Facultatif null Nom du modèle de déploiement d’incorporation situé dans la même ressource Azure OpenAI. Cela vous permet d’utiliser la recherche vectorielle sans clé API Azure OpenAI et sans accès au réseau public Azure OpenAI. 
"embeddingDependency": {
  "type": "DeploymentName",
  "deploymentName": "{embedding deployment name}"
},

Démarrer un travail d’ingestion (préversion)

Conseil

Le choix JOB_NAME sera utilisé comme nom d’index. Tenez compte des contraintes pour le nom de l’index.

curl -i -X PUT https://YOUR_RESOURCE_NAME.openai.azure.com/openai/extensions/on-your-data/ingestion-jobs/JOB_NAME?api-version=2023-10-01-preview \ 
-H "Content-Type: application/json" \ 
-H "api-key: YOUR_API_KEY" \ 
-H "searchServiceEndpoint: https://YOUR_AZURE_COGNITIVE_SEARCH_NAME.search.windows.net" \ 
-H "searchServiceAdminKey: YOUR_SEARCH_SERVICE_ADMIN_KEY" \ 
-H  "storageConnectionString: YOUR_STORAGE_CONNECTION_STRING" \ 
-H "storageContainer: YOUR_INPUT_CONTAINER" \ 
-d '{ "dataRefreshIntervalInMinutes": 10 }'

Exemple de réponse

{ 
    "id": "test-1", 
    "dataRefreshIntervalInMinutes": 10, 
    "completionAction": "cleanUpAssets", 
    "status": "running", 
    "warnings": [], 
    "progress": { 
        "stageProgress": [ 
            { 
                "name": "Preprocessing", 
                "totalItems": 100, 
                "processedItems": 100 
            }, 
            { 
                "name": "Indexing", 
                "totalItems": 350, 
                "processedItems": 40 
            } 
        ] 
    } 
}

Paramètres d’en-tête

Paramètres Type Requis ? Default Description
searchServiceEndpoint string Obligatoire null Point de terminaison de la ressource de recherche dans laquelle les données sont ingérées.
searchServiceAdminKey string Facultatif null Si elle est fournie, la clé est utilisée pour s’authentifier auprès de searchServiceEndpoint. Si elle n’est pas fournie, l’identité attribuée par le système de la ressource Azure OpenAI est utilisée. Dans ce cas, l’identité attribuée par le système doit avoir l’attribution de rôle « Contributeur de service de recherche » sur la ressource de recherche.
storageConnectionString string Obligatoire null Chaîne de connexion du compte de stockage dans lequel se trouvent les données d’entrée. Une clé de compte doit être fournie dans la chaîne de connexion. Il ressemble normalement à ceci : DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>
storageContainer string Obligatoire null Nom du conteneur dans lequel se trouvent les données d’entrée.
embeddingEndpoint string Facultatif null Non obligatoire si vous utilisez une recherche sémantique ou uniquement par mot clé. Obligatoire si vous utilisez une recherche vectorielle, hybride ou hybride + sémantique
embeddingKey string Facultatif null Clé du point de terminaison d’incorporation. Obligatoire si le point de terminaison d’incorporation n’est pas vide.
url string Facultatif null Si l’URL n’est pas nul, l’URL fournie est analysée dans le conteneur de stockage fourni, puis ingérée en conséquence.

Paramètres de corps

Paramètres Type Requis ? Default Description
dataRefreshIntervalInMinutes string Requise 0 Intervalle d’actualisation des données en minutes. Pour exécuter un travail d’ingestion unique sans planification, définissez ce paramètre sur 0.
completionAction string Facultatif cleanUpAssets Ce qui doit arriver aux ressources créées pendant le processus d’ingestion à la fin du travail. Les valeurs valides sont cleanUpAssets ou keepAllAssets. keepAllAssets laisse toutes les ressources intermédiaires aux utilisateurs qui souhaitent examiner les résultats intermédiaires, ce qui peut être utile pour le débogage des ressources. cleanUpAssets supprime les ressources après la fin du travail.
chunkSize int Facultatif 1 024 Cette valeur définit le nombre maximal de jetons dans chaque bloc produit par le flux d’ingestion.

Lister les travaux d’ingestion (préversion)

curl -i -X GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/extensions/on-your-data/ingestion-jobs?api-version=2023-10-01-preview \ 
-H "api-key: YOUR_API_KEY"

Exemple de réponse

{ 
    "value": [ 
        { 
            "id": "test-1", 
            "dataRefreshIntervalInMinutes": 10, 
            "completionAction": "cleanUpAssets", 
            "status": "succeeded", 
            "warnings": [] 
        }, 
        { 
            "id": "test-2", 
            "dataRefreshIntervalInMinutes": 10, 
            "completionAction": "cleanUpAssets", 
            "status": "failed", 
            "error": { 
                "code": "BadRequest", 
                "message": "Could not execute skill because the Web Api request failed." 
            }, 
            "warnings": [] 
        } 
    ] 
}

Obtenir l’état d’un travail d’ingestion (préversion)

curl -i -X GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/extensions/on-your-data/ingestion-jobs/YOUR_JOB_NAME?api-version=2023-10-01-preview \ 
-H "api-key: YOUR_API_KEY"

Exemple de corps de réponse

{ 
    "id": "test-1", 
    "dataRefreshIntervalInMinutes": 10, 
    "completionAction": "cleanUpAssets", 
    "status": "succeeded", 
    "warnings": [] 
}

Génération d’images

Demander une image générée (DALL-E 3)

Générez et récupérez un lot d’images à partir d’un texte de légende.

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/images/generations?api-version={api-version}

Paramètres de chemin d’accès

Paramètre Type Requis ? Description
your-resource-name string Obligatoire Nom de votre ressource Azure OpenAI.
deployment-id string Requise Le nom de votre modèle de déploiement DALL-E 3, tel que MyDalle3. Vous devez d’abord déployer un modèle DALL-E 3 avant de pouvoir effectuer des appels.
api-version string Obligatoire Version de l’API à utiliser pour cette opération. Cela suit le format AAAA-MM-JJ.

Versions prises en charge

Corps de la demande

Paramètre Type Requis ? Default Description
prompt string Obligatoire Description textuelle de la ou des images souhaitées. La longueur maximale est de 4 000 caractères.
n entier Facultatif 1 Nombre d’images à générer. Seul n=1 est pris en charge pour DALL-E 3.
size string Facultatif 1024x1024 Taille des images générées. Doit être 1792x1024, 1024x1024 ou 1024x1792.
quality string Facultatif standard La qualité des images générées. Doit être hd ou standard.
response_format string Facultatif url Le format dans lequel les images générées sont retournées doit être url (une URL pointant vers l’image) ou b64_json (le code de base 64 octets au format JSON).
style string Facultatif vivid Le style des images générées. Doit être natural ou vivid (pour les images hyperréalistes/dramatiques).
user string Facultatif Identificateur unique représentant votre utilisateur final, qui peut vous aider à monitorer et à détecter des abus.

Exemple de requête

curl -X POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/images/generations?api-version=2023-12-01-preview \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{
    "prompt": "An avocado chair",
    "size": "1024x1024",
    "n": 1,
    "quality": "hd", 
    "style": "vivid"
  }'

Exemple de réponse

L’opération retourne un code d’état 202 et un objet JSON GenerateImagesResponse contenant l’ID et l’état de l’opération.

{ 
    "created": 1698116662, 
    "data": [ 
        { 
            "url": "url to the image", 
            "revised_prompt": "the actual prompt that was used" 
        }, 
        { 
            "url": "url to the image" 
        },
        ...
    ]
}

Demander une image générée (DALL-E 2 en préversion)

Générez un lot d’images à partir d’un texte légende.

POST https://{your-resource-name}.openai.azure.com/openai/images/generations:submit?api-version={api-version}

Paramètres de chemin d’accès

Paramètre Type Requis ? Description
your-resource-name string Obligatoire Nom de votre ressource Azure OpenAI.
api-version string Obligatoire Version de l’API à utiliser pour cette opération. Cela suit le format AAAA-MM-JJ.

Versions prises en charge

Corps de la demande

Paramètre Type Requis ? Default Description
prompt string Obligatoire Description textuelle de la ou des images souhaitées. La longueur maximale est de 1 000 caractères.
n entier Facultatif 1 Nombre d’images à générer. Doit être compris entre 1 et 5.
size string Facultatif 1024 x 1024 Taille des images générées. Doit être 256x256, 512x512 ou 1024x1024.

Exemple de requête

curl -X POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/images/generations:submit?api-version=2023-06-01-preview \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{
"prompt": "An avocado chair",
"size": "512x512",
"n": 3
}'

Exemple de réponse

L’opération retourne un code d’état 202 et un objet JSON GenerateImagesResponse contenant l’ID et l’état de l’opération.

{
  "id": "f508bcf2-e651-4b4b-85a7-58ad77981ffa",
  "status": "notRunning"
}

Obtenir un résultat d’image généré (DALL-E 2 en préversion)

Utilisez cette API pour récupérer les résultats d’une opération de génération d’image. La génération d’images est actuellement disponible uniquement avec api-version=2023-06-01-preview.

GET https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version={api-version}

Paramètres de chemin d’accès

Paramètre Type Requis ? Description
your-resource-name string Obligatoire Nom de votre ressource Azure OpenAI.
operation-id string Obligatoire GUID qui identifie la demande de génération d’image d’origine.

Versions prises en charge

Exemple de requête

curl -X GET "https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version=2023-06-01-preview"
-H "Content-Type: application/json"
-H "Api-Key: {api key}"

Exemple de réponse

En cas de réussite, l’opération retourne un code d’état 200 et un objet JSON OperationResponse. Le champ status peut être "notRunning" (la tâche est mise en file d’attente mais n’a pas encore démarré), "running", "succeeded", "canceled" (la tâche a expiré), "failed", ou "deleted". Un état succeeded indique que l’image générée est disponible en téléchargement à l’URL donnée. Si plusieurs images ont été générées, leurs URL sont toutes retournées dans le champ result.data.

{
  "created": 1685064331,
  "expires": 1685150737,
  "id": "4b755937-3173-4b49-bf3f-da6702a3971a",
  "result": {
    "data": [
      {
        "url": "<URL_TO_IMAGE>"
      },
      {
        "url": "<URL_TO_NEXT_IMAGE>"
      },
      ...
    ]
  },
  "status": "succeeded"
}

Supprimer une image générée à partir du serveur (DALL-E 2 en préversion)

Vous pouvez utiliser l’ID d’opération retourné par la demande pour supprimer l’image correspondante du serveur Azure. Les images générées sont automatiquement supprimées après 24 heures par défaut, mais vous pouvez déclencher la suppression plus tôt si vous le souhaitez.

DELETE https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version={api-version}

Paramètres de chemin d’accès

Paramètre Type Requis ? Description
your-resource-name string Obligatoire Nom de votre ressource Azure OpenAI.
operation-id string Obligatoire GUID qui identifie la demande de génération d’image d’origine.

Versions prises en charge

Exemple de requête

curl -X DELETE "https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version=2023-06-01-preview"
-H "Content-Type: application/json"
-H "Api-Key: {api key}"

response

L’opération retourne un code d’état 204 si elle réussit. Cette API réussit uniquement si l’opération est dans un état final (et non running).

Reconnaissance vocale

Vous pouvez utiliser un modèle Whisper dans Azure OpenAI Service pour la transcription de reconnaissance vocale ou la traduction vocale. Pour plus d’informations sur l’utilisation d’un modèle Whisper, consultez le Démarrage rapide et la Vue d’ensemble du modèle Whisper.

Demander une transcription de parole en texte

Transcrit un fichier audio.

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/audio/transcriptions?api-version={api-version}

Paramètres de chemin d’accès

Paramètre Type Requis ? Description
your-resource-name string Obligatoire Nom de votre ressource Azure OpenAI.
deployment-id string Requise Nom de votre déploiement de modèle Whisper, par exemple MyWhisperDeployment. Vous devez d’abord déployer un modèle Whisper avant de pouvoir effectuer des appels.
api-version string Obligatoire Version de l’API à utiliser pour cette opération. La valeur suit le format AAAA-MM-JJ.

Versions prises en charge

Corps de la demande

Paramètre Type Requis ? Default Description
file fichier Oui S/O Objet de fichier audio (et non nom de fichier) à transcrire, dans l’un des formats suivants : flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav ou webm.

Dans Azure OpenAI Service, la limite de taille de fichier pour un modèle Whisper est de 25 Mo. Si vous devez transcrire un fichier de plus de 25 Mo, divisez-le en blocs. Vous pouvez également utiliser l’API de transcription par lots d’Azure AI Speech.

Vous pouvez obtenir des exemples de fichiers audio à partir du référentiel du SDK Azure AI Speech sur GitHub.
language string Non Null La langue de l’audio d’entrée, par exemple fr. Donner la langue d’entrée au format ISO-639-1 améliore la précision et la latence.

Pour obtenir la liste des langues prises en charge, consultez la documentation OpenAI.
prompt string Non Null Un texte facultatif pour guider le style du modèle ou continuer un segment audio précédent. L’invite doit correspondre à la langue audio.

Pour plus d’informations sur les invites, notamment des exemples de cas d’usage, consultez la documentation OpenAI.
response_format string Non json Format de la sortie de transcription, dans l’une des options suivantes : json, text, srt, verbose_json ou vtt.

La valeur par défaut est json.
temperature nombre Non 0 Température d’échantillonnage comprise entre 0 et 1.

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. Si la valeur est 0, le modèle utilise la probabilité logarithmique pour augmenter automatiquement la température jusqu’à ce que certains seuils soient atteints.

La valeur par défaut est 0.

Exemple de requête

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/audio/transcriptions?api-version=2023-09-01-preview \
  -H "Content-Type: multipart/form-data" \
  -H "api-key: $YOUR_API_KEY" \
  -F file="@./YOUR_AUDIO_FILE_NAME.wav" \
  -F "language=en" \
  -F "prompt=The transcript contains zoology terms and geographical locations." \
  -F "temperature=0" \
  -F "response_format=srt"

Exemple de réponse

1
00:00:00,960 --> 00:00:07,680
The ocelot, Lepardus paradalis, is a small wild cat native to the southwestern United States,

2
00:00:07,680 --> 00:00:13,520
Mexico, and Central and South America. This medium-sized cat is characterized by

3
00:00:13,520 --> 00:00:18,960
solid black spots and streaks on its coat, round ears, and white neck and undersides.

4
00:00:19,760 --> 00:00:27,840
It weighs between 8 and 15.5 kilograms, 18 and 34 pounds, and reaches 40 to 50 centimeters

5
00:00:27,840 --> 00:00:34,560
16 to 20 inches at the shoulders. It was first described by Carl Linnaeus in 1758.

6
00:00:35,360 --> 00:00:42,880
Two subspecies are recognized, L. p. paradalis and L. p. mitis. Typically active during twilight

7
00:00:42,880 --> 00:00:48,480
and at night, the ocelot tends to be solitary and territorial. It is efficient at climbing,

8
00:00:48,480 --> 00:00:54,480
leaping, and swimming. It preys on small terrestrial mammals such as armadillo, opossum,

9
00:00:54,480 --> 00:00:56,480
and lagomorphs.

Demander une traduction par reconnaissance vocale

Traduit un fichier audio d’une autre langue vers l’anglais. Pour obtenir la liste des langues prises en charge, consultez la documentation OpenAI.

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/audio/translations?api-version={api-version}

Paramètres de chemin d’accès

Paramètre Type Requis ? Description
your-resource-name string Obligatoire Nom de votre ressource Azure OpenAI.
deployment-id string Requise Nom de votre déploiement de modèle Whisper, par exemple MyWhisperDeployment. Vous devez d’abord déployer un modèle Whisper avant de pouvoir effectuer des appels.
api-version string Obligatoire Version de l’API à utiliser pour cette opération. La valeur suit le format AAAA-MM-JJ.

Versions prises en charge

Corps de la demande

Paramètre Type Requis ? Default Description
file fichier Oui N/A Objet de fichier audio (et non un nom de fichier) à transcrire, dans l’un des formats suivants : flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav ou webm.

La taille limite de fichier pour le modèle Whisper d’Azure OpenAI est de 25 Mo. Si vous devez transcrire un fichier de plus de 25 Mo, divisez-le en blocs.

Vous pouvez télécharger des exemples de fichiers audio à partir du référentiel du SDK Azure AI Speech sur GitHub.
prompt string Non Null Un texte facultatif pour guider le style du modèle ou continuer un segment audio précédent. L’invite doit correspondre à la langue audio.

Pour plus d’informations sur les invites, notamment des exemples de cas d’usage, consultez la documentation OpenAI.
response_format string Non json Format de la sortie de transcription, dans l’une des options suivantes : json, text, srt, verbose_json ou vtt.

La valeur par défaut est json.
temperature nombre Non 0 Température d’échantillonnage comprise entre 0 et 1.

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. Si la valeur est 0, le modèle utilise la probabilité logarithmique pour augmenter automatiquement la température jusqu’à ce que certains seuils soient atteints.

La valeur par défaut est 0.

Exemple de requête

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/audio/translations?api-version=2023-09-01-preview \
  -H "Content-Type: multipart/form-data" \
  -H "api-key: $YOUR_API_KEY" \
  -F file="@./YOUR_AUDIO_FILE_NAME.wav" \
  -F "temperature=0" \
  -F "response_format=json"

Exemple de réponse

{
  "text": "Hello, my name is Wolfgang and I come from Germany. Where are you heading today?"
}

Synthèse vocale

Synthétiser la conversion de texte par synthèse vocale.

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/audio/speech?api-version={api-version}

Paramètres de chemin d’accès

Paramètre Type Requis ? Description
your-resource-name string Obligatoire Nom de votre ressource Azure OpenAI.
deployment-id string Requis Nom de votre modèle de déploiement de synthèse vocale, tel que MyTextToSpeechDeployment. Vous devez d’abord déployer un modèle de synthèse vocale (par exemple tts-1 ou tts-1-hd) avant de pouvoir effectuer des appels.
api-version string Obligatoire Version de l’API à utiliser pour cette opération. La valeur suit le format AAAA-MM-JJ.

Versions prises en charge

Corps de la demande

Paramètre Type Requis ? Default Description
model string Oui S/O Un des modèles TTS disponibles : tts-1 ou tts-1-hd
input string Oui S/O Texte pour lequel générer l’audio. La longueur maximale est de 4096 caractères. Spécifiez le texte d’entrée dans la langue de votre choix.1
voice string Oui S/O Voix à utiliser lors de la génération de l’audio. Les voix prises en charge sont alloy, echo, fable, onyx, nova et shimmer. Les aperçus des voix sont disponibles dans le guide de synthèse vocale OpenAI.

1 Les modèles de synthèse vocale prennent généralement en charge les mêmes langues que le modèle Whisper. Pour obtenir la liste des langues prises en charge, consultez la documentation OpenAI.

Exemple de requête

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/audio/speech?api-version=2024-02-15-preview \
 -H "api-key: $YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "model": "tts-hd",
    "input": "I'm excited to try text to speech.",
    "voice": "alloy"
}' --output speech.mp3

Exemple de réponse

La reconnaissance vocale est retournée en tant que fichier audio de la requête précédente.

API de gestion

Le déploiement d’Azure OpenAI s’effectue dans le cadre d’Azure AI services. Tous les services Azure AI s’appuient sur le même ensemble d’API de gestion pour les opérations de création, de mise à jour et de suppression. Les API de gestion sont également utilisées pour déployer des modèles dans une ressource Azure OpenAI.

Documentation de référence sur les API de gestion

Étapes suivantes

En savoir plus sur les modèles et l’optimisation avec l’API REST. Découvrez-en plus sur les modèles sous-jacents d’Azure OpenAI.