> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yourouter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Embeddings

> 검색, 클러스터링, 분류를 위한 텍스트의 수치 벡터 표현을 생성합니다.

## 개요

Embedding은 텍스트의 수치 벡터 표현으로, 의미 정보를 담습니다. 이를 통해 서로 다른 텍스트 간의 "거리"나 "유사도"와 같은 수학적 연산을 수행할 수 있습니다.

의미 검색, 클러스터링, 추천, 이상 탐지, 분류 등 많은 AI 애플리케이션의 기초 기능입니다. YouRouter는 단일 통합 API로 주요 embedding 모델을 제공합니다.

## 사용법

<CodeGroup>
  ```python Python theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["YOUROUTER_API_KEY"],
      base_url="https://api.yourouter.ai/v1"
  )

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

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

  ```javascript Node.js theme={null}
  import OpenAI from 'openai';

  const openai = new OpenAI({
    apiKey: process.env.YOUROUTER_API_KEY,
    baseURL: 'https://api.yourouter.ai/v1',
  });

  async function main() {
    const response = await openai.embeddings.create({
      input: "Your text string goes here",
      model: "text-embedding-ada-002",
    });
    console.log(response.data[0].embedding);
  }

  main();
  ```

  ```bash cURL theme={null}
  curl https://api.yourouter.ai/v1/embeddings \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $YOUROUTER_API_KEY" \
    -d '{
      "input": "The quick brown fox jumps over the lazy dog",
      "model": "text-embedding-ada-002"
    }'
  ```
</CodeGroup>

### 배치 처리

효율을 위해 `input`에 문자열 배열을 전달하여 여러 embedding을 한 번에 생성할 수 있습니다.

<CodeGroup>
  ```python theme={null}
  response = client.embeddings.create(
      input=[
          "First sentence to embed.",
          "Another sentence for batch processing."
      ],
      model="text-embedding-ada-002"
  )

  for i, data in enumerate(response.data):
      print(f"Embedding for input {i+1}: {len(data.embedding)} dimensions")
  ```
</CodeGroup>

## 매개변수

<ResponseField name="input" type="string or array" required>
  embedding할 텍스트. 단일 문자열 또는 문자열 배열일 수 있습니다.
</ResponseField>

<ResponseField name="model" type="string" required>
  사용할 embedding 모델 ID(예: `text-embedding-ada-002`).
</ResponseField>

<ResponseField name="encoding_format" type="string" default="float">
  반환 embedding의 인코딩 형식. `float` 또는 `base64`를 선택할 수 있습니다. `base64`는 JSON 크기를 줄이는 데 도움이 됩니다.
</ResponseField>

<ResponseField name="user" type="string">
  최종 사용자를 나타내는 고유 식별자로, 모니터링 및 오용 탐지에 사용할 수 있습니다.
</ResponseField>

## 사용 사례

### 의미 검색

의미 검색은 키워드의 정확한 일치에 의존하지 않고, 사용자 질의와 의미적으로 더 관련된 콘텐츠를 찾습니다. 구현은 보통 질의 벡터와 문서 벡터 간 유사도를 비교합니다.

```python theme={null}
import numpy as np
from scipy.spatial.distance import cosine

documents = [
    "The sky is blue and beautiful.",
    "The sun is the star at the center of the Solar System.",
    "Artificial intelligence will reshape our world."
]

doc_embeddings = [
    client.embeddings.create(input=doc, model="text-embedding-ada-002").data[0].embedding
    for doc in documents
]

query = "What is the future of AI?"
query_embedding = client.embeddings.create(input=query, model="text-embedding-ada-002").data[0].embedding

similarities = [1 - cosine(query_embedding, doc_emb) for doc_emb in doc_embeddings]
most_similar_index = np.argmax(similarities)

print(f"Query: '{query}'")
print(f"Most similar document: '{documents[most_similar_index]}'")
```

### 분류 및 클러스터링

Embedding은 강력한 머신러닝 특징이기도 합니다. 감성 분석이나 주제 분류 등 분류기에 입력하거나, 클러스터링 알고리즘으로 유사 콘텐츠를 그룹화할 수 있습니다.

## 모범 사례

<AccordionGroup>
  <Accordion title="전처리">
    최신 embedding 모델은 이미 강건하지만, 특정 시나리오에서는 관련 없는 문자 제거나 기본 정규화와 같은 가벼운 전처리가 도움이 될 수 있습니다. 다만 의미 맥락을 잃을 수 있으므로 과도한 stemming이나 불용어 제거는 권장하지 않습니다.
  </Accordion>

  <Accordion title="배치로 효율 향상">
    여러 텍스트를 처리할 때는 배열을 전달해 배치 embedding을 우선하세요. 네트워크 왕복을 크게 줄이고 지연을 낮출 수 있습니다.
  </Accordion>

  <Accordion title="캐싱">
    인기 검색어나 자주 쓰는 제목처럼 동일 텍스트에 대해 embedding을 자주 호출한다면 Redis나 인메모리 캐시 등 캐시 계층을 두는 것이 좋습니다. API 호출을 줄이고 비용을 절감하며 성능을 높일 수 있습니다.
  </Accordion>
</AccordionGroup>

## 확장: 벡터 데이터베이스

embedding 수가 수천 개를 넘어가면 전수 비교로 유사도를 계산하는 것이 점점 느려집니다. 이 경우 보통 벡터 데이터베이스를 도입합니다.

벡터 데이터베이스는 대규모 벡터를 효율적으로 저장·검색하도록 설계되어 수백만\~수십억 개의 embedding 검색을 지원합니다. HNSW, IVF 등 인덱스 알고리즘으로 근사 최근접 이웃 검색을 수행하여 속도와 정확도의 균형을 맞춥니다.

일반적인 선택지:

* **클라우드 서비스**: Pinecone, Zilliz Cloud
* **오픈소스 / 자체 호스팅**: Weaviate, Milvus, Chroma, Qdrant