Utiliser l'API Azure OpenAI pour les réponses

Utilisez l’API Azure OpenAI Responses pour générer des réponses multi-tours avec état. Il réunit les fonctionnalités des achèvements de conversation et de l’API Assistants dans une expérience unifiée. Utilisez l’orchestration multi-agent pour déléguer un travail indépendant à des sous-agents parallèles ou utilisez la recherche d’outils pour charger des définitions d’outils uniquement lorsque le modèle en a besoin. L’API Réponses prend également en charge le computer-use-preview modèle qui alimente l’utilisation de l’ordinateur.

Pour obtenir des descriptions complètes des paramètres de requête et de réponse, consultez la référence des paramètres de l’API Réponses.

Conditions préalables

  • Modèle OpenAI déployé Azure.
  • Méthode d’authentification :
    • Clé API (par exemple, AZURE_OPENAI_API_KEY) ou
    • Microsoft Entra ID (recommandé).
  • Installez la bibliothèque cliente pour votre langue :
    • Python : pip install openai azure-identity
    • .NET : dotnet add package OpenAI et dotnet add package Azure.Identity
    • JavaScript/TypeScript : npm install openai @azure/identity
    • Java : ajoutez com.openai:openai-java et com.azure:azure-identity à votre projet.
  • Pour obtenir des exemples REST, définissez AZURE_OPENAI_API_KEY (flux de clé API) ou AZURE_OPENAI_AUTH_TOKEN (flux Microsoft Entra ID).

Régions prises en charge

Avant d’exécuter les exemples de cet article, vérifiez que votre région de ressources prend en charge l’API Réponses. L’API v1 est requise pour accéder aux dernières fonctionnalités. Pour plus d’informations, consultez le cycle de vie de la version de l’API. Pour connaître la disponibilité régionale du service Foundry Agent, consultez le tableau de disponibilité régionale. L’API Réponses est actuellement disponible dans les régions suivantes :

  • australiaeast
  • brésilsud
  • canadacentral
  • canadaeast
  • centralus
  • eastus
  • eastus2
  • francecentral
  • allemagnewestcentral
  • italynorth
  • japaneast
  • japanwest
  • koreacentral
  • northcentralus
  • Norvège-Est
  • polandcentral
  • southafricanorth
  • southcentralus
  • sud-estasia
  • sud de l'Inde
  • spaincentral
  • swedencentral
  • suisse-nord
  • switzerlandwest
  • uaenorth
  • uksouth
  • ukwest
  • westcentralus
  • westeurope
  • westus
  • westus2
  • westus3

Modèles pris en charge

L’API Réponses prend en charge les modèles suivants :

  • gpt-6.1-terra (Version : 2026-10-26)
  • gpt-6.1-sol (Version : 2026-09-29)
  • gpt-6-luna (Version : 2026-09-22)
  • gpt-6-sol (Version : 2026-09-22)
  • gpt-6-astra (Version : 2026-09-03)
  • gpt-5.6-sol (Version : 2026-07-09)
  • gpt-5.6-terra (Version : 2026-07-09)
  • gpt-5.6-luna (Version : 2026-07-09)
  • gpt-chat-latest (Versions : 2026-10-07, 2026-06-24, 2026-08-06, 2026-05-28, 2026-05-05)
  • gpt-5.5 (Version : 2026-04-24)
  • gpt-5.4-nano (Version : 2026-03-17)
  • gpt-5.4-mini (Version : 2026-03-17)
  • gpt-5.4-pro (Version :2026-03-05)
  • gpt-5.4 (Version :2026-03-05)
  • gpt-5.3-chat (Version : 2026-03-03)
  • gpt-5.3-codex (Version : 2026-02-24)
  • gpt-5.2-codex (Version : 2026-01-14)
  • gpt-5.2 (Version : 2025-12-11)
  • gpt-5.2-chat (Version : 2025-12-11)
  • gpt-5.2-chat (Version : 2026-02-10)
  • gpt-5.1-codex-max (Version : 2025-12-04)
  • gpt-5.1 (Version : 2025-11-13)
  • gpt-5.1-chat (Version : 2025-11-13)
  • gpt-5.1-codex (Version : 2025-11-13)
  • gpt-5.1-codex-mini (Version : 2025-11-13)
  • gpt-5-pro (Version : 2025-10-06)
  • gpt-5-codex (Version : 2025-09-11)
  • gpt-5 (Version : 2025-08-07)
  • gpt-5-mini (Version : 2025-08-07)
  • gpt-5-nano (Version : 2025-08-07)
  • gpt-5-chat (Version : 2025-08-07)
  • gpt-5-chat (Version : 2025-10-03)
  • gpt-5-codex (Version : 2025-09-15)
  • gpt-4o (Versions : 2024-11-20, 2024-08-06, 2024-05-13)
  • gpt-4o-mini (Version : 2024-07-18)
  • computer-use-preview
  • gpt-4.1 (Version : 2025-04-14)
  • gpt-4.1-nano (Version : 2025-04-14)
  • gpt-4.1-mini (Version : 2025-04-14)
  • gpt-image-1 (Version : 2025-04-15)
  • gpt-image-1-mini (Version : 2025-10-06)
  • gpt-image-1.5 (Version : 2025-12-16)
  • gpt-image-2.5-flare (Version : 2026-09-09)
  • gpt-image-2.5-sunburst (Version : 2026-09-09)
  • o1 (Version : 2024-12-17)
  • o3-mini (Version : 2025-01-31)
  • o3 (Version : 2025-04-16)
  • o4-mini (Version : 2025-04-16)

Tous les modèles ne sont pas disponibles dans chaque région prise en charge. Consultez la page modèles pour la disponibilité de la région de modèle.

Note

Non pris en charge actuellement :

  • Génération d’images à l’aide de modifications itératives et de diffusion en continu.

Voici un problème connu :

  • Le fichier PDF en tant que fichier d’entrée est désormais pris en charge, mais la définition de l’objectif user_data de chargement de fichier n’est pas prise en charge actuellement.
  • Problèmes de performances lorsque le mode en arrière-plan est utilisé avec la diffusion en continu. Microsoft travaille à résoudre ce problème.

Générer une réponse de texte

Générez une réponse de texte simple à l’aide de l’API Réponses. Remplacez YOUR-RESOURCE-NAME et MODEL_NAME par vos valeurs de déploiement.

import os
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

# API key authentication
client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)
response = client.responses.create(
    model="MODEL_NAME",
    input="This is a test."
)
print(response.model_dump_json(indent=2))

# Microsoft Entra ID authentication (recommended)
token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)
client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=token_provider(),
)
response = client.responses.create(
    model="MODEL_NAME",
    input="This is a test."
)
print(response.model_dump_json(indent=2))

Exemple de réponse

