Suporte à linguagem Azure OpenAI SDK

Use os SDKs OpenAI com o endpoint OpenAI v1 do Azure para construir aplicações de inferência de modelos em Python, C#, JavaScript, Java ou Go. Os exemplos utilizam a API Respostas para novas aplicações e mostram Conversas Completas para aplicações que ainda utilizam a sua interface baseada em mensagens.

Pré-requisitos

  • Uma assinatura do Azure. Cria um gratuitamente se não tiveres um.
  • Um recurso Azure OpenAI com uma gpt-5-mini implementação de modelo.
  • O seu endpoint de recurso Azure OpenAI, como https://YOUR-RESOURCE-NAME.openai.azure.com.
  • Para a autenticação Microsoft Entra ID, uma identidade que tem permissão para executar inferência. Para opções de funções, consulte Configurar autenticação do Microsoft Entra ID.
  • Para autenticação de chave API, uma chave de recurso Azure OpenAI. O Microsoft Entra ID é recomendado para aplicações de produção.
  • Um runtime de linguagem suportado e gestor de pacotes para a linguagem que selecionar.

O model valor em cada pedido é o nome do seu modelo de implementação no Azure. Os exemplos usam gpt-5-mini; substitui se a tua implementação tiver um nome diferente.

Código-fonte | Pacote | Superfície API

Os exemplares foram testados com OpenAI as versões 2.12.0, Azure.Identity 1.21.0 e .NET 8. O pacote OpenAI também visa versões .NET Standard 2.0 e .NET posteriores.

Instale os pacotes

Instale os pacotes OpenAI e Azure Identity:

dotnet add package OpenAI
dotnet add package Azure.Identity

Os comandos adicionam ambas as referências de pacotes ao seu projeto.

Crie uma resposta com o Microsoft Entra ID

Usar DefaultAzureCredential e BearerTokenPolicy autenticar sem armazenar uma chave API.

using Azure.Identity;
using OpenAI.Responses;
using System.ClientModel.Primitives;

#pragma warning disable OPENAI001

var endpoint = new Uri(
    "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/");
var tokenPolicy = new BearerTokenPolicy(
    new DefaultAzureCredential(),
    "https://ai.azure.com/.default");
var openAIClient = new ResponsesClient(
    tokenPolicy,
    new ResponsesClientOptions { Endpoint = endpoint });

var response = await openAIClient.CreateResponseAsync(
    "gpt-5-mini",
    "Explain the purpose of an API in one sentence.");
Console.WriteLine(response.Value.GetOutputText());

A saída seguinte é representativa. A redação exata pode variar:

An API allows software applications to communicate and exchange data through a defined set of rules.

Referência: ResponsesClient

Crie uma resposta com uma chave API

As chaves API não são recomendadas para uso em produção. Armazene a chave na AZURE_OPENAI_API_KEY variável ambiente em vez de a colocar no código-fonte.

export AZURE_OPENAI_API_KEY="<your-api-key>"

Depois cria o cliente e solicita:

using OpenAI.Responses;
using System.ClientModel;

#pragma warning disable OPENAI001

var endpoint = new Uri(
    "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/");
var apiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY")
    ?? throw new InvalidOperationException("AZURE_OPENAI_API_KEY is required.");
var openAIClient = new ResponsesClient(
    new ApiKeyCredential(apiKey),
    new ResponsesClientOptions { Endpoint = endpoint });

var response = await openAIClient.CreateResponseAsync(
    "gpt-5-mini",
    "Explain the purpose of an API in one sentence.");
Console.WriteLine(response.Value.GetOutputText());

A saída seguinte é representativa. A redação exata pode variar:

An API allows software applications to communicate and exchange data through a defined set of rules.

Referência: CreateResponseAsync

Usar Completões de Chat

Para novas aplicações, utilize a API Responses. Use o Chat Completions quando precisar da sua interface baseada em mensagens ou estiver a manter uma aplicação já existente.

using Azure.Identity;
using OpenAI;
using OpenAI.Chat;
using System.ClientModel.Primitives;

#pragma warning disable OPENAI001

var endpoint = new Uri(
    "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/");
var tokenPolicy = new BearerTokenPolicy(
    new DefaultAzureCredential(),
    "https://ai.azure.com/.default");
