API リファレンス

Embeddings

セマンティック検索、RAG、クラスタリング、類似度検出のためのベクトル埋め込みを生成します。OpenAI、Cohere、Voyage、BGE-M3などのモデルに単一のエンドポイントからアクセスできます。

エンドポイント

http
POST https://api.tokspan.com/v1/embeddings

リクエストパラメータ

パラメータ型必須説明
modelstringはい埋め込みモデル ID（例：text-embedding-3-large、text-embedding-3-small、voyage-3）
inputstring / arrayはい埋め込むテキスト。1つの埋め込みには文字列を、バッチには文字列の配列を渡します（1リクエストあたり最大 2048 件）。
dimensionsintegerいいえ出力次元数を削減してストレージを節約し、検索速度を向上させます。text-embedding-3 モデルでサポートされています。モデルの最大次元数以下である必要があります。
encoding_formatstringいいえ"float"（デフォルト）またはコンパクトな転送用の "base64"。
userstringいいえ不正利用監視のためのエンドユーザー識別子。

単一埋め込み

python
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-key",
    base_url="https://api.tokspan.com/v1",
)

response = client.embeddings.create(
    model="text-embedding-3-large",
    input="Your text string for embedding",
    dimensions=1024,  # Optional: reduce dimensions
)

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

バッチ埋め込み

最大スループットを得るために、1回のリクエストで最大 2048 入力を送信できます。レスポンスは入力順序を保持します — response.data[0] は input[0] に対応します。

python
# Batch embedding — process up to 2048 inputs per request
texts = ["First document", "Second document", "Third document"]

response = client.embeddings.create(
    model="text-embedding-3-large",
    input=texts,
    dimensions=1024,
)

for i, data in enumerate(response.data):
    print(f"Text {i}: vector[:5] = {data.embedding[:5]}...")

次元削減

text-embedding-3-large（最大 3072 次元）や text-embedding-3-small（最大 1536 次元）などのモデルは、dimensions パラメータによる出力次元の削減をサポートしています。

なぜ次元を削減するのか？

  • ストレージの削減：256 次元のベクトルは 3072 次元と比較して約 12 分の 1 の容量で済みます
  • 高速な検索：次元数が少ないほどコサイン類似度の計算が高速になります
  • 十分な品質：ほとんどのユースケースでは、256～512 次元で意味的品質の約 95% 以上を維持できます
次元数ストレージ（100万ベクトルあたり）品質最適な用途
256~1 GB良好大規模検索、コスト重視のアプリ
512~2 GB非常に良好汎用 RAG および意味検索
1024~4 GB優秀高精度検索、クラスタリング
3072~12 GB最高最高精度、小規模コーパス
python
import numpy as np

def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

# Embed your document corpus (do this once, store results)
doc_embeddings = client.embeddings.create(model="text-embedding-3-large", input=documents)

# Embed a search query
query_embedding = client.embeddings.create(model="text-embedding-3-large", input="How do I reset my password?")

# Find most similar documents
scores = [cosine_similarity(query_embedding.data[0].embedding, d.embedding) for d in doc_embeddings.data]
top_idx = np.argmax(scores)
print(f"Best match: {documents[top_idx]} (score: {scores[top_idx]:.3f})")
プロのヒント：本番環境の RAG では、埋め込みと Rerank を組み合わせた2段階パイプラインが効果的です：埋め込みによる粗い検索（高速かつ低コスト）の後、上位 20～50 件の結果に対して精密なリランキングを実行します。

利用可能なモデル

モデルプロバイダー最大次元数最適な用途
text-embedding-3-largeOpenAI3072最高精度、柔軟な次元削減
text-embedding-3-smallOpenAI1536コスト効率が高く、良好な品質
Cohere Embed v3Cohere1024多言語対応、優れた検索性能
Voyage AIVoyage1024 / 2048コードおよび法律文書の埋め込み
BGE-M3BAAI1024オープンソース、多言語対応、セルフホスティングに最適

トークン単価を含む完全なカタログは モデルページ をご参照ください。