OpenAI Embeddings 프록시

OpenAI Embeddings 형식으로 입력 텍스트의 임베딩을 요청합니다. model에는 Model Catalog에서 확인한 임베딩 모델의 RID를 지정합니다. 예시 모델은 ri.language-model-service..language-model.text-embedding-ada-002_azure입니다.

POST /api/v2/llm/proxy/openai/v1/embeddings

인증과 헤더

OAuth2 애플리케이션은 api:use-language-models-execute 권한 범위를 요청해야 합니다.

헤더	자료형	조건과 동작
`Authorization`	string	Foundry Bearer 토큰으로 인증
`Content-Type`	string	`application/json`
`attribution`	선택적 string	프로젝트에 사용량을 귀속할 RID를 쉼표로 구분. 생략하면 호출 사용자에게 직접 귀속
`traceParent`	선택적 string	W3C traceparent 값. 생략하면 플랫폼 내 관측 기능이 작동하지 않음
`traceState`	선택적 string	W3C tracestate 값. 생략하면 플랫폼 내 관측 기능이 작동하지 않음

Python의 Foundry HTTP 클라이언트와 TypeScript의 PlatformClient fetch는 실행 맥락의 사용량 귀속 정보와 분산 추적 정보를 전파합니다. Python 클라이언트는 사용량 귀속에 attribution을 사용하고, 추적에는 B3 형식의 X-B3-TraceId, X-B3-SpanId, X-B3-Sampled를 사용합니다.

요청과 거버넌스

요청은 OpenAI의 해당 API 형식을 따릅니다. 다음은 예제에서 사용하는 입력입니다.

필드	형식	의미
`model`	string	사용할 Foundry 임베딩 모델 RID
`input`	Embeddings 입력	예시는 문자열 `"Hello, world"`

무보존(ZDR) 및 지역 제한 같은 AIP 데이터 거버넌스를 적용하며, 호환되는 공급자 기능을 선택적으로 활성화합니다. 사용량은 Resource Management에서 확인하고 요청에는 사용량 제한이 적용됩니다. 모델의 접근 가능 여부와 RID는 Model Catalog에서 확인합니다.

응답 처리

응답 객체의 data에서 입력별 임베딩 항목을 읽습니다. 임베딩 데이터와 사용량을 호출자가 함께 사용할 수 있도록 예제는 SDK 응답 객체 전체를 반환합니다. 데이터를 저장하거나 다른 함수에 전달할 때 필요한 벡터를 선택하여 사용합니다.

cURL

FOUNDRY_HOST에 프로토콜을 제외한 Foundry 호스트를, FOUNDRY_TOKEN에 유효한 토큰을 지정합니다. 아래 모델 RID와 입력은 예시입니다.

curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ${FOUNDRY_TOKEN}" \
    "https://${FOUNDRY_HOST}/api/v2/llm/proxy/openai/v1/embeddings" \
    -d '{
      "model": "ri.language-model-service..language-model.text-embedding-ada-002_azure",
      "input": "Hello, world"
    }'

Python

Foundry SDK와 openai==2.11.0을 사용하는 예제입니다. Foundry 호스트와 토큰이 제공되는 실행 맥락 및 HTTP 클라이언트 조건을 충족해야 합니다. 프록시 헬퍼에는 preview=True를 전달하고, 호출이 끝나면 클라이언트를 닫습니다.

from openai import OpenAI
from foundry_sdk.v2.language_models.utils import (
    get_foundry_token,
    get_openai_base_url,
    get_http_client,
)


def openai_embeddings(prompt: str):
    with OpenAI(
        api_key=get_foundry_token(preview=True),
        base_url=get_openai_base_url(preview=True),
        http_client=get_http_client(preview=True),
    ) as client:
        return client.embeddings.create(
            model="ri.language-model-service..language-model.text-embedding-ada-002_azure",
            input=prompt,
        )

TypeScript

서버 측 환경에서 openai와 @osdk/client를 사용합니다. 함수의 platformClient에는 애플리케이션이 사용하는 인증된 클라이언트를 전달합니다.

import OpenAI from "openai";
import { PlatformClient } from "@osdk/client";

export default async function openAiEmbeddings(
  platformClient: PlatformClient,
  prompt: string
) {
  const client = new OpenAI({
    apiKey: await platformClient.tokenProvider(),
    baseURL: new URL("/api/v2/llm/proxy/openai/v1", platformClient.baseUrl).href,
    fetch: platformClient.fetch,
  });
  return client.embeddings.create({
    model: "ri.language-model-service..language-model.text-embedding-ada-002_azure",
    input: prompt,
  });
}

Keyboard shortcuts