Comece com o Azure OpenAI e a API Responses

Este artigo mostra-lhe como usar o Azure OpenAI Starter Kit para implementar um recurso Azure OpenAI e executar uma pequena aplicação hello world. A aplicação utiliza autenticação Microsoft Entra ID e o SDK OpenAI para chamar a API Azure OpenAI Respostas.

No final deste artigo, será capaz de:

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

Note

Este artigo utiliza o Azure OpenAI Starter Kit como base para os exemplos. O kit inicial inclui Infrastructure as Code, configuração da CLI do Azure Developer e exemplos de clientes para múltiplas linguagens de programação.

Custo

Os recursos do Azure criados neste artigo são faturados para a sua subscrição do Azure. Para evitar custos contínuos, limpe os recursos quando terminar o artigo.

Pré-requisitos

Para concluir este artigo, precisa de:

  • Python 3.8 ou posterior.
  • .NET SDK 10 ou posterior. O kit inicial utiliza aplicações C# baseadas em ficheiros com diretivas de pacote.
  • Node.js 18 anos ou mais.
  • Use a versão 1.25.1 ou posterior.
  • 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

Iniciar sessão no Azure

Inicie sessão tanto na CLI do Azure como na Azure Developer CLI.

az login
azd auth login

Se a sua conta tiver acesso a mais do que um inquilino, confirme que o inquilino ativo é o inquilino onde pretende utilizar os recursos.

az account show --query tenantId -o tsv

Deploy Azure OpenAI

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

azd up

Utilize as seguintes orientações para responder às perguntas:

Prompt Answer
Nome do ambiente Use um nome curto e minúsculo, como aoai-hello. O valor é usado nos nomes de recursos do Azure.
Subscrição Selecione a subscrição onde quer criar os recursos.
Localização Selecione uma região perto de si.
Localização do modelo Azure OpenAI Selecione uma região onde o GPT-5-mini esteja disponível.

A implantação normalmente demora vários minutos. Quando o comando termina, o kit inicial já provisionou o Azure OpenAI e implementou um modelo GPT-5-mini.

Configure seu ambiente local

A aplicação hello world usa o seu login no Azure para obter um token de acesso Microsoft Entra. Defina o endpoint 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)

Tip

O Azure OpenAI usa nomes de implementação nas chamadas API. O kit inicial apresenta o nome de implementação do GPT-5-mini como AZURE_OPENAI_GPT_DEPLOYMENT_NAME. Este artigo mapeia esse valor para AZURE_OPENAI_DEPLOYMENT que o código seja o mesmo em todas as línguas.

Cria e executa a aplicação hello world

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

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)

Instala as dependências em Python e executa a aplicação.

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

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

#!/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 nomeado hello_world_entra.ts na src/typescript pasta.

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);

Instala as dependências do TypeScript e executa a aplicação.

cd src/typescript
npm install
npx tsx hello_world_entra.ts

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

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 nomeado HelloWorldEntra.java na src/java/src/main/java/com/azure/openai/starter pasta.

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 exato de saída varia consoante o SDK. Deverá ver o resultado do modelo do Azure OpenAI implementado, que inclui uma breve saudação.

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

Entenda o código

A aplicação hello world tem três partes importantes:

  • DefaultAzureCredential recebe um token de Microsoft Entra do seu Azure local ao iniciar sessão.
  • O cliente OpenAI aponta para o seu endpoint Azure OpenAI v1: /openai/v1/.
  • O valor model é o nome Azure da implementação OpenAI. Neste kit inicial, o nome da implementação é gpt-5-mini.

A aplicação Python usa o pacote openai com azure-identity. O get_bearer_token_provider ajudante cria um fornecedor de tokens que o cliente OpenAI pode usar como sua credencial.

A aplicação C# usa o pacote OpenAI com Azure.Identity. O BearerTokenPolicy adiciona Microsoft Entra tokens aos pedidos enviados pelo ResponsesClient.

A aplicação TypeScript utiliza o pacote openai com @azure/identity. O getBearerTokenProvider ajudante cria um fornecedor de tokens que o cliente OpenAI pode usar como sua credencial.

A aplicação Go utiliza azidentity.NewDefaultAzureCredential com uma política de token portador Azure Core. A política é adicionada ao cliente OpenAI como middleware para que os pedidos utilizem tokens Microsoft Entra ID.

A aplicação Java usa DefaultAzureCredentialBuilder com AuthenticationUtil.getBearerTokenSupplier. O fornecedor de tokens é passado para o cliente OpenAI usando BearerTokenCredential.

Execute o exemplo do kit inicial

O kit inicial inclui também um exemplo maior da API Respostas para cada linguagem.

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"

Resolução de problemas

Problema Experimente o seguinte
azd up falha porque o GPT-5-mini não está disponível na região selecionada. Selecione uma localização diferente do 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 com um erro de atribuição de funções ou autorização. Certifique-se de que a sua conta pode criar recursos e atribuir funções. Normalmente é necessário Proprietário ou Administrador de Acesso ao Utilizador para este modelo.
A aplicação retorna 401 ou PermissionDenied. Confirme que está ligado ao mesmo inquilino e subscrição usado por azd up. Execute az login, azd auth login, e defina AZURE_TENANT_ID para o ID do inquilino a partir de az account show. A propagação de atribuição de funções também pode demorar alguns minutos.
DefaultAzureCredential failed to retrieve a token. Confirme se CLI do Azure está instalado e autenticado com az account show. Se usar vários inquilinos, inicie sessão com o inquilino correto com az login --tenant <tenant-id>.
A aplicação retorna model not found ou deployment not found. Confirme que AZURE_OPENAI_DEPLOYMENT corresponde ao nome de implementação Azure OpenAI. O kit inicial por defeito é gpt-5-mini.
A aplicação .NET não reconhece diretivas de pacotes. Instale a versão do SDK .NET exigida pelo kit inicial. Aplicações C# baseadas em ficheiros com #:package requerem um SDK de .NET recente.
A aplicação Go não consegue encontrar o módulo nem as dependências. Execute os comandos Go de src/go/responses_example_entra. Confirma se o Go 1.25.1 ou posterior está instalado.
A aplicação Java falha devido a um erro na versão de origem ou de destino. Confirma que o Java 21 ou posterior está instalado e selecionado pelo teu terminal.
Precisas de registos detalhados de implementação. Execute azd up --debug.

Pode inspecionar os valores atuais do ambiente CLI do Azure Developer com:

azd env get-values

Limpeza de recursos

Quando já não precisares dos recursos, executa o seguinte comando a partir da raiz do repositório do kit de iniciação:

azd down --purge

O comando elimina os recursos do Azure criados pelo kit inicial e ajuda a travar as cobranças em curso.

Obter ajuda

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

Passos seguintes

Saiba mais sobre a API de Respostas

  • Last updated on