Início rápido: Criar uma instância do escalão AI Gateway (pré-visualização)

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

Importante

O escalão AI Gateway encontra-se atualmente em versão de pré-visualização pública. Durante a pré-visualização pública, o nível AI Gateway está disponível nas seguintes regiões:

• Estados Unidos - East US 2
• Europa - Suécia Central

Neste quickstart, cria-se uma instância de nível (pré-visualização) do AI Gateway, adiciona-se um modelo de chat, liga-se ao gateway, cria-se uma chave de acesso em tempo de execução e visualiza-se a telemetria.

O nível AI Gateway do API Management do Azure é um nível dedicado para cargas de trabalho de IA. Suporta a gestão de tráfego para modelos — desde Microsoft Foundry, Azure OpenAI, AWS Bedrock, Google Vertex, OpenAI, Anthropic ou outros fornecedores — e ferramentas criadas a partir de servidores MCP existentes, definições OpenAPI ou conectores. O escalão AI Gateway é aprovisionado rapidamente, geralmente no prazo de um minuto.

Tempo para completar: cerca de 20-30 minutos. Cria: um gateway, um modelo de chat, uma chave de acesso em tempo de execução e um pedido de conclusão de chat concluído com êxito.

Note

O nível AI Gateway está em pré-visualização pública. As funcionalidades de pré-visualização são fornecidas sem um acordo de nível de serviço e não devem ser usadas para cargas de trabalho de produção, a menos que a sua organização aceite os termos da pré-visualização.

Pré-requisitos

• Uma conta Azure com Microsoft Entra ID. O acesso à pré-visualização do nível AI Gateway está atualmente limitado a utilizadores do Azure que iniciem sessão com o Microsoft Entra ID.
• Uma subscrição do Azure e permissão para criar recursos num grupo de recursos (por exemplo, o papel Contribuidor).
• Acesso a pelo menos um fornecedor de modelos suportado, como um modelo implementado no Microsoft Foundry ou no Azure OpenAI.
• Se o seu fornecedor exigir uma chave API, tenha a chave disponível.
• Para aceder ao gateway, use curl (sem instalação) ou um SDK OpenAI - Python 3.9 ou posterior, ou Node.js 18 ou posterior, com o openai pacote.

1. Iniciar sessão no portal de níveis do AI Gateway

O portal de nível AI Gateway é uma experiência web autónoma – não se usa o portal do Azure.

1. Vá ao portal de níveis do AI Gateway em ai.gateway.azure.com.
2. Selecione Iniciar sessão e autentique-se com o ID do Microsoft Entra.

Use o portal para gerir modelos, servidores MCP, chaves de acesso em tempo de execução, políticas e monitorização, com base nas suas permissões do Entra ID. Os chamadores em tempo de execução não fazem login no portal – chamam o gateway com chaves de acesso em tempo de execução que crias mais tarde.

2. Criar um gateway

1. No portal, selecione Criar gateway. Para usar um gateway já existente, selecione-o e salte para o passo seguinte.

2. Insira um Nome. O nome passa a fazer parte do endpoint de runtime:

   https://<gateway>.azure-api.net

3. Selecione a sua Subscrição e uma região de pré-visualização suportada (East US 2 ou Suécia Central).

4. Opcionalmente, define o grupo de Recursos como Avançado. Por predefinição, o portal cria um para si.

5. Selecione Criar. A ativação normalmente demora menos de um minuto.

O gateway é um recurso dedicado na sua subscrição do Azure. Não escolhes a capacidade nem adicionas unidades à escala antes de adicionares modelos. Para automação, a versão da API de gestão de pré-visualização é 2026-05-01-preview; os pedidos em tempo de execução usam o nome do host gateway, não o Azure Resource Manager.

3. Adicionar um modelo

A forma mais rápida de criar um modelo é importando-o a partir de contas da Microsoft Foundry.

1. Em Início, em Configure o seu gateway, selecione a opção Introdução ou abra a página de configuração diretamente no caminho /settings/start.

   

2. Selecione uma ou mais subscrições para analisar. Opcionalmente, aplique um filtro de grupo de recursos para restringir os resultados.

3. Analise as contas descobertas. As implementações são agrupadas pela sua conta Foundry principal (o recurso Azure). A seleção é por conta: quando selecionas uma conta, o assistente importa todas as implementações do modelo.

   

4. Escolha um método de autenticação backend para esta importação:

   • Baseado em teclas (por defeito). O gateway armazena a chave API da conta e envia-a no api-key cabeçalho. O assistente obtém a chave no momento da importação.
   • Identidade gerida (Microsoft Entra ID). O gateway autentica-se com a sua identidade gerida. Se o gateway não tiver identidade gerida, o assistente ativa uma identidade atribuída ao sistema. Se já existir, escolhes qual identidade usar. O assistente atribui à identidade a função Foundry User em cada conta selecionada.

5. Selecione Importar.

6. Quando seleciona Importar, o assistente executa uma verificação de requisitos para cada conta selecionada antes de criar qualquer coisa. Esta verificação confirma que a autenticação está configurada corretamente e que os nomes dos modelos não entram em conflito com modelos já no gateway. As contas aprovadas são importadas; as contas que falham são ignoradas com um aviso em linha, e a restante execução continua.

Para ligar um fornecedor que não seja da Foundry (AWS Bedrock, Google Vertex, OpenAI ou Anthropic), selecione Adicionar um modelo personalizado em vez disso. Veja Gerir modelos e ferramentas.

Os chamadores passam o nome do modelo no model campo de pedidos compatíveis com OpenAI. Este quickstart usa gpt-5.6-sol; substitua-o pelo modelo que registou.

Sugestão

