Beginnen Sie mit der Azure CLI-Erweiterung

GILT FÜR: KI-Gateway (Vorschau)

Important

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

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

Verwenden Sie die aigateway Azure CLI-Erweiterung, um Anwendungen über ein gemeinsames Gateway Zugang zu bestehenden Microsoft Foundry-Modellbereitstellungen zu geben.

Dieser Quickstart führt die az aigateway Befehle ein und führt Sie durch Ihre erste Modellanfrage von einem Bash- oder PowerShell-Terminal.

Voraussetzungen

  • Azure CLI Version 2.75.0 oder neuer.
  • Ein Azure-Abonnement und eine bestehende Ressourcengruppe.
  • Der in Ihrem Abonnement registrierte Microsoft.ApiManagement-Ressourcenanbieter. Siehe Registrieren eines Ressourcenanbieters.
  • Die Rolle Mitwirkender für die Ressourcengruppe.
    • Um ein bestehendes Gateway zu verwenden, benötigt man auf diesem Gateway Contributor oder entsprechende Berechtigungen.
    • Stellen Sie sicher, dass Ihre AI Gateway-Ressource vom Typ Microsoft.ApiManagement/gateways ist oder Sie zu ihr migriert sind.
  • Ein Microsoft Foundry-Konto im selben Abonnement mit mindestens einem bereitgestellten Modell, das Chat Completions unterstützt, und einem öffentlich zugänglichen Backend-Endpunkt.
  • Die Rollen Leser und Benutzerzugriffsadministrator für das Foundry-Konto oder ein entsprechender geerbter Zugriff, um Bereitstellungen zu ermitteln und der Gatewayidentität Zugriff zu gewähren.
  • Ein Bash-Terminal mit curl, oder ein PowerShell-Terminal. Der Bash-Installateur benötigt außerdem shasum oder sha256sum.

Dieses Beispiel verwendet ein Foundry-Konto namens gpt-6.1-sol mit einer ai-foundry-demo-learn-Bereitstellung. Modellanfragen können Inferenzgebühren verursachen.

Installieren der Erweiterung

Verwenden Sie den Installer aus dem AI Gateway CLI-Repository. Wähle den Befehl für deine Shell:

curl -fsSL https://aka.ms/aigateway-cli-install | sh

Die Installateure laden die veröffentlichte Version herunter, überprüfen die SHA-256-Prüfsumme und installieren oder aktualisieren die aigateway Erweiterung. Die Installation erfordert HTTPS-Zugriff und eine Berechtigung, um in Ihr Azure CLI-Erweiterungsverzeichnis zu schreiben, erfordert jedoch keine Azure-Anmeldung. Um die Skripte vor dem Ausführen zu überprüfen, siehe install.sh oder install.ps1.

Überprüfen Sie die Installation und die verfügbaren Befehle:

az aigateway version
az aigateway --help

Wir empfehlen, Gateways mit dem früheren Ressourcentyp Microsoft.ApiManagement/service mit der AIGateway-SKU zu Microsoft.ApiManagement/aigateways zu migrieren. Schließen Sie die Migration vor dem 15. Januar 2027 ab. Befolgen Sie Migrieren zum AI Gateway-Ressourcentyp, um die Konfiguration neu zu erstellen und Clients zu aktualisieren. Die Installation oder das Upgrade der Erweiterung führt nicht zur Migration eines Gateways.

Erstellen oder wählen Sie Ihr Gateway aus

Erstellen Sie ein Testgateway oder wählen Sie eine bestehende Microsoft.ApiManagement/aigateways Ressource mit öffentlichem Laufzeitzugriff aus:

  1. Melden Sie sich an und wählen Sie das Abonnement aus, zu dem Ihr Gateway und Ihr Foundry-Konto gehören:

    az login
az account set --subscription "<subscription-id>"

  2. Setzen Sie die Standard-Ressourcengruppe auf die Gruppe, die Ihr Gateway enthält oder enthalten wird:

    az configure --defaults group="<gateway-resource-group>"

    Gateway-Befehle verwenden diesen Standard während des gesamten Quickstarts. Foundry-Befehle geben ihre eigene Ressourcengruppe an. Der Standard bleibt bestehen, bis du ihn änderst oder löschst.

  3. Setze den Gateway-Namen und die anderen Ressourcennamen. Verwenden Sie den Namen eines bestehenden Gateways oder wählen Sie einen Namen für ein neues Gateway. Ersetzen Sie die Foundry-Werte durch Ihre eigenen und wählen Sie ungenutzte Anbieter- und Schlüsselnamen:

    GATEWAY="aigw-demo-learn"