var openAIClient = new ChatClient(
    model: "gpt-5-mini",
    authenticationPolicy: tokenPolicy,
    options: new OpenAIClientOptions { Endpoint = endpoint });

var completion = await openAIClient.CompleteChatAsync([
    new SystemChatMessage("You are a helpful assistant."),
    new UserChatMessage("Explain the purpose of an API.")
]);
Console.WriteLine(completion.Value.Content[0].Text);

A saída seguinte é representativa. A redação exata pode variar:

An API allows software applications to communicate and exchange data through a defined set of rules.

Referência: ChatClient

Transmita uma resposta

Chamadas CreateResponseStreamingAsync e processamentos de data delta de texto à medida que o modelo as gera:

using OpenAI.Responses;
using System.ClientModel;

#pragma warning disable OPENAI001

var endpoint = new Uri(
    "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/");
var apiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY")
    ?? throw new InvalidOperationException("AZURE_OPENAI_API_KEY is required.");
var openAIClient = new ResponsesClient(
    new ApiKeyCredential(apiKey),
    new ResponsesClientOptions { Endpoint = endpoint });

// Stream text as the model generates it.
var updates = openAIClient.CreateResponseStreamingAsync(
    "gpt-5-mini",
    "Explain the purpose of an API in one sentence.");
await foreach (var update in updates)
{
    if (update is StreamingResponseOutputTextDeltaUpdate delta)
    {
        Console.Write(delta.Delta);
    }
}

A seguinte saída transmitida em streaming é representativa. A redação exata pode variar:

An API allows software applications to communicate and exchange data through a defined set of rules.

Referência: CreateResponseStreamingAsync

Lidar com erros e tentativas repetidas

O cliente tenta automaticamente as respostas HTTP 408, 429, 500, 502, 503 e 504 com recuo exponencial. Configura a política de retentativa através das opções do cliente quando precisares de comportamentos diferentes. Catch ClientResultException para inspecionar o estado HTTP e os detalhes de erro de um pedido falhado.

Para diagnósticos, mantém o ClientResult<T> retorno de uma operação e inspeciona os seus cabeçalhos de resposta brutos. Operações falhadas expõem informações de estado através de ClientResultException.

Referência: Gestão de erros e detalhes dos resultados do cliente

Mais exemplos de SDK

Código-fonte | Pacote | Referência | Go API reference

Os exemplos exigem Go 1.25 ou posterior. Foram testados com github.com/openai/openai-go/v3 3.44.0 e azidentity 1.14.0.

Instalar os módulos

Instale os módulos OpenAI e Azure Identity:

go get github.com/openai/openai-go/v3
go get github.com/Azure/azure-sdk-for-go/sdk/azidentity

O sufixo /v3 é necessário porque identifica a versão principal atual do módulo Go.

Crie uma resposta com o Microsoft Entra ID

Use DefaultAzureCredential a opção de autenticação do Azure para autenticar sem armazenar uma chave API.

package main

import (
	"context"
	"fmt"

	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/azure"
	"github.com/openai/openai-go/v3/option"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	credential, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil { panic(err) }
	endpoint := "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
	openaiClient := openai.NewClient(
		option.WithBaseURL(endpoint),
		azure.WithTokenCredential(credential, azure.WithTokenCredentialScopes(
			[]string{"https://ai.azure.com/.default"})))
	response, err := openaiClient.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: openai.ChatModel("gpt-5-mini"),
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String(
			"Explain the purpose of an API in one sentence.")},
	})
	if err != nil { panic(err) }
	fmt.Println(response.OutputText())
}

A saída seguinte é representativa. A redação exata pode variar:

An API allows software applications to communicate and exchange data through a defined set of rules.

Referência: ResponseService.New e WithTokenCredentialScopes

Crie uma resposta com uma chave API

As chaves API não são recomendadas para uso em produção. Armazene a chave na AZURE_OPENAI_API_KEY variável ambiente em vez de a colocar no código-fonte.

export AZURE_OPENAI_API_KEY="<your-api-key>"

