モデルとモダリティの実践ガイド2026年11月10日Flatkey Team

Open AI Embeddings API：セマンティック検索の構築と検証

OpenAI embeddingsを使った小規模なセマンティック検索の例を構築し、ベクトルマッピング、トークン制限、インデックスの変更、検索品質を検証します。

Open AI embeddings APIをお探しですか？OpenAIのembeddingsエンドポイントは、テキストを数値ベクトルに変換し、アプリケーションが関連する文章を取得できるようにします。リクエストは最初のステップにすぎません。有用な検索機能には、安定したドキュメントID、一貫したベクトル空間、そして取得が改善されたかどうかを判断するテストも必要です。

このガイドでは、小規模なPython検索の例を構築し、各ベクトルとともに保存する内容を示し、実験を製品に移行するためのチェックリストを提供します。OpenAIを直接使用します。ゲートウェイの互換性とモデルの可用性は、プロバイダーごとに個別に検証する必要があります。

Open AI embeddings API：必要なリクエスト

埋め込みモデルとAPIキーを指定して、POST https://api.openai.com/v1/embeddings にテキストを送信します。アプリケーションが数値配列を想定している場合は、encoding_format="float" を選択します。バッチでは、各レスポンス項目の index を使用して、ベクトルを対応する入力に再接続します。レスポンスにはトークン使用量も含まれます。dimensions オプションは、第3世代の埋め込みモデルでサポートされています。OpenAI APIリファレンス。

埋め込みは生成された回答ではありません。検索拡張アプリケーションでは、まず検索によってソース文章を選択し、その後、別の生成呼び出しでそれらの文章を使用して回答できます。ステージを分離しておくことで、不適切な結果を診断できます。検索が誤った根拠を取得したのか、それとも回答モデルが適切な根拠を誤用したのかを判別できます。

モデルを選択し、その構成を固定する

ドキュメント化されているデフォルトのベクトル長は、text-embedding-3-small では1,536、text-embedding-3-large では3,072です。これらのモデルは、dimensions を通じてより短い出力ベクトルをサポートします。ベクトルを短くすると、ストレージと検索のトレードオフが変わります。評価を省略する理由にはなりません。OpenAI embeddingsガイド。

まずは1つの構成と、代表的な少数のクエリから始めます。モデル、要求した次元数、テキスト処理バージョンをインデックスとともに記録します。同じ長さの2つのベクトルが、互換性のあるモデルから生成されたことを保証するわけではありません。モデルまたは処理ルールを変更する場合は、別のインデックスを構築して比較してから、本番トラフィックを切り替えてください。

最小限のPythonセマンティック検索の例

Python環境に openai をインストールし、通常のシークレットマネージャーまたは環境設定を通じて OPENAI_API_KEY を利用できるようにします。キーはソース管理やブラウザーコードに含めないでください。公式Python SDKは、OpenAI() の構築時にこの変数を読み取ります。

以下を search_demo.py として保存します。3つの架空のサポートドキュメントを使用し、コーパスとクエリを埋め込み、コサイン類似度でドキュメントをランク付けします。実行すると課金対象のAPIリクエストが発生します。出力はサービスのレスポンスに依存します。この例は特定のスコアやランキングを保証するものではありません。

import math
from openai import OpenAI

client = OpenAI(timeout=30.0, max_retries=2)
model = "text-embedding-3-small"
dimensions = 1536

documents = [
    {"id": "key-rotation", "text": "Replace an exposed API key and revoke the old credential."},
    {"id": "invoice-export", "text": "Download a monthly invoice from the billing workspace."},
    {"id": "request-timeout", "text": "Record the request ID and retry temporary upstream timeouts."},
]
query = "What should I do after accidentally sharing a secret key?"


def embed(texts):
    response = client.embeddings.create(
        model=model, input=texts,
        dimensions=dimensions, encoding_format="float",
    )
    ordered = sorted(response.data, key=lambda item: item.index)
    if [item.index for item in ordered] != list(range(len(texts))):
        raise ValueError("Unexpected embedding response indices")
    vectors = [item.embedding for item in ordered]
    if any(len(vector) != dimensions for vector in vectors):
        raise ValueError("Unexpected vector dimensions")
    print("Input tokens:", response.usage.prompt_tokens)
    return vectors


def cosine(a, b):
    if len(a) != len(b):
        raise ValueError("Vector dimensions do not match")
    denominator = math.sqrt(sum(x*x for x in a) * sum(y*y for y in b))
    if not denominator:
        raise ValueError("Cannot compare a zero vector")
    return sum(x*y for x, y in zip(a, b)) / denominator


vectors = embed([document["text"] for document in documents])
query_vector = embed([query])[0]
ranked = sorted(
    ((cosine(query_vector, vector), document["id"])
     for document, vector in zip(documents, vectors)),
    reverse=True,
)
for score, document_id in ranked:
    print(document_id, round(score, 4))

python search_demo.py を実行します。3つすべてのIDがそれぞれ1回表示され、各埋め込みが構成した長さであることを確認してください。次に、請求書について尋ねるようクエリを変更します。これはデータフローのスモークテストであり、システムが実際のサポートトラフィックに対応できることの証明ではありません。わかりやすくするため、この例では実行のたびにコーパスを再度埋め込みます。デプロイ済みのサービスでは通常、ドキュメントベクトルを永続化し、新規または変更されたコンテンツだけを埋め込む必要があります。

デモを信頼性の高いドキュメントインデックスにする

以下のレコードレイアウトは、実用的な出発点です。これはアプリケーション設計の例であり、OpenAIが必須とするフィールドスキーマではありません。

各チャンクとともに保存するもの	重要な理由
`document_id` と `chunk_id`	配列の順序に依存せず、適切なコンテンツを更新または削除できます。
ソース URL、セクションタイトル、ソース改訂版	有用な出典を表示し、古くなった回答を追跡できます。
コンテンツハッシュと処理バージョン	実際に再埋め込みが必要なチャンクを特定できます。
モデルと次元数	互換性のないベクトル構成が誤って混在することを防ぎます。
テナントおよびアクセス制御メタデータ	取得対象を、リクエストしたユーザーがアクセスできるドキュメントに絞り込みます。
テキストと埋め込み	ベクトルを選択した後、元の文章を返します。

意味のある境界でドキュメントを分割し、その後でトークン長を確認します。質問への回答を含むセクションは、単体で取得された場合でも理解できる状態に保つ必要があります。オーバーラップは意図的に評価してください。過剰なオーバーラップは、同じ文章の重複バージョンで結果セットを埋める可能性があります。

最初の実験では、上記のインメモリループで十分です。コーパスの規模が大きくなったら、必要なフィルタリング、削除、取得の動作をサポートするインデックスまたはベクトルストアを使用してください。類似度スコアに依存する前に、それらの操作をテストします。誤った顧客の非常に類似した文章が、単に最上位にランク付けされたという理由だけで返されることは決してあってはなりません。

入力上限とバッチ上限を個別に確認する

OpenAI の現在のエンドポイントリファレンスでは、入力ごとの最大値は 8,192 トークン、1 リクエスト内の入力全体での合計最大値は 300,000 トークンと定められています。また、バッチ入力の最大数は 2,048 です。空のテキストは無効です。文字数ではなくトークン数を数え、バッチを構築する際は上限を下回る余裕を確保してください。エンドポイントの制約。

Azure OpenAI を使用する場合、エンドポイント設定、認証、デプロイ名には固有の設定があります。直接の OpenAI リクエストをそのまま変更せずにコピーできると想定せず、そのサービスについてはAzure の埋め込み手順に従ってください。ゲートウェイを使用する場合も同様に分けて考えてください。まず、そのエンドポイント、モデルアクセス、サポートされるパラメーター、請求先アカウントを確認します。

インデックス再構築を隠さずにコストを見積もる