{
  "id": "resp_67cb32528d6881909eb2859a55e18a85",
  "created_at": 1741369938.0,
  "output_text": "Great! How can I help you today?",
  ...
}

Récupérer une réponse

Récupérez une réponse par son ID à partir d’un appel d’API Réponses précédent.

import os
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

# API key authentication
client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)
response = client.responses.retrieve("<response_id>")
print(response.model_dump_json(indent=2))

# Microsoft Entra ID authentication
token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)
client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=token_provider,
)
response = client.responses.retrieve("<response_id>")
print(response.model_dump_json(indent=2))

Exemple de réponse

{
  "id": "resp_67cb61fa3a448190bcf2c42d96f0d1a8",
  "output_text": "Hello! How can I assist you today?",
  ...
}

Supprimer une réponse

Par défaut, les données de réponse sont conservées pendant 30 jours. Supprimez une réponse stockée par ID.

import os
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

# API key authentication
client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)
response = client.responses.delete("<response_id>")
print(response)

# Microsoft Entra ID authentication
token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)
client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=token_provider,
)
response = client.responses.delete("<response_id>")
print(response)

Chaînage des réponses

Enchaînez les tours en transmettant l’identifiant de la réponse précédente à previous_response_id.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

first_response = client.responses.create(
    model="MODEL_NAME",
    input="Define catastrophic forgetting."
)

second_response = client.responses.create(
    model="MODEL_NAME",
    previous_response_id=first_response.id,
    input="Explain it for a college freshman."
)

print(second_response.output_text)

Chaîner manuellement les réponses

Vous pouvez également transférer manuellement les éléments de sortie dans la requête suivante.

import os
from openai import OpenAI

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")  
)

inputs = [{"type": "message", "role": "user", "content": "Define and explain the concept of catastrophic forgetting?"}] 
  
response = client.responses.create(  
    model="gpt-4o",  # replace with your model deployment name  
    input=inputs  
)  
  
inputs += response.output

inputs.append({"role": "user", "type": "message", "content": "Explain this at a level that could be understood by a college freshman"}) 
               

second_response = client.responses.create(
  model="MODEL_NAME",
    input=inputs
)

print(second_response.model_dump_json(indent=2))

Compacter une réponse

Le compactage réduit le contexte d’entrée tout en préservant l’état essentiel pour les tours ultérieurs.

import os
from openai import OpenAI

client = OpenAI(
  base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

compacted = client.responses.compact(
  model="MODEL_NAME",
  input=[
    {"role": "user", "content": "Create a simple landing page for a dog cafe."},
    {
      "id": "msg_001",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [{"type": "output_text", "text": "..."}],
    },
  ]
)

follow_up = client.responses.create(
  model="MODEL_NAME",
  input=[*compacted.output, {"role": "user", "content": "Add a booking form."}]
)
print(follow_up.output_text)

Compacter à l’aide d’éléments retournés

Vous pouvez compacter tous les éléments retournés par les requêtes précédentes, comme le raisonnement, le message, l’appel de fonction, etc.

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses/compact \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
        "model": "MODEL_NAME",
        "input": [
          {
            "role"   : "user",
            "content": "Create a simple landing page for a dog petting café."
          },
          {
            "id": "msg_001",
            "type": "message",
            "status": "completed",
            "content": [
              {
                "type": "output_text",
                "annotations": [],
                "logprobs": [],
                "text": "Below is a single file, ready-to-use landing page for a dog petting café:..."
              }
            ],
            "role": "assistant"
          }
        ]
    }'

# Use the compacted output as input for the next turn.
next_response = client.responses.create(
  model="MODEL_NAME",
  input=[*compacted.output, {"role": "user", "content": "Add opening hours."}],
)
print(next_response.output_text)

Compresser en utilisant l'ID de réponse précédent

Vous pouvez également compresser en utilisant un ID de réponse précédent.

initial_response = client.responses.create(
  model="MODEL_NAME",
  input="What is the size of France?"
)

compacted_response = client.responses.compact(
  model="MODEL_NAME",
  previous_response_id=initial_response.id
)

follow_up_response = client.responses.create(
  model="MODEL_NAME",
  input=[
    *compacted_response.output,
    {"role": "user", "content": "What is the capital?"}
  ]
)
print(follow_up_response.output_text)

Compactage côté serveur

Vous pouvez également utiliser le compactage côté serveur directement dans Les réponses (POST /responses ou client.responses.create) en définissant context_management avec un compact_threshold.

  • Lorsque le nombre de jetons de sortie dépasse le seuil configuré, l’API Réponses exécute automatiquement la compaction.
  • Dans ce mode, vous n’avez pas besoin d’appeler /responses/compact séparément.
  • La réponse inclut un élément de compactage chiffré.
  • Le compactage côté serveur fonctionne lorsque vous définissez store=false sur vos requêtes de création de réponses.

L’élément de compactage transporte l’état antérieur essentiel et la logique dans le prochain tour en utilisant moins de jetons. Il est opaque et n’est pas destiné à être lisible par l’homme.

Si vous utilisez un chaînage sans état avec un tableau d’entrée, ajoutez les éléments de sortie comme d’habitude. Si vous utilisez previous_response_id, transmettez uniquement le nouveau message utilisateur à chaque tour. Dans les deux modèles, l’élément de compactage porte le contexte nécessaire pour la fenêtre suivante.

Conseil

Après avoir ajouté des éléments de sortie aux éléments d’entrée précédents, vous pouvez supprimer les éléments qui sont arrivés avant le plus récent élément de compactage pour maintenir les requêtes plus petites et réduire la latence de fond de file. Le dernier élément compressé contient le contexte nécessaire pour poursuivre la conversation. Si vous utilisez previous_response_id l'enchaînement, ne supprimez pas manuellement.

Flux

  1. Appelez responses comme d’habitude. Ajoutez context_management avec compact_threshold pour activer le compactage côté serveur.
  2. Si la sortie dépasse le seuil, le service déclenche un compactage, émet un élément de compactage dans le flux de sortie et supprime le contexte avant de poursuivre l’inférence.
  3. Poursuivez la conversation à l’aide de l’un de ces modèles :
    1. Chaînage sans état du tableau d’entrée : ajoutez des éléments de sortie, y compris des éléments de compactage, au tableau d’entrée suivant.
    2. previous_response_id chaînage : transmettez uniquement le nouveau message utilisateur à chaque tour et transférez l’ID de réponse le plus récent.

Exemple

conversation = [
  {
    "type": "message",
    "role": "user",
    "content": "Let's begin a long coding task.",
  }
]

while keep_going:
  response = client.responses.create(
    model="MODEL_NAME",
    input=conversation,
    store=False,
    context_management=[{"type": "compaction", "compact_threshold": 200000}],
  )

  conversation.append(
    {
      "type": "message",
       "role": "user",
      "content": get_next_user_input(),
    }
  )

