원라우터 임베딩 API

OneRouter는 이제 Embeddings API를 지원합니다.

날짜

2025. 12. 21.

저자

앤드류 젱

임베딩은 깊은 의미를 포착하는 고차원 숫자 표현입니다. 이들은 텍스트를 기계 학습 작업에 사용될 수 있는 벡터(숫자 배열)로 변환합니다.

OneRouter는 여러 제공자의 임베딩 모델에 접근할 수 있는 통합 API를 제공합니다.

임베딩이란 무엇인가요?

임베딩은 텍스트를 고차원 벡터로 변환하여 의미상 유사한 텍스트가 벡터 공간에서 더 가까이 위치하도록 합니다. 예를 들어, "고양이"와 "아기 고양이"는 유사한 임베딩을 가지지만, "고양이"와 "비행기"는 멀리 떨어져 있습니다.

이러한 벡터 표현은 기계가 텍스트 조각 간의 관계를 이해할 수 있게 하여 많은 AI 응용 프로그램에 필수적입니다.

일반적인 사용 사례

임베딩은 다양한 응용 프로그램에 사용됩니다:

RAG (Retrieval-Augmented Generation): 답변을 생성하기 전에 지식 베이스에서 관련 컨텍스트를 검색하는 RAG 시스템을 구축합니다. 임베딩은 LLM의 컨텍스트에 포함될 가장 관련성 높은 문서를 찾는 데 도움을 줍니다.
시맨틱 검색: 문서와 쿼리를 임베딩으로 변환한 후, 벡터 유사성을 비교하여 가장 관련성 높은 문서를 찾습니다. 이는 전통적인 키워드 일치보다 더 정확한 결과를 제공합니다. 왜냐하면 의미를 이해하기 때문입니다.
추천 시스템: 항목(제품, 기사, 영화) 및 사용자 선호도에 대한 임베딩을 생성하여 유사한 항목을 추천합니다. 임베딩 벡터를 비교하여 명백한 키워드를 공유하지 않더라도 의미상 관련된 항목을 찾을 수 있습니다.
군집화 및 분류: 유사한 문서를 함께 그룹화하거나 임베딩 패턴을 분석하여 텍스트를 카테고리로 분류합니다. 유사한 임베딩을 가진 문서는 같은 주제나 카테고리에 속할 가능성이 높습니다.
중복 탐지: 임베딩 유사성을 비교하여 중복 또는 거의 중복된 콘텐츠를 식별합니다. 이는 텍스트가 다른 방식으로 표현되거나 다시 작성되었을 때도 작동합니다.
이상 탐지: 데이터셋에서 일반적인 패턴에서 멀리 떨어진 임베딩을 식별하여 이상하거나 특이한 콘텐츠를 감지합니다.

임베딩을 사용하는 방법은?

기본 요청

임베딩을 생성하려면 /embeddings에 텍스트 입력과 선택한 모델을 담아 POST 요청을 보내십시오:

import requests

response = requests.post(
  "https://llm.onerouter.pro/v1/embeddings",
  headers={
    "Authorization": f"Bearer {{API_KEY_REF}}",
    "Content-Type": "application/json",
  },
  json={
    "model": "{{MODEL}}",
    "input": "The quick brown fox jumps over the lazy dog"
  }
)

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

배치 처리

문자열 배열을 전달하여 단일 요청으로 여러 텍스트의 임베딩을 생성할 수 있습니다:

import requests

response = requests.post(
  "https://llm.onerouter.pro/v1/embeddings",
  headers={
    "Authorization": f"Bearer {{API_KEY_REF}}",
    "Content-Type": "application/json",
  },
  json={
    "model": "{{MODEL}}",
    "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"
    ]
  }
)

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

실용적인 예시

시맨틱 검색

다음은 임베딩을 사용하여 시맨틱 검색 시스템을 구축하는 완전한 예시입니다:

import requests
import numpy as np

ONEROUTER_API_KEY = "{{API_KEY_REF}}"

# Sample documents
documents = [
  "The cat sat on the mat",
  "Dogs are loyal companions",
  "Python is a programming language",
  "Machine learning models require training data",
  "The weather is sunny today"
]

def cosine_similarity(a, b):
  """Calculate cosine similarity between two vectors"""
  dot_product = np.dot(a, b)
  magnitude_a = np.linalg.norm(a)
  magnitude_b = np.linalg.norm(b)
  return dot_product / (magnitude_a * magnitude_b)

