Embeddings（埋め込み）

Embeddings（埋め込み）は、テキストを高次元ベクトルに変換する技術で、セマンティック検索、RAG（検索拡張生成）、テキスト分類、類似度計算などに一般的に使用されます。RouteAPI は標準的な OpenAI 互換の Embeddings インターフェースを提供し、複数の埋め込みモデルをサポートしています。

Endpoint

POST /v1/embeddings

完全なURL:

https://api.routeapi.ai/v1/embeddings

ユースケース

シナリオ	説明
セマンティック検索	ドキュメントとクエリをベクトルに変換し、類似度により関連コンテンツを検索
RAG	関連ドキュメントの断片をコンテキストとして検索し、LLM生成品質を向上
テキスト分類	テキストをベクトル化してクラスタリングまたは分類タスクに使用
推薦システム	コンテンツ推薦のためのテキスト類似度を計算
重複検出	ベクトル類似度により重複または類似コンテンツを識別

リクエスト例

単一テキスト

curl https://api.routeapi.ai/v1/embeddings \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "RouteAPI 是一个统一的 AI API 网关"
  }'

バッチテキスト

curl https://api.routeapi.ai/v1/embeddings \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": [
      "第一段文本",
      "第二段文本",
      "第三段文本"
    ]
  }'

リクエストパラメータ

フィールド	タイプ	必須	説明
model	string	はい	埋め込みモデル ID
input	string/array	はい	単一テキスト文字列またはテキスト配列
encoding_format	string	いいえ	ベクトルエンコード形式、float または base64、デフォルトは float
dimensions	number	いいえ	返されるベクトル次元数（一部モデルでサポート）、次元削減に使用
user	string	いいえ	エンドユーザー識別子、追跡および不正利用監視用

レスポンス例

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0.0023064255,
        -0.009327292,
        0.015797347,
        ...
      ]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}

レスポンスフィールド

フィールド	説明
object	固定値 list
data	埋め込み結果の配列
data[].embedding	浮動小数点ベクトル配列
data[].index	入力テキストのインデックス位置
model	実際に使用されたモデル ID
usage.prompt_tokens	入力で消費された token 数
usage.total_tokens	合計 token 数

サポートされている埋め込みモデル

OpenAI モデル

モデル ID	デフォルト次元数	パフォーマンス	ユースケース
text-embedding-3-small	1536	コストパフォーマンス	一般的なセマンティック検索、RAG
text-embedding-3-large	3072	高精度	複雑なセマンティックタスク
text-embedding-ada-002	1536	安定したクラシック	後方互換性

Google モデル

モデル ID	デフォルト次元数	説明
text-embedding-004	768	Google の最新埋め込みモデル
gemini-embedding-001	768	Gemini シリーズ埋め込みモデル

その他のプロバイダー

モデル ID	デフォルト次元数	プロバイダー
text-embedding-v1	1024	Baidu Wenxin
embedding-bert-512-v1	512	Zhipu AI
bge-large-zh	1024	BAAI BGE（中国語）
bge-large-en	1024	BAAI BGE（英語）

モデルの可用性はコンソールのモデルリストに従い、アカウントによって利用可能なモデルが異なる場合があります。

バッチ処理

バッチサイズ制限

• 単一リクエストで処理できる最大テキスト数は、特定のモデルとサービス構成によって異なります。
• 単一リクエストで100テキストを超えないことを推奨します。
• 単一テキストの token 数は、通常、モデルの最大入力制限（通常8192 tokens）を超えないようにしてください。

バッチ最適化のヒント

1. リクエストのマージ: 複数の短いテキストを1つのリクエストにまとめて、ネットワークラウンドトリップを削減します。
2. 並行制御: 大規模バッチタスクは分割して並行処理できますが、並行数は5を超えないことを推奨します。
3. エラー処理: バッチ内の1つのテキストが失敗すると、リクエスト全体が失敗する可能性があるため、適切な再試行とエラー処理が必要です。

コード例

Python（OpenAI SDK）

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-routeapi-token",
    base_url="https://api.routeapi.ai/v1"
)

# 単一テキスト
response = client.embeddings.create(
    model="text-embedding-3-small",
    input="RouteAPI 是一个统一的 AI API 网关"
)
embedding = response.data[0].embedding
print(f"向量维度: {len(embedding)}")
print(f"前 5 个值: {embedding[:5]}")

