OneRouter エンベディング API

OneRouterは現在、Embedding APIをサポートしています

日付

2025/12/21

著者

アンドリュー・ジェン

埋め込みは、テキストの深い意味を捉える高次元の数値表現です。これらはテキストをベクトル（数の配列）に変換し、さまざまな機械学習のタスクに使用できます。

OneRouterは、複数のプロバイダーからの埋め込みモデルにアクセスするための統一APIを提供します。

埋め込みとは何ですか？

埋め込みは、テキストを高次元のベクトルに変換し、意味的に類似したテキストがベクトル空間で互いに近くに配置されるようにします。例えば、「猫」と「子猫」は似た埋め込みを持ちますが、「猫」と「飛行機」は遠く離れます。

これらのベクトル表現により、機械がテキストの間の関係を理解できるようになり、多くのAIアプリケーションにとって不可欠です。

一般的な使用例

埋め込みは、さまざまなアプリケーションで使用されています:

RAG（Retrieval-Augmented Generation）: 知識ベースから関連するコンテキストを取得して、回答を生成するRAGシステムを構築します。埋め込みは、LLMのコンテキストに含める最も関連性のある文書を見つけるのに役立ちます。
セマンティック検索: 文書とクエリを埋め込みに変換した後、ベクトルの類似性を比較して最も関連性のある文書を見つけます。これは、単に単語を一致させるのではなく、意味を理解するため、従来のキーワードマッチングよりも正確な結果を提供します。
推薦システム: アイテム（製品、記事、映画）やユーザーの好みに対して埋め込みを生成し、類似のアイテムを推薦します。埋め込みベクトルを比較することで、明白なキーワードを共有していなくても意味的に関連するアイテムを見つけることができます。
クラスタリングと分類: 埋め込みパターンを分析して、類似の文書をグループ化したり、テキストをカテゴリに分類したりします。似た埋め込みを持つ文書は、同じトピックまたはカテゴリに属する可能性があります。
重複検出: 埋め込みの類似性を比較することで、重複または近い重複のコンテンツを特定します。これは、テキストがパラフレーズされたり言い換えられたりしても機能します。
異常検出: データセット内の典型的なパターンから遠い埋め込みを特定することにより、異常なまたは外れ値のコンテンツを検出します。

埋め込みを使用する方法は？

基本リクエスト

埋め込みを生成するには、テキスト入力と選択したモデルを含むPOSTリクエストを/embeddingsに送信します:

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埋め込みAPI: 検索、RAG、エージェントアプリケーション向けのトップパフォーマンスのマルチモーダルな多言語長文埋め込み。
Voyage AI埋め込みAPI: Voyage AIは最先端の埋め込みと再ランキングを提供します。
OpenAI埋め込みAPI: 機械学習モデルやアルゴリズムで容易に消費できる入力のベクトル表現を取得します。