Introducción a Azure OpenAI y la API de respuestas

En este artículo se muestra cómo usar el kit de inicio de OpenAI de Azure para implementar un recurso de OpenAI Azure y ejecutar una aplicación hola mundo pequeña. La aplicación usa la autenticación de Microsoft Entra ID y el SDK de OpenAI para llamar a la Responses API de Azure OpenAI.

Al final de este artículo, hará lo siguiente:

  • Implemente Azure OpenAI con GPT-5-mini mediante la CLI de Azure Developer.
  • Ejecute una aplicación local que se autentique con Microsoft Entra ID en lugar de una clave de API.
  • Envíe una solicitud a la API de respuestas e imprima la salida del modelo.

Note

En este artículo se usa el Azure OpenAI Starter Kit como base para los ejemplos. El kit de inicio incluye infraestructura como código, Azure configuración de la CLI para desarrolladores y ejemplos de cliente para varios lenguajes de programación.

Costo

Los recursos de Azure creados en este artículo se facturan a la suscripción de Azure. Para evitar cargos en curso, limpie los recursos cuando termine el artículo.

Prerequisites

Para completar este artículo, necesitará lo siguiente:

  • Python 3.8 o posterior.
  • .NET SDK 10 o posterior. El kit de inicio usa aplicaciones de C# basadas en archivos con directivas de paquete.
  • Node.js 18 o una versión posterior.
  • Vaya a la versión 1.25.1 o posterior.
  • Java 21 o posterior.
  • Maven 3.9 o posterior.

Obtención del código

Clone el repositorio de Azure OpenAI Starter Kit y abra la carpeta del proyecto.

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

Iniciar sesión en Azure

Inicie sesión con el CLI de Azure y la CLI para desarrolladores de Azure.

az login
azd auth login

Si la cuenta tiene acceso a más de un inquilino, confirme que el inquilino activo es el inquilino donde desea implementar los recursos.

az account show --query tenantId -o tsv

Implementación de Azure OpenAI

Ejecute el siguiente comando Azure cli para desarrolladores desde la raíz del repositorio:

azd up

Use las instrucciones siguientes para responder a las indicaciones:

Prompt Answer
Nombre del entorno Use un nombre corto y en minúsculas, como aoai-hello. El valor se utiliza en los nombres de recursos de Azure.
Subscription Seleccione la suscripción en la que desea crear los recursos.
Location Seleccione una región cerca de usted.
Ubicación del modelo de Azure OpenAI Seleccione una región donde GPT-5-mini esté disponible.

La implementación suele tardar varios minutos. Cuando se complete el comando, el kit de inicio habrá aprovisionado Azure OpenAI y desplegado un modelo GPT-5-mini.

Configuración del entorno local

La aplicación «Hola mundo» usa el inicio de sesión de Azure para obtener un token de acceso de Microsoft Entra. Establezca el punto de conexión usado por el cliente de 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)

Sugerencia

Azure OpenAI usa nombres de implementación en llamadas API. El kit de inicio muestra el nombre de implementación de GPT-5-mini como AZURE_OPENAI_GPT_DEPLOYMENT_NAME. En este artículo se asigna ese valor a AZURE_OPENAI_DEPLOYMENT de modo que el código sea el mismo en todos los idiomas.

Creación y ejecución de la aplicación hello world

Cree un archivo denominado hello_world_entra.py en la carpeta 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 las dependencias de Python y ejecute la aplicación.

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

Cree un archivo denominado hello_world_entra.cs en la carpeta 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());

Ejecute la aplicación.

cd src/dotnet
dotnet run hello_world_entra.cs

Cree un archivo denominado hello_world_entra.ts en la carpeta 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 las dependencias de TypeScript y ejecute la aplicación.

cd src/typescript
npm install
npx tsx hello_world_entra.ts

Cree un archivo denominado hello_world_entra.go en la carpeta 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())
}

Ejecute la aplicación.

cd src/go/responses_example_entra
go run hello_world_entra.go

Cree un archivo denominado HelloWorldEntra.java en la carpeta 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());
    }
}

Ejecute la aplicación.

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