FOUNDRY_RG="aigw-microsoft-learn-docs"
FOUNDRY_ACCOUNT="ai-foundry-demo-learn"
KEY_NAME="cli-quickstart-app"

  4. Wenn du ein neues Gateway brauchst, erstelle es in einer unterstützten Region. Wenn Sie ein bestehendes Gateway ausgewählt haben, fahren Sie mit der Gateway-Prüfung fort:

    az aigateway create \
  --name "$GATEWAY" \
  --location eastus2 \
  --system-assigned true

  5. Überprüfen Sie das Gateway, das Sie erstellt oder ausgewählt haben:

    az aigateway show --name "$GATEWAY"

  6. Bestätigen Sie, dass typeMicrosoft.ApiManagement/aigateways ist und properties.provisioningStateSucceeded ist.

    {
   "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/my-resource-group/aigw-microsoft-learn-docs/providers/Microsoft.ApiManagement/aigateways/aigw-demo-learn",
   "identity": {
     "principalId": "00000000-1111-1111-1111-000000000000",
     "tenantId": "00000000-1111-1111-1111-000000000000",
     "type": "SystemAssigned"
   },
   "location": "eastus2",
   "name": "aigw-demo-learn",
   "properties": {
     "frontend": {
       "defaultHostname": "aigw-demo-learn.eastus2-01.ai.gateway.azure.com"
     },
     "provisioningState": "Succeeded"
   },
   "resourceGroup": "aigw-microsoft-learn-docs",
   "sku": {
     "name": "Premium"
   },
   "tags": {},
   "type": "Microsoft.ApiManagement/aigateways"
}

Foundry-Modelle importieren

Verbinden Sie Modelle von Microsoft Foundry, um sie in Ihrem Gateway zu verwenden. Der Importbefehl aktiviert die systemseitig zugewiesene verwaltete Identität des Gateways, gewährt ihr Foundry-Benutzer für das Konto und registriert die aktuellen Bereitstellungen des Kontos unter einem Anbieter.

Um Ihre Foundry-Bereitstellungen zu importieren:

  1. Schau dir die Ressourcen-ID des Foundry-Kontos an. Verwenden Sie den Kontonamen, nicht einen Projekt- oder Deploymentsnamen:

    FOUNDRY_RESOURCE_ID="$(az cognitiveservices account show \
  --resource-group "$FOUNDRY_RG" --name "$FOUNDRY_ACCOUNT" \
  --query id --output tsv)"

  2. Importiere die Deployments:

    az aigateway model-provider create \
  --gateway-name "$GATEWAY" \
  --name "$FOUNDRY_ACCOUNT" \
  --foundry-resource-id "$FOUNDRY_RESOURCE_ID"

  3. Überprüfen Sie die Importübersicht auf fehlgeschlagene Registrierungen, bevor Sie fortfahren. Behalten Sie die zurückgegebene roleAssignmentId für die Bereinigungsüberprüfung. Lassen Sie Zeit ein, damit eine neue Rollenzuweisung in Kraft tritt, bevor Sie die Inferenz testen.

  4. Führen Sie die importierten Modelle auf:

    az aigateway model list \
  --gateway-name "$GATEWAY" \
  --model-provider "$FOUNDRY_ACCOUNT" --output table

  5. Die Ausgabe sieht wie folgt aus:

    Name                    Provider               Kind     Model                   Version
----------------------  ---------------------  -------  ----------------------  ----------
deepseek-v4-flash       ai-foundry-demo-learn  Foundry  DeepSeek-V4-Flash       2026-04-23
fw-deepseek-v4-1-flash  ai-foundry-demo-learn  Foundry  FW-DeepSeek-V4.1-Flash  1
fw-kimi-k3              ai-foundry-demo-learn  Foundry  FW-Kimi-K3              1
gpt-6-1-sol             ai-foundry-demo-learn  Foundry  gpt-6.1-sol             2026-09-29
gpt-6-astra             ai-foundry-demo-learn  Foundry  gpt-6-astra             2026-09-03
gpt-6-luna              ai-foundry-demo-learn  Foundry  gpt-6-luna              2026-09-22
grok-4-7                ai-foundry-demo-learn  Foundry  grok-4.7                1

  6. Legen Sie MODEL auf den Registrierungsnamen einer Bereitstellung fest, die Chatvervollständigungen unterstützt. Für die Beispielbereitstellung:

    MODEL="gpt-6-1-sol"

Der Anbieter gruppiert die Modellregistrierungen für Ihr Konto.

Erstellen Sie einen Laufzeit-API-Schlüssel

Dein Terminal verwendet einen Gateway-Runtime-API-Schlüssel, um sich beim Gateway zu authentifizieren. Erstellen Sie einen separaten Schlüssel für Ihren Test, damit Sie ihn widerrufen können, ohne die Zugangsdaten einer anderen Anwendung zu ändern.

Warning

