Início rápido: Crie uma instância da camada do Gateway de IA (versão prévia)

APLICA-SE A: camada do gateway de IA (versão preliminar)

Importante

A camada AI Gateway está atualmente em versão prévia pública. Durante a prévia pública, o nível AI Gateway está disponível nas seguintes regiões:

Estados Unidos - Leste dos EUA 2
Europa - Suécia Central

Neste Início Rápido, você vai criar uma instância da camada do gateway de IA (versão preliminar), adicionar um modelo de chat, fazer uma chamada ao gateway, criar uma chave de acesso de runtime e exibir a telemetria.

O nível AI Gateway do Gerenciamento de API do Azure é um nível dedicado para cargas de trabalho de IA. Ele suporta o gerenciamento de tráfego para modelos — de Microsoft Foundry, Azure OpenAI, AWS Bedrock, Google Vertex, OpenAI, Anthropic ou outros provedores — e ferramentas criadas a partir de servidores MCP existentes, definições OpenAPI ou conectores. A camada do AI Gateway é provisionada rapidamente, geralmente em até um minuto.

Tempo para concluir: cerca de 20-30 minutos. Você cria: um gateway, um modelo de chat, uma chave de acesso em tempo de execução e uma solicitação de conclusão bem-sucedida do chat.

Note

A camada do AI Gateway está em versão prévia 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 sua organização aceite os termos de pré-visualização.

Pré-requisitos

Uma conta Azure com Microsoft Entra ID. O acesso à prévia de níveis do AI Gateway atualmente é limitado a usuários do Azure que fazem login com o Microsoft Entra ID.
Uma assinatura do Azure e permissão para criar recursos em um grupo de recursos (por exemplo, o papel de Contribuidor).
Acesso a pelo menos um provedor de modelos suportado, como um modelo implantado no Microsoft Foundry ou no Azure OpenAI.
Se seu provedor exigir uma chave de API, tenha a chave disponível.
Para chamar o gateway, use curl (sem instalação) ou o SDK da OpenAI — Python 3.9 ou superior, ou Node.js 18 ou superior, com o pacote openai.

O portal de nível AI Gateway é uma experiência web independente – você não usa o portal do Azure.

Acesse o portal de camada do gateway de IA em ai.gateway.azure.com.
Selecione Login e autenticar com o Microsoft Entra ID.

Use o portal para gerenciar modelos, servidores MCP, chaves de acesso em tempo de execução, políticas e monitoramento, com base nas permissões do seu Entra ID. Os chamadores de runtime não entram no portal; eles fazem chamadas ao gateway com chaves de acesso de runtime que você criará mais tarde.

2. Criar um gateway

No portal, selecione Criar gateway. Para usar um gateway existente em vez disso, selecione-o e pule para a próxima etapa.
Insira um Nome. O nome passa a fazer parte do endpoint de runtime:

https://<gateway>.azure-api.net
Selecione sua Assinatura e uma região de pré-visualização suportada (Leste dos EUA 2 ou Suécia Central).
Opcionalmente, coloque o grupo de Recursos em Avançado. Por padrão, o portal cria um para você.
Selecione Criar. A ativação normalmente leva menos de um minuto.

O gateway é um recurso dedicado na sua assinatura do Azure. Você não escolhe a capacidade nem adiciona unidades de escala antes de adicionar modelos. Para automação, a versão da API de gerenciamento de pré-visualização é 2026-05-01-preview; as requisições em tempo de execução usam o nome do host gateway, não o Azure Resource Manager.

3. Adicionar um modelo

A maneira mais rápida de criar um modelo é importando-o das contas da Microsoft Foundry.

Na página Home, em Configure seu gateway, selecione a opção Primeiros passos ou abra diretamente a página de configuração no caminho /settings/start.
Selecione uma ou mais assinaturas para escanear. Opcionalmente, aplique um filtro de grupo de recursos para restringir os resultados.
Revise as contas descobertas. As implantações são agrupadas pela conta mãe do Foundry (o recurso do Azure). A seleção é por conta: quando você seleciona uma conta, o assistente importa todas as implantações do modelo.
Escolha um método de autenticação backend para essa importação:
- Baseado em chaves (padrão). O gateway armazena a chave API da conta e a envia no api-key cabeçalho. O assistente recupera a chave no momento da importação.
- Identidade gerenciada (Microsoft Entra ID). O gateway se autentica usando sua identidade gerenciada. Se o gateway não tiver uma identidade gerenciada, o assistente habilitará uma identidade atribuída ao sistema. Se já existir uma, você escolhe qual identidade usar. O assistente concede à identidade a função Usuário do Foundry em cada conta selecionada.
Selecione Importar.
Quando você seleciona Importar, o assistente executa uma verificação de requisitos para cada conta selecionada antes de criar qualquer coisa. Essa verificação confirma que a autenticação está configurada corretamente e que os nomes dos modelos não entram em conflito com modelos já existentes no gateway. Contas aprovadas são importadas; contas que falham são ignoradas com um aviso em linha, e o restante da execução continua.

