Introdução ao Azure OpenAI e à API de Respostas

Este artigo mostra como usar o Azure OpenAI Starter Kit para implantar um recurso Azure OpenAI e executar um pequeno aplicativo hello world. O aplicativo usa a autenticação do Microsoft Entra ID e o SDK da OpenAI para chamar a API de Respostas do Azure OpenAI.

Ao final deste artigo, você vai:

  • Implantar o Azure OpenAI com o GPT-5-mini usando o Azure Developer CLI.
  • Execute um aplicativo local que se autentique com Microsoft Entra ID em vez de uma chave de API.
  • Envie uma solicitação para a API de Respostas e imprima a saída do modelo.

Note

Este artigo usa o Azure OpenAI Starter Kit como base para os exemplos. O kit inicial inclui infraestrutura como código, configuração da CLI do desenvolvedor Azure e exemplos de cliente para várias linguagens de programação.

Custo

Os recursos do Azure criados neste artigo são cobrados na sua assinatura do Azure. Para evitar cobranças contínuas, limpe os recursos quando terminar o artigo.

Pré-requisitos

Para concluir este artigo, você precisa do seguinte:

  • Python 3.8 ou posterior.
  • .NET SDK 10 ou posterior. O kit inicial usa aplicativos C# baseados em arquivo com diretivas de pacote.
  • Node.js 18 ou posterior.
  • Go 1.25.1 ou mais recente.
  • Java 21 ou posterior.
  • Maven 3.9 ou posterior.

Obter o código

Clone o repositório Azure OpenAI Starter Kit e abra a pasta do projeto.

git clone https://github.com/Azure-Samples/azure-openai-starter.git
cd azure-openai-starter

Entrar no Azure

Faça login no CLI do Azure e no Azure Developer CLI.

az login
azd auth login

Se sua conta tiver acesso a mais de um locatário, confirme se o locatário ativo é o locatário em que você deseja implantar os recursos.

az account show --query tenantId -o tsv

Implantar Azure OpenAI

Execute o seguinte comando da CLI do Desenvolvedor do Azure a partir da raiz do repositório:

azd up

Use as seguintes diretrizes para responder aos prompts:

Prompt Answer
Nome do ambiente Use um nome curto e minúsculo, como aoai-hello. O valor é usado em nomes de recursos do Azure.
Subscription Selecione a assinatura na qual você deseja criar os recursos.
Localização Selecione uma região perto de você.
Localização do modelo do Azure OpenAI Selecione uma região em que o GPT-5-mini está disponível.

A implantação geralmente leva vários minutos. Quando o comando for concluído, o kit inicial terá provisionado o Azure OpenAI e implantado um modelo GPT-5-mini.

Configurar o ambiente local

O aplicativo hello world usa sua conta do Azure para obter um token de acesso do Microsoft Entra. Defina o ponto de extremidade usado pelo cliente OpenAI.

export AZURE_OPENAI_ENDPOINT=$(azd env get-value AZURE_OPENAI_ENDPOINT)
export AZURE_OPENAI_DEPLOYMENT=$(azd env get-value AZURE_OPENAI_GPT_DEPLOYMENT_NAME)
export AZURE_TENANT_ID=$(az account show --query tenantId -o tsv)

Dica

Azure OpenAI usa nomes de implantação em chamadas à API. O kit inicial retorna o nome da implantação do GPT-5-mini como AZURE_OPENAI_GPT_DEPLOYMENT_NAME. Este artigo mapeia esse valor para AZURE_OPENAI_DEPLOYMENT, de modo que o código seja o mesmo em todos os idiomas.

Criar e executar o aplicativo hello world

Crie um arquivo chamado hello_world_entra.py na pasta src/python.

import os

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

endpoint = os.environ["AZURE_OPENAI_ENDPOINT"].rstrip("/")
deployment = os.getenv("AZURE_OPENAI_DEPLOYMENT", "gpt-5-mini")

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

client = OpenAI(
    base_url=f"{endpoint}/openai/v1/",
    api_key=token_provider,
)

response = client.responses.create(
    model=deployment,
    input="Say hello from Azure OpenAI in one sentence.",
    max_output_tokens=300,
)

print(response.output_text)

Instale as dependências do Python e execute o aplicativo.

cd src/python
python -m pip install -r requirements.txt
python hello_world_entra.py

Crie um arquivo chamado hello_world_entra.cs na pasta src/dotnet.

#!/usr/bin/dotnet run
#:package OpenAI@2.9.1
#:package Azure.Identity@1.*

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

#pragma warning disable OPENAI001

string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
    ?? throw new InvalidOperationException("Set AZURE_OPENAI_ENDPOINT.");
string deployment = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT")
    ?? "gpt-5-mini";

BearerTokenPolicy tokenPolicy = new(
    new DefaultAzureCredential(),
    "https://cognitiveservices.azure.com/.default");

