Zacznij od rozszerzenia Azure CLI

DOTYCZY: AI Gateway (podgląd)

Użyj rozszerzenia aigateway Azure CLI, aby dać aplikacjom dostęp do istniejących wdrożeń modelu Microsoft Foundry poprzez wspólną bramę.

Ten szybki start wprowadza polecenia az aigateway i przeprowadza Cię przez pierwsze żądanie modelu z terminala Bash lub PowerShell.

Prerequisites

• Azure CLI w wersji 2.75.0 lub nowszej.
• Subskrypcja Azure i istniejąca grupa zasobów.
• Microsoft.ApiManagement Dostawca zasobów zarejestrowany w ramach subskrypcji. Zobacz Rejestrowanie dostawcy zasobów.
• Rola Współtwórca w grupie zasobów.
  • Aby korzystać z istniejącej bramy, potrzebujesz roli Współautor dla tej bramy lub równoważnych uprawnień.
  • Upewnij się, że Twój zasób AI Gateway jest typu Microsoft.ApiManagement/gateways lub że zmigrowałeś do niego.
• Konto Microsoft Foundry w tej samej subskrypcji musi mieć co najmniej jeden wdrożony model obsługujący funkcję Chat Completions oraz publicznie dostępny punkt końcowy zaplecza.
• Role Reader i User Access Administrator są wymagane na koncie Foundry lub równoważny dostęp dziedziczony, aby wykrywać wdrożenia i przyznawać tożsamości bramy dostęp.
• Terminal Bash z curl, lub terminal PowerShell. Instalator Bash również wymaga shasum lub sha256sum.

Ten przykład wykorzystuje konto Foundry o nazwie ai-foundry-demo-learn z wdrożeniem gpt-6.1-sol. Żądania modeli mogą wiązać się z opłatami za wnioskowanie.

Instalowanie rozszerzenia

Użyj instalatora z repozytorium AI Gateway CLI. Wybierz komendę dla swojej powłoki:

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

irm https://aka.ms/aigateway-cli-install-ps | iex

Instalatory pobierają opublikowaną wersję, weryfikują sumę kontrolną SHA-256 oraz instalują lub aktualizują aigateway rozszerzenie. Instalacja wymaga dostępu HTTPS i uprawnień do zapisu do katalogu rozszerzenia Azure CLI, ale nie wymaga logowania do Azure. Aby przejrzeć skrypty przed ich uruchomieniem, zobacz install.sh lub install.ps1.

Sprawdź instalację i dostępne polecenia:

az aigateway version
az aigateway --help

Zalecamy migrację bram typu wcześniejszego zasobu Microsoft.ApiManagement/service z jednostką SKU AIGateway do Microsoft.ApiManagement/aigateways. Zakończ migrację przed 15 stycznia 2027 roku. Postępuj zgodnie z Migrowanie do typu zasobu AI Gateway, aby odtworzyć konfigurację i zaktualizować klientów. Instalacja lub aktualizacja rozszerzenia nie powoduje migracji bramy.

Utwórz lub wybierz swój gateway

Stwórz testową bramę lub wybierz Microsoft.ApiManagement/aigateways istniejący zasób z publicznym dostępem w czasie działania:

1. Zaloguj się i wybierz subskrypcję, która zawiera Twój gateway i konto Foundry:

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

2. Ustaw domyślną grupę zasobów na grupę, która zawiera lub będzie zawierać Twoją bramę:

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

   Polecenia bramki używają tego ustawienia domyślnego w całym przewodniku szybkiego startu. Polecenia Foundry określają własną grupę zasobów. Ustawienie domyślne pozostaje, dopóki go nie zmienisz lub nie zresetujesz.

3. Ustaw nazwę bramy i pozostałe nazwy zasobów. Użyj nazwy istniejącej bramy lub wybierz nazwę dla nowej bramy. Zastąp wartości Foundry swoimi i wybierz nieużywane nazwy dostawców i kluczy:

   • Bash
   • PowerShell

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

4. Jeśli potrzebujesz nowej bramy, stwórz ją w obsługiwanym regionie. Jeśli wybrałeś istniejącą bramę, przejdź do sprawdzania bramy:

   • Bash
   • PowerShell

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

5. Sprawdź bramę, którą stworzyłeś lub wybrałeś:

   • Bash
   • PowerShell

   az aigateway show --name "$GATEWAY"
   

6. Upewnij się, że type jest to Microsoft.ApiManagement/aigateways i properties.provisioningState ma wartość Succeeded.

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

Importowane modele odlewniczy