Diffusion en continu

Diffusez en continu la réponse au fur et à mesure qu’elle est générée en définissant stream=true. Le service émet des événements incrémentaux que vous pouvez consommer pour afficher la sortie jeton par jeton.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

stream = client.responses.create(
    model="MODEL_NAME",
    input="Summarize Azure OpenAI Responses API in one sentence.",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="")

Pendant la diffusion en continu, si une erreur se produit au milieu du flux, le système tente de relancer les tentatives internes pour résoudre l’erreur. Si la requête échoue toujours, le service rencontre une erreur irrécupérable. Dans ce cas, le code de réponse HTTP est 200 (réussite), mais l’événement d’erreur dans le flux inclut des détails sur les erreurs intermédiaires.

Le serveur retourne les types d’erreurs suivants :

Type d’erreur Peut être traduit en tant que
server_error Code de retour 500
too_many_requests Code de retour 429
forbidden Code de retour 403
user_error Code de retour 400

Exemple d’événement d’erreur :

{
  "type": "error",
  "error": {
    "type": "too_many_requests",
    "code": "no_capacity",
    "headers": {
      "skip-error-remapping": "true"
    },
    "message": "The system is currently experiencing high demand and cannot process your request. Your request exceeds the maximum usage size allowed during peak load. For improved capacity reliability, consider switching to Provisioned Throughput.",
    "param": null
  }
}

Les applications doivent détecter ces erreurs et arrêter ou redémarrer correctement la diffusion en continu. Vous n’êtes pas facturé pour les jetons générés pendant les réponses de streaming qui ont échoué.

Sorties structurées

Utilisez des sorties structurées pour effectuer une réponse en suivant un schéma JSON. Dans une demande d’API Réponses, définissez le schéma dans text.format. Chat Completions utilise response_format à la place. Pour obtenir des exemples SDK et REST, des contraintes de schéma prises en charge et des limitations, consultez les sorties structurées.

Appel de fonction

L’API Responses prend en charge les appels de fonction.

import os
import json
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

response = client.responses.create(
    model="MODEL_NAME",
    tools=[
        {
            "type": "function",
            "name": "get_weather",
            "description": "Get weather for a location",
            "parameters": {
                "type": "object",
                "properties": {"location": {"type": "string"}},
                "required": ["location"],
            },
        }
    ],
    input="What is the weather in San Francisco?",
)

tool_outputs = []
for item in response.output:
    if item.type == "function_call" and item.name == "get_weather":
        args = json.loads(item.arguments)
        weather = {"location": args["location"], "temperature": "70 F"}
        tool_outputs.append(
            {
                "type": "function_call_output",
                "call_id": item.call_id,
                "output": json.dumps(weather),
            }
        )

final_response = client.responses.create(
    model="MODEL_NAME",
    previous_response_id=response.id,
    input=tool_outputs,
)

print(final_response.output_text)

Gérer les garde-fous et le filtrage de contenu

Appliquez des garde-fous (filtres de contenu) au niveau du déploiement. Chaque contrôle configuré évalue le contenu et les points d’intervention qu’il prend en charge : les filtres core-harm évaluent l’entrée et la sortie, la détection des attaques par prompt utilisateur évalue l’entrée utilisateur et la détection des attaques de document évalue le contenu du document lorsqu’elle est activée. Configurez les garde-fous séparément. Pour plus d’informations, consultez Configurer les garde-fous et les contrôles. Cette section montre comment détecter et gérer les résultats de garde-fou lorsque vous appelez l’API Réponses.

L’API Réponses fait apparaître des résultats de garde-fou différemment des achèvements de conversation. Au lieu des champs prompt_filter_results et content_filter_results que renvoient les complétions de chat, l’objet de réponse inclut un tableau content_filters de premier niveau. Chaque entrée décrit un résultat de filtre.

Champ Description
blocked Indique si le contenu a été bloqué.
source_type Indique si le résultat s’applique à l' prompt (entrée) ou à la completion (sortie).
content_filter_results Les résultats de catégorie, tels que hate, , sexualviolenceet self_harm avec des niveaux de gravité, ainsi que des catégories facultatives telles que jailbreak, indirect_attack, protected_material_text, et protected_material_code.
content_filter_offsets Décalages de caractères auxquels le résultat s’applique.

Note

Le content_filters tableau est une extension Microsoft Foundry qui ne fait pas partie du schéma de réponse OpenAI de base, de sorte que les kits SDK n'exposent pas de propriété typée pour celle-ci. Lisez-le en tant que champ brut ou supplémentaire, comme illustré dans les exemples suivants.

Détecter les entrées bloquées

Lorsque les garde-fous bloquent votre entrée, l’API retourne une erreur HTTP 400 avec le code content_filter. Interceptez cette erreur pour gérer correctement les requêtes bloquées.

import os
from openai import OpenAI, BadRequestError

client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)

# A blocked prompt raises BadRequestError with the code "content_filter"
try:
    response = client.responses.create(
        model="MODEL_NAME",
        input="This is a test."
    )
    print(response.output_text)
except BadRequestError as error:
    if error.code == "content_filter":
        print("The prompt was blocked by a guardrail.")
    else:
        raise

Lire les annotations de garde-fou

Lorsqu’une requête aboutit, lisez le tableau content_filters dans la réponse pour examiner les résultats du garde-fou appliqués à l’entrée et à la sortie.

En mode annotation, les contrôles configurés peuvent signaler la gravité ou les résultats de détection sans les appliquer. Les valeurs blocked et filtered correspondantes restent false. Le mode d’annotation pour les quatre catégories principales de préjudices nécessite l’approbation des Guardrails modifiés.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)
response = client.responses.create(
    model="MODEL_NAME",
    input="This is a test."
)

# content_filters is an Azure extension, so read it from model_extra
content_filters = response.model_extra.get("content_filters", [])
for result in content_filters:
    print(f"Source: {result['source_type']}, Blocked: {result['blocked']}")

Pour en savoir plus sur les catégories de garde-fous et les niveaux de gravité, consultez la vue d’ensemble des garde-fous et l’utilisation des annotations.

Interpréteur de code

L’outil Interpréteur de code permet aux modèles d’écrire et d’exécuter du code Python dans un environnement sécurisé et en bac à sable. Il prend en charge une gamme de tâches avancées, notamment :

  • Traitement de fichiers avec des formats et structures de données variés
  • Génération de fichiers incluant des données et des visualisations (par exemple, des graphiques)
  • Écriture itérative et exécution de code pour résoudre les problèmes : les modèles peuvent déboguer et réessayer du code jusqu’à ce qu’ils réussissent
  • Amélioration du raisonnement visuel dans les modèles pris en charge (par exemple, o3, o4-mini) en activant des transformations d’image telles que rognage, zoom et rotation
  • Cet outil est particulièrement utile pour les scénarios impliquant l’analyse des données, le calcul mathématique et la génération de code.
curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -d '{
        "model": "MODEL_NAME",
        "tools": [
            { "type": "code_interpreter", "container": {"type": "auto"} }
        ],
        "instructions": "You are a personal math tutor. When asked a math question, write and run code using the python tool to answer the question.",
        "input": "I need to solve the equation 3x + 11 = 14. Can you help me?"
    }'

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

response = client.responses.create(
    model="MODEL_NAME",
    tools=[{"type": "code_interpreter", "container": {"type": "auto"}}],
    instructions="You are a math tutor. Write and run Python code to solve math problems.",
    input="Solve 3x + 11 = 14."
)

print(response.output_text)

Conteneurs

Important

L’interpréteur de code a des frais supplémentaires au-delà des frais basés sur les jetons pour l’utilisation d’Azure OpenAI. Si votre API Réponses appelle l’interpréteur de code simultanément dans deux threads différents, deux sessions d’interpréteur de code sont créées. Chaque session entraîne des frais par minute, avec un minimum de cinq minutes. Une session reste active tant que vous accédez à son conteneur dans le délai d’inactivité de 20 minutes.

L’outil Interpréteur de code nécessite un conteneur : une machine virtuelle entièrement sandboxée où le modèle peut exécuter du code Python. Les conteneurs peuvent inclure des fichiers chargés ou des fichiers générés pendant l’exécution.

Pour créer un conteneur, spécifiez "container": { "type": "auto", "file_ids": ["file-1", "file-2"] } dans la configuration de l’outil lors de la création d’un objet Response. Cela crée automatiquement un conteneur ou réutilise un conteneur actif à partir d’un code_interpreter_call précédent dans le contexte du modèle. La sortie code_interpreter_call de l’API contiendra le container_id qui a été généré. Ce conteneur expire s’il n’est pas utilisé pendant 20 minutes.

Les limites de fichier suivantes s’appliquent :

  • Une demande peut inclure jusqu’à 50 ID de fichier.
  • Un conteneur peut contenir jusqu’à 1 000 fichiers au total, y compris les fichiers d’entrée et les fichiers générés par l’interpréteur de code.

Entrées et sorties de fichier

Lors de l’exécution de l’interpréteur de code, le modèle peut créer ses propres fichiers. Par exemple, si vous lui demandez de construire un tracé ou de créer un fichier CSV, il crée ces images directement sur votre conteneur. Il cite ces fichiers dans les annotations de son message suivant.

Tous les fichiers de l’entrée du modèle sont automatiquement chargés dans le conteneur. Vous n’avez pas besoin de le charger explicitement dans le conteneur.

Fichiers pris en charge

Format de fichier Type MIME
.c text/x-c
.cs text/x-csharp
.cpp text/x-c++
.csv text/csv
.doc application/msword
.docx application/vnd.openxmlformats-officedocument.wordprocessingml.document
.html text/html
.java text/x-java
.json application/json
.md text/markdown
.pdf application/pdf
.php text/x-php
.pptx application/vnd.openxmlformats-officedocument.presentationml.presentation
.py text/x-python
.py text/x-script.python
.rb text/x-ruby
.tex text/x-tex
.txt texte brut
.css text/css
.js text/JavaScript
.sh application/x-sh
.ts application/TypeScript
.csv application/csv
.jpeg image/jpeg
.jpg image/jpeg
.gif image/gif
.pkl application/octet-stream
.png image/png
.tar application/x-tar
.xlsx application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
.xml application/xml ou « text/xml »
.zip application/zip

Répertorier les éléments d’entrée

Récupérez les éléments d’entrée envoyés dans une réponse. Ceci est utile pour examiner l’intégralité du contexte de la conversation, y compris les éléments ajoutés par le modèle (par exemple, les appels de fonction ou les éléments de compaction).

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

items = client.responses.input_items.list("<response_id>")
print(items.model_dump_json(indent=2))

Exemple de réponse

{
  "object": "list",
  "data": [
    {
      "id": "msg_...",
      "type": "message",
      "role": "user",
      "content": [{"type": "input_text", "text": "This is a test."}]
    }
  ]
}

Entrée d’image

Les modèles compatibles vision peuvent interpréter des images en même temps que du texte. Ils peuvent reconnaître des objets, des formes, des couleurs et des textures, et lire du texte contenu dans une image, sous réserve des limitations répertoriées plus loin dans cet article.

Vous pouvez fournir une image en tant qu’entrée à une requête de l’une des manières suivantes :

  • Une URL complète vers un fichier image
  • URI de données encodé en Base64
  • ID de fichier créé avec l’API Files

URL de l’image

Référencez une image hébergée à l’URL publique. Le modèle extrait l’image et l’inclut dans le cadre du contenu d’entrée.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

response = client.responses.create(
    model="MODEL_NAME",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "What is in this image?"},
                {"type": "input_image", "image_url": "<image_url>"}
            ]
        }
    ]
)

print(response.output_text)

Image encodée en base64

Envoyez une image inline en encodant ses octets sous la forme d’un URI de données base64. Utilisez ce modèle lorsque l’image n’est pas hébergée à une URL publique ou si vous souhaitez éviter une extraction de réseau supplémentaire.

import base64
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

with open("path_to_your_image.jpg", "rb") as image_file:
    base64_image = base64.b64encode(image_file.read()).decode("utf-8")

response = client.responses.create(
    model="MODEL_NAME",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "What is in this image?"},
                {"type": "input_image", "image_url": f"data:image/jpeg;base64,{base64_image}"}
            ]
        }
    ]
)

print(response.output_text)

ID de fichier

Chargez une image avec l’API Files à l’aide purpose="assistants"de , puis référencez l’ID de fichier retourné dans votre requête. Cette approche est utile lorsque vous souhaitez réutiliser la même image sur plusieurs requêtes sans renvoyer ses octets.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

def create_file(file_path):
    with open(file_path, "rb") as file_content:
        result = client.files.create(
            file=file_content,
            purpose="assistants",
        )
        return result.id

file_id = create_file("path_to_your_image.jpg")

response = client.responses.create(
    model="MODEL_NAME",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "What is in this image?"},
                {"type": "input_image", "file_id": file_id},
            ],
        }
    ],
)

print(response.output_text)

Exigences d’entrée d’image

Le tableau suivant répertorie les types de fichiers pris en charge pour les entrées d’image.

Type de fichier Type MIME
PNG image/png
JPEG image/jpeg
WebP image/webp
GIF non animé image/gif

Dans une seule requête, vous pouvez inclure jusqu’à 50 images. Chaque fichier image individuel doit être inférieur à 512 Mo, et la taille combinée de l’invite, y compris toutes les images de la demande, doit également être inférieure à 512 Mo.

