Comece com a extensão CLI do Azure

APLICA-SE A: AI Gateway (pré-visualização)

Use a aigateway extensão do CLI do Azure para dar às aplicações acesso às implementações de modelos existentes do Microsoft Foundry através de um gateway partilhado.

Este quickstart introduz os az aigateway comandos e guia-o através do seu primeiro pedido de modelo a partir de um terminal Bash ou PowerShell.

Prerequisites

• CLI do Azure versão 2.75.0 ou posterior.
• Uma subscrição do Azure e um grupo de recursos existente.
• O Microsoft.ApiManagement fornecedor de recursos registou-se na sua subscrição. Consulte Registar um fornecedor de recursos.
• O papel de Contribuidor no grupo de recursos.
  • Para usar um gateway existente, precisa de Contributor nesse gateway, ou permissões equivalentes.
  • Certifique-se de que o seu recurso do Gateway de IA é do tipo Microsoft.ApiManagement/gateways ou de que tenha migrado para o mesmo.
• Uma conta Microsoft Foundry na mesma subscrição com pelo menos um modelo implementado que suporta Chat Completions e um endpoint backend acessível publicamente.
• Os papéis Leitor e Administrador de Acesso de Utilizador na conta Foundry, ou acesso herdado equivalente, para descobrir implementações e conceder acesso à identidade do gateway.
• Um terminal Bash com curl, ou um terminal PowerShell. O instalador do Bash também requer shasum ou sha256sum.

Este exemplo utiliza uma conta Foundry nomeada ai-foundry-demo-learn com uma gpt-6.1-sol implantação. Os pedidos de modelo podem incorrer em custos de inferência.

Instalar a extensão

Use o instalador do repositório AI Gateway CLI. Escolhe o comando para a tua shell:

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

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

Os instaladores descarregam a versão publicada, verificam a sua soma de verificação SHA-256 e instalam ou atualizam a aigateway extensão. A instalação requer acesso HTTPS e permissão para escrever no diretório de extensões do CLI do Azure, mas não requer login no Azure. Para rever os scripts antes de os executar, veja install.sh ou install.ps1.

Verifique a instalação e os comandos disponíveis:

az aigateway version
az aigateway --help

Recomendamos migrar gateways que utilizam o tipo de recurso anterior Microsoft.ApiManagement/service com o SKU AIGateway para Microsoft.ApiManagement/aigateways. Migração completa antes de 15 de janeiro de 2027. Siga Migrar para o tipo de recurso AI Gateway para recriar a configuração e atualizar os clientes. Instalar ou atualizar a extensão não migra um gateway.

Crie ou selecione o seu gateway

Crie um gateway de teste ou selecione um recurso existente Microsoft.ApiManagement/aigateways com acesso público em tempo de execução:

1. Inicie sessão e selecione a subscrição que contém o seu gateway e a sua conta Foundry:

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

2. Defina o grupo de recursos por defeito para o grupo que contém, ou irá conter, o seu gateway:

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

   Os comandos do gateway usam este padrão durante todo o quickstart. Os comandos do Foundry especificam o seu próprio grupo de recursos. A predefinição mantém-se até a alterar ou eliminar.

3. Define o nome do gateway e os outros nomes de recursos. Utilize o nome de um gateway existente ou escolha um nome para um novo gateway. Substitua os valores da Foundry pelos seus próprios e escolha os nomes de fornecedores e chaves não utilizados:

   • Bash
   • PowerShell

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

4. Se precisares de um novo gateway, cria-o numa região suportada. Se selecionou um gateway existente, continue até à verificação do gateway:

   • Bash
   • PowerShell

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

5. Verifique o gateway que criou ou selecionou:

   • Bash
   • PowerShell

   az aigateway show --name "$GATEWAY"
   

6. Confirma que type é Microsoft.ApiManagement/aigateways e properties.provisioningState é 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"
   }
   

Importar modelos do Foundry

Ligue modelos da Microsoft Foundry para os usar no seu gateway. O comando de importação ativa a identidade gerida atribuída pelo sistema ao gateway, concede-lhe Foundry User na conta e regista as implementações atuais da conta sob um único provedor.

Para importar as suas implantações no Foundry:

1. Procura o ID de recurso da conta da Foundry. Utilize o nome da conta, não um nome de projeto ou implementação:

   • Bash
   • PowerShell

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

2. Importar as implantações:

   • Bash
   • PowerShell

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

3. Consulte o resumo de importação para registos falhados antes de continuar. Guarda o resultado devolvido roleAssignmentId para a revisão da limpeza. Dê tempo para que uma nova atribuição de função entre em vigor antes de testar a inferência.

4. Liste os modelos importados:

   • Bash
   • PowerShell

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

5. A saída tem a seguinte aparência:

   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. Defina MODEL para o nome de registo de uma implementação que suporta Chat Completions. Para o exemplo de implementação:

   • Bash
   • PowerShell

   MODEL="gpt-6-1-sol"
   

O fornecedor agrupa os registos de modelos para a sua conta.

Criar uma chave API em tempo de execução

O seu terminal usa uma chave API de runtime do gateway para autenticar no gateway. Cria uma chave separada para o teu teste para poderes revogá-lo sem alterar as credenciais de outra aplicação.

Para criar e recuperar a sua chave de teste:

1. Crie a chave:

   • Bash
   • PowerShell

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

2. Verifique a saída:

   {
      "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. Recupere o seu valor primário numa variável shell:

   • Bash
   • PowerShell

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

Criar uma chave devolve metadados. O comando separado list-secrets recupera a credencial usada para pedidos em tempo de execução.

Invocar o modelo

Envie um prompt através do gateway para verificar o registo do modelo, a chave do gateway e a ligação Foundry em conjunto.

Para enviar o seu primeiro pedido de modelo:

1. Recupere o nome de host atribuído e o identificador do modelo em tempo de execução, e depois construa o URL de 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. Utilize o nome de anfitrião devolvido em vez de o construir a partir do nome do gateway. O URL completo de Chat Completions tem a forma https://<assigned-gateway-hostname>.ai.gateway.azure.com/default/models/openai/v1/chat/completions.

3. Envie um pedido de 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
   

A resposta inclui a réplica do modelo em choices[0].message.content. Uma resposta bem-sucedida confirma que o registo do modelo, a chave de gateway e a ligação Foundry funcionam em conjunto.

Limpeza de recursos

Remova apenas os recursos que criou para este quickstart. Mantenha qualquer gateway pré-existente, todos os grupos de recursos e a conta e as implementações do Foundry.

Para remover a sua configuração de teste:

1. Apague a chave API de runtime e limpe o seu valor da sessão do terminal:

   • Bash
   • PowerShell

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

2. Eliminar o prestador de teste:

   • Bash
   • PowerShell

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

3. Revise a atribuição da função Utilizador do Foundry na conta do Foundry. Se o criaste para este quickstart, remove-o do controlo de acesso (IAM) apenas se nenhuma outra ligação de gateway precisar dele. Mantém a identidade gerida do gateway se outras ligações a usarem.

4. Se criaste um gateway para este quickstart e já não precisas dele, apaga-o. Não execute este comando para um gateway já existente:

   • Bash
   • PowerShell

   az aigateway delete --name "$GATEWAY"
   

5. Revise o prompt de confirmação antes de apagar o gateway.

6. Limpar a predefinição do grupo de recursos:

   az configure --defaults group=""
   

Conteúdo relacionado

• Referência de comandos da CLI do AI Gateway
• Início Rápido: Crie um Gateway de IA
• Conceitos do AI Gateway
• Migrar do SKU AIGateway no API Management do Azure