# バッチテキスト
texts = [
    "人工智能正在改变世界",
    "机器学习是 AI 的核心技术",
    "深度学习推动了 AI 的发展"
]
response = client.embeddings.create(
    model="text-embedding-3-small",
    input=texts
)
for i, data in enumerate(response.data):
    print(f"文本 {i}: 维度 {len(data.embedding)}")

Node.js（OpenAI SDK）

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-routeapi-token',
  baseURL: 'https://api.routeapi.ai/v1'
});

async function getEmbedding() {
  // 単一テキスト
  const response = await client.embeddings.create({
    model: 'text-embedding-3-small',
    input: 'RouteAPI 是一个统一的 AI API 网关'
  });

  const embedding = response.data[0].embedding;
  console.log(`向量维度: ${embedding.length}`);
  console.log(`前 5 个值: ${embedding.slice(0, 5)}`);

  // バッチテキスト
  const texts = [
    '人工智能正在改变世界',
    '机器学习是 AI 的核心技术',
    '深度学习推动了 AI 的发展'
  ];

  const batchResponse = await client.embeddings.create({
    model: 'text-embedding-3-small',
    input: texts
  });

  batchResponse.data.forEach((item, i) => {
    console.log(`文本 ${i}: 维度 ${item.embedding.length}`);
  });
}

getEmbedding();

curl

curl https://api.routeapi.ai/v1/embeddings \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": ["文本1", "文本2", "文本3"]
  }'

セマンティック類似度計算

Python（NumPy を使用）

import numpy as np
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-routeapi-token",
    base_url="https://api.routeapi.ai/v1"
)

def cosine_similarity(vec1, vec2):
    """コサイン類似度を計算"""
    return np.dot(vec1, vec2) / (np.linalg.norm(vec1) * np.linalg.norm(vec2))

# 2つのテキストの埋め込みベクトルを取得
texts = [
    "RouteAPI 是一个 AI API 网关",
    "RouteAPI 提供统一的模型接入服务",
    "今天天气很好"
]

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

embeddings = [data.embedding for data in response.data]

# 類似度を計算
sim_0_1 = cosine_similarity(embeddings[0], embeddings[1])
sim_0_2 = cosine_similarity(embeddings[0], embeddings[2])

print(f"文本0 和 文本1 的相似度: {sim_0_1:.4f}")  # 高類似度
print(f"文本0 和 文本2 的相似度: {sim_0_2:.4f}")  # 低類似度

Node.js（数学ライブラリを使用）

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-routeapi-token',
  baseURL: 'https://api.routeapi.ai/v1'
});

function cosineSimilarity(vec1, vec2) {
  const dotProduct = vec1.reduce((sum, val, i) => sum + val * vec2[i], 0);
  const mag1 = Math.sqrt(vec1.reduce((sum, val) => sum + val * val, 0));
  const mag2 = Math.sqrt(vec2.reduce((sum, val) => sum + val * val, 0));
  return dotProduct / (mag1 * mag2);
}

async function computeSimilarity() {
  const texts = [
    'RouteAPI 是一个 AI API 网关',
    'RouteAPI 提供统一的模型接入服务',
    '今天天气很好'
  ];

  const response = await client.embeddings.create({
    model: 'text-embedding-3-small',
    input: texts
  });

  const embeddings = response.data.map(d => d.embedding);

  const sim_0_1 = cosineSimilarity(embeddings[0], embeddings[1]);
  const sim_0_2 = cosineSimilarity(embeddings[0], embeddings[2]);

  console.log(`文本0 和 文本1 的相似度: ${sim_0_1.toFixed(4)}`);
  console.log(`文本0 和 文本2 的相似度: ${sim_0_2.toFixed(4)}`);
}

computeSimilarity();

ベクトルデータベース統合

Pinecone の例

from openai import OpenAI
import pinecone

# RouteAPI クライアントを初期化
client = OpenAI(
    api_key="sk-your-routeapi-token",
    base_url="https://api.routeapi.ai/v1"
)

# Pinecone を初期化
pinecone.init(api_key="your-pinecone-key", environment="your-env")
index = pinecone.Index("your-index-name")

# 埋め込みを生成して保存
documents = [
    {"id": "doc1", "text": "RouteAPI 是一个 AI API 网关"},
    {"id": "doc2", "text": "支持多家 AI 模型供应商"},
    {"id": "doc3", "text": "提供统一的接口和计费"}
]

for doc in documents:
    # 埋め込みを生成
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=doc["text"]
    )
    embedding = response.data[0].embedding

    # Pinecone に保存
    index.upsert([(doc["id"], embedding, {"text": doc["text"]})])

