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 novos sem a necessidade de especificar novos api-version todos os meses.
  • Ciclo de lançamento de API mais rápido com novos recursos sendo iniciados com mais frequência.
  • Suporte de cliente OpenAI com mínimas alterações de código para alternar entre OpenAI e Azure OpenAI ao usar 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 será controlado passando cabeçalhos de visualização específicos do recurso, permitindo que você aceite os recursos desejados, sem precisar trocar as versões da API. Como alternativa, alguns recursos indicarão o status de visualização por meio de seu caminho de API e não exigirão um cabeçalho adicional.

Exemplos:

  • Quando /openai/v1/evals 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().
  • base_url passa pelo endpoint do Azure OpenAI e /openai/v1 é acrescentado ao endereço do endpoint.
  • 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)) 
  • base_url passa pelo endpoint do Azure OpenAI e /openai/v1 é acrescentado ao endereço do endpoint.
  • api_key o parâmetro é definido como , habilitando a token_providerrecuperação automática e a atualização 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 aceitará 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 diretamente 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 da ferramenta do servidor 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 acrescentou.
  • stream_options & include_usage acrescentou.

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