Para conectar um provedor que não seja da Foundry (AWS Bedrock, Google Vertex, OpenAI ou Anthropic), selecione Adicionar um modelo personalizado. Veja Gerenciar modelos e ferramentas.

Quem faz a chamada passa o nome do modelo no campo model em solicitações compatíveis com a OpenAI. Este Início Rápido usa gpt-5.6-sol; substitua-o pelo modelo que você registrou.

Dica

Para testar o modelo imediatamente, abra a página Discover e selecione o modelo para invocá-lo no playground embutido. O playground usa a chave incorporada do gateway, então você pode explorar e testar modelos ou ferramentas adicionadas antes de criar uma chave de acesso em runtime.

4. Chamar o gateway

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

Para realizar um teste rápido, use a chave integrada do gateway — a mesma chave que o playground do Discover usa. Copie isso da página Keys, que lista a chave interna junto com as chaves de API que concedem acesso em tempo de execução a todos os recursos no gateway. Para suas próprias aplicações, crie uma chave de acesso em tempo de execução (veja a próxima seção).

Defina esses valores uma vez:

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

Dica

Copie a URL base exata da página de visão geral do seu gateway em vez de construí-la manualmente.

Faça sua primeira ligação com o cliente de sua escolha:

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 da solicitação.

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 conforme eles 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)

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 fazer streaming, adicione stream: true e itere a resposta assíncrona.

Toda resposta do ponto de extremidade /chat/completions usa o formato do OpenAI Chat Completions, independentemente do provedor compatível com OpenAI por trás do modelo.

Uma chamada sem streaming exibe a conclusão do chat:

{
  "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 o streaming ativado, o gateway retorna chat.completion.chunk eventos:

{
  "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 atende à API de Respostas do OpenAI em /responses.

Se uma solicitação falhar, o gateway retorna um código de status HTTP padrão:

Status	Meaning	O que verificar
400	Solicitação inválida	Verifique o corpo da solicitação.
400	Bloqueados por segurança de conteúdo ou por um filtro de IP, ou negados pelo backend	Uma política de segurança de conteúdo pode bloquear um prompt ou resposta; Também verifique qualquer política de filtro de IP. Para a identidade gerenciada, atribua a função Usuário do Foundry à identidade do gateway no recurso de back-end. Consulte Usar a identidade gerenciada para autenticação de back-end.
401	Chave de acesso de runtime ausente ou inválida	Envie a chave no `api-key` cabeçalho e confirme que a chave está ativa.
404	Modelo desconhecido	Confirme se 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 back-end	Analise as políticas de token e de limitação de taxa das solicitações e respeite o cabeçalho de resposta `Retry-After`.
5xx	Erro de servidor	Confirme que o provedor de backend está saudável e que a credencial do prestador é válida.

Os SDKs OpenAI geram exceções tipadas para esses códigos de status, entã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 o gateway com uma chave de acesso em tempo de execução em vez da chave embutida. Crie uma chave separada para cada aplicação e ambiente.

Selecione Chaves.
Escolha Criar chave de API.
Insira um nome, como quickstart-client.
Selecione Criar.
Copie o valor-chave e armazene de forma segura. Você também pode vê-lo novamente mais tarde na página Keys.

Crie chaves de acesso em tempo de execução no nível do gateway. Essas chaves concedem acesso a todos os modelos e ferramentas do gateway. Trata-os como segredos. Armazene chaves em um armazenamento secreto para aplicativos, faça a rotação delas regularmente e revogue as chaves que não são mais necessárias. Para chamar o gateway com uma chave de acesso em tempo de execução, defina AI_GATEWAY_API_KEY como seu valor nas chamadas mostradas anteriormente.

6. Veja telemetria

O nível do gateway de IA emite métricas de uso de tokens do OpenTelemetry. Para vê-los, configure primeiro um destino de telemetria e depois envie as requisições:

Configure um destino de telemetria para o gateway, como Application Insights. Veja Governar, garantir e operar.
Envie uma ou mais solicitações pelo gateway, como mostrado anteriormente em Chame o gateway.
Abra seu destino de telemetria para revisar o uso do token. Se você usar o Application Insights, o portal oferece um painel de consumo de tokens embutido.

Como a telemetria só é emitida depois que você conecta um destino, configure o monitoramento antes de depender dele. O uso de tokens é, no momento, a única métrica emitida; logs, rastreamentos e outras métricas para modelos e ferramentas estarão disponíveis em breve. Os chamadores usam chaves de acesso de runtime em nível de gateway, então você pode monitorar o tráfego sem expor as credenciais do provedor aos aplicativos cliente. Para configurar um destino de telemetria, veja Governar, proteger e operar.

Limpar os recursos

Quando terminar, exclua todos os recursos que não precisar mais. Remova a instância de nível do gateway de IA, as implantações de teste do provedor e as chaves de acesso em runtime que você criou apenas para avaliação.

Próximas Etapas

Comentários

Esta página foi útil?

Last updated on 2026-08-04