Generare incorporamenti con Azure OpenAI

Un incorporamento è un vettore di numeri a virgola mobile che rappresenta il significato semantico del testo. Un testo simile produce vettori vicini, che rendono utili gli incorporamenti per la ricerca vettoriale, le raccomandazioni, la classificazione e il clustering.

Prerequisiti

Una sottoscrizione di Azure. Crearne uno gratuitamente se non ne hai uno.
Una risorsa OpenAI di Azure con una distribuzione di un modello di embedding.
L'endpoint della risorsa, ad esempio https://YOUR-RESOURCE-NAME.openai.azure.com.
Per l'autenticazione Microsoft Entra ID, un'identità con ruolo Cognitive Services OpenAI User assegnato alla risorsa Azure OpenAI. Per altre informazioni, vedere Controllo degli accessi in base al ruolo per Azure OpenAI.
interfaccia della riga di comando di Azure per l'autenticazione locale.
Il runtime e il gestore di pacchetti del linguaggio selezionato.

Per altre indicazioni sulla configurazione specifiche del linguaggio, vedere Azure Linguaggi di programmazione supportati da OpenAI.

Il valore model in ogni richiesta è il nome della distribuzione del modello di Azure. Gli esempi usano text-embedding-3-small; sostituitelo se la distribuzione in uso ha un nome diverso.

Generare un'integrazione

Inviare testo all'endpoint di integrazione e leggere il vettore dal primo elemento nella risposta.

L'API di incorporamento v1 supporta Microsoft Entra ID e l'autenticazione della chiave API. Microsoft Entra ID è consigliabile perché evita di archiviare credenziali di lunga durata. Gli esempi in questo articolo usano Microsoft Entra ID.

Per lo sviluppo locale, accedere a Azure prima di eseguire un esempio di SDK:

az login

DefaultAzureCredential usa localmente l'identità con cui hai effettuato l'accesso e può usare un'identità gestita quando l'applicazione viene eseguita in Azure.

È supportata anche l'autenticazione della chiave API. Per la configurazione del client basata su chiave, consulta la guida all'API Azure OpenAI v1.

Installare i pacchetti OpenAI e Azure Identity:

pip install openai azure-identity

Generare un incorporamento e stamparne le dimensioni:

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

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

# Generate one embedding vector.
response = openai.embeddings.create(
	model="text-embedding-3-small",
	input="The quick brown fox jumped over the lazy dog.",
)
print(f"Embedding dimensions: {len(response.data[0].embedding)}")

Embedding dimensions: <number>

Informazioni di riferimento: embeddings.create

Installare i pacchetti OpenAI e Azure Identity:

dotnet add package OpenAI
dotnet add package Azure.Identity

Generare un incorporamento e stamparne le dimensioni:

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

#pragma warning disable OPENAI001

var endpoint = new Uri(
	"https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/");
BearerTokenPolicy tokenPolicy = new(
	new DefaultAzureCredential(),
	"https://ai.azure.com/.default");
var openAIClient = new EmbeddingClient(
	model: "text-embedding-3-small",
	authenticationPolicy: tokenPolicy,
	options: new OpenAIClientOptions { Endpoint = endpoint });

// Generate one embedding vector.
OpenAIEmbedding embedding = openAIClient.GenerateEmbedding(
	"The quick brown fox jumped over the lazy dog.");
Console.WriteLine($"Embedding dimensions: {embedding.ToFloats().Length}");

Embedding dimensions: <number>

Informazioni di riferimento: EmbeddingClient.GenerateEmbedding

Installare i pacchetti OpenAI e Azure Identity:

npm install openai @azure/identity

Generare un incorporamento e stamparne le dimensioni:

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

// Generate one embedding vector.
const response = await openai.embeddings.create({
  model: "text-embedding-3-small",
  input: "The quick brown fox jumped over the lazy dog.",
});
console.log(`Embedding dimensions: ${response.data[0].embedding.length}`);

Embedding dimensions: <number>

Informazioni di riferimento: embeddings.create

Per Maven, aggiungere i pacchetti OpenAI e Azure Identity:

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

Per la configurazione di Gradle, vedere Azure supporto Java OpenAI.

Generare un incorporamento e stamparne le dimensioni:

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.embeddings.EmbeddingCreateParams;

public class EmbeddingsExample {
	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();

		// Generate one embedding vector.
		EmbeddingCreateParams params = EmbeddingCreateParams.builder()
				.model("text-embedding-3-small")
				.input("The quick brown fox jumped over the lazy dog.")
				.encodingFormat(EmbeddingCreateParams.EncodingFormat.FLOAT)
				.build();
		int dimensions = openAIClient.embeddings().create(params)
				.data().get(0).embedding().size();
		System.out.println("Embedding dimensions: " + dimensions);
	}
}