Para experimentar o modelo imediatamente, abra a página Discover e selecione o modelo para o invocar no playground incorporado. O playground usa a chave incorporada do gateway, para que possa explorar e testar modelos ou ferramentas adicionadas antes de criar uma chave de acesso em tempo de execução.

4. Chamar o gateway

O gateway expõe a API que o modelo backend suporta. Modelos de fornecedores compatíveis com OpenAI — como Microsoft Foundry, Azure OpenAI, AWS Bedrock, Google Vertex e OpenAI — são servidos num endpoint compatível com OpenAI. Aponte qualquer cliente OpenAI para o URL base do gateway, envie um cabeçalho api-key e passe o nome do modelo no campo model. Os modelos Anthropic utilizam a API Anthropic Messages em vez disso; veja Gerir modelos e ferramentas.

Para um teste rápido, use a chave integrada do gateway — a mesma chave que o playground do Discover utiliza. Copie-o da página de Chaves , que lista a chave incorporada juntamente com as chaves API que concedem acesso em tempo de execução a todos os ativos do gateway. Para as suas próprias aplicações, crie antes uma chave de acesso em tempo de execução (ver a secção seguinte).

Defina estes valores uma vez:

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

Sugestão

Copie o URL base exato da página de visão geral do seu gateway em vez de o construir manualmente.

Faça a sua primeira chamada com o cliente da sua escolha:

curl

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

Para transmitir tokens como eventos enviados pelo servidor, adicione "stream": true ao corpo do pedido.

Python

Instale o cliente com 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)

Para transmitir tokens à medida que são gerados, adicione stream=True e itere a resposta:

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)

Node.js

Instale o pacote com 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);

Para transmitir, adicione stream: true e itere a resposta assíncrona.

Cada resposta do /chat/completions endpoint utiliza o formato OpenAI Chat Completions, seja qual for o fornecedor compatível com OpenAI que apoie o modelo.

Uma chamada não transmitida retorna a conclusão da conversa:

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

Com a transmissão ativada, o gateway devolve eventos chat.completion.chunk:

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

A mesma URL base também serve a API de Respostas do OpenAI em /responses.

Se um pedido falhar, o gateway devolve um código de estado HTTP padrão:

Status	Meaning	O que deve verificar
400	Pedido inválido	Verifique o corpo do pedido.
400	Bloqueados pela segurança de conteúdos ou por um filtro IP, ou negados pelo backend	Uma política de segurança de conteúdos pode bloquear um prompt ou resposta; verifique também qualquer política de filtro de IP. Para a identidade gerida, atribua o papel Foundry User à identidade do gateway no recurso de back-end. Consulte Utilizar identidade gerida para a autenticação da infraestrutura de back-end.
401	Chave de acesso em tempo de execução em falta ou inválida	Envia a chave no api-key cabeçalho e confirma que a chave está ativa.
404	Modelo desconhecido	Confirme que o model valor corresponde ao nome de um modelo na página de Modelos .
429	Limitado por uma política de limite de taxa ou pelo backend	Reveja as políticas de tokens e de limitação da taxa de pedidos e respeite o cabeçalho de resposta Retry-After.
5xx	Erro de backend	Confirme que o fornecedor de backend está saudável e que a credencial do prestador é válida.

Os SDKs OpenAI levantam exceções tipadas para estes códigos de estado, por isso o seu tratamento de erros existente funciona:

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. Criar uma chave de acesso em tempo de execução

As aplicações autenticam-se no gateway com uma chave de acesso em tempo de execução em vez da chave incorporada. Crie uma chave separada para cada aplicação e ambiente.

1. Selecione Chaves.
2. Selecione Criar chave de API.
3. Insira um nome, como quickstart-client.
4. Selecione Criar.
5. Copie o valor-chave e armazene-o de forma segura. Também pode vê-lo novamente mais tarde na página Chaves.

Crie chaves de acesso em tempo de execução ao nível do gateway. Estas chaves concedem acesso a todos os modelos e ferramentas no gateway. Trata-os como segredos. Armazene chaves num cofre de segredos para aplicações, efetue a sua rotação regularmente e revogue as chaves que já não são necessárias. Para chamar o gateway com uma chave de acesso em tempo de execução, defina AI_GATEWAY_API_KEY com o respetivo valor nas chamadas apresentadas anteriormente.

6. Ver telemetria

O nível do AI Gateway emite métricas de utilização de tokens OpenTelemetry. Para os ver, configure primeiro um destino de telemetria e depois envie pedidos:

1. Configure um destino de telemetria para o gateway, como o Application Insights. Veja Governar, proteger e operar.
2. Envie um ou mais pedidos através do gateway, como mostrado anteriormente em Chamar o gateway.
3. Abra o seu destino de telemetria para rever o uso do token. Se usar o Application Insights, o portal disponibiliza um painel de controlo de consumo de tokens incorporado.

Como a telemetria só é emitida depois de ligares a um destino, configura a monitorização antes de confiares nela. A utilização de tokens é atualmente a única métrica emitida; os registos, os rastreios e outras métricas para modelos e ferramentas estarão disponíveis em breve. Os que chamam usam chaves de acesso em tempo de execução ao nível do gateway, para que possa monitorizar o tráfego sem expor as credenciais do fornecedor às aplicações clientes. Para configurar um destino de telemetria, consulte Governar, proteger e operar.

Limpeza de recursos

Quando terminares, apaga quaisquer recursos que já não precises. Remova a instância de nível do AI Gateway, as implementações de teste do fornecedor e as chaves de acesso em tempo de execução que criou apenas para avaliação.

Passos seguintes

• Adicionar ferramentas MCP que os agentes possam chamar
• Aplique políticas de governação aos seus modelos e ferramentas
• Configurar redes privadas
• Gerir modelos e ferramentas
• Visão geral dos níveis do AI Gateway