Depois cria o cliente e solicita:

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/option"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	apiKey := os.Getenv("AZURE_OPENAI_API_KEY")
	if apiKey == "" { panic("AZURE_OPENAI_API_KEY is required") }
	endpoint := "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
	openaiClient := openai.NewClient(
		option.WithBaseURL(endpoint),
		option.WithAPIKey(apiKey))
	response, err := openaiClient.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: openai.ChatModel("gpt-5-mini"),
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String(
			"Explain the purpose of an API in one sentence.")},
	})
	if err != nil { panic(err) }
	fmt.Println(response.OutputText())
}

A saída seguinte é representativa. A redação exata pode variar:

An API allows software applications to communicate and exchange data through a defined set of rules.

Referência: Responses.New

Usar Completões de Chat

Para novas aplicações, utilize a API Responses. Use o Chat Completions quando precisar da sua interface baseada em mensagens ou estiver a manter uma aplicação já existente.

package main

import (
	"context"
	"fmt"

	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/azure"
	"github.com/openai/openai-go/v3/option"
)

func main() {
	credential, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil { panic(err) }
	endpoint := "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
	openaiClient := openai.NewClient(
		option.WithBaseURL(endpoint),
		azure.WithTokenCredential(credential, azure.WithTokenCredentialScopes(
			[]string{"https://ai.azure.com/.default"})))
	completion, err := openaiClient.Chat.Completions.New(context.Background(),
		openai.ChatCompletionNewParams{
			Model: openai.ChatModel("gpt-5-mini"),
			Messages: []openai.ChatCompletionMessageParamUnion{
				openai.DeveloperMessage("You are a helpful assistant."),
				openai.UserMessage("Explain the purpose of an API.")}})
	if err != nil { panic(err) }
	fmt.Println(completion.Choices[0].Message.Content)
}

A saída seguinte é representativa. A redação exata pode variar:

An API allows software applications to communicate and exchange data through a defined set of rules.

Referência: Chat.Completions.New

Transmita uma resposta

Chame Responses.NewStreaming, e processe eventos delta de texto à medida que o modelo os gera:

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/option"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	endpoint := "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
	openaiClient := openai.NewClient(option.WithBaseURL(endpoint),
		option.WithAPIKey(os.Getenv("AZURE_OPENAI_API_KEY")))
	// Stream text as the model generates it.
	stream := openaiClient.Responses.NewStreaming(context.Background(), responses.ResponseNewParams{
		Model: openai.ChatModel("gpt-5-mini"),
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String(
			"Explain the purpose of an API in one sentence.")},
	})
	for stream.Next() { fmt.Print(stream.Current().Delta) }
	if err := stream.Err(); err != nil { panic(err) }
}

A seguinte saída transmitida em streaming é representativa. A redação exata pode variar:

An API allows software applications to communicate and exchange data through a defined set of rules.

Referência: Responses.NewStreaming

Lidar com erros e tentativas repetidas

O SDK tenta novamente erros de ligação e as respostas HTTP 408, 409, 429 e 5xx duas vezes com recuo exponencial. Usa option.WithMaxRetries para mudar o padrão. Verifique o retorno error antes de ler uma resposta, e use errors.As para inspecionar um openai.Error.

package main

import (
	"context"
	"errors"
	"fmt"
	"os"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/option"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	endpoint := "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
	openaiClient := openai.NewClient(option.WithBaseURL(endpoint),
		option.WithAPIKey(os.Getenv("AZURE_OPENAI_API_KEY")), option.WithMaxRetries(4))
	// Send the request and inspect structured service errors.
	result, err := openaiClient.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: openai.ChatModel("gpt-5-mini"),
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Explain an API.")},
	})
	if err != nil {
		var apiError *openai.Error
		if errors.As(err, &apiError) { fmt.Printf("Status: %d; Request ID: %s\n",
			apiError.StatusCode, apiError.Response.Header.Get("x-request-id")) }
		panic(err)
	}
	fmt.Println(result.OutputText())
}

Para um pedido bem-sucedido, o resultado seguinte é representativo. A redação exata pode variar:

An API allows software applications to communicate and exchange data through a defined set of rules.

Referência: Erros e tentativas repetidas

Mais exemplos de SDK

Código-fonte | Pacote | Referência | Referência à API Java

Os exemplos requerem Java 8 ou posterior. Foram testados com openai-java 4.43.0 e azure-identity 1.18.4.

Instale os pacotes

Maven

Adicione as dependências OpenAI e Azure Identity ao seu projeto Maven:

<dependencies>
  <dependency>
    <groupId>com.openai</groupId>
    <artifactId>openai-java</artifactId>
                <version>4.43.0</version>
  </dependency>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.18.4</version>
  </dependency>
</dependencies>

O Maven resolve os pacotes e as suas dependências transitivas quando constróis o projeto.

Gradle

Adicione os mesmos pacotes ao dependencies bloco no seu ficheiro de build do Gradle:

dependencies {
        implementation("com.openai:openai-java:4.43.0")
        implementation("com.azure:azure-identity:1.18.4")
}

O Gradle resolve os pacotes quando constróis o projeto.

Crie uma resposta com o Microsoft Entra ID

Usar DefaultAzureCredential e BearerTokenCredential autenticar sem armazenar uma chave API.

import com.azure.identity.AuthenticationUtil;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.credential.BearerTokenCredential;
import com.openai.models.responses.ResponseCreateParams;

public class ResponsesExample {
    public static void main(String[] args) {
        String endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/";
        OpenAIClient openAIClient = OpenAIOkHttpClient.builder()
                .baseUrl(endpoint)
                .credential(BearerTokenCredential.create(
                        AuthenticationUtil.getBearerTokenSupplier(
                                new DefaultAzureCredentialBuilder().build(),
                                "https://ai.azure.com/.default")))
                .build();
        ResponseCreateParams params = ResponseCreateParams.builder()
                .model("gpt-5-mini")
                .input("Explain the purpose of an API in one sentence.")
                .build();
        openAIClient.responses().create(params).output().stream()
                .flatMap(item -> item.message().stream())
                .flatMap(message -> message.content().stream())
                .flatMap(content -> content.outputText().stream())
                .forEach(output -> System.out.println(output.text()));
    }
}

A saída seguinte é representativa. A redação exata pode variar:

An API allows software applications to communicate and exchange data through a defined set of rules.

Referência: AzureEntraIdExample e ResponsesExample

Crie uma resposta com uma chave API

Não uses chaves API para produção. Armazene a chave na AZURE_OPENAI_API_KEY variável ambiente em vez de a colocar no código-fonte.

export AZURE_OPENAI_API_KEY="<your-api-key>"

Depois cria o cliente e solicita:

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;

public class ApiKeyResponsesExample {
    public static void main(String[] args) {
        String endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/";
        String apiKey = System.getenv("AZURE_OPENAI_API_KEY");
        if (apiKey == null) throw new IllegalStateException(
                "AZURE_OPENAI_API_KEY is required.");
        OpenAIClient openAIClient = OpenAIOkHttpClient.builder()
                .baseUrl(endpoint).apiKey(apiKey).build();
        ResponseCreateParams params = ResponseCreateParams.builder()
                .model("gpt-5-mini")
                .input("Explain the purpose of an API in one sentence.")
                .build();
        openAIClient.responses().create(params).output().stream()
                .flatMap(item -> item.message().stream())
                .flatMap(message -> message.content().stream())
                .flatMap(content -> content.outputText().stream())
                .forEach(output -> System.out.println(output.text()));
    }
}

A saída seguinte é representativa. A redação exata pode variar:

An API allows software applications to communicate and exchange data through a defined set of rules.

Referência: OpenAIOkHttpClient

Usar Completões de Chat

Para novas aplicações, utilize a API Responses. Use o Chat Completions quando precisar da sua interface baseada em mensagens ou estiver a manter uma aplicação já existente.

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.chat.completions.ChatCompletionCreateParams;

public class ChatExample {
    public static void main(String[] args) {
        String endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/";
        String apiKey = System.getenv("AZURE_OPENAI_API_KEY");
        if (apiKey == null) throw new IllegalStateException(
                "AZURE_OPENAI_API_KEY is required.");
        OpenAIClient openAIClient = OpenAIOkHttpClient.builder()
                .baseUrl(endpoint).apiKey(apiKey).build();
        ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
                .model("gpt-5-mini")
                .addDeveloperMessage("You are a helpful assistant.")
                .addUserMessage("Explain the purpose of an API.")
                .build();
        openAIClient.chat().completions().create(params).choices().stream()
                .flatMap(choice -> choice.message().content().stream())
                .forEach(System.out::println);
    }
}

A saída seguinte é representativa. A redação exata pode variar:

An API allows software applications to communicate and exchange data through a defined set of rules.