OpenAIClientOptions options = new()
{
    Endpoint = new Uri($"{endpoint.TrimEnd('/')}/openai/v1/")
};

ResponsesClient client = new(tokenPolicy, options);

ResponseResult response = await client.CreateResponseAsync(
    deployment,
    "Say hello from Azure OpenAI in one sentence.",
    null);

Console.WriteLine(response.GetOutputText());

Execute o aplicativo.

cd src/dotnet
dotnet run hello_world_entra.cs

Crie um arquivo chamado hello_world_entra.ts na pasta src/typescript.

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

const endpoint = process.env.AZURE_OPENAI_ENDPOINT;

if (!endpoint) {
  throw new Error("Set AZURE_OPENAI_ENDPOINT.");
}

const deployment = process.env.AZURE_OPENAI_DEPLOYMENT ?? "gpt-5-mini";
const tokenProvider = getBearerTokenProvider(
  new DefaultAzureCredential(),
  "https://cognitiveservices.azure.com/.default"
);

const client = new OpenAI({
  baseURL: `${endpoint.replace(/\/+$/, "")}/openai/v1/`,
  apiKey: tokenProvider as any,
});

const response = await client.responses.create({
  model: deployment,
  input: "Say hello from Azure OpenAI in one sentence.",
  max_output_tokens: 300,
});

console.log(response.output_text);

Instale as dependências do TypeScript e execute o aplicativo.

cd src/typescript
npm install
npx tsx hello_world_entra.ts

Crie um arquivo chamado hello_world_entra.go na pasta src/go/responses_example_entra.

package main

import (
  "context"
  "fmt"
  "log"
  "net/http"
  "os"
  "strings"

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

type policyAdapter option.MiddlewareNext

func (adapter policyAdapter) Do(req *policy.Request) (*http.Response, error) {
  return (option.MiddlewareNext)(adapter)(req.Raw())
}

func newClient(endpoint string) openai.Client {
  const scope = "https://cognitiveservices.azure.com/.default"

  credential, err := azidentity.NewDefaultAzureCredential(nil)
  if err != nil {
    log.Fatalf("Failed to create DefaultAzureCredential: %s", err)
  }

  bearerTokenPolicy := runtime.NewBearerTokenPolicy(
    credential,
    []string{scope},
    nil,
  )

  return openai.NewClient(
    option.WithBaseURL(strings.TrimRight(endpoint, "/")+"/openai/v1/"),
    option.WithMiddleware(func(req *http.Request, next option.MiddlewareNext) (*http.Response, error) {
      pipeline := runtime.NewPipeline(
        "aoai-hello-world",
        "",
        runtime.PipelineOptions{},
        &policy.ClientOptions{
          PerRetryPolicies: []policy.Policy{
            bearerTokenPolicy,
            policyAdapter(next),
          },
        },
      )

      pipelineRequest, err := runtime.NewRequestFromRequest(req)
      if err != nil {
        return nil, err
      }

      return pipeline.Do(pipelineRequest)
    }),
  )
}

func main() {
  endpoint := os.Getenv("AZURE_OPENAI_ENDPOINT")
  if endpoint == "" {
    log.Fatal("Set AZURE_OPENAI_ENDPOINT.")
  }

  deployment := os.Getenv("AZURE_OPENAI_DEPLOYMENT")
  if deployment == "" {
    deployment = "gpt-5-mini"
  }

  client := newClient(endpoint)

  response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
    Model: deployment,
    Input: responses.ResponseNewParamsInputUnion{
      OfString: openai.String("Say hello from Azure OpenAI in one sentence."),
    },
    MaxOutputTokens: openai.Int(300),
  })
  if err != nil {
    log.Fatalf("Failed to create response: %s", err)
  }

  fmt.Println(response.OutputText())
}

Execute o aplicativo.

cd src/go/responses_example_entra
go run hello_world_entra.go

Crie um arquivo chamado HelloWorldEntra.java na pasta src/java/src/main/java/com/azure/openai/starter.

package com.azure.openai.starter;

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.Response;
import com.openai.models.responses.ResponseCreateParams;

import java.util.function.Supplier;

public class HelloWorldEntra {

    public static void main(String[] args) {
        String endpoint = System.getenv("AZURE_OPENAI_ENDPOINT");
        if (endpoint == null || endpoint.isBlank()) {
            throw new IllegalStateException("Set AZURE_OPENAI_ENDPOINT.");
        }

        String deployment = System.getenv().getOrDefault(
                "AZURE_OPENAI_DEPLOYMENT",
                "gpt-5-mini");

        Supplier<String> bearerTokenSupplier = AuthenticationUtil.getBearerTokenSupplier(
                new DefaultAzureCredentialBuilder().build(),
                "https://cognitiveservices.azure.com/.default");

        OpenAIClient client = OpenAIOkHttpClient.builder()
                .baseUrl(endpoint.replaceAll("/+$", "") + "/openai/v1/")
                .credential(BearerTokenCredential.create(bearerTokenSupplier))
                .build();

        Response response = client.responses().create(
                ResponseCreateParams.builder()
                        .model(deployment)
                        .input(ResponseCreateParams.Input.ofText(
                                "Say hello from Azure OpenAI in one sentence."))
                        .maxOutputTokens(300)
                        .build());

        System.out.println(response.output());
    }
}