Połącz modele z Microsoft Foundry, aby używać ich w swojej bramie. Polecenie import włącza przypisaną przez system tożsamość zarządzaną bramy, przyznaje jej rolę Foundry User na koncie i rejestruje aktualne wdrożenia konta pod jednym dostawcą.

Aby zaimportować swoje wdrożenia w Foundry:

1. Znajdź identyfikator zasobu konta Foundry. Używaj nazwy konta, a nie nazwy projektu czy wdrożenia:

   • Bash
   • PowerShell

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

2. Importuj wdrożenia:

   • Bash
   • PowerShell

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

3. Przed kontynuowaniem przejrzyj podsumowanie importu pod kątem nieudanych rejestracji. Zachowaj zwrócony element roleAssignmentId do przeglądu porządkowego. Daj czas na wejście w życie nowego przypisania roli, zanim przejdzie się do testowania wnioskowania.

4. Wymień importowane modele:

   • Bash
   • PowerShell

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

5. Dane wyjściowe wyglądają następująco:

   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. Ustaw MODEL na nazwę rejestracyjną wdrożenia, które obsługuje Chat Completions. Dla przykładowego wdrożenia:

   • Bash
   • PowerShell

   MODEL="gpt-6-1-sol"
   

Dostawca grupuje rejestracje modeli dla Twojego konta.

Stwórz klucz API środowiska uruchomieniowego

Twój terminal używa klucza API uruchomieniowego bramy do uwierzytelniania się do bramy. Stwórz osobny klucz do testu, aby móc go unieważnić bez zmiany poświadczeń innej aplikacji.

Aby utworzyć i pobrać swój klucz testowy:

1. Stwórz klucz:

   • Bash
   • PowerShell

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

2. Sprawdź wynik:

   {
      "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. Pobierz jego wartość podstawową do zmiennej powłoki:

   • Bash
   • PowerShell

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

Tworzenie klucza zwraca metadane. Oddzielne list-secrets polecenie pobiera dane uwierzytelniające używane do żądań w czasie wykonywania.

Wywołaj model

Wyślij przez bramę prompt, aby zweryfikować rejestrację modelu, klucz bramy i połączenie z Foundry razem.

Aby wysłać swoje pierwsze zapytanie do modelu:

1. Pobierz przypisaną nazwę hosta i identyfikator modelu wykonawczego, a następnie zbuduj adres URL Chat Completions:

   • Bash
   • PowerShell

   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. Użyj zwróconej nazwy hosta zamiast tworzyć ją na podstawie nazwy bramy. Pełny adres URL Chat Completions ma formę https://<assigned-gateway-hostname>.ai.gateway.azure.com/default/models/openai/v1/chat/completions.

3. Wyślij żądanie Chat Completions:

   • Bash
   • PowerShell

   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
   

Odpowiedź zawiera odpowiedź modelu w choices[0].message.content. Udana odpowiedź potwierdza, że rejestracja modelu, klucz bramowy i połączenie z Foundry współpracują.

Uprzątnij zasoby

Usuń tylko te zasoby, które stworzyłeś do tego szybkiego startu. Zachowaj wszelką istniejącą bramę, wszystkie grupy zasobów oraz konto Foundry i wdrożenia.

Aby usunąć konfigurację testową:

1. Usuń klucz API środowiska uruchomieniowego i usuń jego wartość z sesji terminala:

   • Bash
   • PowerShell

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

2. Usuń dostawcę testowego:

   • Bash
   • PowerShell

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

3. Przejrzyj przypisanie roli użytkownika Foundry na koncie Foundry. Jeśli stworzyłeś go dla tego szybkiego startu, usuń go z kontroli dostępu (IAM) tylko wtedy, gdy żadne inne połączenie bramki tego nie wymaga. Zachowaj zarządzaną tożsamość bramy, jeśli inne połączenia ją używają.

4. Jeśli utworzyłeś bramę do tego szybkiego startu i już jej nie potrzebujesz, usuń ją. Nie uruchamiaj tego polecenia dla istniejącej bramy sieciowej:

   • Bash
   • PowerShell

   az aigateway delete --name "$GATEWAY"
   

5. Przed usunięciem bramki przejrzyj monit potwierdzenia.

6. Wyczyść domyślną grupę zasobów:

   az configure --defaults group=""
   

Treści powiązane

• Referencja poleceń AI Gateway CLI
• Szybki przewodnik: Utwórz AI Gateway
• Podstawowe pojęcia AI Gateway
• Przejście z jednostki SKU AIGateway w usłudze Azure API Management