Referência: ChatCompletionCreateParams

Transmita uma resposta

Chame createStreaming, e processe eventos delta de texto à medida que o modelo os gera:

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.http.StreamResponse;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseStreamEvent;

public class StreamingExample {
    public static void main(String[] args) {
        String endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/";
        String apiKey = System.getenv("AZURE_OPENAI_API_KEY");
        if (apiKey == null) throw new IllegalStateException(
                "AZURE_OPENAI_API_KEY is required.");
        OpenAIClient openAIClient = OpenAIOkHttpClient.builder()
                .baseUrl(endpoint).apiKey(apiKey).build();
        // Stream text as the model generates it.
        ResponseCreateParams params = ResponseCreateParams.builder()
                .model("gpt-5-mini")
                .input("Explain the purpose of an API in one sentence.")
                .build();
        try (StreamResponse<ResponseStreamEvent> stream =
                openAIClient.responses().createStreaming(params)) {
            stream.stream().flatMap(event -> event.outputTextDelta().stream())
                    .forEach(delta -> System.out.print(delta.delta()));
        }
    }
}

A seguinte saída transmitida em streaming é representativa. A redação exata pode variar:

An API allows software applications to communicate and exchange data through a defined set of rules.

Referência: responses.createStreaming

Lidar com erros e tentativas repetidas

O SDK tenta novamente erros de ligação e as respostas HTTP 408, 409, 429 e 5xx duas vezes com recuo exponencial. Catch OpenAIServiceException para inspecionar o estado HTTP e os detalhes de erro para uma resposta de serviço, e detectar OpenAIException outras falhas do SDK.

Pede maxRetriesOpenAIOkHttpClient.builder() para mudar o padrão. Preserve a exceção de serviço para que a sua aplicação possa registar o seu estado e pedir metadados.

Referência: Tratamento de erros e retentativas

Mais exemplos de SDK

Código-fonte | Pacote | Referência | Azure OpenAI v1 guidance

Os exemplos exigem Node.js 20 ou mais tarde. Foram testados com openai 6.46.0 e @azure/identity 4.13.1. Use openai a 5.18.0 ou posterior quando passar por um fornecedor de tokens Microsoft Entra como apiKey.

Instale os pacotes

Instale os pacotes OpenAI e Azure Identity:

npm install openai @azure/identity

O comando adiciona ambos os pacotes ao teu projeto.

Crie uma resposta com o Microsoft Entra ID

Usar DefaultAzureCredential e getBearerTokenProvider autenticar sem armazenar uma chave API. O fornecedor de tokens atualiza o token de acesso quando necessário.

import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
import OpenAI from "openai";

const endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/";
const tokenProvider = getBearerTokenProvider(
  new DefaultAzureCredential(),
  "https://ai.azure.com/.default",
);
const openai = new OpenAI({ baseURL: endpoint, apiKey: tokenProvider });

async function main() {
  const response = await openai.responses.create({
    model: "gpt-5-mini",
    input: "Explain the purpose of an API in one sentence.",
  });
  console.log(response.output_text);
}

main().catch(console.error);

A saída seguinte é representativa. A redação exata pode variar:

An API allows software applications to communicate and exchange data through a defined set of rules.

Referência: OpenAI cliente e autenticação Azure OpenAI v1

Crie uma resposta com uma chave API

As chaves API não são recomendadas para uso em produção. Armazene a chave na AZURE_OPENAI_API_KEY variável ambiente em vez de a colocar no código-fonte.

export AZURE_OPENAI_API_KEY="<your-api-key>"

Depois cria o cliente e solicita:

import OpenAI from "openai";

const endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/";
const apiKey = process.env["AZURE_OPENAI_API_KEY"];
if (!apiKey) throw new Error("AZURE_OPENAI_API_KEY is required.");

const openai = new OpenAI({ baseURL: endpoint, apiKey });

async function main() {
  const response = await openai.responses.create({
    model: "gpt-5-mini",
    input: "Explain the purpose of an API in one sentence.",
  });
  console.log(response.output_text);
}

main().catch(console.error);

A saída seguinte é representativa. A redação exata pode variar:

An API allows software applications to communicate and exchange data through a defined set of rules.

Referência: responses.create

Usar Completões de Chat