埋め込みコストは入力トークン数に応じて発生するため、ドキュメントの取り込み、変更されたチャンク、クエリの埋め込みを個別に数えます。text-embedding-3-small など、該当するモデルページで最新価格を確認し、提示された料金が自分のリクエストモードに適用されるか確認してください。

計画例として、P を検証済みの入力トークン 100 万あたりの価格とします。

初回取り込み:     50,000 チャンク × 400 トークン = 20 百万トークン
月次変更:          5,000 チャンク × 400 トークン =  2 百万トークン
月次クエリ:      200,000 クエリ × 20 トークン =  4 百万トークン

初回埋め込みコスト = 20 × P
継続的な埋め込みコスト = (2 + 4) × P = 6 × P

これらは説明用のワークロード仮定であり、Flatkey または OpenAI の価格ではありません。ベクトルストレージ、検索インフラストラクチャ、回答生成呼び出しは別途加算してください。埋め込みモデルを変更する場合は、移行予算に完全な再埋め込み処理を含めます。変更されていないドキュメントを再埋め込みするパイプラインでは、より大きくても適切にキャッシュされたモデルを使う同じワークロードよりもコストがかかる可能性があります。

リトライを追加する前にエラーを診断する

症状	最初に行う有用な確認
認証エラー	キーが、呼び出しているエンドポイントおよびアカウントに対して有効であることを確認します。
無効なリクエスト	エラー本文、空文字列、トークン数、サポートされるパラメーターを確認します。
レート制限またはクォータエラー	リクエストレートの負荷と、アカウントクォータの枯渇を区別します。
一時的なサーバーエラーまたはタイムアウト	リクエスト識別子を保持し、上限を設けたリトライ動作を使用します。
ベクトルストアの次元エラー	コレクション構成と、実際に返されたベクトル長を比較します。
もっともらしいが無関係な結果	ネットワークを疑う前に、チャンクテキスト、モデルの一貫性、クエリ例を確認します。

最初の 4 つの確認は、OpenAI のエラーガイドに従っています。最後の 2 つは、アプリケーションとインデックスに関するものです。追加のリトライループを加える前に、サーバーのリトライに関する指針を尊重し、SDK のリトライも考慮してください。認証情報や不要な非公開ドキュメントのテキストを記録せずに、運用メタデータをログに残します。

回答モデルを選ぶ前に検索を評価する

実際のユーザー質問から、言い換え、正確な製品名、曖昧な質問、コーパスでは回答できない質問を含む小規模なラベル付きセットを作成します。システムを調整する前に、回答可能な各クエリについて期待されるソースドキュメントを書き出してください。

候補となる各構成について、許容できるソースが最初の数件の結果に含まれるか、どの程度の重複コンテンツが返されるか、取得レイテンシ、クエリあたりのコストを記録します。失敗は個別にレビューしてください。クエリが正確なエラーコードを尋ねている場合、キーワード一致がセマンティック類似性を補完できることがあります。ソースが存在しない場合、埋め込みの次元数を変更しても作り出すことはできません。

最終比較のために、質問の一部をホールドアウトとして保持します。3 ドキュメントのデモから類似度しきい値を選び、それを普遍的な信頼度スコアとして扱わないでください。有用な受け入れテストは、自身のアプリケーションにおいて誤った検索がもたらす影響を反映します。

アプリケーションにおける Flatkey の位置付け

Flatkey は、OpenAI 互換のモデルルーターと最新のモデルディレクトリを提供しています。アプリケーションのモデル生成側を評価するには、Flatkey 統合ドキュメントを使用してください。上記の例は OpenAI を直接呼び出しており、Flatkey を通じて埋め込みモデルまたはすべての埋め込みパラメータが利用可能であることを保証するものではありません。

マルチプロバイダーのアプリケーションでは、検索設定を回答モデルの設定から独立させてください。これにより、実験ごとにドキュメントインデックスを再構築することなく、回答モデルを比較できます。ルーティング、アカウント管理、運用チェックを計画する際は、Flatkey の API アーキテクチャガイドを確認してください。