> ## 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 で主要な埋め込みモデルにアクセスできます。

## 使い方

<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` に文字列配列を渡すと、1 回のリクエストで複数の埋め込みを生成できます。

<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>
  埋め込み対象のテキスト。単一文字列または配列（バッチ）を指定できます。
</ResponseField>

<ResponseField name="model" type="string" required>
  使用する埋め込みモデル ID（例: `text-embedding-ada-002`）。
</ResponseField>

<ResponseField name="encoding_format" type="string" default="float">
  返却形式。`float` または `base64`。JSON サイズ削減には `base64` が有効です。
</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]}'")
```

### 分類とクラスタリング

埋め込みは機械学習モデルの特徴量として強力です。感情分析やトピック分類などの分類器の学習に使ったり、クラスタリングアルゴリズムで類似項目をグループ化したりできます。

## ベストプラクティス

<AccordionGroup>
  <Accordion title="前処理">
    最新の埋め込みモデルは堅牢ですが、用途によっては不要な文字の除去やテキスト正規化などの軽い前処理が有効な場合があります。ただし、過度な stemming やストップワード除去は重要な文脈を削ることがあるため避けてください。
  </Accordion>

  <Accordion title="バッチで効率化">
    複数のテキストを埋め込む必要がある場合は、文字列配列を渡すバッチ機能を使います。ネットワーク往復回数を減らせるため、レイテンシを大きく下げられます。
  </Accordion>

  <Accordion title="キャッシュ">
    人気の検索クエリや文書タイトルなど、同じテキストを頻繁に埋め込む場合は、Redis やインメモリキャッシュなどのキャッシュ層を用意します。API 呼び出しを減らし、コストを下げ、性能を改善できます。
  </Accordion>
</AccordionGroup>

## スケール：ベクトル DB

数千件を超える埋め込みを扱う場合、上の例のような全件比較による類似検索は遅く非効率になります。このような規模では、ベクトルデータベースが有効です。

ベクトルデータベースは、数百万から数十億規模のベクトル埋め込みを高速に保存・検索するための専用システムです。HNSW や IVF などの高度なインデックスアルゴリズムを使って近似最近傍（ANN）検索を行い、速度と精度のバランスを取ります。

代表的な選択肢：

* **クラウドサービス**：Pinecone、Zilliz Cloud
* **オープンソース / セルフホスト**：Weaviate、Milvus、Chroma、Qdrant