Generieren von Einbettungen mit Azure OpenAI

Eine Einbettung ist ein Vektor von Gleitkommazahlen, der die semantische Bedeutung von Text darstellt. Ähnlicher Text erzeugt Vektoren, die eng miteinander verbunden sind, wodurch Einbettungen für die Vektorsuche, Empfehlungen, Klassifizierung und Clustering nützlich sind.

Voraussetzungen

Ein Azure-Abonnement. Erstellen Sie eine kostenlos , wenn Sie keins haben.
Eine Azure OpenAI-Ressource mit einer Einbettungsmodellbereitstellung.
Ihr Ressourcenendpunkt, wie zum Beispiel https://YOUR-RESOURCE-NAME.openai.azure.com.
Für die Microsoft Entra ID-Authentifizierung, eine Identität, der für die Azure OpenAI-Ressource die Rolle Cognitive Services OpenAI User zugewiesen ist. Weitere Informationen finden Sie unter Rollenbasierte Zugriffssteuerung für Azure OpenAI.
Die Azure CLI für die lokale Authentifizierung.
Der Laufzeit- und Paket-Manager für die von Ihnen ausgewählte Sprache.

Weitere sprachspezifische Einrichtungsanleitungen finden Sie unter Azure OpenAI unterstützte Programmiersprachen.

Der Wert model in jeder Anfrage ist der Bereitstellungsname Ihres Azure-Modells. Die Beispiele verwenden text-embedding-3-small; ersetzen Sie es, wenn Ihre Bereitstellung einen anderen Namen hat.

Ein Embedding generieren

Senden Sie Text an den Endpunkt der Einbettungen, und lesen Sie den Vektor aus dem ersten Element in der Antwort.

Die v1-Einbettungs-API unterstützt Microsoft Entra ID- und API-Schlüsselauthentifizierung. Microsoft Entra ID wird empfohlen, da dadurch keine langlebigen Anmeldeinformationen gespeichert werden. In den Beispielen in diesem Artikel wird Microsoft Entra ID verwendet.

Melden Sie sich für die lokale Entwicklung bei Azure an, bevor Sie ein SDK-Beispiel ausführen:

az login

DefaultAzureCredentialverwendet Ihre angemeldete Identität lokal und kann eine verwaltete Identität verwenden, wenn Ihre Anwendung in Azure ausgeführt wird.

Die API-Schlüsselauthentifizierung wird ebenfalls unterstützt. Informationen zur schlüsselbasierten Clientkonfiguration finden Sie unter Azure OpenAI v1-API-Leitfaden.

Installieren Sie die OpenAI- und Azure Identity-Pakete:

pip install openai azure-identity

Generieren Sie eine Einbettung, und drucken Sie deren Abmessungen:

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>

Referenz: embeddings.create

Installieren Sie die OpenAI- und Azure Identity-Pakete:

dotnet add package OpenAI
dotnet add package Azure.Identity

Generieren Sie eine Einbettung, und drucken Sie deren Abmessungen:

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>

Referenz: EmbeddingClient.GenerateEmbedding

Installieren Sie die OpenAI- und Azure Identity-Pakete:

npm install openai @azure/identity

Generieren Sie eine Einbettung, und drucken Sie deren Abmessungen:

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>

Referenz: embeddings.create

Fügen Sie für Maven die OpenAI- und Azure Identity-Pakete hinzu:

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

Informationen zum Gradle-Setup finden Sie unter Azure OpenAI Java Support.

Generieren Sie eine Einbettung, und drucken Sie deren Abmessungen:

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>

Referenz: EmbeddingCreateParams

Installieren Sie Version 3 des OpenAI Go-Moduls und des Azure Identity-Moduls:

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

Generieren Sie eine Einbettung, und drucken Sie deren Abmessungen:

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>

Referenz: Embeddings.New

Speichern Sie Ihren Ressourcenendpunkt in AZURE_OPENAI_ENDPOINT. Rufen Sie dann ein Zugriffstoken ab und generieren Sie eine Einbettung:

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

Referenz: Invoke-RestMethod und az account get-access-token

Rufen Sie ein Zugriffstoken ab, und senden Sie eine Anforderung an den v1-Einbettungsendpunkt:

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

Referenz: Azure OpenAI embeddings REST API undaz account get-access-token

Bewährte Methoden

Tip

Einbettungsanforderungen geben HTTP 400 zurück, wenn die Summe der Eingabetoken 300.000 überschreitet, auch wenn jede einzelne Eingabe unter dem Grenzwert pro Eingabe liegt. Teilen Sie große Batches in kleinere Anforderungen auf.

Überprüfen, ob Eingaben die maximale Länge nicht überschreiten

Die maximale Eingabelänge für die aktuellen Einbettungsmodelle beträgt 8.192 Token. Überprüfen Sie die einzelnen Eingaben, bevor Sie die Anforderung senden.
Wenn Sie ein Array von Eingaben in einer einzigen Einbettungsanforderung senden, beträgt die maximale Arraygröße 2.048.
Jede /embeddings Anforderung verfügt über einen 300.000-Token-Aggregatgrenzwert für alle Eingaben. Anforderungen oberhalb dieses Grenzwerts schlagen mit HTTP 400 fehl.
Halten Sie die Gesamtzahl der Token pro Minute unter dem Kontingent, das Ihrer Modellbereitstellung zugewiesen ist. Aktuelle Grenzwerte finden Sie unter Azure OpenAI-Kontingente und -Grenzwerte.

Problembehandlung

Bei einer 401-Antwort melden Sie sich erneut an und vergewissern Sie sich, dass das Zugriffstoken die richtige Audience verwendet.
Vergewissern Sie sich für eine 403-Antwort, dass Ihrer Identität für die Azure OpenAI-Ressource die Rolle Cognitive Services OpenAI User zugewiesen ist.
Vergewissern Sie sich bei einer Antwort vom Typ 404, dass der Endpunkt /openai/v1/ enthält und dass model einen gültigen Bereitstellungsnamen enthält.
Überprüfen Sie für eine 400 Antwort den Anforderungstext, die Tokenanzahl der einzelnen Eingaben, die Anzahl der Eingaben und die Aggregattokenanzahl.

Einschränkungen und Risiken

Einbettungsmodelle können in bestimmten Fällen unzuverlässig sein oder soziale Risiken darstellen. Sie können Schaden verursachen, wenn sie ohne Entschärfungen verwendet werden. Weitere Informationen zum verantwortungsvollen Umgang mit ihrer Nutzung finden Sie in den Inhalten "Verantwortungsvolle KI ".

Nächste Schritte

Erkunden Sie Einbettungen und Dokumentsuche.
Überprüfen Sie die verfügbaren Azure OpenAI-Modelle.
Wählen Sie einen Dienst zum Speichern und Suchen von Vektoren aus:

Feedback

War diese Seite hilfreich?

Last updated on 2026-07-22

Generieren von Einbettungen mit Azure OpenAI

Voraussetzungen

Ein Embedding generieren

Bewährte Methoden

Überprüfen, ob Eingaben die maximale Länge nicht überschreiten

Problembehandlung

Einschränkungen und Risiken

Nächste Schritte

Feedback

Zusätzliche Ressourcen