Erfahren Sie, wie Sie Einbettungen generieren

Bei einer Einbettung handelt es sich um ein spezielles Format der Datendarstellung, das maschinelle Lernmodelle und Algorithmen problemlos verwenden können. Eine Einbettung ist eine informationsdichte Darstellung der semantischen Bedeutung eines Textteils. Jede Einbettung ist ein Vektor von Gleitkommazahlen, sodass der Abstand zwischen zwei Einbettungen im Vektorraum mit der semantischen Ähnlichkeit zwischen zwei Eingaben im ursprünglichen Format korreliert. Wenn beispielsweise zwei Texte ähnlich sind, sind ihre Vektordarstellungen ebenfalls ähnlich. Einbettungen ermöglichen die Vektorsimilaritätssuche in Azure-Datenbanken wie Azure Cosmos DB for NoSQL, Azure SQL-Datenbank und Azure Database for PostgreSQL - Flexible Server.

Voraussetzungen

• Ein Azure OpenAI-Einbettungsmodell bereitgestellt.
• Die folgenden Werte aus Ihrer Ressource:
  • Endpunkt, z. B. https://YOUR-RESOURCE-NAME.openai.azure.com/.
  • API-Schlüssel.
  • Modell Bereitstellungsname

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

Wie man Einbettungen erhält

Um einen Einbettungsvektor für einen Text zu erhalten, stellen Sie eine Anforderung an den Endpunkt für einbettende Elemente vor, wie in den folgenden Codeausschnitten gezeigt:

Hinweis

Die Azure OpenAI-Einbettungs-API unterstützt derzeit keine Microsoft Entra ID mit der v1-API. Verwenden Sie die API-Schlüsselauthentifizierung für die Beispiele in diesem Artikel.

C#

using OpenAI;
using OpenAI.Embeddings;
using System.ClientModel;

EmbeddingClient client = new(
    "text-embedding-3-small",
    credential: new ApiKeyCredential("API-KEY"),
    options: new OpenAIClientOptions()
    {

        Endpoint = new Uri("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1")
    }
);

string input = "This is a test";

OpenAIEmbedding embedding = client.GenerateEmbedding(input);
ReadOnlyMemory<float> vector = embedding.ToFloats();
Console.WriteLine($"Embeddings: [{string.Join(", ", vector.ToArray())}]");

Los

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/openai/openai-go/v2"
	"github.com/openai/openai-go/v2/option"
)

func main() {
	// Get API key from environment variable
	apiKey := os.Getenv("AZURE_OPENAI_API_KEY")
	if apiKey == "" {
		panic("AZURE_OPENAI_API_KEY environment variable is not set")
	}

	// Create a client with Azure OpenAI endpoint and API key
	client := openai.NewClient(
		option.WithBaseURL("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"),
		option.WithAPIKey(apiKey),
	)

	ctx := context.Background()
	text := "The attention mechanism revolutionized natural language processing"

	// Make an embedding request
	embedding, err := client.Embeddings.New(ctx, openai.EmbeddingNewParams{
		Input: openai.EmbeddingNewParamsInputUnion{OfString: openai.String(text)},
		Model: "text-embedding-3-large", // Use your deployed model name on Azure
	})
	if err != nil {
		panic(err.Error())
	}

	// Print embedding information
	fmt.Printf("Model: %s\n", embedding.Model)
	fmt.Printf("Number of embeddings: %d\n", len(embedding.Data))
	fmt.Printf("Embedding dimensions: %d\n", len(embedding.Data[0].Embedding))
	fmt.Printf("Usage - Prompt tokens: %d, Total tokens: %d\n", embedding.Usage.PromptTokens, embedding.Usage.TotalTokens)
	
	// Print first few values of the embedding vector
	fmt.Printf("First 10 embedding values: %v\n", embedding.Data[0].Embedding[:10])
}

Javascript

import OpenAI from "openai";
const client = new OpenAI({
    baseURL: "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    apiKey: process.env['OPENAI_API_KEY'] //Your Azure OpenAI API key
});

const embedding = await client.embeddings.create({
  model: "text-embedding-3-small",
  input: "Your text string goes here",
});

console.log(embedding);

Python

import os
from openai import OpenAI

client = OpenAI(
  api_key = os.getenv("AZURE_OPENAI_API_KEY"),  
  base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
)

