學習如何產生嵌入

內嵌是一種特殊格式的資料表示法，可供機器學習模型和演算法輕易使用。 嵌入是一種資訊密集的文字語意表示法。 每個嵌入都是浮點數向量，使得向量空間中兩個嵌入之間的距離與原始格式中兩個輸入的語意相似性相關。 例如，如果兩個文本相似，它們的向量表示也相似。 內嵌會在 Azure 資料庫中支援向量相似性搜尋，例如 Azure Cosmos DB for NoSQL、Azure SQL Database 和 適用於 PostgreSQL 的 Azure 資料庫 - Flexible Server。

先決條件

• 一個 Azure OpenAI 嵌入模型已部署。
• 以下是你資源中的數值：
  • 端點，例如。 https://YOUR-RESOURCE-NAME.openai.azure.com/
  • API 金鑰。
  • 模型部署名稱。

如需更多語言專屬的設定指引，請參見 Azure OpenAI 支援程式語言。

如何取得嵌入

要取得一段文字的嵌入向量，請向嵌入端點提出請求，如下程式碼片段所示：

註

Azure OpenAI 嵌入 API 目前不支援 Microsoft Entra ID 與 v1 API 的使用。 本文範例中請使用 API 金鑰認證。

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())}]");

Go

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

休息

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

最佳實務

Tip

當輸入標記 總和 超過 300,000 個時，嵌入請求會回傳 HTTP 400，即使每個輸入的數量遠低於每個輸入的限制。 如果你之前成功批次處理過大量長輸入陣列，請將它們拆分成較小的請求。

請確認輸入不會超過最大長度

• 最新嵌入模型的最大輸入文字長度為 8,192 個標記。 在提出申請前，請確認你的輸入沒有超過這個限制。
• 如果你在單一嵌入請求中傳送一個輸入陣列，最大陣列大小是 2,048。
• 每個 /embeddings 請求也有 300,000 個代幣的硬性上限，所有輸入加總後不得超過此數。 超過 HTTP 400 的請求會失敗，即使每個輸入少於 8,192 個標記且陣列長度低於 2,048。 將大型工作負載分成多個較小的請求，以免超過上限。
• 當你在單一請求中傳送多個輸入陣列時，請記得每分鐘的令牌數必須低於模型部署所分配的配額限制。 預設情況下，最新第三代嵌入模型每區域受 350 K TPM 限制。

故障排除

• 如果出現 401 or 403 錯誤，請確認該資源的 API 金鑰是否有效。
• 如果出現 404 錯誤，請確認端點是否包含 /openai/v1/ 路徑，且你使用了正確的基礎網址。
• 如果遇到 400 錯誤，確認 model 會設定為你的部署名稱，請求主體是有效的 JSON。

限制與風險

嵌入模型在某些情況下可能不可靠或帶來社會風險。 如果沒有緩解措施，使用可能會造成傷害。 關於如何負責任地使用這些資訊，請參閱 負責任的人工智慧 內容。

下一步

• 想進一步了解如何使用 Azure OpenAI 和嵌入來執行文件搜尋，請參閱 embeddings 教學。
• 若要進一步了解為 Azure OpenAI 提供支援的底層模型。
• 要儲存你的嵌入並執行向量（相似度）搜尋，請從以下服務中選擇：
  • Azure AI 搜尋服務
  • Azure SQL Database
  • Azure Cosmos DB 用於 NoSQL
  • Azure Cosmos DB for PostgreSQL
  • 適用於 PostgreSQL 的 Azure 資料庫 - 彈性伺服器
  • Azure Cache for Redis
  • 將 Eventhouse 當作向量資料庫使用 - Real-Time Intelligence in Microsoft Fabric