Démarrage rapide : Créer une instance de palier (aperçu) de la passerelle IA

S’APPLIQUE AU : niveau AI Gateway (aperçu)

Important

Le niveau de service AI Gateway est actuellement en préversion publique. Lors de l’aperçu public, le niveau IA Gateway est disponible dans les régions suivantes :

États-Unis - USA Est 2
Europe - Suède centrale

Dans ce démarrage rapide, vous créez une instance de niveau IA Gateway (aperçu), ajoutez un modèle de chat, appelez la passerelle, créez une clé d’accès à l’exécution et consultez la télémétrie.

Le niveau AI Gateway d’Gestion des API Azure est un niveau dédié aux charges de travail IA. Il permet de gérer le trafic vers des modèles — provenant de Microsoft Foundry, Azure OpenAI, AWS Bedrock, Google Vertex, OpenAI, Anthropic ou d’autres fournisseurs — ainsi que d’outils créés à partir de serveurs MCP existants, de définitions OpenAPI ou de connecteurs. L’offre AI Gateway est généralement mise à disposition rapidement, en une minute environ.

Temps pour terminer : environ 20-30 minutes. Vous créez : une passerelle, un modèle de chat, une clé d’accès à l’exécution et une requête de réussite de chat réussie.

Note

Le palier IA Gateway est en aperçu public. Les fonctionnalités de prévisualisation sont fournies sans accord de niveau de service et ne doivent pas être utilisées pour les charges de travail de production à moins que votre organisation n’accepte les conditions de prévisualisation.

Prerequisites

Un compte Azure avec Microsoft Entra ID. L’accès à la version preview de niveau AI Gateway est actuellement limité aux utilisateurs Azure qui se connectent avec Microsoft Entra ID.
Un abonnement Azure, et la permission de créer des ressources dans un groupe de ressources (par exemple, le rôle Contributeur).
Accès à au moins un fournisseur de modèles pris en charge, comme un modèle déployé dans Microsoft Foundry ou Azure OpenAI.
Si votre fournisseur nécessite une clé API, ayez la clé disponible.
Pour appeler la passerelle, utilisez curl (pas d’installation) ou un SDK OpenAI - Python 3.9 ou ultérieur, ou Node.js 18 ou plus récent, avec le openai package.

Le portail AI Gateway est une expérience web autonome – vous n'utilisez pas le portail Azure.

Rendez-vous sur le portail de niveau IA Gateway à ai.gateway.azure.com.
Sélectionnez Se connecter, puis authentifiez-vous avec Microsoft Entra ID.

Utilisez le portail pour gérer les modèles, serveurs MCP, clés d’accès à l’exécution, politiques et surveillance, en fonction de vos permissions Entra ID. Les appelants du runtime ne s’authentifient pas sur le portail ; ils invoquent la passerelle avec des clés d’accès du runtime que vous créerez ultérieurement.

2. Créer une passerelle

Dans le portail, sélectionnez Créer passerelle. Pour utiliser une passerelle existante à la place, sélectionnez-la et passez à l’étape suivante.
Saisissez un Nom. Le nom devient partie intégrante du point de terminaison d’exécution :

https://<gateway>.azure-api.net
Sélectionnez votre abonnement et une région de prévisualisation prise en charge (East US 2 ou Sweden Central).
Éventuellement, mettez le groupe de ressources sous Avancé. Par défaut, le portail en crée un pour vous.
Cliquez sur Créer. L’activation prend généralement moins d’une minute.

La passerelle est une ressource dédiée dans votre abonnement Azure. Vous ne choisissez pas la capacité et vous n’ajoutez pas d’unités de mise à l’échelle avant d’ajouter des modèles. Pour l’automatisation, la version de l’API de gestion d’aperçu est 2026-05-01-preview; les requêtes à l’exécution utilisent le nom d’hôte de la passerelle, et non Azure Resource Manager.

3. Ajouter un modèle

La façon la plus rapide de créer un modèle est de l’importer depuis des comptes Microsoft Foundry.