# クエリ
query = "什么是 RouteAPI"
query_response = client.embeddings.create(
    model="text-embedding-3-small",
    input=query
)
query_embedding = query_response.data[0].embedding

# 類似ドキュメントを検索
results = index.query(query_embedding, top_k=3, include_metadata=True)
for match in results["matches"]:
    print(f"相似度: {match['score']:.4f}, 文本: {match['metadata']['text']}")

Weaviate の例

import weaviate
from openai import OpenAI

# RouteAPI クライアントを初期化
client = OpenAI(
    api_key="sk-your-routeapi-token",
    base_url="https://api.routeapi.ai/v1"
)

# Weaviate に接続
weaviate_client = weaviate.Client("http://localhost:8080")

# スキーマを作成（存在しない場合）
schema = {
    "class": "Document",
    "vectorizer": "none",  # 自分でベクトルを提供
    "properties": [
        {"name": "text", "dataType": ["text"]}
    ]
}

# ドキュメントを挿入
documents = [
    "RouteAPI 是一个 AI API 网关",
    "支持多家 AI 模型供应商",
    "提供统一的接口和计费"
]

for doc_text in documents:
    # 埋め込みを生成
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=doc_text
    )
    embedding = response.data[0].embedding

    # Weaviate に保存
    weaviate_client.data_object.create(
        data_object={"text": doc_text},
        class_name="Document",
        vector=embedding
    )

# クエリ
query = "什么是 RouteAPI"
query_response = client.embeddings.create(
    model="text-embedding-3-small",
    input=query
)
query_embedding = query_response.data[0].embedding

# ベクトル検索
results = weaviate_client.query.get("Document", ["text"]) \
    .with_near_vector({"vector": query_embedding}) \
    .with_limit(3) \
    .with_additional(["distance"]) \
    .do()

for item in results["data"]["Get"]["Document"]:
    print(f"距离: {item['_additional']['distance']:.4f}, 文本: {item['text']}")

RAG アプリケーション例

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-routeapi-token",
    base_url="https://api.routeapi.ai/v1"
)

# ナレッジベースドキュメント
knowledge_base = [
    "RouteAPI 是一个统一的 AI API 网关,聚合了 OpenAI、Claude、Gemini 等多家供应商。",
    "RouteAPI 提供统一的认证、计费和监控能力。",
    "RouteAPI 支持流式输出、工具调用和多模态输入。",
    "用户可以通过控制台管理 API Token、查看用量日志和充值余额。"
]

# ナレッジベース用の埋め込みを生成
kb_embeddings_response = client.embeddings.create(
    model="text-embedding-3-small",
    input=knowledge_base
)
kb_embeddings = [data.embedding for data in kb_embeddings_response.data]

# ユーザークエリ
user_query = "RouteAPI 有哪些功能?"

# クエリ用の埋め込みを生成
query_response = client.embeddings.create(
    model="text-embedding-3-small",
    input=user_query
)
query_embedding = query_response.data[0].embedding

# 類似度を計算して最も関連性の高いドキュメントを検索
import numpy as np

def cosine_similarity(vec1, vec2):
    return np.dot(vec1, vec2) / (np.linalg.norm(vec1) * np.linalg.norm(vec2))

similarities = [cosine_similarity(query_embedding, kb_emb) for kb_emb in kb_embeddings]
top_k = 2
top_indices = np.argsort(similarities)[-top_k:][::-1]

# コンテキストを構築
context = "\n".join([knowledge_base[i] for i in top_indices])

# Chat Completions を呼び出して回答を生成
chat_response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[
        {"role": "system", "content": "你是一个 RouteAPI 助手。请根据提供的上下文回答用户问题。"},
        {"role": "user", "content": f"上下文:\n{context}\n\n问题:{user_query}"}
    ]
)

print(chat_response.choices[0].message.content)

ベストプラクティス

1. 適切な埋め込みモデルを選択

考慮事項	推奨
一般的なシナリオ	text-embedding-3-small を使用、コストパフォーマンスが高い
高精度が必要	text-embedding-3-large を使用、次元数が高い
中国語セマンティクス	bge-large-zh などの中国語最適化モデルを検討
コスト優先	低次元モデルを選択するか、dimensions パラメータで削減

2. テキスト前処理