Ein Laufzeit-API-Schlüssel gewährt gateway-weiten Zugriff, nicht nur Zugriff auf das importierte Modell. Drucken Sie ihn nicht, aktivieren Sie keine Shellablaufverfolgung, zeichnen Sie ihn nicht in Transkripten auf, und committen Sie ihn nicht in die Quellcodeverwaltung. Löschen Sie den Schlüssel, wenn Sie fertig sind.

Um Ihren Testschlüssel zu erstellen und abzurufen:

  1. Erstellen Sie den Schlüssel:

    az aigateway api-key create \
  --gateway-name "$GATEWAY" \
  --name "$KEY_NAME" --display-name "CLI quickstart application"

  2. Überprüfen Sie die Ausgabe:

    {
   "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/aigw-microsoft-learn-docs/providers/Microsoft.ApiManagement/aigateways/aigw-demo-learn/apiKeys/cli-quickstart-app",
   "name": "cli-quickstart-app",
   "properties": {
     "createdDate": "2026-10-25T15:24:59.3183401Z",
     "displayName": "All APIs subscription",
     "expirationDate": null,
     "state": "active"
   },
   "resourceGroup": "aigw-microsoft-learn-docs",
   "type": "Microsoft.ApiManagement/aigateways/apiKeys"
}

  3. Rufen Sie den primären Wert in einer Shellvariablen ab:

    AI_GATEWAY_API_KEY="$(az aigateway api-key list-secrets \
  --gateway-name "$GATEWAY" \
  --name "$KEY_NAME" --query primaryKey --output tsv)"

Das Erstellen eines Schlüssels liefert Metadaten zurück. Der separate list-secrets Befehl ruft die für Laufzeitanfragen verwendeten Zugangsdaten ab.

Aufrufen des Modells

Senden Sie eine Aufforderung über das Gateway, um die Modellregistrierung, den Gateway-Schlüssel und die Foundry-Verbindung gemeinsam zu überprüfen.

Um Ihre erste Modellanfrage zu senden:

  1. Rufen Sie den zugewiesenen Hostnamen und die Laufzeitmodell-Kennung ab und erstellen Sie dann die URL für Chat Completions:

    AI_GATEWAY_HOSTNAME="$(az aigateway show \
  --name "$GATEWAY" \
  --query properties.frontend.defaultHostname --output tsv)"

AI_GATEWAY_CHAT_URL="https://${AI_GATEWAY_HOSTNAME}/default/models/openai/v1/chat/completions"

  2. Verwenden Sie den zurückgegebenen Hostnamen, anstatt ihn aus dem Gateway-Namen zu konstruieren. Die vollständige URL für Chatvervollständigungen hat das Format https://<assigned-gateway-hostname>.ai.gateway.azure.com/default/models/openai/v1/chat/completions.

  3. Senden Sie eine Anfrage für Chat Completions:

    curl "$AI_GATEWAY_CHAT_URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  --data @- <<EOF
{
  "model": "$MODEL",
  "messages": [
    {"role": "user", "content": "Give me three uses for an AI gateway."}
  ]
}
EOF

Die Antwort enthält die Erwiderung des Modells in choices[0].message.content. Eine erfolgreiche Antwort bestätigt, dass die Modellregistrierung, der Gateway-Schlüssel und die Foundry-Verbindung zusammenarbeiten.

Bereinigen von Ressourcen

Entferne nur die Ressourcen, die du für diesen Quickstart erstellt hast. Behalten Sie alle bereits vorhandenen Gateways, alle Ressourcengruppen sowie das Foundry-Konto und die Deployments auf.

Um Ihre Testkonfiguration zu entfernen:

  1. Löschen Sie den Laufzeit-API-Schlüssel und löschen Sie seinen Wert aus der Terminalsitzung:

    az aigateway api-key delete \
  --gateway-name "$GATEWAY" --name "$KEY_NAME"
unset AI_GATEWAY_API_KEY

  2. Den Testanbieter löschen:

    az aigateway model-provider delete \
  --gateway-name "$GATEWAY" --name "$FOUNDRY_ACCOUNT"

  3. Überprüfen Sie die Rollenzuweisung für Foundry User im Foundry-Konto. Wenn du es für diesen Quickstart erstellt hast, entferne es aus der Access Control (IAM) nur, wenn keine andere Gateway-Verbindung es benötigt. Behalte die verwaltete Identität des Gateways, falls andere Verbindungen sie nutzen.

  4. Wenn du ein Gateway für diesen Quickstart erstellt hast und es nicht mehr brauchst, lösche es. Führe diesen Befehl nicht für ein bereits vorhandenes Gateway aus:

    az aigateway delete --name "$GATEWAY"

  5. Überprüfe die Bestätigungsaufforderung, bevor du das Gateway löschst.

  6. Löschen Sie den Standardwert der Ressourcengruppe:

    az configure --defaults group=""

Verwandte Inhalte

  • Zuletzt aktualisiert um