Dans la section Accueil,Configurez votre passerelle, sélectionnez l’option Démarrer ou ouvrez directement la page de configuration sur l’itinéraire /settings/start .
Sélectionnez un ou plusieurs abonnements à scanner. Optionnellement, appliquez un filtre de groupe de ressources pour affiner les résultats.
Examinez les comptes découverts. Les déploiements sont regroupés selon leur compte parent Foundry (la ressource Azure). La sélection s’effectue par compte : lorsque vous sélectionnez un compte, l’assistant importe tous ses déploiements de modèles.
Choisissez une méthode d’authentification en arrière-plan pour cette importation :
- Basé sur des touches (par défaut). La passerelle stocke la clé API du compte et l’envoie dans l’en-tête api-key . L’assistant récupère la clé au moment de l’importation.
- Identité gérée (Microsoft Entra ID). La passerelle s’authentifie avec son identité gérée. Si la passerelle n’a pas d’identité gérée, l’assistant active une identité attribuée par le système. Si une identité existe déjà, vous choisissez quelle identité utiliser. L’assistant attribue à l’identité le rôle Utilisateur Foundry pour chaque compte sélectionné.
Cliquez sur Importer.
Lorsque vous sélectionnez Importer, l’assistant effectue une vérification des exigences pour chaque compte sélectionné avant de créer quoi que ce soit. Cette vérification confirme que l’authentification est correctement configurée et que les noms de modèles ne sont pas en conflit avec les modèles déjà présents sur la passerelle. Les comptes qui réussissent le contrôle sont importés ; ceux qui échouent sont ignorés avec un message d’avertissement intégré, et le reste du processus se poursuit.

Pour connecter un fournisseur non Foundry (AWS Bedrock, Google Vertex, OpenAI ou Anthropic), sélectionnez plutôt Ajouter un modèle personnalisé. Voir Gérer les modèles et outils.

Les appelants passent le nom du modèle dans le model champ des requêtes compatibles OpenAI. Ce démarrage rapide utilise gpt-5.6-sol; remplacez-le par le modèle que vous avez enregistré.

Tip

Pour essayer le modèle immédiatement, ouvrez la page Discover et sélectionnez le modèle à invoquer dans le playground intégré. Le terrain de jeu utilise la clé intégrée de la passerelle, ce qui vous permet d’explorer et de tester des modèles ou outils ajoutés avant de créer une clé d’accès à l’exécution.

4. Appeler la passerelle

La passerelle expose l’API prise en charge par le modèle backend. Les modèles de fournisseurs compatibles OpenAI — tels que Microsoft Foundry, Azure OpenAI, AWS Bedrock, Google Vertex et OpenAI — sont servis sur un point de terminaison compatible OpenAI. Pointer n’importe quel client OpenAI vers l’URL de base de la passerelle, envoyer un api-key en-tête, puis passer le nom du modèle dans le model champ. Les modèles Anthropic utilisent plutôt l’API Anthropic Messages ; voir Gérer les modèles et outils.

Pour un test rapide, utilisez la clé intégrée de la passerelle — la même clé que le terrain de jeu Discover. Copiez-le depuis la page Clés , qui liste la clé intégrée aux côtés des clés API qui accordent l’accès à l’exécution à chaque asset de la passerelle. Pour vos propres applications, créez plutôt une clé d’accès à l’exécution (voir la section suivante).

Définissez ces valeurs une fois :

export AI_GATEWAY_BASE_URL="https://<gateway>.azure-api.net/default/models/openai/v1"
export AI_GATEWAY_API_KEY="<gateway-key>"

Tip

Copiez l’URL de base exacte depuis la page d’aperçu de votre passerelle plutôt que de la construire à la main.

Passez votre premier appel avec le client de votre choix :

curl "$AI_GATEWAY_BASE_URL/chat/completions" \
  -H "Content-Type: application/json" \
  -H "api-key: $AI_GATEWAY_API_KEY" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "Give me three benefits of using an AI gateway." }
    ]
  }'

Pour diffuser les jetons en tant qu’événements envoyés par le serveur, ajoutez "stream": true au corps de la requête.

Installez le client avec pip install openai.

import os
from openai import OpenAI

# The gateway reads the api-key header, not the api_key argument.
client = OpenAI(
    base_url=os.environ["AI_GATEWAY_BASE_URL"],
    api_key="unused",
    default_headers={"api-key": os.environ["AI_GATEWAY_API_KEY"]},
)

response = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Give me three benefits of using an AI gateway."},
    ],
)
print(response.choices[0].message.content)

Pour diffuser les jetons au fur et à mesure de leur génération, ajoutez stream=True et itérez la réponse :

stream = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[{"role": "user", "content": "Stream a short greeting."}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Installez le package avec npm install openai.

import OpenAI from "openai";

// The gateway reads the api-key header, not the apiKey argument.
const client = new OpenAI({
  baseURL: process.env.AI_GATEWAY_BASE_URL,
  apiKey: "unused",
  defaultHeaders: { "api-key": process.env.AI_GATEWAY_API_KEY },
});

const response = await client.chat.completions.create({
  model: "gpt-5.6-sol",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Give me three benefits of using an AI gateway." },
  ],
});
console.log(response.choices[0].message.content);

Pour streamer, ajoutez stream: true et itérez la réponse asynchrone.

Chaque réponse du point de terminaison /chat/completions utilise le format OpenAI Chat Completions, quel que soit le fournisseur compatible OpenAI sur lequel repose le modèle.