Les images doivent répondre à ces exigences supplémentaires :

  • L’image doit être pertinente pour l’invite ; le modèle n’est pas conçu pour le contenu visuel non lié.
  • Les images ne doivent pas contenir de contenu dangereux ou sensible qui enfreint les stratégies de contenu.
  • Les fichiers image ne peuvent pas être endommagés ou illisibles. Si le modèle ne peut pas traiter une image, la requête échoue.

Choisir un niveau de détail d’image

Utilisez la detail propriété sur une input_image partie de contenu pour contrôler la façon dont le modèle traite l’image. Un niveau de détail inférieur utilise moins de tokens et est plus rapide, tandis qu’un niveau de détail plus élevé utilise davantage de tokens, mais permet au modèle de capturer des caractéristiques plus fines.

{
  "type": "input_image",
  "image_url": "<image_url>",
  "detail": "high"
}

Le tableau suivant décrit chaque niveau de détail.

Niveau de détail Description
low Le modèle utilise une version de résolution inférieure de l’image. Cette option utilise le moins de tokens et produit la réponse la plus rapide, mais le modèle risque de passer à côté de détails subtils.
high Le modèle utilise une version plus haute résolution de l’image. Cette option capture des détails plus fins, mais utilise plus de jetons et prend plus de temps pour répondre.
auto Valeur par défaut. Le modèle sélectionne le niveau de détail approprié en fonction de l’image et de l’invite.

Limitations de l’entrée d’image

Les modèles compatibles vision ont les limitations suivantes :

  • Images médicales : le modèle n’est pas adapté à l’interprétation d’images médicales spécialisées telles que les scanners CT et ne doit pas être utilisé pour les conseils médicaux.
  • Texte non anglais : le modèle peut ne pas fonctionner de manière optimale lors de la gestion des images qui contiennent du texte dans des alphabets non latins, tels que le japonais ou le coréen.
  • Petit texte : agrandissez le texte dans une image pour améliorer la lisibilité, mais évitez de rogner les détails importants.
  • Rotation : le modèle peut mal interpréter le texte et les images pivotés ou à l’envers.
  • Éléments visuels : Le modèle peut avoir du mal avec des graphiques ou des textes lorsque les couleurs ou les styles, tels que des lignes continues, en tirets ou en pointillés, varient.
  • Raisonnement spatial : le modèle a des difficultés avec les tâches qui nécessitent une localisation spatiale précise, comme l’identification des positions d’échecs.
  • Précision : le modèle peut générer des descriptions ou des légendes incorrectes dans certains cas.
  • Forme d’image : le modèle a des difficultés avec des images panoramiques et fisheye.
  • Métadonnées et redimensionnement : le modèle ne traite pas les noms de fichiers ou les métadonnées d’origine, et les images sont redimensionnées avant l’analyse, ce qui affecte leurs dimensions d’origine.
  • Comptage : le modèle peut donner des nombres approximatifs d’objets dans des images.
  • CAPTCHAs : pour des raisons de sécurité, un système est en place pour bloquer la soumission des CAPTCHAs.

Entrée de fichier

Les modèles avec fonctionnalités de vision prennent en charge l’entrée PDF. Vous pouvez fournir un fichier PDF de l’une des manières suivantes :

  • Données encodées en Base64
  • ID de fichier créé avec l’API Files
  • URL d’un fichier externe (file_url)

Pour aider les modèles à interpréter le contenu PDF, le contexte du modèle inclut à la fois le texte extrait et une image de chaque page. Cette fonctionnalité est utile lorsque des informations clés sont transmises via des diagrammes ou du contenu non textuel.

Note

  • Tous les textes et images extraits sont placés dans le contexte du modèle. Assurez-vous de bien comprendre les implications relatives à la tarification et à l'utilisation des jetons lorsque les fichiers PDF sont utilisés comme entrée.
  • Dans une seule requête d’API, vous pouvez inclure plusieurs fichiers, mais chaque fichier doit être inférieur à 50 Mo. La limite combinée entre tous les fichiers de la requête est de 50 Mo.
  • Seuls les modèles qui prennent en charge les entrées de texte et d’image peuvent accepter des fichiers PDF comme entrée.
  • Un purpose de user_data n’est actuellement pas pris en charge. En guise de solution de contournement temporaire, vous devez définir l’objectif sur assistants.

Convertir pdf en Base64 et analyser

Envoyez un fichier PDF inline en encodant ses octets en tant qu’URI de données base64. Le modèle reçoit à la fois le texte extrait et une image rendue de chaque page.

import base64
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

with open("PDF-FILE-NAME.pdf", "rb") as f:
    base64_string = base64.b64encode(f.read()).decode("utf-8")

response = client.responses.create(
    model="MODEL_NAME",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_file",
                    "filename": "PDF-FILE-NAME.pdf",
                    "file_data": f"data:application/pdf;base64,{base64_string}",
                },
                {"type": "input_text", "text": "Summarize this PDF."},
            ],
        },
    ]
)

print(response.output_text)

Charger pdf et analyser

Chargez le fichier PDF avec purpose="assistants". Un purpose de user_data n’est actuellement pas pris en charge.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

file = client.files.create(
    file=open("nucleus_sampling.pdf", "rb"),
    purpose="assistants"
)

response = client.responses.create(
    model="MODEL_NAME",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_file", "file_id": file.id},
                {"type": "input_text", "text": "Summarize this PDF."},
            ],
        },
    ]
)

print(response.output_text)

Analyser un PDF à partir d’une URL de fichier externe

Référencez un FICHIER PDF hébergé sur une URL accessible publiquement à l’aide de la file_url propriété d’un input_file élément de contenu. Vous n’avez pas besoin de télécharger, d’encoder ou de charger le fichier en premier.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

response = client.responses.create(
    model="MODEL_NAME",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Analyze the letter and provide a summary of the key points.",
                },
                {
                    "type": "input_file",
                    "file_url": "https://www.berkshirehathaway.com/letters/2024ltr.pdf",
                },
            ],
        },
    ]
)

print(response.output_text)

Utilisation de serveurs MCP distants

Vous pouvez étendre les fonctionnalités de votre modèle en la connectant à des outils hébergés sur des serveurs MCP (Remote Model Context Protocol). Ces serveurs sont gérés par les développeurs et les organisations et exposent des outils accessibles par des clients compatibles MCP, tels que l’API Réponses.

Le protocole MCP (Model Context Protocol) est une norme ouverte qui définit la façon dont les applications fournissent des outils et des données contextuelles aux modèles de langage volumineux (LLMs). Il permet une intégration cohérente et évolutive d’outils externes dans des flux de travail de modèle.

