Introduzione a Azure OpenAI e all'API Risposte

Questo articolo illustra come usare Azure OpenAI Starter Kit per distribuire una risorsa Azure OpenAI ed eseguire una piccola app hello world. L'app usa l'autenticazione Microsoft Entra ID e OpenAI SDK per chiamare l'API Azure OpenAI Responses.

Al termine di questo articolo, si eseguiranno le seguenti procedure:

  • Distribuire Azure OpenAI con GPT-5-mini usando l'interfaccia della riga di comando per sviluppatori di Azure.
  • Eseguire un'app locale che esegue l'autenticazione con Microsoft Entra ID anziché una chiave API.
  • Inviare una richiesta all'API Risposte e stampare l'output del modello.

Note

Questo articolo usa il Azure OpenAI Starter Kit come base per gli esempi. Il kit iniziale include infrastruttura come codice, la configurazione di Azure Developer CLI ed esempi di client per diversi linguaggi di programmazione.

Cost

Le risorse di Azure create in questo articolo sono addebitate alla sottoscrizione di Azure. Per evitare addebiti in corso, pulire le risorse al termine dell'articolo.

Prerequisiti

Per completare questo articolo, è necessario:

  • Python 3.8 o versione successiva.
  • .NET SDK 10 o versione successiva. Il kit iniziale usa applicazioni C# basate su file con direttive di pacchetto.
  • Node.js 18 o versione successiva.
  • Passare alla versione 1.25.1 o successiva.
  • Java 21 o versione successiva.
  • Maven 3.9 o versione successiva.

Ottenere il codice

Clonare il repository openAI Starter Kit di Azure e aprire la cartella del progetto.

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

Accedere ad Azure

Accedere sia con l'interfaccia della riga di comando di interfaccia della riga di comando di Azure che con l'interfaccia della riga di comando per sviluppatori di Azure.

az login
azd auth login

Se l'account ha accesso a più tenant, verificare che il tenant attivo sia il tenant in cui si vogliono distribuire le risorse.

az account show --query tenantId -o tsv

Distribuire Azure OpenAI

Esegui il seguente comando di Azure Developer CLI dalla directory radice del repository:

azd up

Usare le indicazioni seguenti per rispondere alle richieste:

Prompt Answer
Nome dell'ambiente Usare un nome breve e minuscolo, ad esempio aoai-hello. Il valore viene usato nei nomi delle risorse Azure.
Abbonamento Selezionare la sottoscrizione in cui si vogliono creare le risorse.
Posizione Selezionare un'area nelle vicinanze.
Località del modello Azure OpenAI Selezionare un'area in cui è disponibile GPT-5-mini.

La distribuzione richiede in genere alcuni minuti. Al termine del comando, il kit di avvio ha effettuato il provisioning di Azure OpenAI e ha distribuito un modello GPT-5-mini.

Configurare l'ambiente locale

L'app Hello World usa l'accesso ad Azure per ottenere un token di accesso Microsoft Entra. Impostare l'endpoint usato dal client 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

Azure OpenAI usa nomi di distribuzione nelle chiamate API. Lo starter kit restituisce il nome della distribuzione GPT-5-mini come AZURE_OPENAI_GPT_DEPLOYMENT_NAME. Questo articolo esegue il mapping di tale valore a AZURE_OPENAI_DEPLOYMENT in modo che il codice sia lo stesso tra i linguaggi.

Creare ed eseguire l'app hello world

Creare un file denominato hello_world_entra.py nella cartella 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)

Installare le dipendenze Python ed eseguire l'app.

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

Creare un file denominato hello_world_entra.cs nella cartella 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());

Avvia l'app.

cd src/dotnet
dotnet run hello_world_entra.cs

Creare un file denominato hello_world_entra.ts nella cartella 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);

Installare le dipendenze TypeScript ed eseguire l'app.

cd src/typescript
npm install
npx tsx hello_world_entra.ts

Creare un file denominato hello_world_entra.go nella cartella 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())
}

Avvia l'app.

cd src/go/responses_example_entra
go run hello_world_entra.go

Creare un file denominato HelloWorldEntra.java nella cartella 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());
    }
}

Avvia l'app.

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