El formato de salida exacto varía según el SDK. Debería ver una salida del modelo de Azure OpenAI implementado que incluye un saludo breve.

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

Descripción del código

La aplicación hola mundo tiene tres partes importantes:

  • DefaultAzureCredential obtiene un token de Microsoft Entra de tu inicio de sesión local de Azure.
  • El cliente de OpenAI apunta al punto de conexión de OpenAI v1 de Azure: /openai/v1/.
  • El valor model es el nombre de implementación de Azure OpenAI. En este kit de inicio, el nombre de implementación es gpt-5-mini.

La aplicación Python usa el openai paquete con azure-identity. El get_bearer_token_provider asistente crea un proveedor de tokens que el cliente de OpenAI puede usar como credencial.

La aplicación de C# usa el OpenAI paquete con Azure.Identity. El BearerTokenPolicy agrega tokens de Microsoft Entra a las solicitudes enviadas por el ResponsesClient.

La aplicación TypeScript usa el openai paquete con @azure/identity. El getBearerTokenProvider asistente crea un proveedor de tokens que el cliente de OpenAI puede usar como credencial.

La aplicación Go usa azidentity.NewDefaultAzureCredential con una directiva de token de portador de Azure Core. La política se agrega al cliente de OpenAI como middleware para que las solicitudes usen tokens de Microsoft Entra ID.

La aplicación Java usa DefaultAzureCredentialBuilder con AuthenticationUtil.getBearerTokenSupplier. El proveedor de tokens se pasa al cliente de OpenAI mediante BearerTokenCredential.

Ejecución del ejemplo del kit de inicio

El kit de inicio también incluye un ejemplo de API de respuestas más grande 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 Intente lo siguiente
azd up produce un error porque GPT-5-mini no está disponible en la región seleccionada. Seleccione otra ubicación del modelo de Azure OpenAI cuando se le solicite, o configure otra región con azd env set AZURE_LOCATION eastus2 y ejecute de nuevo azd up.
azd up genera un error de asignación de roles o un error de autorización. Asegúrese de que la cuenta puede crear recursos y asignaciones de roles. El propietario o el administrador de acceso de usuario suelen ser necesarios para esta plantilla.
La aplicación devuelve 401 o PermissionDenied. Confirme que ha iniciado sesión con el mismo tenant y la misma suscripción que usa azd up. Ejecute az login, azd auth login, y establezca AZURE_TENANT_ID en el identificador del inquilino de az account show. La propagación de la asignación de roles también puede tardar unos minutos.
DefaultAzureCredential failed to retrieve a token. Confirme que CLI de Azure está instalado y autenticado con az account show. Si usa varios inquilinos, inicie sesión en el inquilino correcto con az login --tenant <tenant-id>.
La aplicación devuelve model not found o deployment not found. Confirme que AZURE_OPENAI_DEPLOYMENT coincide con el nombre de implementación de OpenAI de Azure. El valor predeterminado del kit de inicio es gpt-5-mini.
La aplicación .NET no reconoce directivas de paquete. Instale la versión del SDK de .NET requerida por el kit de inicio. Las aplicaciones de C# basadas en archivos con #:package requieren un SDK de .NET reciente.
La aplicación Go no puede encontrar el módulo o las dependencias. Ejecute los comandos Go desde src/go/responses_example_entra. Confirme que Go 1.25.1 o posterior está instalado.
La aplicación Java falla con un error de versión de origen o destino. Confirme que Java 21 o posterior está instalado y seleccionado por el terminal.
Necesita registros de implementación detallados. Ejecute azd up --debug.

Puede inspeccionar los valores actuales del entorno de la CLI para desarrolladores de Azure con:

azd env get-values

Limpieza de recursos

Cuando ya no necesite los recursos, ejecute el siguiente comando desde la raíz del repositorio del kit de inicio:

azd down --purge

El comando elimina los recursos de Azure creados por el kit de inicio y ayuda a detener los cargos continuos.

Obtención de ayuda

Si necesita ayuda con el kit de inicio, use estos recursos:

Pasos siguientes

Más información sobre la API de respuestas

  • Last updated on