Quickstart: Erstellen Sie eine AI-Gateway-Tier-Instanz (Vorschau)

GILT FÜR: KI-Gateway-Ebene (Vorschau)

Important

Die AI Gateway-Stufe befindet sich derzeit in der öffentlichen Vorschau. Während der öffentlichen Vorschau ist die AI-Gateway-Stufe in den folgenden Regionen verfügbar:

USA - Osten der US-Region 2
Europa – Schweden Zentral

In diesem Quickstart erstellen Sie eine AI-Gateway-Tier-Instanz (Vorschau), fügen ein Chat-Modell hinzu, rufen das Gateway auf, erstellen einen Laufzeit-Zugangsschlüssel und sehen sich die Telemetrie an.

Das AI-Gateway-Tier von Azure API Management ist ein dediziertes Tier für KI-Workloads. Es unterstützt die Verwaltung von Traffic zu Modellen – von Microsoft Foundry, Azure OpenAI, AWS Bedrock, Google Vertex, OpenAI, Anthropic oder anderen Anbietern – sowie Werkzeuge, die aus bestehenden MCP-Servern, OpenAPI-Definitionen oder Connectoren erstellt wurden. Die KI-Gateway-Tier-Stufe wird schnell bereitgestellt, meist innerhalb einer Minute.

Fertigstellungszeit: etwa 20-30 Minuten. Du erstellst: ein Gateway, ein Chat-Modell, einen Laufzeit-Zugriffsschlüssel und eine erfolgreiche Chat-Abschlussanfrage.

Note

Die AI-Gateway-Stufe befindet sich in der öffentlichen Vorschau. Vorschaufunktionen werden ohne Service-Level-Vereinbarung bereitgestellt und sollten nicht für Produktions-Workloads verwendet werden, es sei denn, Ihre Organisation akzeptiert die Vorschaubedingungen.

Voraussetzungen

Ein Azure-Konto mit Microsoft Entra ID. Der Zugriff auf die AI-Gateway-Tier-Vorschau ist derzeit auf Azure-Nutzer beschränkt, die sich mit Microsoft Entra ID anmelden.
Ein Azure-Abonnement und die Berechtigung, Ressourcen in einer Ressourcengruppe zu erstellen (zum Beispiel die Rolle Mitwirkender).
Zugang zu mindestens einem unterstützten Modellanbieter, wie zum Beispiel einem bereitgestellten Modell in Microsoft Foundry oder Azure OpenAI.
Wenn dein Anbieter einen API-Schlüssel verlangt, halte den Schlüssel verfügbar.
Um das Gateway aufzurufen, verwenden Sie curl (keine Installation) oder ein OpenAI-SDK – Python 3.9 oder höher oder Node.js 18 oder später, mit dem openai Paket.

Das AI Gateway Tier-Portal ist ein eigenständiges Weberlebnis – du nutzt das Azure-Portal nicht.

Gehe zum AI Gateway Tier-Portal unter ai.gateway.azure.com.
Wählen Sie Anmelden und authentifizieren Sie sich mit der Microsoft Entra ID.

Nutzen Sie das Portal, um Modelle, MCP-Server, Laufzeit-Zugriffsschlüssel, Richtlinien und Überwachung basierend auf Ihren Entra ID-Berechtigungen zu verwalten. Runtime-Anrufer melden sich nicht im Portal an – sie rufen das Gateway mit Runtime-Zugriffsschlüsseln auf, die du später erstellst.

2. Erstellen Sie ein Gateway

Im Portal wählen Sie Gateway erstellen. Um stattdessen ein bestehendes Gateway zu verwenden, wählen Sie es aus und springen Sie zum nächsten Schritt.
Geben Sie einen Namen ein. Der Name wird Teil des Laufzeitendpunkts:

https://<gateway>.azure-api.net
Wählen Sie Ihr Abonnement und eine unterstützte Vorschauregion (East US 2 oder Sweden Central).
Setze optional die Ressourcengruppe unter Fortgeschritten. Standardmäßig erstellt das Portal einen für dich.
Wählen Sie "Erstellen" aus. Die Aktivierung dauert in der Regel weniger als eine Minute.

Das Gateway ist eine dedizierte Ressource in deinem Azure-Abonnement. Man wählt keine Kapazität oder fügt Maßstabseinheiten hinzu, bevor man Modelle anbaut. Für die Automatisierung ist die Vorschauversion der Verwaltungs-API 2026-05-01-preview; Laufzeitanforderungen verwenden den Gateway-Hostnamen, nicht Azure Resource Manager.

3. Ein Modell hinzufügen

Der schnellste Weg, ein Modell zu erstellen, ist, es aus Microsoft Foundry-Konten zu importieren. Außerdem können Sie Ressourcen über mehrere Abonnements hinweg automatisch entdecken und importieren, indem Sie den Erstkonfigurationsassistenten nutzen, der Foundry-Konten und MCP-Server in Azure-gehosteten Diensten entdeckt.

