임베딩

임베딩

임베딩(Embeddings)은 의미를 포착하는 수치 표현으로, 텍스트를 벡터(숫자 배열)로 변환하여 다양한 머신러닝 작업에 활용할 수 있습니다. BazaarLink는 OpenAI 임베딩 API와 호환되는 통합 엔드포인트를 제공하여 하나의 인터페이스로 여러 공급자의 임베딩 모델을 호출할 수 있습니다.

Embedding 응답은 x-request-id와 같은 불투명한 BazaarLink 요청 ID를 사용하며 GET /v1/generation에서 사용할 수 있습니다. 비스트리밍 응답은 같은 ID를 x-generation-id에도 반환합니다. usage.cost는 이 요청에 대해 고객에게 청구된 USD 금액입니다. 통계는 완료 후 몇 초 뒤에 표시될 수 있으므로 404는 잠시 재시도하세요.

임베딩이란?

임베딩은 텍스트를 고차원 벡터로 변환하며, 의미적으로 유사한 텍스트는 벡터 공간에서 더 가깝게 위치합니다——예를 들어 "고양이"와 "새끼 고양이"의 임베딩은 비슷하지만, "고양이"와 "비행기"는 멀리 떨어져 있습니다. 이러한 벡터 표현 덕분에 기계가 텍스트 간의 관계를 이해할 수 있으며, 많은 AI 애플리케이션의 기반이 됩니다.

일반적인 사용 사례

매개변수

기본 요청

from openai import OpenAI

client = OpenAI(
    base_url="https://api.bazaarlink.ai/v1",
    api_key="sk-bl-YOUR_API_KEY",
)

response = client.embeddings.create(
    model="openai/text-embedding-3-small",
    input="The quick brown fox jumps over the lazy dog",
)

print(response.data[0].embedding)  # 1536-dimensional vector

배치 처리

문자열 배열을 보내면 한 번의 요청으로 여러 텍스트를 임베딩할 수 있습니다 — 텍스트별로 호출하는 것보다 저렴하고 빠릅니다.

response = client.embeddings.create(
    model="openai/text-embedding-3-small",
    input=[
        "Machine learning is a subset of artificial intelligence",
        "Deep learning uses neural networks with multiple layers",
        "Natural language processing enables computers to understand text",
    ],
)

for i, item in enumerate(response.data):
    print(f"Embedding {i}: {len(item.embedding)} dimensions")

멀티모달 입력 (이미지 + 텍스트)

이미지 입력을 지원하는 모델(output_modalities에 "embeddings", inputModalities에 "image" 포함)은 {content:[{type:"text",...}, {type:"image_url",...}]} 형태의 입력 항목을 받아, 이미지 단독 또는 텍스트와 함께 임베딩할 수 있습니다.

import requests

response = requests.post(
    "https://api.bazaarlink.ai/v1/embeddings",
    headers={
        "Authorization": "Bearer sk-bl-YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "google/gemini-embedding-2-preview",
        "input": [{
            "content": [
                {"type": "text", "text": "A scenic boardwalk through a green meadow"},
                {"type": "image_url", "image_url": {"url": "https://example.com/boardwalk.jpg"}},
            ]
        }],
        "encoding_format": "float",
    },
)

embedding = response.json()["data"][0]["embedding"]
print(f"Embedding dimension: {len(embedding)}")

임베딩 모델 찾기

임베딩 전용 모델 목록 엔드포인트는 없습니다 — GET /v1/models를 호출한 뒤 output_modalities에 "embeddings"가 포함된 항목을 클라이언트 측에서 필터링하거나, Models 페이지를 둘러보세요.

제한사항

• 스트리밍 미지원 — 채팅 완성과 달리 임베딩은 항상 완전한 응답으로 반환됩니다.
• 각 모델에는 최대 입력 길이가 있으며, 이를 초과하는 텍스트는 업스트림에서 잘리거나 거부됩니다.
• 동일한 입력에 대한 임베딩은 결정론적입니다 — temperature나 무작위성이 개입하지 않습니다.

모범 사례

• 속도/품질/비용 트레이드오프에 맞는 모델을 선택하세요 — 작은 모델(예: qwen/qwen3-embedding-4b)은 저렴하고 빠르며, 큰 모델(예: openai/text-embedding-3-large)은 일반적으로 더 높은 정확도로 임베딩합니다.
• 텍스트별로 호출하는 대신 여러 텍스트를 한 번의 요청에 배치로 담으세요 — 왕복 횟수와 오버헤드가 줄어듭니다.
• 결과를 캐시하세요 — 동일한 입력의 임베딩은 절대 변하지 않으므로, 다시 생성하지 말고 저장해 두세요.
• 유클리드 거리 대신 코사인 유사도로 비교하세요 — 스케일에 불변하며 고차원 벡터에 더 적합합니다.
• 각 모델의 컨텍스트 길이에 유의하세요 — 긴 문서는 임베딩 전에 청크로 나눠야 할 수 있습니다.