Criar e gerir uma API de modelo unificada

APLICA-SE A: Developer | Basic | Basic v2 | Standard | Standard v2 | Premium | Premium v2

Pode criar uma API de modelo unificada no API Management do Azure para expor múltiplos backends de LLM através de um único endpoint voltado para o cliente. As aplicações clientes utilizam um formato de API familiar – a OpenAI Chat Completions API – enquanto a API Management traduz automaticamente os pedidos para os modelos backend usando a OpenAI Chat Completions API ou a Anthropic Messages API.

Ao centralizar o acesso ao modelo atrás de uma única camada de API, pode:

• Padronizar num único formato de API para clientes independentemente dos formatos usados pelos modelos backend.
• Unifique a observabilidade, a segurança e a governação através de políticas aplicadas aos vários fornecedores de modelos.
• Configure o failover dos modelos entre os fornecedores de modelos.
• Desacoplar os nomes dos modelos visíveis para o cliente dos nomes dos modelos de backend usando nomes alternativos.

Para saber mais sobre a gestão de APIs de IA no API Management, consulte Capacidades do gateway de IA no API Management do Azure.

Sistemas de backend suportados

A API unificada do modelo suporta os seguintes formatos de API backend:

• API de Conclusão de Chat OpenAI
• API de Mensagens Antrópicas

Pré-requisitos

• Uma instância de gerenciamento de API existente. Crie um, caso ainda não o tenha feito.
• Uma ou mais implementações de modelos num backend suportado.
• Para monitorizar a utilização de tokens pela API, consulte Emitir métricas personalizadas para conhecer os pré-requisitos.
• Para impor verificações de segurança de conteúdo na API, veja Impor verificações de segurança de conteúdo em pedidos de LLM para pré-requisitos.

Criar uma API de modelo unificada - Portal Azure

Use os seguintes passos para criar uma API unificada de modelo na API Management.

Quando cria a API, a Gestão de APIs configura automaticamente:

• /models Um endpoint para descoberta de modelos que lista todos os modelos configurados.
• Um único endpoint de roteamento, como /llm/v1/chat/completions, que aceita solicitações no formato OpenAI Chat Completions.
• Formate a lógica de tradução para cada modelo backend que adicionar.
• Recursos backend que encaminham pedidos para o endpoint correto do fornecedor.

Para criar uma API de modelo unificada:

1. No portal do Azure, vá para sua instância de Gerenciamento de API.

2. No menu lateral, em APIs, selecione Models>+ Adicionar>API unificada de modelos.

   

3. No separador Configurar API do Modelo Unificado:

   1. Introduza um nome de visualização para a API. A Gestão de APIs gera automaticamente um nome de API com base no nome de visualização, mas pode editá-lo se quiser.
   2. No caminho da API, introduza o caminho que os clientes usam para chamar a API. O padrão é /llm/v1, o que resulta num endpoint de conclusão de chat em /llm/v1/chat/completions.
   3. Opcionalmente, selecione um ou mais Produtos para associar à API.
   4. Selecione Avançar.

4. No separador Configurar modelos , selecione + Adicionar para abrir o painel Adicionar modelo , depois configure as seguintes definições para cada implementação de modelo:

   1. Em Configuração de backend:

      • No Model, introduza o nome do modelo backend (por exemplo, gpt-4o ou claude-sonnet-4.6).
      • No formato API, selecione o formato que o modelo backend espera, como OpenAI Chat Completions API ou Anthropic Messages API.
      • No URL, introduza o URL do endpoint backend, por exemplo, uma implementação de modelo no Foundry ou, para outros fornecedores, o URL do endpoint API do fornecedor.

   2. Em Credenciais de Autorização, selecione como a Gestão de API se autentica no backend:

      • Cabeçalhos: Introduza o nome do Cabeçalho (por exemplo, api-key ou Authorization) e o valor correspondente do Cabeçalho (a sua chave API ou segredo).
      • Identidade Gerida: Para implementações de modelos em Azure, pode usar a identidade gerida atribuída pelo sistema da instância ou uma identidade gerida atribuída pelo utilizador para autenticar no backend.

      Para obter uma explicação das definições da identidade gerida, consulte a referência da política authentication-managed-identity.

   

5. No separador Gerir o consumo de tokens, configure, opcionalmente, as seguintes políticas para monitorizar e gerir a utilização de tokens:

   • Gerenciar o consumo de tokens
   • Rastreie o uso do token

6. No separador Configurar segurança de conteúdo IA, configura opcionalmente o serviço de Segurança de conteúdo de IA do Azure para bloquear prompts com conteúdo inseguro:

   • Impor verificações de segurança de conteúdo em solicitações LLM

7. Selecione Rever + criar e, em seguida, selecione Criar.

Gerir aliases de modelos

Os pseudónimos de modelos dão aos clientes um nome estável e neutro em relação ao fornecedor para usar ao chamar um modelo. Ao atribuir um alias como gpt ou claude-sonnet, desacopla o nome do modelo voltado para o cliente da implementação real do backend. Quando atualizas um modelo ou queres fazer um teste A/B, podes atualizar o alvo do alias sem quaisquer alterações ao código do cliente.

Atualizar ou adicionar um alias de modelo

Para atualizar um alias de modelo após criar a API unificada do modelo:

1. No portal Azure, vai à tua instância de Gestão de APIs e depois seleciona APIs.
2. Selecione a API unificada do modelo.
3. Selecione o separador Modelos para atualizar ou adicionar um alias de modelo.
   • Para atualizar um alias virado para o cliente, selecione o alias que pretende atualizar e depois atualize a configuração do backend para especificar o modelo do backend. Adicione credenciais de autorização para o novo backend.
   • Para adicionar um novo modelo, selecione + Adicionar e configure o backend, a autorização e as definições do cliente conforme descrito na secção anterior.
4. Selecione Guardar.

Descobrir alias de modelos

Os programadores podem descobrir os modelos disponíveis e os seus pseudónimos ao chamar o /models endpoint da API unificada do modelo. A gestão de APIs devolve uma lista de modelos com os respetivos aliases visíveis para o cliente.

Chamar a API a partir de uma aplicação cliente

As aplicações cliente podem chamar a API unificada do modelo usando qualquer SDK compatível com OpenAI. Aponte a URL base do SDK para o seu endpoint de Gestão de APIs e use uma chave de subscrição de Gestão de API ou outro método de autenticação suportado para autenticação.

O exemplo seguinte utiliza o SDK OpenAI para Python e passa uma chave de subscrição do API Management no cabeçalho HTTP para autenticação. O corpo do pedido especifica um alias de modelo voltado para o cliente configurado em API Management, por exemplo, gpt ou claude-sonnet.:

from openai import OpenAI

client = OpenAI(
    base_url="https://<apim-instance>.azure-api.net/llm/v1",
    api_key="<api-management-subscription-key>",
)

# Specify the client-facing model alias
response = client.chat.completions.create(
    model="gpt",  # or "claude-sonnet", "gemini", or any other configured alias
    messages=[{"role": "user", "content": "What can you do?"}],
)
print(response.choices[0].message.content)

Para mudar para um modelo backend diferente, altere apenas o model valor. Não são necessárias outras alterações ao código.

Conteúdo relacionado

• Funcionalidades de gateway de IA na Gestão de API do Azure
• Importar uma API Microsoft Foundry
• Gerir o consumo de tokens LLM
• Rastreie o uso do token
• Impor verificações de segurança de conteúdo em solicitações LLM
• Habilitar cache semântico de respostas
• Backends em API Management do Azure