Um ein Modell aus Foundry zu importieren:

Im Gateway wählen Sie Models aus und dann Add Models.
Wählen Sie Aus Foundry importieren aus.
Wählen Sie unter Select Resource Ihr Abonnement und Foundry Resource aus. Der Assistent listet die Modelleinsätze in dieser Ressource auf. Beachten Sie den Namen eines Chat-Modells (dieser Quickstart verwendet gpt-5.6-sol).
Bei den Anbieterdaten geben Sie einen Anbieternamen und einen Anzeigenamen ein (kurze Kennungen in der Modellliste und in der Telemetrie; sie müssen nicht mit dem Namen der Foundry-Ressource übereinstimmen) und wählen Sie eine Authentifizierungsmethode:
- Schlüsselbasiert (am schnellsten für diesen Quickstart): Das Gateway speichert den Provider-Schlüssel. Eine Rollenzuweisung ist nicht erforderlich.
- Verwaltete Identität: verfügbar, wenn der Anbieter die Microsoft Entra ID-Authentifizierung unterstützt. Bevor Sie es verwenden, weisen Sie der Gateway-Identität die erforderliche Backend-Rolle zu (für Microsoft Foundry, Foundry User). Sieh Governieren, sichern und operieren.
Wählen Sie "Erstellen" aus. Es gibt keinen separaten Validierungsschritt; Das Gateway richtet die Verbindung ein, wenn du den Anbieter erstellst.

Um einen Nicht-Foundry-Anbieter (AWS Bedrock, Google Vertex, OpenAI oder Anthropic) zu verbinden, wählen Sie stattdessen ein benutzerdefiniertes Modell hinzufügen. Siehe Modelle und Werkzeuge verwalten.

Anrufer geben den Modellnamen im model Bereich der OpenAI-kompatiblen Anfragen weiter. Dieser Quickstart verwendet gpt-5.6-sol; ersetzen Sie ihn durch das von Ihnen registrierte Modell.

Tip

Um das Modell sofort auszuprobieren, öffne die Discover-Seite und wähle das Modell aus, um es im integrierten Spielplatz zu starten. Der Spielplatz verwendet den eingebauten Schlüssel des Gateways, sodass du hinzugefügte Modelle oder Werkzeuge erkunden und testen kannst, bevor du einen Laufzeit-Zugangsschlüssel erstellst.

4. Rufen Sie das Gateway auf

Das Gateway stellt die API frei, die das Backend-Modell unterstützt. Modelle von OpenAI-kompatiblen Anbietern – wie Microsoft Foundry, Azure OpenAI, AWS Bedrock, Google Vertex und OpenAI – werden auf einem OpenAI-kompatiblen Endpunkt bereitgestellt. Richten Sie einen beliebigen OpenAI-Client auf die Basis-URL des Gateways aus, senden Sie einen api-key-Header und übergeben Sie den Modellnamen im Feld model. Anthropic-Modelle verwenden stattdessen die Anthropic Messages API; siehe Modelle und Werkzeuge verwalten.

Für einen schnellen Test verwenden Sie den eingebauten Schlüssel des Gateways – denselben Schlüssel, den der Discover-Spielplatz verwendet. Kopiere es von der Keys-Seite , die den eingebauten Schlüssel zusammen mit den API-Schlüsseln auflistet, die Laufzeitzugriff auf jedes Asset im Gateway gewähren. Für Ihre eigenen Anwendungen erstellen Sie stattdessen einen Laufzeit-Zugriffsschlüssel (siehe nächsten Abschnitt).

Setzen Sie diese Werte einmal:

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

Tip

Kopieren Sie die genaue Basis-URL von der Übersichtsseite Ihres Gateways, anstatt sie von Hand zu erstellen.

Machen Sie Ihren ersten Anruf mit dem Kunden Ihrer Wahl:

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." }
    ]
  }'

Um Token als Server-Sent Events zu streamen, fügen Sie "stream": true dem Anfragetext hinzu.

Installiere den Client mit 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)

Um Token während ihrer Generierung zu streamen, fügen Sie stream=True hinzu und iterieren Sie über die Antwort:

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)

Installiere das Paket mit 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);

Um zu streamen, füge stream: true hinzu und iteriere die asynchrone Antwort.

Jede Antwort des Endpunkts /chat/completions verwendet das OpenAI Chat Completions-Format, je nachdem, welcher OpenAI-kompatible Anbieter das Modell unterstützt.

Ein nicht-streamender Aufruf gibt eine Chat-Vervollständigung zurück:

{
  "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 }
}

Mit aktiviertem Streaming gibt das Gateway Ereignisse zurück:chat.completion.chunk

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

