Importar uma API do OpenAI do Azure

APLICA-SE A: todas as camadas do Gerenciamento de API

Você pode importar pontos de extremidade de modelo de IA implantados em Serviço OpenAI do Azure nos Modelos Foundry para sua instância do Gerenciamento de API como uma API REST. Use políticas de gateway de IA e outros recursos no Gerenciamento de API para simplificar a integração, melhorar a observabilidade e aprimorar o controle sobre os pontos de extremidade do modelo.

Este artigo mostra duas opções para importar uma API do Azure OpenAI para uma instância de Gerenciamento de API do Azure como uma API REST:

Importar uma API do Azure OpenAI diretamente do Azure OpenAI (recomendado)
Baixar e adicionar a especificação OpenAPI para o OpenAI do Azure e adicioná-la ao Gerenciamento de API como uma API OpenAPI.

Saiba mais sobre como gerenciar APIs de IA no Gerenciamento de API:

Funcionalidades do gateway de IA no Gerenciamento de API do Azure

Pré-requisitos

Uma instância de Gerenciamento de API existente. Crie uma, se ainda não tiver.
Um recurso do OpenAI do Azure com um modelo implantado. Para obter mais informações sobre a implantação de modelo no Azure OpenAI, consulte o guia de implantação de recursos.

Anote a ID (o nome) da implantação. Você precisará dela ao testar a API importada no Gerenciamento de API.

Observação

As políticas de Gerenciamento de API, como azure-openai-token-limit e azure-openai-emit-token-metric , têm suporte para determinados pontos de extremidade de API expostos por meio de modelos específicos do Azure OpenAI. Para obter mais informações, consulte modelos do Azure OpenAI com suporte.
Permissões para conceder acesso ao recurso do OpenAI do Azure da instância de Gerenciamento de API.

Opção 1. Importar a API do Azure OpenAI

Você pode importar uma API openai do Azure diretamente do Azure OpenAI para o Gerenciamento de API.

Observação

Atualmente, esse recurso não está disponível em workspaces.

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

Operações para cada um dos pontos de extremidade da API REST do Azure OpenAI
Uma identidade atribuída pelo sistema com as permissões necessárias para acessar o recurso do OpenAI do Azure.
Um recurso de back-end e uma política set-backend-service que direcionam as solicitações de API para o ponto de extremidade do Serviço OpenAI do Azure.
Autenticação para o back-end do Azure OpenAI usando a identidade gerenciada atribuída pelo sistema da instância.
(opcionalmente) Políticas para ajudá-lo a monitorar e gerenciar a API do Azure OpenAI.

Para importar uma API do OpenAI do Azure para o Gerenciamento de API:

No portal do Azure, navegue até a instância do Gerenciamento de API.
No menu do lado esquerdo, em APIs, selecione APIs>+ Adicionar API.
Em Criar a partir do recurso do Azure, selecione Azure OpenAI.
No guia Básico:
1. Selecione o recurso do OpenAI do Azure que você quer importar.
2. Opcionalmente, selecione uma versão da API do OpenAI do Azure. Se você não selecionar uma, a versão mais recente da API REST pronta para a produção será usada por padrão. Anote a versão selecionada. Você precisará dela para testar a API.
3. Insira um Nome de exibição e uma Descrição opcional para a API.
4. Na URL de Base, acrescente um caminho que sua instância de Gerenciamento de API usará para acessar os pontos de extremidade da API do OpenAI do Azure. Se você habilitar Garantir a compatibilidade do SDK da OpenAI (recomendado), /openai será acrescentado automaticamente à URL de Base.
  
  Por exemplo, se o seu ponto de extremidade do gateway do Gerenciamento de API for https://contoso.azure-api.net, defina uma URL de Base semelhante a https://contoso.azure-api.net/my-openai-api/openai.
5. Opcionalmente, selecione um ou mais produtos e os associe à API. Selecione Avançar.
Na guia Políticas , opcionalmente, habilite políticas para ajudar a monitorar e gerenciar a API. Você também pode definir ou editar políticas posteriormente.

Se selecionado, insira as configurações ou aceite os padrões que definem as políticas a seguir (consulte artigos vinculados para pré-requisitos e detalhes de configuração):
Selecione Examinar + criar.
Após as configurações terem sido validadas, selecione Criar.

Opção 2. Adicionar a especificação OpenAPI ao Gerenciamento de API

Alternativamente, baixe manualmente a especificação OpenAPI para a API REST do OpenAI do Azure e a adicione ao Gerenciamento de API como uma API OpenAPI.

Baixar a especificação OpenAPI

Baixe a especificação OpenAPI para a API REST do Azure OpenAI, como a versão 2024-10-21 GA.

Em um editor de texto, abra o arquivo de especificação que você baixou.
No elemento servers da especificação, substitua o nome do ponto de extremidade do Serviço OpenAI do Azure nos valores de espaço reservado do ponto de extremidade url e default na especificação. Por exemplo, se o ponto de extremidade do Serviço OpenAI do Azure for contoso.openai.azure.com, atualize o elemento servers com os seguintes valores:
- url: https://contoso.openai.azure.com/openai
- ponto de extremidade padrão:contoso.openai.azure.com
```
[...]
"servers": [
    {
      "url": "https://contoso.openai.azure.com/openai",
      "variables": {
        "endpoint": {
          "default": "contoso.openai.azure.com"
        }
      }
    }
  ],
[...]
```
Anote o valor da API version na especificação. Você precisará dela para testar a API. Exemplo: 2024-10-21.

Adicionar a especificação OpenAPI para o Gerenciamento de API

No portal do Azure, navegue até a instância do Gerenciamento de API.
No menu à esquerda, selecione APIs >+Adicionar API.
Em Definir uma nova API, selecione OpenAPI. Insira um Nome de exibição e um Nome para a API.
Insira um sufixo de URL de API que termine em /openai para acessar os pontos de extremidade da API do OpenAI do Azure na sua instância de Gerenciamento de API. Exemplo: my-openai-api/openai.
Selecione Criar.

A API é importada e exibe as operações da especificação OpenAPI.

Configurar a autenticação para a API do OpenAI do Azure

Para se autenticar na API do OpenAI do Azure, você deve fornecer uma chave de API ou uma identidade gerenciada. Se você importou a API do OpenAI do Azure diretamente para a sua instância de Gerenciamento de API, a autenticação usando a identidade gerenciada da instância de Gerenciamento de API será configurada automaticamente.

Se adicionou a API do OpenAI do Azure da sua especificação OpenAPI, você precisará configurar a autenticação. Para obter mais informações sobre como configurar a autenticação usando políticas de Gerenciamento de API, confira Autenticar-se e autorizar a API do OpenAI do Azure.

Testar a API do OpenAI do Azure

Para garantir que a API do OpenAI do Azure esteja funcionando conforme o esperado, teste-a no console de testes do Gerenciamento de API. Você precisa fornecer uma ID de implantação de modelo (nome) configurada no recurso Azure OpenAI e na versão da API para testar a API.

Selecione a API que você criou na etapa anterior.
Selecione a guia Testar.
Selecione uma operação que seja compatível com o modelo que você implantou no recurso do OpenAI do Azure. A página mostra os campos dos parâmetros e cabeçalhos.
Nos Parâmetros de modelo, insira os seguintes valores:
- deployment-id – a ID de uma implantação no Azure OpenAI
- api-version — uma versão válida da API do OpenAI do Azure, como a versão da API que você selecionou quando importou a API.
Insira outros parâmetros e cabeçalhos conforme necessário. Dependendo da operação, talvez seja necessário configurar ou atualizar um corpo da solicitação.

Observação

No console de teste, o Gerenciamento de API preenche automaticamente um cabeçalho Ocp-Apim-Subscription-Key e configura a chave de assinatura da assinatura interna de acesso total. Essa chave permite o acesso a todas as API na instância de Gerenciamento de API. Opcionalmente, exiba o cabeçalho Ocp-Apim-Subscription-Key selecionando o ícone "olho" ao lado da Solicitação HTTP.
Selecione Enviar.

Quando o teste é bem-sucedido, o back-end responde com um código de resposta HTTP bem-sucedido e alguns dados. Acrescentados à resposta estão os dados de uso de token para ajudá-lo a monitorar e gerenciar o consumo de token da API OpenAI do Azure.

Comentários

Esta página foi útil?

Last updated on 2025-05-16