Il formato di output esatto varia in base all'SDK. Verrà visualizzato l'output del modello OpenAI distribuito Azure che include un breve messaggio di saluto.

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

Informazioni sul codice

L'app hello world include tre parti importanti:

  • DefaultAzureCredential ottiene un token Microsoft Entra dall'accesso locale ad Azure.
  • Il client OpenAI punta all'endpoint Azure OpenAI v1: /openai/v1/.
  • Il valore model è il nome della distribuzione OpenAI Azure. In questo starter kit il nome della distribuzione è gpt-5-mini.

L'app Python usa il pacchetto openai con azure-identity. L'helper get_bearer_token_provider crea un provider di token che il client OpenAI può usare come credenziale.

L'app C# usa il pacchetto OpenAI con Azure.Identity. Il BearerTokenPolicy aggiunge token di Microsoft Entra alle richieste inviate dal ResponsesClient.

L'app TypeScript usa il pacchetto openai con @azure/identity. L'helper getBearerTokenProvider crea un provider di token che il client OpenAI può usare come credenziale.

L'app Go usa azidentity.NewDefaultAzureCredential con un criterio dei token bearer di Azure Core. Il criterio viene aggiunto al client OpenAI sotto forma di middleware, in modo che le richieste utilizzino token Microsoft Entra ID.

L'app Java usa DefaultAzureCredentialBuilder con AuthenticationUtil.getBearerTokenSupplier. Il fornitore di token viene passato al client OpenAI usando BearerTokenCredential.

Esegui l'esempio del kit iniziale

Lo starter kit include anche un esempio di API Risposte più grande per ogni lingua.

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 Prova questo
azd up ha esito negativo perché GPT-5-mini non è disponibile nell'area selezionata. Selezionare un'altra area geografica per il modello Azure OpenAI quando richiesto oppure impostare un'altra area geografica con azd env set AZURE_LOCATION eastus2 ed eseguire nuovamente azd up.
azd up non riesce a causa di un'assegnazione di ruolo o di un errore di autorizzazione. Assicurarsi che l'account possa creare risorse e assegnazioni di ruolo. Il Proprietario o l'Amministratore dell'accesso degli utenti è solitamente richiesto per questo modello.
L'app restituisce 401 o PermissionDenied. Verifica di aver effettuato l'accesso allo stesso tenant e alla stessa sottoscrizione utilizzati da azd up. Esegui az login, azd auth login e imposta AZURE_TENANT_ID sull'ID del tenant da az account show. La propagazione dell'assegnazione di ruolo può richiedere anche alcuni minuti.
DefaultAzureCredential failed to retrieve a token. Verificare che interfaccia della riga di comando di Azure sia installato e autenticato con az account show. Se si utilizzano più tenant, accedere al tenant corretto con az login --tenant <tenant-id>.
L'app restituisce model not found o deployment not found. Verificare che AZURE_OPENAI_DEPLOYMENT corrisponda al nome della distribuzione OpenAI Azure. Il valore predefinito del starter kit è gpt-5-mini.
L'app .NET non riconosce le direttive del pacchetto. Installare la versione .NET SDK richiesta dallo starter kit. Le app C# basate su file con #:package richiedono un SDK di .NET recente.
L'app Go non riesce a trovare il modulo o le dipendenze. Esegui i comandi Go da src/go/responses_example_entra. Verificare che Sia installato Go 1.25.1 o versione successiva.
L'app Java non viene eseguita a causa di un errore relativo alla versione sorgente o di destinazione. Verificare che Java 21 o versione successiva sia installato e selezionato dal terminale.
Sono necessari log di distribuzione dettagliati. Eseguire azd up --debug.

È possibile esaminare i valori correnti dell'ambiente dell'interfaccia della riga di comando per sviluppatori Azure con:

azd env get-values

Pulire le risorse

Quando le risorse non sono più necessarie, eseguire il comando seguente dalla radice del repository starter kit:

azd down --purge

Il comando elimina le risorse Azure create dallo starter kit e consente di arrestare gli addebiti in corso.

Come ottenere assistenza

Per assistenza con lo starter kit, usare queste risorse:

Passaggi successivi

Altre informazioni sull'API Risposte

  • Last updated on