Azure OpenAI를 사용하여 임베딩 생성

임베딩은 텍스트의 의미론적 의미를 나타내는 부동 소수점 수의 벡터입니다. 유사한 텍스트는 서로 가까운 벡터를 생성하므로 포함은 벡터 검색, 권장 사항, 분류 및 클러스터링에 유용합니다.

필수 구성 요소

• Azure 구독입니다. 없다면 무료로 하나 만드세요.
• 포함 모델 배포가 있는 Azure OpenAI 리소스입니다.
• 리소스 엔드포인트(예: https://YOUR-RESOURCE-NAME.openai.azure.com).
• Microsoft Entra ID 인증의 경우 Azure OpenAI 리소스에 Cognitive Services OpenAI User 역할이 할당된 ID입니다. 자세한 내용은 Azure OpenAI에 대한 역할 기반 액세스 제어를 참조하세요.
• 로컬 인증에 대한 Azure CLI.
• 선택한 언어에 대한 런타임 및 패키지 관리자입니다.

언어별 설정 지침은 Azure OpenAI 지원 프로그래밍 언어 참조하세요.

각 요청의 값은 model Azure 모델 배포 이름입니다. 예제에서는 text-embedding-3-small를 사용합니다. 배포 이름이 다른 경우 이를 해당 이름으로 바꾸세요.

임베딩 생성

embeddings 엔드포인트로 텍스트를 보내고 응답의 첫 번째 항목에서 벡터를 읽습니다.

v1 포함 API는 Microsoft Entra ID 및 API 키 인증을 지원합니다. Microsoft Entra ID 수명이 긴 자격 증명을 저장하지 않기 때문에 권장됩니다. 이 문서의 예제에서는 Microsoft Entra ID 사용합니다.

로컬 개발의 경우 SDK 예제를 실행하기 전에 Azure 로그인합니다.

az login

DefaultAzureCredential는 로그인한 ID를 로컬로 사용하고 애플리케이션이 Azure 실행되면 관리 ID를 사용할 수 있습니다.

API 키 인증도 지원됩니다. 키 기반 클라이언트 구성은 Azure OpenAI v1 API 지침을 참조하세요.

Python

OpenAI 및 Azure ID 패키지를 설치합니다.

pip install openai azure-identity

임베딩을 생성하고 차원을 출력합니다.

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>

참조: embeddings.create

C#

OpenAI 및 Azure ID 패키지를 설치합니다.

dotnet add package OpenAI
dotnet add package Azure.Identity

임베딩을 생성하고 차원을 출력합니다.

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>

참조: EmbeddingClient.GenerateEmbedding

자바 스크립트

OpenAI 및 Azure ID 패키지를 설치합니다.

npm install openai @azure/identity

임베딩을 생성하고 차원을 출력합니다.

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>

참조: embeddings.create

Java

Maven의 경우 OpenAI 및 Azure ID 패키지를 추가합니다.

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

Gradle 설정은 Azure OpenAI Java 지원을 참조하세요.

임베딩을 생성하고 차원을 출력합니다.

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>

참조: EmbeddingCreateParams

이동

OpenAI Go 모듈 및 Azure ID 모듈의 버전 3을 설치합니다.

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

임베딩을 생성하고 차원을 출력합니다.

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>

참조: Embeddings.New

Powershell

리소스 엔드포인트를 에 저장합니다 AZURE_OPENAI_ENDPOINT. 그런 다음 액세스 토큰을 가져와 임베딩을 생성합니다:

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

참조: Invoke-RestMethod 및 az account get-access-token

REST

액세스 토큰을 가져오고 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>]}]}

참조: Azure OpenAI 임베딩 REST API 및 az account get-access-token

모범 사례

Tip

모든 개별 입력이 입력당 한도 미만인 경우에도 입력 토큰의 합계 가 300,000을 초과하면 포함 요청은 HTTP 400을 반환합니다. 큰 일괄 처리를 더 작은 요청으로 분할합니다.

입력이 최대 길이를 초과하지 않는지 확인합니다.

• 현재 포함 모델의 최대 입력 길이는 8,192개의 토큰입니다. 요청을 보내기 전에 각 입력을 확인합니다.
• 단일 포함 요청에 입력 배열을 보내는 경우 최대 배열 크기는 2,048입니다.
• 각 /embeddings 요청에는 모든 입력에서 300,000개의 토큰 집계 제한이 있습니다. 이 제한을 초과하는 요청은 HTTP 400으로 실패합니다.
• 분당 총 토큰을 모델 배포에 할당된 할당량보다 낮게 유지합니다. 현재 제한은 Azure OpenAI 할당량 및 제한을 참조하세요.

문제 해결

• 401 응답을 위해 다시 로그인하고 액세스 토큰이 올바른 대상 그룹을 사용하는지 확인합니다.
• 403 응답의 경우 ID에 Cognitive Services OpenAI User 역할이 Azure OpenAI 리소스에 할당되어 있는지 확인하세요.
• 404 응답의 경우, 엔드포인트에 /openai/v1/이(가) 포함되어 있는지, 그리고 model에 유효한 배포 이름이 포함되어 있는지 확인하세요.
• 응답의 400 경우 요청 본문, 각 입력의 토큰 수, 입력 수 및 집계 토큰 수를 확인합니다.

제한 사항 및 위험

모델 포함은 신뢰할 수 없거나 특정 경우에 사회적 위험을 초래할 수 있습니다. 완화 없이 사용하면 해를 입힐 수 있습니다. 책임감 있게 사용에 접근하는 방법에 대한 자세한 내용은 책임 있는 AI 콘텐츠를 참조하세요.

다음 단계

• 임베딩 및 문서 검색 살펴보기
• 사용 가능한 Azure OpenAI 모델을 검토합니다.
• 벡터를 저장하고 검색할 서비스를 선택합니다.
  • Azure AI 검색
  • Azure SQL 데이터베이스
  • NoSQL용 Azure Cosmos DB
  • Azure Database for PostgreSQL Flexible Server
  • 관리되는 Redis Azure
  • Microsoft Fabric의 이벤트하우스