エンベディング

エンベディング

エンベディング（Embeddings）は意味を捉えた数値表現で、テキストをベクトル（数値の配列）に変換し、さまざまな機械学習タスクに利用できます。BazaarLinkはOpenAI Embeddings API互換の統一エンドポイントを提供し、単一のインターフェースで複数プロバイダーのエンベディングモデルを呼び出せます。

Embeddingのレスポンスでは、x-request-idと一致する不透明なBazaarLinkリクエストIDが使われます。GET /v1/generationで使用してください。非ストリーミングのレスポンスでは、同じIDがx-generation-idにも返されます。usage.costはこのリクエストでお客様に請求されたUSD金額です。統計は完了後数秒かかる場合があるため、404は短時間再試行してください。

エンベディングとは？

エンベディングはテキストを高次元ベクトルに変換し、意味的に近いテキストはベクトル空間上でも近い距離に位置します——例えば「猫」と「子猫」のエンベディングは似ていますが、「猫」と「飛行機」は大きく離れています。このベクトル表現により、機械はテキスト間の関係を理解できるようになり、多くのAIアプリケーションの基盤となっています。

一般的なユースケース

パラメータ

基本リクエスト

from openai import OpenAI

client = OpenAI(
    base_url="https://api.bazaarlink.ai/v1",
    api_key="sk-bl-YOUR_API_KEY",
)

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

print(response.data[0].embedding)  # 1536-dimensional vector

バッチ処理

文字列の配列を送信すると、1回のリクエストで複数のテキストをまとめてエンベディングできます — テキストごとに呼び出すより安く速くなります。

response = client.embeddings.create(
    model="openai/text-embedding-3-small",
    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",
    ],
)

for i, item in enumerate(response.data):
    print(f"Embedding {i}: {len(item.embedding)} dimensions")

マルチモーダル入力（画像＋テキスト）

画像入力に対応したモデル（output_modalities に "embeddings"、inputModalities に "image" を含む）は、{content:[{type:"text",...}, {type:"image_url",...}]} 形式の入力アイテムを受け付け、画像単体、またはテキストと組み合わせてエンベディングできます。

import requests

response = requests.post(
    "https://api.bazaarlink.ai/v1/embeddings",
    headers={
        "Authorization": "Bearer sk-bl-YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "google/gemini-embedding-2-preview",
        "input": [{
            "content": [
                {"type": "text", "text": "A scenic boardwalk through a green meadow"},
                {"type": "image_url", "image_url": {"url": "https://example.com/boardwalk.jpg"}},
            ]
        }],
        "encoding_format": "float",
    },
)

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

エンベディングモデルの探し方

エンベディング専用のモデル一覧エンドポイントはありません。GET /v1/models を呼び出し、output_modalities に "embeddings" を含むエントリをクライアント側でフィルタするか、Models ページを参照してください。

制限事項

• ストリーミング非対応 — チャット補完と異なり、エンベディングは常に完全なレスポンスとして返されます。
• 各モデルには最大入力長があります。それを超えるテキストはアップストリーム側で切り詰められるか拒否されます。
• 同一の入力に対するエンベディングは決定論的です — temperature やランダム性はありません。

ベストプラクティス

• 速度・品質・コストのトレードオフに応じてモデルを選びましょう — 小型モデル（例：qwen/qwen3-embedding-4b）は安価で高速、大型モデル（例：openai/text-embedding-3-large）は一般的により高精度にエンベディングします。
• テキストごとに呼び出すのではなく、複数のテキストを1回のリクエストにまとめましょう — ラウンドトリップが減り、オーバーヘッドも下がります。
• 結果をキャッシュしましょう — 同じ入力のエンベディングは変化しないため、再生成せず保存しておくべきです。
• 比較にはユークリッド距離ではなくコサイン類似度を使いましょう — スケール不変で高次元ベクトルに向いています。
• 各モデルのコンテキスト長に注意しましょう — 長い文書はエンベディング前にチャンク分割が必要な場合があります。