L’exemple suivant montre comment utiliser un serveur MCP distant pour interroger des informations sur un référentiel d’API REST Azure. Le modèle récupère le contenu du référentiel et effectue un raisonnement sur celui-ci en temps réel.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

response = client.responses.create(
    model="MODEL_NAME",
    tools=[
        {
            "type": "mcp",
            "server_label": "github",
            "server_url": "https://contoso.com/Azure/azure-rest-api-specs",
            "require_approval": "never"
        }
    ],
    input="What transport protocols are supported in the 2025-03-26 version of the MCP spec?"
)

print(response.output_text)

L’outil MCP fonctionne uniquement dans l’API Réponses et est disponible sur tous les modèles plus récents (gpt-4o, gpt-4.1 et nos modèles de raisonnement). Lorsque vous utilisez l’outil MCP, vous payez uniquement les jetons utilisés lors de l’importation de définitions d’outils ou lors de l’appel d’outils, il n’y a pas de frais supplémentaires impliqués.

Approbations

Par défaut, l’API Réponses nécessite une approbation explicite avant que toutes les données ne soient partagées avec un serveur MCP distant. Cette étape d’approbation vous permet de garantir la transparence et de contrôler les informations envoyées en externe.

Nous vous recommandons d’examiner toutes les données partagées avec des serveurs MCP distants et de les journaliser éventuellement à des fins d’audit.

Lorsqu’une approbation est requise, le modèle retourne un mcp_approval_request élément dans la sortie de la réponse. Cet objet contient les détails de la demande en attente et vous permet d’inspecter ou de modifier les données avant de continuer.

{
  "id": "mcpr_682bd9cd428c8198b170dc6b549d66fc016e86a03f4cc828",
  "type": "mcp_approval_request",
  "arguments": {},
  "name": "fetch_azure_rest_api_docs",
  "server_label": "github"
}

Pour passer à l’appel MCP distant, vous devez répondre à la demande d’approbation en créant un objet de réponse qui inclut un élément mcp_approval_response. Cet objet confirme votre intention d’autoriser le modèle à envoyer les données spécifiées au serveur MCP distant.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

response = client.responses.create(
    model="MODEL_NAME",
    tools=[
        {
            "type": "mcp",
            "server_label": "github",
            "server_url": "https://contoso.com/Azure/azure-rest-api-specs",
            "require_approval": "never"
        }
    ],
    previous_response_id="<previous_response_id>",
    input=[
        {
            "type": "mcp_approval_response",
            "approve": True,
            "approval_request_id": "<approval_request_id>"
        }
    ]
)

print(response.output_text)

Authentification

Important

  • Le client MCP au sein de l’API Réponses nécessite TLS 1.2 ou une version ultérieure.
  • Le protocole TLS mutuel (mTLS) n’est actuellement pas pris en charge.
  • Les étiquettes de service Azure ne sont actuellement pas prises en charge pour le trafic client MCP.

Contrairement au serveur GITHUB MCP, la plupart des serveurs MCP distants nécessitent une authentification. L’outil MCP de l’API Réponses prend en charge les en-têtes personnalisés, ce qui vous permet de vous connecter en toute sécurité à ces serveurs à l’aide du schéma d’authentification dont ils ont besoin.

Vous pouvez spécifier des en-têtes tels que des clés API, des jetons d’accès OAuth ou d’autres informations d’identification directement dans votre demande. L’en-tête le plus couramment utilisé est l’en-tête Authorization .

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

response = client.responses.create(
    model="MODEL_NAME",
    input="What is this repo in 100 words?",
    tools=[
        {
            "type": "mcp",
            "server_label": "github",
            "server_url": "https://contoso.com/Azure/azure-rest-api-specs",
            "headers": {"Authorization": "Bearer $YOUR_MCP_TOKEN"}
        }
    ]
)

print(response.output_text)

Tâches en arrière-plan

Le mode en arrière-plan vous permet d’exécuter des tâches de longue durée de manière asynchrone avec des modèles de raisonnement tels que o3 et o1-pro. Il est utile pour les tâches complexes qui peuvent prendre plusieurs minutes (par exemple, les agents de type Codex- ou Deep Research). Lorsqu’une demande est envoyée avec "background": true, la tâche est traitée de manière asynchrone et vous interrogez son état.

Démarrer une tâche en arrière-plan

Définissez background=true sur la demande pour mettre en file d’attente la tâche. Le service renvoie immédiatement un ID de réponse et un queued statut — utilisez cet ID pour interroger, suivre en streaming ou annuler la tâche.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

response = client.responses.create(
    model="MODEL_NAME",
    input="Write me a very long story.",
    background=True
)

print(response.status)

Interroger jusqu’à la fin

Continuez à interroger tant que l’état est queued ou in_progress. Une fois que la réponse atteint un état terminal, elle est disponible pour la récupération.

from time import sleep

while response.status in {"queued", "in_progress"}:
    print(f"Current status: {response.status}")
    sleep(2)
    response = client.responses.retrieve(response.id)

print(f"Final status: {response.status}\nOutput:\n{response.output_text}")

Annuler une tâche en arrière-plan

Annulez une tâche d’arrière-plan en cours à l’aide du point de terminaison cancel. L’annulation est idempotente : les appels ultérieurs retournent l’objet de réponse final.

response = client.responses.cancel("<response_id>")
print(response.status)

Pour diffuser en streaming une réponse en arrière-plan, définissez background et stream sur true. Ce modèle vous permet de reprendre la diffusion en continu si la connexion tombe. Suivez votre position avec le sequence_number depuis chaque événement.

stream = client.responses.create(
    model="MODEL_NAME",
    input="Write me a very long story.",
    background=True,
    stream=True,
)

cursor = None
for event in stream:
    print(event)
    cursor = event["sequence_number"]

Actuellement, les réponses en arrière-plan ont une latence de temps à premier jeton plus élevée que les réponses synchrones. Des améliorations sont en cours pour réduire cet écart.

Limitations

  • Le mode en arrière-plan nécessite store=true. Les requêtes sans état ne sont pas prises en charge.
  • Vous ne pouvez reprendre le streaming que si la demande d'origine comprenait stream=true.
  • Pour annuler une réponse synchrone, terminez la connexion directement.

Reprendre la diffusion en continu à partir d’un point spécifique

Si une connexion de streaming est interrompue, vous pouvez reprendre à partir d’un événement connu en passant stream=true avec starting_after=<sequence_number> dans une GET de la réponse. Le service relit les événements émis après ce numéro de séquence.

curl -N -X GET "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses/<response_id>?stream=true&starting_after=42" \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY"

Encrypted reasoning

Lorsque vous utilisez un modèle de raisonnement avec l’API Réponses en mode sans état (store=false), votre application fournit le contexte pour chaque requête suivante. Les messages précédents fournissent l’historique des conversations, mais ils ne contiennent pas le raisonnement interne du modèle. Un élément de raisonnement chiffré vous permet de conserver un contexte de raisonnement compatible dans une requête ultérieure sans exposer ce raisonnement comme texte lisible à votre application.