Embedding dimensions: <number>

Informazioni di riferimento: EmbeddingCreateParams

Installare la versione 3 del modulo OpenAI Go e il modulo Azure Identity:

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

Generare un incorporamento e stamparne le dimensioni:

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"})))

	// Generate one embedding vector.
	response, err := openaiClient.Embeddings.New(context.Background(), openai.EmbeddingNewParams{
		Model: "text-embedding-3-small",
		Input: openai.EmbeddingNewParamsInputUnion{OfString: openai.String(
			"The quick brown fox jumped over the lazy dog.")},
	})
	if err != nil { panic(err) }
	fmt.Printf("Embedding dimensions: %d\n", len(response.Data[0].Embedding))
}

Embedding dimensions: <number>

Informazioni di riferimento: Embeddings.New

Memorizza l'endpoint della risorsa in AZURE_OPENAI_ENDPOINT. Ottenere quindi un token di accesso e generare un incorporamento:

$Env:AZURE_OPENAI_ENDPOINT = "https://YOUR-RESOURCE-NAME.openai.azure.com"

$endpoint = "$($env:AZURE_OPENAI_ENDPOINT.TrimEnd('/'))/openai/v1/embeddings"
$token = az account get-access-token `
	--resource https://cognitiveservices.azure.com `
	--query accessToken `
	--output tsv
$headers = @{ Authorization = "Bearer $token" }

# Generate one embedding vector.
$body = @{
    model = "text-embedding-3-small"
    input = "The quick brown fox jumped over the lazy dog."
} | ConvertTo-Json
$response = Invoke-RestMethod `
    -Uri $endpoint `
    -Method Post `
    -Headers $headers `
    -ContentType "application/json" `
    -Body $body
Write-Output "Embedding dimensions: $($response.data[0].embedding.Count)"

Embedding dimensions: <number>

Riferimento: Invoke-RestMethod e az account get-access-token

Ottenere un token di accesso e inviare una richiesta all'endpoint di incorporamento v1:

AZURE_OPENAI_AUTH_TOKEN=$(az account get-access-token \
	--resource https://cognitiveservices.azure.com \
	--query accessToken \
	--output tsv)
curl "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/embeddings" \
  -H "Content-Type: application/json" \
	-H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{"model":"text-embedding-3-small","input":"The quick brown fox."}'

{"data":[{"embedding":[<vector-values>]}]}

Riferimento: API REST delle integrazioni di Azure OpenAI e az account get-access-token

Procedure consigliate

Tip

Le richieste di incorporamento restituiscono HTTP 400 quando la somma dei token di input supera 300.000, anche se ogni singolo input è inferiore al limite per input. Suddividere batch di grandi dimensioni in richieste più piccole.

Verificare che gli input non superino la lunghezza massima

La lunghezza massima di input per i modelli di incorporamento correnti è di 8.192 token. Controllare ogni input prima di inviare la richiesta.
Se si invia una matrice di input in una singola richiesta di incorporamento, la dimensione massima della matrice è 2.048.
Ogni /embeddings richiesta ha un limite di aggregazione di 300.000 token in tutti gli input. Le richieste superiori a questo limite hanno esito negativo con HTTP 400.
Mantenere i token totali al minuto al di sotto della quota assegnata alla distribuzione del modello. Per i limiti attuali, vedere quote e limiti di Azure OpenAI.

Risoluzione dei problemi

Per una 401 risposta, accedere di nuovo e verificare che il token di accesso usi il gruppo di destinatari corretto.
In caso di risposta 403, verifica che alla tua identità sia assegnato il ruolo Cognitive Services OpenAI User per la risorsa Azure OpenAI.
Per una 404 risposta, verificare che l'endpoint includa /openai/v1/ e che model contenga un nome di distribuzione valido.
Per ottenere una risposta 400, controlla il corpo della richiesta, il numero di token di ciascun input, il numero totale di input e il conteggio totale dei token.

Limitazioni e rischi

L'incorporamento di modelli potrebbe non essere affidabile o rappresentare rischi sociali in determinati casi. Potrebbero causare danni se usati senza mitigazioni. Per altre informazioni su come approcciare il proprio uso in modo responsabile, vedere il contenuto dell'intelligenza artificiale responsabile .

Passaggi successivi

Esplorare gli incorporamenti e la ricerca di documenti.
Esaminare i modelli di Azure OpenAI disponibili.
Scegliere un servizio per archiviare e cercare vettori:

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-07-27

Generare incorporamenti con Azure OpenAI

Prerequisiti

Generare un'integrazione

Procedure consigliate

Verificare che gli input non superino la lunghezza massima

Risoluzione dei problemi

Limitazioni e rischi

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive