Azure OpenAI na API Microsoft Foundry Models v1

Este artigo mostra como usar a API do OpenAI Azure v1. A API v1 simplifica a autenticação, remove a necessidade de parâmetros datados api-version e dá suporte a chamadas de modelo entre provedores.

Nota

Novos objetos de resposta de API podem ser adicionados à resposta da API a qualquer momento. Recomendamos que você analise apenas os objetos de resposta necessários.

Pré-requisitos

Evolução da API

Anteriormente, Azure OpenAI recebia atualizações mensais de novas versões de API. Aproveitar os novos recursos exigia atualizar constantemente o código e as variáveis de ambiente a cada nova versão da API. Azure OpenAI também exigiu a etapa extra de usar Azure clientes específicos que criaram sobrecarga ao migrar código entre OpenAI e Azure OpenAI.

A partir de agosto de 2025, você pode optar pela próxima geração v1 Azure APIs OpenAI que adicionam suporte para:

  • Acesso contínuo aos recursos mais recentes, sem necessidade de especificar novos api-versiona cada mês.
  • Ciclo de lançamento de API mais rápido com novos recursos sendo iniciados com mais frequência.
  • Suporte ao cliente OpenAI com alterações mínimas de código para trocar entre OpenAI e OpenAI do Azure ao usar a autenticação baseada em chave.
  • Suporte ao cliente OpenAI para autenticação baseada em token e atualização automática de token sem a necessidade de assumir uma dependência em um cliente OpenAI Azure separado.
  • Faça chamadas de conclusão de chat com modelos de outros provedores, como DeepSeek e Grok, que dão suporte à sintaxe de conclusões de chat v1.

O acesso a novas chamadas à API que ainda estão em versão prévia é controlado passando cabeçalhos de visualização específicos do recurso. Essa abordagem permite que você opte pelos recursos desejados, sem precisar trocar as versões da API. Alternativamente, alguns recursos indicam o status de prévia pelo caminho da API e não exigem um cabeçalho adicional.

Exemplos:

  • Quando /openai/v1/evals ainda estava em versão prévia, era necessário enviar o cabeçalho "aoai-evals":"preview". /evals não está mais em versão prévia.
  • /openai/v1/fine_tuning/alpha/graders/ está em versão prévia e não requer nenhum cabeçalho personalizado devido à presença no caminho da alpha API.

Para o lançamento inicial da API GA (Disponibilidade Geral) v1, apenas um subconjunto das funcionalidades de inferência e criação da API é suportado. Todos os recursos de GA têm suporte para uso em produção. O suporte para mais recursos está sendo adicionado rapidamente.

Alterações de código

API v1

Python v1 exemplos

Chave de API:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
)

response = client.responses.create(   
  model="gpt-4.1-nano", # Replace with your model deployment name 
  input="This is a test.",
)

print(response.model_dump_json(indent=2)) 

Principais diferenças da API anterior:

  • OpenAI() o cliente é usado em vez de AzureOpenAI().
  • Passe o ponto de extremidade do OpenAI do Azure para base_url e anexe /openai/v1 ao endereço do ponto de extremidade.
  • api-version não é mais um parâmetro necessário com a API ga v1.

Chave de API com variáveis de ambiente:

Defina as seguintes variáveis de ambiente antes de executar o código:

Variável Valor
OPENAI_BASE_URL https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/
OPENAI_API_KEY Sua chave de API openai do Azure

Em seguida, crie o cliente sem parâmetros:

client = OpenAI()

Microsoft Entra ID:

Importante

O gerenciamento da atualização automática de token era anteriormente feito por meio do uso do cliente AzureOpenAI(). A API v1 remove essa dependência adicionando suporte automático de atualização de token ao OpenAI() cliente.

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",  
  api_key = token_provider  
)

response = client.responses.create(
    model="gpt-4.1-nano",
    input= "This is a test" 
)

print(response.model_dump_json(indent=2)) 
  • Passe o ponto de extremidade do OpenAI do Azure para base_url e anexe /openai/v1 ao endereço do ponto de extremidade.
  • Defina o parâmetro api_key como token_provider para habilitar a obtenção e a atualização automáticas de um token de autenticação em vez de usar uma chave de API estática.

Suporte ao modelo

Para Azure modelos OpenAI, recomendamos usar a API Responses, no entanto, a API v1 também permite que você faça chamadas de conclusão de chat com modelos de outros provedores, como DeepSeek e Grok, que dão suporte à sintaxe de conclusões de chat do OpenAI v1.

base_url aceita ambos https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/ e https://YOUR-RESOURCE-NAME.services.ai.azure.com/openai/v1/ formatos.

Nota

A API de Respostas também funciona com modelos de Foundry vendidos por Azure, como modelos de IA Microsoft, DeepSeek e Grok. Para saber como usar a API de Respostas com esses modelos, consulte Como gerar respostas de texto com modelos Microsoft foundry.

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",  
  api_key=token_provider,
)
completion = client.chat.completions.create(
  model="MAI-DS-R1", # Replace with your model deployment name.
  messages=[
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Tell me about the attention is all you need paper"}
  ]
)

#print(completion.choices[0].message)
print(completion.model_dump_json(indent=2))

Suporte à API v1

Registro de alterações da versão da API

As seções a seguir resumem as alterações entre as versões da API.

Alterações entre a versão prévia da v1 e a versão 2025-04-01-preview

  • API de visualização v1
  • Suporte à geração de vídeo
  • NOVIDADES Recursos da API de respostas:
    • Integração com a ferramenta de servidores do Protocolo de Contexto de Modelo Remoto (MCP)
    • Suporte para tarefas em segundo plano assíncronas
    • Itens de raciocínio criptografados
    • Geração de imagem

Alterações entre 2025-04-01-preview e 2025-03-01-preview

Alterações entre 2025-03-01-preview e 2025-02-01-preview

Alterações entre 2025-02-01-preview e 2025-01-01-preview

  • Conclusões armazenadas (suporte à API de destilação).

Alterações entre 2025-01-01-preview e 2024-12-01-preview

Alterações entre 2024-12-01-preview e 2024-10-01-preview

Alterações entre 2024-09-01-preview e 2024-08-01-preview

  • max_completion_tokens adicionado para dar suporte aos modelos o1-preview e o1-mini. max_tokens não funciona com os modelos da série o1 .
  • parallel_tool_calls Adicionado.
  • completion_tokens_details & reasoning_tokens adicionado.
  • stream_options & include_usage adicionado.

Alterações entre a especificação da API 2024-07-01-preview e 2024-08-01-preview

  • Suporte a saídas estruturadas.
  • API de upload para arquivos grandes adicionada.
  • Em suas alterações de dados:
    • Integração do Mongo DB.
    • role_information parâmetro removido.
    • rerank_score adicionado ao objeto de citação.
    • Fonte de dados AML removida.
    • Melhorias de integração na vetorização de Pesquisa de IA.

Alterações entre a especificação da API 2024-05-01-preview e 2024-07-01-preview

Alterações entre a especificação da API 2024-04-01-preview e 2024-05-01-preview

Alterações entre a especificação da API 2024-03-01-preview e 2024-04-01-preview

Problemas conhecidos

  • A especificação 2025-04-01-preview Azure OpenAI usa OpenAPI 3.1. É um problema conhecido que essa versão não é totalmente compatível com Gerenciamento de API do Azure.

Próximas etapas