Criar e gerenciar uma API de modelo unificada

APLICA-SE A: Desenvolvedor | Básico | Básico v2 | Padrão | Standard v2 | Premium | Premium v2

Você pode criar uma API unificada de modelos no Gerenciamento de API do Azure para expor vários back-ends de LLM por meio de um único endpoint voltado ao cliente. Os aplicativos cliente usam um formato de API conhecido — a API Chat Completions da OpenAI — enquanto o API Management traduz automaticamente as solicitações para os modelos de back-end usando a API Chat Completions da OpenAI ou a API Messages da Anthropic.

Centralizando o acesso de modelo por trás de uma única camada de API, você pode:

• Padronizar em um único formato de API para clientes independentemente dos formatos usados por modelos de back-end.
• Unificar observabilidade, segurança e governança com políticas entre provedores de modelo.
• Configure o failover de modelo entre provedores de modelo.
• Desacoplar os nomes de modelo exibidos ao cliente dos nomes de modelo do backend usando aliases.

Para saber mais sobre como gerenciar APIs de IA no Gerenciamento de API do Azure, consulte Recursos do gateway de IA no Gerenciamento de API do Azure.

Back-ends com suporte

A API de modelo unificado dá suporte aos seguintes formatos de API de back-end:

• API de Conclusões de Chat do OpenAI
• API de Mensagens Antropáticas

Pré-requisitos

• Uma instância de Gerenciamento de API existente. Crie uma, se ainda não tiver.
• Uma ou mais implantações de modelo em um back-end com suporte.
• Para acompanhar o uso de token pela API, consulte Emitir métricas personalizadas para pré-requisitos.
• Para impor verificações de segurança de conteúdo na API, consulte Impor verificações de segurança de conteúdo em solicitações LLM para pré-requisitos.

Criar uma API de modelo unificada – portal Azure

Use as etapas a seguir para criar uma API de modelo unificada no Gerenciamento de API.

Quando você cria a API, o Gerenciamento de API configura automaticamente:

• Um /models 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 do OpenAI Chat Completions.
• Formate a lógica de tradução para cada modelo de back-end que você adicionar.
• Recursos de backend que encaminham solicitações para o endpoint correto do provedor.

Para criar uma API de modelo unificada:

1. No portal do Azure, acesse sua instância de Gerenciamento de API.

2. No menu da barra lateral, em APIs, selecione Modelos>+ Adicionar>API de Modelo Unificado.

   

3. Na guia Configurar a API de Modelo Unificado :

   1. Insira um nome de exibição para a API. O Gerenciamento de API gera automaticamente um Nome de API com base no nome de exibição, mas você pode editá-lo se desejar.
   2. No caminho da API, insira o caminho que os clientes usam para chamar a API. O padrão é /llm/v1, o que resulta em um endpoint de conclusões de chat em /llm/v1/chat/completions.
   3. Opcionalmente, selecione um ou mais Produtos a serem associados à API.
   4. Selecione Próximo.

4. Na guia Configurar modelos, selecione+ Adicionar para abrir o painel Adicionar modelo e defina as seguintes configurações para cada implantação de modelo:

   1. Em Configuração de backend:

      • No Modelo, insira o nome do modelo de back-end (por exemplo, gpt-4o ou claude-sonnet-4.6).
      • No formato API, selecione o formato esperado pelo modelo de back-end, como OpenAI Chat Completions API ou Anthropic Messages API.
      • Em URL, insira a URL do endpoint de backend, por exemplo, o endpoint de uma implantação de modelo no Foundry ou, para outros provedores, a URL do endpoint da API do provedor.

   2. Em credenciais de autorização, selecione como o Gerenciamento de API se autentica no back-end:

      • Cabeçalhos: insira um nome de cabeçalho (por exemplo, api-key ou Authorization) e o valor de cabeçalho correspondente (sua chave de API ou segredo).
      • Managed Identity: para implantações de modelo em Azure, você pode usar a identidade gerenciada atribuída pelo sistema da instância ou uma identidade gerenciada atribuída pelo usuário para se autenticar no back-end.

      Para obter uma explicação das configurações para a identidade gerenciada, consulte a referência para a política de identidade gerenciada por autenticação .

   

5. Na guia Gerenciar consumo de token , opcionalmente, configure as seguintes políticas para monitorar e gerenciar o uso de token:

   • Gerenciar o consumo de token
   • Controlar o uso do token

6. Na guia Set up AI content safety tab, opcionalmente configure o serviço Segurança de Conteúdo de IA do Azure para bloquear prompts com conteúdo não seguro:

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

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

Gerenciar aliases de modelo

Os aliases de modelos dão aos clientes um nome estável e neutro em relação ao provedor para usar ao invocar um modelo. Ao atribuir um alias como gpt ou claude-sonnet, você desacopla o nome do modelo voltado para o cliente da implantação real no back-end. Quando você atualiza um modelo ou deseja executar um teste A/B, pode atualizar o destino do alias sem alterações no código do cliente.

Atualizar ou adicionar um alias de modelo

Para atualizar um alias de modelo depois de criar a API de modelo unificado:

1. No portal Azure, vá para a instância de Gerenciamento de API e selecione APIs.
2. Selecione a API do modelo unificado.
3. Selecione a guia Modelos para atualizar ou adicionar um alias de modelo.
   • Para atualizar um alias voltado para o cliente, selecione o alias que você deseja atualizar e atualize a configuração de back-end para especificar o modelo de back-end. Adicione credenciais de autorização para o novo back-end.
   • Para adicionar um novo modelo, selecione + Adicionar e defina as configurações de back-end, autorização e cliente, conforme descrito na seção anterior.
4. Selecione Salvar.

Descobrir aliases de modelo

Os desenvolvedores podem descobrir os modelos disponíveis e seus apelidos ao chamar o endpoint /models da API unificada de modelos. O Gerenciamento de API retorna uma lista de modelos com seus aliases voltados para o cliente.

Chamar a API de um aplicativo cliente

Os aplicativos cliente podem chamar a API de modelo unificado usando qualquer SDK compatível com OpenAI. Direcione a URL base do SDK para o endpoint do API Management e use uma chave de assinatura do API Management ou outro método de autenticação compatível.

O exemplo a seguir usa o SDK Python da OpenAI e envia uma chave de assinatura do Gerenciamento de API no cabeçalho para autenticação. O corpo da solicitação especifica um alias de modelo voltado para o cliente configurado no Gerenciamento de API, 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 alternar para um modelo de back-end diferente, altere apenas o model valor. Nenhuma outra alteração de código é necessária.

Conteúdo relacionado

• Funcionalidades do gateway de IA no Gerenciamento de API do Azure
• Importar uma API do Microsoft Foundry
• Gerenciar o consumo de token LLM
• Controlar o uso do token
• Impor verificações de segurança de conteúdo em solicitações LLM
• Habilitar o cache semântico de respostas
• Backends no Gerenciamento de API do Azure