Pourquoi utiliser le raisonnement crypté ?

Utilisez le raisonnement chiffré lorsque votre application gère l’état de conversation et doit poursuivre un flux de travail de raisonnement à plusieurs tour. Par exemple, un utilisateur peut poser une question de suivi, ou le modèle peut appeler un outil, puis continuer après avoir reçu son résultat.

Le simple fait de transmettre les messages antérieurs à lui seul ne transmet pas le contexte de raisonnement du modèle à partir du tour précédent. Un élément de raisonnement chiffré transmet ce contexte pour la suite tout en conservant son contenu opaque pour votre application.

Comment l’utiliser ?

  1. Définissez store=false. Pour demander explicitement le raisonnement chiffré, ajoutez reasoning.encrypted_content au include paramètre, comme indiqué dans les exemples suivants.
  2. Conservez tous les éléments de sortie retournés dans leur ordre d’origine, y compris les éléments de raisonnement dotés de la propriété encrypted_content.
  3. Lors de l’appel suivant, incluez ces éléments avec les autres éléments pertinents de la conversation dans input, puis continuez à définir store=false. N’utilisez pas previous_response_id pour une réponse non enregistrée.

Les réponses sans état retournent le contenu chiffré par défaut ; le include paramètre reste pris en charge pour la compatibilité. La réexécution d’un élément rend le raisonnement compatible disponible, mais le raisonnement utilisé par le modèle dépend de son mode de contexte de raisonnement pris en charge. Pour plus d’informations, consultez Conserver le raisonnement entre les appels.

En mode sans état, l’élément de raisonnement chiffré est retourné à votre application. Votre application est chargée de la conserver en toute sécurité et de la renvoyer lors d’une requête ultérieure. Choisissez un emplacement de stockage côté application qui répond à vos exigences de sécurité et de cycle de vie.

Les exemples suivants utilisent l’authentification par clé API. Les exemples Python utilisent la bibliothèque de client OpenAI. Les autres exemples appellent directement le point de terminaison REST Responses et conservent les éléments de sortie complets au format JSON.

Installez les dépendances pour votre langue :

  • Python : installez le client avec pip install --upgrade openai.
  • C# : Utilisez une application console .NET 8 ou ultérieure. Aucun package supplémentaire n’est requis.
  • JavaScript : utilisez Node.js 18 ou version ultérieure et enregistrez chaque exemple dans un fichier .mjs. Aucun package supplémentaire n’est requis.
  • Java : utilisez JDK 17 ou version ultérieure et ajoutez la dépendance Maven com.fasterxml.jackson.core:jackson-databind:2.22.4. Enregistrez chaque échantillon avec le nom de fichier affiché dans son onglet.
  • REST : Exécutez les exemples PowerShell avec PowerShell 7 ou version ultérieure.

Définissez ces variables d’environnement pour chaque langage :

  • AZURE_OPENAI_ENDPOINT: votre point de terminaison de ressource, tel que https://YOUR-RESOURCE-NAME.openai.azure.com.
  • AZURE_OPENAI_API_KEY: Votre clé API.
  • AZURE_OPENAI_DEPLOYMENT: nom d’un déploiement de modèle de raisonnement pris en charge.

Les deux échantillons vérifient un élément reasoning crypté et déclenchent une erreur si aucun n’est retourné. Utilisez une configuration de déploiement et de raisonnement qui produit des éléments de raisonnement pour les requêtes d’exemple.

Continuer une conversation sans conservation d’état

Cet exemple conserve les éléments retournés dans une liste gérée par l’application et les transmet à une demande de suivi.

import os

from openai import BadRequestError, OpenAI

client = OpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    base_url=f"{os.environ['AZURE_OPENAI_ENDPOINT'].rstrip('/')}/openai/v1/",
)
deployment = os.environ["AZURE_OPENAI_DEPLOYMENT"]

# Application-managed state. This example keeps it in memory.
conversation = [
    {"role": "user", "content": "Explain the trade-offs of this design."}
]


def add_response_items(response):
    items = [item.model_dump(exclude_none=True) for item in response.output]

    if not any(
        item.get("type") == "reasoning" and item.get("encrypted_content")
        for item in items
    ):
        raise RuntimeError(
            "No encrypted reasoning item was returned. Check the deployment "
            "and the request's include parameter."
        )

    # Preserve the returned items, including encrypted reasoning.
    conversation.extend(items)


try:
    first = client.responses.create(
        model=deployment,
        input=conversation,
        store=False,
        include=["reasoning.encrypted_content"],
    )
    add_response_items(first)
    print("First answer:", first.output_text)

    conversation.append({
        "role": "user",
        "content": "Which trade-off matters most for reliability?",
    })

    second = client.responses.create(
        model=deployment,
        input=conversation,
        store=False,
        include=["reasoning.encrypted_content"],
    )
    add_response_items(second)
    print("Follow-up answer:", second.output_text)

except BadRequestError as exc:
    # Inspect the service error before deciding whether to restart.
    print(f"Request rejected: {exc}")
    raise

L’exemple imprime la première réponse et la réponse de suivi. Il conserve tous les éléments de sortie, y compris le raisonnement crypté, plutôt que la seule réponse lisible.

La conversation liste est l’emplacement où l’application de cet exemple conserve les éléments. Elle est conservée en mémoire et ne survit pas à un redémarrage du processus. Une application qui doit reprendre son exécution plus tard doit choisir et sécuriser son propre stockage.

Continuer après un appel d’outil

Cet exemple conserve le raisonnement et les éléments d’appel de fonction, exécute un exemple de fonction et renvoie son résultat en utilisant la balise correspondante call_id.

import json
import os

from openai import BadRequestError, OpenAI

client = OpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    base_url=f"{os.environ['AZURE_OPENAI_ENDPOINT'].rstrip('/')}/openai/v1/",
)
deployment = os.environ["AZURE_OPENAI_DEPLOYMENT"]

tools = [{
    "type": "function",
    "name": "get_order_status",
    "description": "Look up the status of an example order.",
    "parameters": {
        "type": "object",
        "properties": {
            "order_id": {"type": "string"}
        },
        "required": ["order_id"],
        "additionalProperties": False,
    },
}]


def get_order_status(order_id):
    # Replace this example with your own trusted data source.
    if order_id == "A123":
        return {"order_id": order_id, "status": "Shipped"}
    return {"order_id": order_id, "status": "Not found"}


conversation = [{
    "role": "user",
    "content": "What is the status of order A123?",
}]


def create_response():
    return client.responses.create(
        model=deployment,
        input=conversation,
        tools=tools,
        store=False,
        include=["reasoning.encrypted_content"],
    )