response = client.embeddings.create(
    input = "Your text string goes here",
    model= "text-embedding-3-large"
)

print(response.model_dump_json(indent=2))

Powershell

# Azure OpenAI metadata variables
$openai = @{
    api_key     = $Env:AZURE_OPENAI_API_KEY
    api_base    = $Env:AZURE_OPENAI_ENDPOINT # your endpoint should look like the following https://YOUR_RESOURCE_NAME.openai.azure.com/
    name        = 'YOUR-DEPLOYMENT-NAME-HERE' #This will correspond to the custom name you chose for your deployment when you deployed a model.
}

$headers = [ordered]@{
    'api-key' = $openai.api_key
}

$text = 'Your text string goes here'

$body = [ordered]@{
    input = $text
	model = $openai.name
} | ConvertTo-Json

$url = "$($openai.api_base)/openai/v1/embeddings"

$response = Invoke-RestMethod -Uri $url -Headers $headers -Body $body -Method Post -ContentType 'application/json'
return $response.data.embedding

REST

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1/embeddings \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY' \
	-d '{"model": "YOUR-DEPLOYMENT-NAME", "input": "Sample Document goes here"}'

Bewährte Methoden

Tip

Einbettungsanforderungen geben HTTP 400 zurück, wenn die Summe der Eingabetoken 300.000 überschreitet, auch wenn jede einzelne Eingabe gut unter dem Grenzwert pro Eingabe liegt. Wenn Sie zuvor große Arrays mit langen Eingaben erfolgreich in Stapeln verarbeitet haben, teilen Sie sie in kleinere Anfragen auf.

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

• Die maximale Länge des Eingabetexts für die neuesten Einbettungsmodelle beträgt 8.192 Token. Stellen Sie sicher, dass Ihre Eingaben diesen Grenzwert nicht überschreiten, bevor Sie eine Anforderung stellen.
• Wenn Sie ein Array von Eingaben in einer einzigen Einbettungsanforderung senden, beträgt die maximale Arraygröße 2.048.
• Jede /embeddings Anforderung hat auch eine harte Obergrenze von 300.000 Token, die über alle Eingaben summiert werden. Anforderungen, die diesen Aggregatgrenzwert überschreiten, schlagen mit HTTP 400 fehl, auch wenn jede einzelne Eingabe unter 8.192 Token liegt und die Arraylänge unter 2.048 liegt. Teilen Sie große Workloads in mehrere kleinere Anfragen auf, um das Limit nicht zu überschreiten.
• Wenn Sie ein Array von Eingaben in einer einzigen Anforderung senden, denken Sie daran, dass die Anzahl der Token pro Minute in Ihren Anforderungen unter dem Kontingentlimit bleiben muss, das der Modellbereitstellung zugewiesen ist. Standardmäßig unterliegen Einbettungsmodelle der neuesten Generation 3 einem Grenzwert von 350 K TPM pro Region.

Problembehandlung

• Wenn Sie einen 401-Fehler oder 403-Fehler erhalten, bestätigen Sie, dass der API-Schlüssel für die Ressource gültig ist.
• Wenn sie einen 404 Fehler erhalten, bestätigen Sie, dass der Endpunkt den /openai/v1/ Pfad enthält und Sie die richtige Basis-URL verwendet haben.
• Wenn ein 400 Fehler angezeigt wird, stellen Sie sicher, dass model auf Ihren Bereitstellungsnamen festgelegt ist und der Anforderungstext gültiges JSON ist.

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

• Weitere Informationen zur Verwendung von Azure OpenAI und Einbettungen zur Dokumentsuche finden Sie im Lernprogramm embeddings.
• Weitere Informationen zu den zugrunde liegenden Modellen, die Azure OpenAI zugrunde liegen.
• Um Ihre Einbettungen zu speichern und eine Vektorsuche (Ähnlichkeit) durchzuführen, wählen Sie aus den folgenden Diensten aus:
  • Azure KI-Suche
  • Azure SQL-Datenbank
  • Azure Cosmos DB für NoSQL
  • Azure Cosmos DB für PostgreSQL
  • Azure-Datenbank für PostgreSQL – Flexibler Server
  • Azure Cache for Redis
  • Use Eventhouse als Vektordatenbank – Real-Time Intelligence in Microsoft Fabric