Un appel sans diffusion en continu renvoie une complétion de chat :

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "gpt-5.6-sol",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "1. Centralized governance ...\n2. ...\n3. ..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 24, "completion_tokens": 61, "total_tokens": 85 }
}

Avec le streaming activé, la passerelle renvoie chat.completion.chunk les événements suivants :

{
  "id": "chatcmpl-...",
  "object": "chat.completion.chunk",
  "model": "gpt-5.6-sol",
  "choices": [
    { "index": 0, "delta": { "content": "Hello" }, "finish_reason": null }
  ]
}

La même URL de base sert également l’API OpenAI Responses à /responses.

Si une requête échoue, la passerelle renvoie un code d’état HTTP standard :

Status	Meaning	Que vérifier
400	Demande non valide	Vérifiez le corps de la demande.
400	Bloqué par la sécurité du contenu ou un filtre IP, ou refusé par le backend	Une politique de sécurité du contenu peut bloquer une invite ou une réponse ; vérifiez aussi toute politique de filtre IP. Pour l’identité gérée, attribuez le rôle Foundry User à l’identité de passerelle sur la ressource backend. Voir Utiliser une identité gérée pour l’authentification backend.
401	Clé d’accès à l’exécution manquante ou invalide	Envoie la clé dans l’en-tête `api-key` et confirme que la clé est active.
404	Modèle inconnu	Confirmez que la `model` valeur correspond à un nom de modèle sur la page Modèles .
429	Limité par une politique de limitation du débit ou par le système backend	Consultez les politiques de limitation du nombre de jetons et de requêtes, et respectez l’en-tête de réponse `Retry-After`.
5xx	Erreur du serveur	Confirmez que le prestataire en arrière-plan est en bonne santé et que la certification du prestataire est valide.

Les SDK OpenAI suscitent des exceptions typées pour ces codes d’état, donc votre gestion des erreurs existante fonctionne :

from openai import AuthenticationError, RateLimitError, APIStatusError

try:
    response = client.chat.completions.create(
        model="gpt-5.6-sol",
        messages=[{"role": "user", "content": "Hello"}],
    )
except AuthenticationError:
    ...  # 401 — check the api-key header and that the key is active
except RateLimitError:
    ...  # 429 — back off and honor the Retry-After header
except APIStatusError as e:
    ...  # inspect e.status_code for 400, 403, 404, or 5xx

5. Créer une clé d’accès à l’exécution

Les applications s’authentifient à la passerelle avec une clé d’accès à l’exécution plutôt que la clé intégrée. Créez une clé distincte pour chaque application et environnement.

Sélectionnez Clés.
Sélectionnez Créer une clé API.
Entrez un nom, tel que quickstart-client.
Cliquez sur Créer.
Copiez la valeur de la clé et stockez-la en toute sécurité. Vous pourrez aussi le revoir plus tard sur la page des Clés .

Créez des clés d’accès d’exécution au niveau de la passerelle. Ces clés donnent accès à tous les modèles et outils de la passerelle. Traitez-les comme des secrets. Stockez les clés dans un gestionnaire de secrets pour les applications, effectuez régulièrement leur rotation et révoquez les clés qui ne sont plus nécessaires. Pour appeler la passerelle avec une clé d’accès d’exécution, définissez AI_GATEWAY_API_KEY à sa valeur dans les appels présentés plus haut.

6. Voir télémétrie

Le niveau IA Gateway émet des indicateurs d’utilisation des tokens OpenTelemetry. Pour les voir, configurez d’abord une destination de télémétrie, puis envoyez les requêtes :

Configurez une destination de télémétrie pour la passerelle, telle que Application Insights. Voir Gouverner, sécuriser et opérer.
Envoyez une ou plusieurs requêtes via la passerelle, comme indiqué précédemment dans Appeler la passerelle.
Ouvrez votre destination de télémétrie pour consulter l’utilisation du jeton. Si vous utilisez Application Insights, le portail propose un tableau de bord de consommation de tokens intégré.

Comme la télémétrie n’est émise qu’après avoir connecté une destination, configurez la surveillance avant de vous y fier. L’utilisation des tokens est actuellement la seule métrique disponible ; les journaux, les traces et d’autres métriques pour les modèles et les outils seront bientôt disponibles. Les appelants utilisent des clés d’accès au niveau de la passerelle, ce qui vous permet de surveiller le trafic sans exposer les identifiants du fournisseur aux applications clientes. Pour configurer une destination de télémétrie, voir Gouverner, sécuriser et opérer.

Nettoyer les ressources

Quand vous avez fini, supprimez toutes les ressources dont vous n’avez plus besoin. Supprimez l’instance de niveau IA Gateway, les déploiements de test du fournisseur et les clés d’accès à l’exécution que vous avez créées uniquement pour évaluation.

Étapes suivantes

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-07-28