def semantic_search(query, documents):
  """Perform semantic search using embeddings"""
  # Generate embeddings for query and all documents
  response = requests.post(
    "https://llm.onerouter.pro/v1/embeddings",
    headers={
      "Authorization": f"Bearer {API_KEY}",
      "Content-Type": "application/json",
    },
    json={
      "model": "{{MODEL}}",
      "input": [query] + documents
    }
  )
  
  data = response.json()
  query_embedding = np.array(data["data"][0]["embedding"])
  doc_embeddings = [np.array(item["embedding"]) for item in data["data"][1:]]
  
  # Calculate similarity scores
  results = []
  for i, doc in enumerate(documents):
    similarity = cosine_similarity(query_embedding, doc_embeddings[i])
    results.append({"document": doc, "similarity": similarity})
  
  # Sort by similarity (highest first)
  results.sort(key=lambda x: x["similarity"], reverse=True)
  
  return results

# Search for documents related to pets
results = semantic_search("pets and animals", documents)
print("Search results:")
for i, result in enumerate(results):
  print(f"{i + 1}. {result['document']} (similarity: {result['similarity']:.4f})")

예상 출력:

모범 사례

올바른 모델 선택: 다양한 임베딩 모델은 각기 다른 강점을 가지고 있습니다. 작은 모델(예: qwen-qwen3-embedding-0.6b 또는 openai-text-embedding-3-small)은 더 빠르고 저렴하며, 더 큰 모델(예: openai-text-embedding-3-large)은 더 나은 품질을 제공합니다. 여러 모델을 테스트하여 사용 사례에 가장 적합한 모델을 찾으세요.
요청 일괄 처리: 여러 텍스트를 처리할 때 개별 API 호출을 하는 것보다 단일 요청으로 보내는 것이 좋습니다. 이렇게 하면 대기 시간이 줄어들고 비용이 절감됩니다.
임베딩 캐싱: 동일한 텍스트에 대한 임베딩은 결정론적입니다(변하지 않음). 임베딩을 데이터베이스 또는 벡터 저장소에 저장하여 반복적으로 생성하지 않도록 하세요.
비교를 위한 정규화: 임베딩을 비교할 때 유클리드 거리보다 코사인 유사성을 사용하세요. 코사인 유사성은 크기 불변성을 가지며 고차원 벡터에 더 잘 작동합니다.
컨텍스트 길이 고려: 각 모델에는 최대 입력 길이가 있습니다(컨텍스트 윈도우). 긴 텍스트는 청크로 나누거나 잘릴 수 있습니다. 긴 문서를 처리하기 전에 모델의 사양을 확인하세요.
적절한 청크 사용: 긴 문서의 경우, 임의의 문자 제한이 아닌 의미 있는 청크(단락, 섹션)로 분할해야 합니다. 이렇게 하면 의미적 일관성이 유지됩니다.

제한 사항

스트리밍 없음: 채팅 완성처럼, 임베딩은 완전한 응답으로 반환됩니다. 스트리밍은 지원되지 않습니다.
토큰 제한: 각 모델에는 최대 입력 길이가 있습니다. 이 한계를 초과하는 텍스트는 잘리거나 거부됩니다.
결정론적 출력: 동일한 입력 텍스트에 대한 임베딩은 항상 동일합니다(온도나 무작위성이 없음).
언어 지원: 일부 모델은 특정 언어에 최적화되어 있습니다. 언어 기능에 대한 모델 문서를 확인하세요.

고급 기능

OneRouter는 다양한 제공자 간에 API 형식 및 매개변수를 표준화하고 집계하여 일관되고 통합된 개발자 경험을 보장합니다. 이를 통해 사용자는 각 제공자에 따라 코드를 조정하지 않고도 공통 인터페이스를 통해 다양한 모델 엔드포인트와 상호작용할 수 있습니다.

그러나 특정 제공자가 제공하는 일부 임베딩 API는 통합 사양을 초과하는 고급 기능이나 사용자 정의 매개변수를 포함합니다. 이러한 추가 기능은 OneRouter 통합 API 정의 내에서 항상 완전히 표현되지 않을 수 있습니다. 이러한 고급 매개변수, 동작 또는 사용 예에 대한 자세한 정보는 해당 제공자의 공식 문서를 참조하십시오.

Jina Embeddings API: 검색, RAG, 에이전트 응용 프로그램을 위한 최상의 성능을 가진 다중 모달 다국어 긴 문맥 임베딩.
Voyage AI Embedding API: Voyage AI는 최첨단 임베딩과 재정렬 기능을 제공합니다.
OpenAI embedding API: 기계 학습 모델 및 알고리즘이 쉽게 소비할 수 있도록 주어진 입력의 벡터 표현을 가져옵니다.