try:
    # Bound the number of tool rounds.
    for _ in range(3):
        response = create_response()
        items = [item.model_dump(exclude_none=True) for item in response.output]

        if not any(
            item.get("type") == "reasoning" and item.get("encrypted_content")
            for item in items
        ):
            raise RuntimeError("No encrypted reasoning item was returned.")

        # Preserve returned items in order, including reasoning and tool calls.
        conversation.extend(items)

        calls = [
            item for item in response.output
            if item.type == "function_call"
        ]
        if not calls:
            print(response.output_text)
            break

        for call in calls:
            if call.name != "get_order_status":
                raise ValueError(f"Unexpected tool: {call.name}")

            arguments = json.loads(call.arguments)
            result = get_order_status(arguments["order_id"])

            conversation.append({
                "type": "function_call_output",
                "call_id": call.call_id,
                "output": json.dumps(result),
            })
    else:
        raise RuntimeError("The tool-call limit was reached.")

except BadRequestError as exc:
    print(f"Request rejected: {exc}")
    raise

L’exemple imprime la réponse finale du modèle après avoir traité l’état de l’exemple de commande. La fonction utilise des exemples de données, et non un système de commande en direct. La boucle limite le nombre de demandes de réponse à trois et génère une erreur si le modèle continue de demander des outils.

Conserver les éléments de raisonnement chiffrés intacts ; n’essayez pas de lire ou de modifier leur contenu chiffré. Pour connaître les définitions de fonction et les formats de résultat des outils, consultez Appel de fonction.

Considérations relatives au routage

Si vous effectuez un routage via Gestion des API Azure, validez la relecture de raisonnement chiffrée sur vos back-ends configurés avant de vous appuyer dessus. Si le service retourne invalid_encrypted_content, inspectez l’erreur et le routage des ressources avant de décider s’il faut redémarrer la conversation.

Considérations relatives à la protection des données

Les éléments de raisonnement chiffrés comportent un contexte de raisonnement opaque entre les requêtes. Ils ne décrivent pas comment le service chiffre les données stockées, les clés qui protègent les prompts stockés ou l’état de la conversation, ou où votre application doit stocker les éléments retournés.

Le paramètre store=false n’est pas une garantie globale de rétention zéro dans chaque processus de service. Pour plus d’informations sur le stockage côté service et la surveillance des abus, consultez Données, confidentialité et sécurité pour Azure OpenAI.

Génération d'image

L’API Réponses active la génération d’images dans le cadre de conversations et de flux de travail à plusieurs étapes. Il prend en charge les entrées et sorties d’image dans le contexte, et inclut des outils intégrés pour générer et modifier des images.

Par rapport à l’API Image autonome, l’API Réponses offre deux avantages :

  • Streaming : affichez des sorties d’image partielles pendant la génération pour améliorer la latence perçue.
  • Entrées flexibles : acceptez les ID de fichier image en tant qu’entrées en plus des octets d’image bruts.

Note

L’outil de génération d’images de l’API Responses est pris en charge par les modèles de la série gpt-image-1, et vous pouvez l’invoquer depuis un ensemble de modèles de chat et de raisonnement compatibles. Pour obtenir la liste actuelle des modèles d’orchestration pris en charge, consultez la section Modèles pris en charge plus loin dans cet article.

L’outil de génération d’images ne prend actuellement pas en charge le mode de diffusion en continu. Pour diffuser des images partielles, appelez l’API de génération d’images directement en dehors de l’API Réponses.

Utilisez l’API Réponses pour générer des expériences d’image conversationnelle avec des modèles d’image GPT.

import base64
import os
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=token_provider,
    default_headers={
        "x-ms-oai-image-generation-deployment": os.getenv("IMAGE_MODEL_NAME"),
        "api_version": "preview",
    },
)

response = client.responses.create(
    model="MODEL_NAME",
    input="Generate an image of a gray tabby cat hugging an otter with an orange scarf.",
    tools=[{"type": "image_generation"}],
)

image_data = [
    output.result
    for output in response.output
    if output.type == "image_generation_call"
]

if image_data:
    with open("otter.png", "wb") as f:
        f.write(base64.b64decode(image_data[0]))

Modèles de raisonnement

Pour obtenir des exemples d’utilisation de modèles de raisonnement avec l’API réponses, consultez le guide des modèles de raisonnement.

Utilisation de l’ordinateur

L’utilisation de l’ordinateur avec Playwright a été déplacée vers le guide de modèle d’utilisation de l’ordinateur dédié.

Dépannage

Pourquoi ma session d’API s’est-elle terminée par précaution ?

Lorsque vous utilisez des modèles Astra, pour vous assurer que les agents interprètent et suivent correctement vos instructions, nous avons un système qui arrête les sessions dans l’API Réponses s’il détecte que l’agent n’a peut-être pas interprété vos instructions correctement dans des cas tels que le transfert de données sensibles, l’accès aux données sensibles ou l’exécution de modifications destructrices. Si votre session a été terminée, cela ne signifie pas nécessairement que l’agent a commis une erreur, seulement qu’il vaut la peine d’examiner les actions de l’agent pour s’assurer qu’il a interprété et suivi correctement vos instructions.

Quelles demandes d’API sont surveillées par ce système ?

Le même système décrit ci-dessus surveille de façon asynchrone les requêtes adressées à Astra dans l’API Réponses. L’API Chat Completions n’est pas analysée par ce système de surveillance spécifique. Nous vous recommandons d’utiliser l’API Réponses pour obtenir le plus grand degré de performance et de sécurité pour les cas d’usage agentiques.

Comment détecter qu’une conversation a été terminée dans l’API par ce système ?

Lorsque le système de sécurité détecte qu’un agent peut avoir interprété des instructions incorrectement de manière significative, l’API retourne une mise en œuvre incorrecte du code d’annotation de sécurité. Dans ce cas, la session donnée ne peut pas être reprise.

Que dois-je faire pour mon application si un tel cas est détecté ?

Vous pouvez envisager de configurer un système pour permettre à quelqu’un de passer en revue les actions que l’agent a effectuées dans de telles conversations, par exemple en fournissant une interface utilisateur à l’utilisateur final pour passer en revue. Une fois qu’une conversation est arrêtée pour cette raison dans l’API, elle ne peut pas être reprise.

Résoudre les erreurs d’API courantes

Utilisez les instructions suivantes pour résoudre les erreurs d’API courantes :

  • 401/403 : si vous utilisez Microsoft Entra ID, vérifiez que votre jeton est limité à https://ai.azure.com/.default. Si vous utilisez une clé API, vérifiez que vous utilisez la clé correcte pour la ressource.
  • 404 : Assurez-vous que model correspond à votre nom de déploiement.

Contenu connexe

  • Dernière mise à jour :