Execute o aplicativo.

cd src/java
mvn compile exec:java -Dexec.mainClass="com.azure.openai.starter.HelloWorldEntra"

O formato de saída exato varia de acordo com o SDK. Você deverá ver a saída do modelo implantado do Azure OpenAI, que inclui uma breve saudação.

Hello from Azure OpenAI! I'm running on your Azure OpenAI deployment and ready to help.

Entender o código

O aplicativo hello world tem três partes importantes:

  • DefaultAzureCredential obtém um token do Microsoft Entra do seu login local no Azure.
  • O cliente OpenAI aponta para o endpoint do Azure OpenAI v1: /openai/v1/.
  • O valor model é o nome da implantação do Azure OpenAI. Neste kit inicial, o nome da implantação é gpt-5-mini.

O aplicativo Python usa o pacote openai com azure-identity. O get_bearer_token_provider auxiliar cria um provedor de token que o cliente OpenAI pode usar como sua credencial.

O aplicativo C# usa o pacote OpenAI com Azure.Identity. O BearerTokenPolicy adiciona tokens do Microsoft Entra às solicitações enviadas pelo ResponsesClient.

O aplicativo TypeScript usa o pacote openai com @azure/identity. O getBearerTokenProvider auxiliar cria um provedor de token que o cliente OpenAI pode usar como sua credencial.

O aplicativo Go usa azidentity.NewDefaultAzureCredential com uma política de token Bearer do Azure Core. A política é adicionada ao cliente OpenAI como middleware para que as solicitações usem tokens do Microsoft Entra ID.

O aplicativo Java usa DefaultAzureCredentialBuilder com AuthenticationUtil.getBearerTokenSupplier. O fornecedor de token é passado para o cliente OpenAI usando BearerTokenCredential.

Executar o exemplo de kit inicial

O kit inicial também inclui um exemplo de API de Respostas maior para cada idioma.

python responses_example_entra.py

dotnet run responses_example_entra.cs

npx tsx responses_example_entra.ts

go run main.go

mvn compile exec:java -Dexec.mainClass="com.azure.openai.starter.ResponsesExampleEntra"

Troubleshooting

Issue Tente fazer isto
azd up falha porque GPT-5-mini não está disponível na região selecionada. Selecione uma localização diferente para o modelo do Azure OpenAI quando solicitado ou defina outra região com azd env set AZURE_LOCATION eastus2 e execute azd up novamente.
azd up falha devido a um erro de atribuição de função ou de autorização. Verifique se sua conta pode criar recursos e atribuições de função. Proprietário ou Administrador de Acesso do Usuário são normalmente necessários para este modelo.
O aplicativo retorna 401 ou PermissionDenied. Confirme se você está conectado ao mesmo locatário e assinatura usados por azd up. Execute az login, azd auth login e defina AZURE_TENANT_ID com o ID do locatário de az account show. A propagação da atribuição de função também pode levar alguns minutos.
DefaultAzureCredential failed to retrieve a token. Confirme se CLI do Azure está instalado e autenticado com az account show. Se você usar vários locatários, entre no locatário correto com az login --tenant <tenant-id>.
O aplicativo retorna model not found ou deployment not found. Confirme se AZURE_OPENAI_DEPLOYMENT corresponde ao nome da implantação do Azure OpenAI. O padrão do kit inicial é gpt-5-mini.
O aplicativo .NET não reconhece diretivas de pacote. Instale a versão do SDK .NET exigida pelo kit inicial. Os aplicativos C# baseados em arquivo #:package exigem um SDK recente do .NET.
O aplicativo Go não consegue localizar o módulo ou as dependências. Execute os comandos Go de src/go/responses_example_entra. Confirme se a Go 1.25.1 ou posterior está instalada.
O aplicativo Java falha com um erro de versão de origem ou de destino. Confirme se Java 21 ou posterior está instalado e selecionado pelo terminal.
Você precisa de logs de implantação detalhados. Execute azd up --debug.

Você pode inspecionar os valores atuais de ambiente da CLI do Desenvolvedor Azure com:

azd env get-values

Limpar os recursos

Quando você não precisar mais dos recursos, execute o seguinte comando na raiz do repositório de kit inicial:

azd down --purge

O comando exclui os recursos Azure criados pelo kit inicial e ajuda a interromper os encargos contínuos.

Obter ajuda

Se você precisar de ajuda com o kit inicial, use estes recursos:

Próximas Etapas 

Saiba mais sobre a API de Respostas

  • Last updated on