Para novas aplicações, utilize a API Responses. Use o Chat Completions quando precisar da sua interface baseada em mensagens ou estiver a manter uma aplicação já existente.

import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
import OpenAI from "openai";

const endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/";
const tokenProvider = getBearerTokenProvider(
  new DefaultAzureCredential(),
  "https://ai.azure.com/.default",
);
const openai = new OpenAI({ baseURL: endpoint, apiKey: tokenProvider });

async function main() {
  const completion = await openai.chat.completions.create({
    model: "gpt-5-mini",
    messages: [
      { role: "system", content: "You are a helpful assistant." },
      { role: "user", content: "Explain the purpose of an API." },
    ],
  });
  console.log(completion.choices[0]?.message.content ?? "No response returned.");
}

main().catch(console.error);

A saída seguinte é representativa. A redação exata pode variar:

An API allows software applications to communicate and exchange data through a defined set of rules.

Manter messages dentro do pedido fornece a tipagem contextual necessária para os role valores. Se definir o array separadamente, declare-o como OpenAI.Chat.ChatCompletionMessageParam[].

Referência: chat.completions.create

Transmita uma resposta

Defina stream para true, e processe eventos delta de texto à medida que o modelo os gera:

import OpenAI from "openai";

const endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/";
const apiKey = process.env["AZURE_OPENAI_API_KEY"];
if (!apiKey) throw new Error("AZURE_OPENAI_API_KEY is required.");
const openai = new OpenAI({ baseURL: endpoint, apiKey });

async function main() {
  // Stream text as the model generates it.
  const stream = await openai.responses.create({
    model: "gpt-5-mini",
    input: "Explain the purpose of an API in one sentence.",
    stream: true,
  });
  for await (const event of stream) {
    if (event.type === "response.output_text.delta") {
      process.stdout.write(event.delta);
    }
  }
}

main().catch(console.error);

A seguinte saída transmitida em streaming é representativa. A redação exata pode variar:

An API allows software applications to communicate and exchange data through a defined set of rules.

Referência: responses.create streaming

Lidar com erros e tentativas repetidas

O SDK tenta automaticamente erros de ligação, timeouts, respostas HTTP 408, 409, 429 e 5xx duas vezes com backoff exponencial. Defina maxRetries o OpenAI cliente para mudar este comportamento. Catch APIError para inspecionar o estado HTTP, ID do pedido e detalhes de erro para um pedido falhado.

O exemplo seguinte estabelece quatro tentativas e regista o ID do pedido para pedidos bem-sucedidos e falhados:

import OpenAI from "openai";

const endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/";
const apiKey = process.env["AZURE_OPENAI_API_KEY"];
if (!apiKey) throw new Error("AZURE_OPENAI_API_KEY is required.");
const openai = new OpenAI({ baseURL: endpoint, apiKey, maxRetries: 4 });

async function main() {
  try {
    // Send the request and record its request ID.
    const response = await openai.responses.create({
      model: "gpt-5-mini",
      input: "Explain the purpose of an API in one sentence.",
    });
    console.log(response.output_text);
    console.log(`Request ID: ${response._request_id}`);
  } catch (error) {
    if (error instanceof OpenAI.APIError) {
      console.error(`Status: ${error.status}; Request ID: ${error.requestID}`);
    }
    throw error;
  }
}

main().catch(console.error);

Para um pedido bem-sucedido, o resultado seguinte é representativo. A mensagem de texto da resposta e o ID do pedido variam:

An API allows software applications to communicate and exchange data through a defined set of rules.
Request ID: <request-id>

Referência: Solicitar IDs, erros e tentativas repetidas

Mais exemplos de SDK

Código-fonte | Pacote | Referência da API

Os exemplos requerem Python 3.9 ou posterior. Foram testados com openai 2.46.0 e azure-identity 1.25.3. Use openai a versão 1.106.0 ou posterior quando passar por um fornecedor de tokens Microsoft Entra como api_key.

Instale os pacotes

Instale os pacotes OpenAI e Azure Identity:

pip install openai azure-identity

O comando instala ambos os pacotes no ambiente Python ativo.

Crie uma resposta com o Microsoft Entra ID

Usar DefaultAzureCredential e get_bearer_token_provider autenticar sem armazenar uma chave API. O fornecedor de tokens atualiza o token de acesso quando necessário.

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

endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)
openai = OpenAI(base_url=endpoint, api_key=token_provider)

response = openai.responses.create(
    model="gpt-5-mini",
    input="Explain the purpose of an API in one sentence.",
)
print(response.output_text)

A saída seguinte é representativa. A redação exata pode variar:

An API allows software applications to communicate and exchange data through a defined set of rules.

Referência: OpenAI cliente e get_bearer_token_provider

Crie uma resposta com uma chave API

As chaves API não são recomendadas para uso em produção. Armazene a chave na AZURE_OPENAI_API_KEY variável ambiente em vez de a colocar no código-fonte.

export AZURE_OPENAI_API_KEY="<your-api-key>"

Depois cria o cliente e solicita:

import os
from openai import OpenAI

endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
api_key = os.environ["AZURE_OPENAI_API_KEY"]
openai = OpenAI(base_url=endpoint, api_key=api_key)

response = openai.responses.create(
    model="gpt-5-mini",
    input="Explain the purpose of an API in one sentence.",
)
print(response.output_text)

A saída seguinte é representativa. A redação exata pode variar:

An API allows software applications to communicate and exchange data through a defined set of rules.

Referência: responses.create

Usar Completões de Chat

Para novas aplicações, utilize a API Responses. Use o Chat Completions quando precisar da sua interface baseada em mensagens ou estiver a manter uma aplicação já existente.

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

endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)
openai = OpenAI(base_url=endpoint, api_key=token_provider)

completion = openai.chat.completions.create(
    model="gpt-5-mini",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain the purpose of an API."},
    ],
)
print(completion.choices[0].message.content)

A saída seguinte é representativa. A redação exata pode variar:

An API allows software applications to communicate and exchange data through a defined set of rules.

Referência: chat.completions.create

Transmita uma resposta

Defina stream para True, e processe eventos delta de texto à medida que o modelo os gera:

import os
from openai import OpenAI

endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
openai = OpenAI(
    base_url=endpoint,
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
)

# Stream text as the model generates it.
stream = openai.responses.create(
    model="gpt-5-mini",
    input="Explain the purpose of an API in one sentence.",
    stream=True,
)
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

A seguinte saída transmitida em streaming é representativa. A redação exata pode variar:

An API allows software applications to communicate and exchange data through a defined set of rules.

Referência: responses.create streaming

Lidar com erros e tentativas repetidas

O SDK tenta automaticamente erros de ligação, timeouts, respostas HTTP 408, 409, 429 e 5xx duas vezes com backoff exponencial. Defina max_retries o OpenAI cliente para mudar este comportamento. Catch openai.APIStatusError para inspecionar o estado HTTP, ID do pedido e resposta a um pedido falhado.

O exemplo seguinte estabelece quatro tentativas e regista o ID do pedido para pedidos bem-sucedidos e falhados:

import os
import openai as openai_sdk
from openai import OpenAI

endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
openai = OpenAI(
    base_url=endpoint,
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    max_retries=4,
)

try:
    # Send the request and record its request ID.
    response = openai.responses.create(
        model="gpt-5-mini",
        input="Explain the purpose of an API in one sentence.",
    )
    print(response.output_text)
    print(f"Request ID: {response._request_id}")
except openai_sdk.APIStatusError as error:
    print(f"Status: {error.status_code}; Request ID: {error.request_id}")
    raise

Para um pedido bem-sucedido, o resultado seguinte é representativo. A mensagem de texto da resposta e o ID do pedido variam:

An API allows software applications to communicate and exchange data through a defined set of rules.
Request ID: <request-id>

Referência: Solicitar IDs, erros e tentativas repetidas

Mais exemplos de SDK

Resolução de problemas

  • Para uma 401 resposta de OR403, confirme que a identidade pretendida ou a chave API pode aceder ao recurso Azure OpenAI.
  • Para uma 404 resposta, confirme que a URL base termina em /openai/v1/ e que model contém um nome de implementação válido.
  • Para um erro de pacote ou tipo, atualize o SDK e compare a versão instalada com a versão testada nesta página.
  • Para um erro de parâmetro do modelo, verifique se o modelo implementado suporta o parâmetro. O suporte a parâmetros pode diferir entre famílias de modelos.

Conteúdo relacionado

  • Last updated on