Die gleiche Basis-URL bedient auch die OpenAI Responses API unter /responses.

Wenn eine Anfrage fehlschlägt, gibt das Gateway einen Standard-HTTP-Statuscode zurück:

Status	Bedeutung	Was soll überprüft werden?
400	Ungültige Anforderung	Überprüfen Sie den Anfragetext.
400	Blockiert durch Inhaltssicherheit oder einen IP-Filter oder vom Backend abgelehnt	Eine Inhaltssicherheitsrichtlinie kann eine Aufforderung oder Antwort blockieren; Überprüfen Sie auch die IP-Filter-Richtlinien. Für die verwaltete Identität weisen Sie der Gateway-Identität auf der Backend-Ressource die Rolle Foundry User zu. Siehe Use managed identity für Backend-Authentifizierung.
401	Fehlender oder ungültiger Laufzeitzugriffsschlüssel	Senden Sie den Schlüssel in den `api-key` Header und bestätigen Sie, dass der Schlüssel aktiv ist.
404	Unbekanntes Modell	Bestätigen Sie, dass der `model` Wert mit einem Modellnamen auf der Modellseite übereinstimmt.
429	Durch eine Ratenbegrenzungsrichtlinie oder das Backend gedrosselt	Überprüfen Sie die Richtlinien zur Token- und Anfrageratenbegrenzung und beachten Sie den Antwortheader `Retry-After`.
5xx	Backend-Fehler	Bestätigen Sie, dass der Backend-Anbieter gesund ist und die Provider-Credential gültig ist.

Die OpenAI-SDKs erzeugen typisierte Ausnahmen für diese Statuscodes, daher funktioniert deine bestehende Fehlerbehandlung:

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. Erstellen Sie einen Laufzeitzugriffsschlüssel

Anwendungen authentifizieren sich beim Gateway mit einem Laufzeitzugriffsschlüssel und nicht mit dem eingebauten Schlüssel. Erstelle für jede Anwendung und Umgebung einen separaten Schlüssel.

Wählen Sie Schlüssel aus.
Wählen Sie API-Schlüssel erstellen aus.
Geben Sie einen Namen ein, z. B. quickstart-client.
Wählen Sie "Erstellen" aus.
Kopieren Sie den Schlüsselwert und bewahren Sie ihn sicher auf. Du kannst es später auch auf der Keys-Seite erneut ansehen.

Erstelle Laufzeit-Zugriffsschlüssel auf Gateway-Ebene. Diese Schlüssel gewähren Zugriff auf jedes Modell und Werkzeug im Gateway. Behandle sie wie Geheimnisse. Speichern Sie Schlüssel in einem geheimen Speicher für Anwendungen, rotieren Sie sie regelmäßig und widerrufen Schlüssel, die nicht mehr benötigt werden. Um das Gateway mit einem Runtimezugriffsschlüssel aufzurufen, setzen Sie AI_GATEWAY_API_KEY in den zuvor gezeigten Aufrufen auf diesen Wert.

6. Siehe Telemetrie

Die KI-Gateway-Schicht sendet OpenTelemetrie-Token-Nutzungsmetriken. Um sie zu sehen, konfigurieren Sie zuerst ein Telemetrieziel und senden Sie dann Anfragen:

Konfigurieren Sie ein Telemetrieziel für das Gateway, wie zum Beispiel Application Insights. Sieh Governieren, sichern und operieren.
Senden Sie eine oder mehrere Anfragen über das Gateway, wie bereits in Call the Gateway gezeigt.
Öffnen Sie Ihr Telemetrieziel, um die Tokennutzung zu überprüfen. Wenn Sie Application Insights verwenden, bietet das Portal ein integriertes Token Verbrauchs-Dashboard.

Da Telemetrie erst nach der Verbindung eines Ziels ausgesandt wird, konfigurieren Sie die Überwachung, bevor Sie sich darauf verlassen. Die Verwendung von Token ist derzeit die einzige emittierte Kennzahl; Logs, Traces und andere Metriken für Modelle und Werkzeuge kommen bald. Anrufer verwenden Gateway-Level-Zugriffsschlüssel, sodass Sie den Datenverkehr überwachen können, ohne Provider-Zugangsdaten für Client-Anwendungen freizugeben. Informationen zum Konfigurieren eines Telemetrieziels finden Sie unter Govern, secure, and operate.

Bereinigen von Ressourcen

Wenn du fertig bist, lösche alle Ressourcen, die du nicht mehr brauchst. Entfernen Sie die AI-Gateway-Tier-Instanz, die Bereitstellungen von Provider-Tests und die Laufzeitzugriffsschlüssel, die Sie ausschließlich zur Bewertung erstellt haben.

Nächste Schritte

Feedback

War diese Seite hilfreich?

Last updated on 2026-07-23