def preprocess_text(text):
    """テキスト前処理"""
    # 余分な空白を削除
    text = " ".join(text.split())
    # 長さを制限（モデル制限を超えないように）
    max_tokens = 8000  # 余裕を持たせる
    if len(text.split()) > max_tokens:
        text = " ".join(text.split()[:max_tokens])
    return text

# 使用法
clean_text = preprocess_text(raw_text)
response = client.embeddings.create(
    model="text-embedding-3-small",
    input=clean_text
)

3. 次元選択

一部のモデル（text-embedding-3-small や text-embedding-3-large など）は、dimensions パラメータを介して出力次元をカスタマイズできます。

# ストレージと計算コストを節約するために次元を削減
response = client.embeddings.create(
    model="text-embedding-3-small",
    input="RouteAPI 是一个 AI API 网关",
    dimensions=512  # デフォルト 1536 から 512 に削減
)

次元削減は精度をわずかに低下させますが、ストレージコストとクエリレイテンシを大幅に削減できます。開発段階で異なる次元がビジネス指標に与える影響をテストすることをお勧めします。

4. コスト最適化

• バッチ処理: 複数のテキストを1つのリクエストにまとめます。
• 埋め込みのキャッシュ: 静的ドキュメントの場合、1回埋め込みを生成してキャッシュして再利用します。
• 適切なモデルを選択: 最大のモデルを盲目的に使用しないでください。text-embedding-3-small はほとんどのシナリオで十分です。
• 次元削減: dimensions パラメータを使用してベクトル次元を削減します。

5. エラー処理

from openai import OpenAI, OpenAIError

client = OpenAI(
    api_key="sk-your-routeapi-token",
    base_url="https://api.routeapi.ai/v1"
)

def get_embedding_with_retry(text, max_retries=3):
    """再試行付き埋め込み生成"""
    for attempt in range(max_retries):
        try:
            response = client.embeddings.create(
                model="text-embedding-3-small",
                input=text
            )
            return response.data[0].embedding
        except OpenAIError as e:
            if attempt == max_retries - 1:
                raise
            print(f"请求失败,重试 {attempt + 1}/{max_retries}: {e}")
            time.sleep(2 ** attempt)  # 指数バックオフ
    return None

6. パフォーマンス最適化

import asyncio
from openai import AsyncOpenAI

async_client = AsyncOpenAI(
    api_key="sk-your-routeapi-token",
    base_url="https://api.routeapi.ai/v1"
)

async def get_embeddings_batch(texts, batch_size=50):
    """非同期バッチ取得埋め込み"""
    results = []
    for i in range(0, len(texts), batch_size):
        batch = texts[i:i + batch_size]
        response = await async_client.embeddings.create(
            model="text-embedding-3-small",
            input=batch
        )
        results.extend([data.embedding for data in response.data])
    return results

# 使用法
texts = ["テキスト1", "テキスト2", ..., "テキスト1000"]
embeddings = asyncio.run(get_embeddings_batch(texts))

よくある質問

Q: 埋め込みベクトルはモデル間で使用できますか?
いいえ。異なるモデルは異なる次元とセマンティック空間を持つベクトルを生成するため、クエリベクトルとドキュメントベクトルを生成するには同じモデルを使用する必要があります。

Q: 類似度しきい値を選択する方法は?
コサイン類似度の範囲は -1 から 1 です。一般的に:

• 0.8: 高度に関連

• 0.6-0.8: 関連
• < 0.6: 弱い関連または無関連

具体的なしきい値は、ビジネスシナリオに基づいてテストと調整が必要です。

Q: 埋め込み生成失敗の一般的な原因は?

エラー	原因	解決策
invalid_api_key	無効な token	Authorization header を確認
model_not_found	モデル ID が間違っているまたは利用不可	モデル ID とアカウント権限を確認
context_length_exceeded	入力テキストが長すぎる	テキストを短縮またはセグメントで処理
rate_limit_exceeded	リクエストが頻繁すぎる	並行処理を減らすか間隔を増やす

Q: 多言語テキストの処理方法は?
ほとんどの埋め込みモデル（text-embedding-3-small など）は多言語をサポートしていますが、言語間セマンティックマッチングの効果はモデルトレーニングに依存します。中国語シナリオの場合、bge-large-zh などの中国語最適化モデルを優先的に検討してください。

Q: 埋め込みベクトルはどのくらい保存できますか?
埋め込みベクトルは決定論的（同じ入力で同じベクトルを生成）であり、モデルを切り替えるかモデルバージョンが更新されるまで、長期保存および再利用できます。