セマンティックキャッシュ

概要

セマンティックキャッシュは、同一または意味的に近いリクエストで既存の回答を再利用し、重複するモデル生成呼び出しを減らします。たとえば「商品に満足できません。返金を申請するにはどうすればよいですか？」と「購入後に返金したいのですが、どう操作すればよいですか？」は、同じ回答を再利用できる場合があります。

よくある質問や製品に関する問い合わせなど、回答が安定している業務に適しています。リアルタイム情報、個人の状態、毎回異なる内容の生成が必要なタスクでは、慎重に有効化してください。セマンティックヒットは以前の回答をそのまま返し、新しい質問に合わせて書き換えることはありません。

これはプロバイダーのプロンプトキャッシュ（Prompt Caching）とは異なります。プロンプトキャッシュでは通常モデル生成が引き続き実行され、統計や課金の扱いも異なります。

利用の前提とモードの選択

管理者があらかじめキャッシュを有効化し、利用可能なストレージを設定しておく必要があります。また、リクエストには有効な単一の API 認証情報と解決可能なキャッシュキーが必要で、メッセージ数が履歴しきい値（デフォルトは 3 メッセージ。3 ラウンドではありません）を超えないことが条件です。

モード	仕組み	必要な準備
完全一致のみ（Direct）	正規化後に同一となるリクエストの回答を再利用	キャッシュストレージ
完全一致とセマンティック一致（Semantic）	まず完全一致を確認し、ヒットしない場合は意味的類似度で検索	キャッシュストレージ、Embedding サービス、一致するベクトル次元

Embedding はテキストをベクトルに変換し、意味の比較に使用します。セマンティック検索は呼び出しのオーバーヘッドを増やし、それでもヒットしない場合は上流へのリクエストが引き続き必要になるため、ヒット率の低い業務では必ずしも速く、安くなるとは限りません。

対応インターフェース

インターフェースの種類	パス	対応範囲
OpenAI 形式	POST /v1/chat/completions	非ストリーミングとストリーミング
Anthropic 形式	POST /v1/messages	非ストリーミングとストリーミング
OpenAI Responses 形式	POST /v1/responses	ステートレスなリクエスト（ストリーミングを含む）

Responses で background: true、conversation、または空でない previous_response_id を使用する場合はキャッシュをスキップします。/v1/responses/compact はキャッシュの対象外です。

クイック検証

キャッシュが有効になっていることを確認し、アドレス、API Key、モデルを実際の値に置き換えてください。

curl -i 'https://your-gateway.example.com/v1/chat/completions' \
  -H 'Authorization: Bearer <ONEGATEWAY_API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'hcd-og-cache-key: faq-demo' \
  -d '{
    "model": "<MODEL_ID>",
    "messages": [{"role": "user", "content": "商品に満足できません。返金を申請するにはどうすればよいですか？"}],
    "temperature": 0
  }'

1. 初回リクエスト：利用可能なエントリがない場合は og-cache: MISS が返され、成功した回答はバックグラウンドで書き込まれます。
2. 同一リクエスト：書き込みの完了を待ってからそのまま再試行します。ヒットすると og-cache: HIT と og-cache-type: direct が返されます。
3. 類似リクエスト：セマンティックモードを有効にした状態で、質問を「購入後に返金したいのですが、どう操作すればよいですか？」に変更し、その他の条件は変えません。しきい値に達すると、ヒットの種類は semantic になります。

初回レスポンスの直後に再試行すると MISS になる場合があり、類似した言い回しでも必ずヒットするとは限りません。詳しくはトラブルシューティング表を参照してください。

管理者による設定

設定は対象の Gate インスタンスごとに適用されます。コンソールが連携済みの場合は、該当するインスタンスで操作できます。インターフェースを直接呼び出す必要がある場合は、専用の Gate 管理用認証情報を使用し、設定手順の詳細を参照してください。

1. キャッシュストレージとネームスペースを設定し、テスト環境と本番環境を区別します。
2. モードを選択します。完全一致のみのモードでは embedding_url を空欄のままにします。セマンティックモードでは、Embedding インターフェースの完全なアドレス、形式、モデル、キー、実際のベクトル次元を入力します。
3. 以下のポリシーを設定し、検証して保存した後、クイック検証を実施します。

設定項目	デフォルト値	説明
TTL	5m	新しいエントリの有効期間
Similarity threshold	0.8	高いほど厳格になります。回答の正確率を表すものではありません
History threshold	3	メッセージ数で数え、超えた場合はキャッシュをスキップします
Default cache key	空	リクエストに業務キーもテナントヘッダーもない場合に使用されます
Isolate by model and provider	オン	モデルやプロバイダーごとに個別にキャッシュします
Exclude system prompt	オフ	デフォルトではシステムプロンプトがマッチングと履歴数のカウントに含まれます

通常はデフォルトの分離ルールを維持してください。システムプロンプトを無視すると、別のロール設定で生成された回答が再利用される可能性があります。Embedding モデルを変更する場合は新しいネームスペースを使用し、次元が変わる場合は対応するコレクションまたはインデックスも必要です。

キャッシュ設定はホットアップデートに対応しています。更新に失敗した場合は直前の有効な設定が保持され、処理中のリクエストは元の設定を引き続き使用します。ストレージのフィールド、設定例、保存エラーの対処は技術リファレンスを参照してください。

リクエスト単位でのキャッシュ制御

リクエストヘッダー	用途
hcd-og-cache-key	業務用のキャッシュ空間を指定します（例：product-faq:v1）
hcd-og-ttl	新しいエントリの有効期間を設定します（例：30s、5m、または整数の秒数）
hcd-og-threshold	セマンティックしきい値を設定します。範囲は 0 より大きく 1 以下です
hcd-og-cache-type	direct は完全一致のみ、semantic はセマンティックのみ。デフォルトは完全一致の後にセマンティック
hcd-og-no-store	true の場合、読み取りは許可しますが、今回の回答は保存しません

リクエスト単位の TTL は、既にヒットしたエントリの有効期限を変更しません。不正な制御値はデフォルトの動作にフォールバックします。Embedding が設定されていない状態でセマンティックのみのリクエストを送ると、キャッシュはスキップされます。完全な解析ルールは技術リファレンスを参照してください。

No-Store でも以前の回答が返される場合があります

hcd-og-no-store: true はキャッシュの読み取りや Embedding による検索を禁止しません。回答を再生成する必要がある場合は、新しい業務キャッシュキーを使用するか、管理者に関連キャッシュの削除を依頼してください。さらに新しい回答を保存したくない場合は、No-Store を併用します。

キャッシュ空間とマッチングの範囲

キャッシュ空間は次の順序で選択されます：リクエストヘッダー hcd-og-cache-key → リクエストヘッダー hcd-og-tenant-id で指定されたテナント識別子 → ゲートウェイコンテキスト内のユーザー識別子（user:<ユーザー識別子>）→ 設定済みのデフォルトキャッシュキー。すべてのソースが空の場合にのみキャッシュがスキップされます。ユーザー識別子の層は、ゲートウェイコンテキストにその値が設定されている場合にのみ使用されます。

hcd-og-tenant-id は Gate がサポートするリクエストヘッダーで、業務上のテナントを表します。必須のキャッシュキー用フィールドが別にあるわけではありません。アプリケーションで業務シナリオや回答のバージョンを明示的に区別する必要がある場合は、優先度の高い hcd-og-cache-key を使用してください（例：product-faq:v2）。

異なる API 認証情報やキャッシュキーの間ではキャッシュは共有されません。異なるインターフェース、ストリーミングと非ストリーミングも個別にキャッシュされます。モデル、プロバイダー、生成パラメーター、ツール、添付ファイルなどもマッチングに影響するため、質問文だけを比較するわけではありません。完全一致ではテキストが正規化されるため、元のリクエストのバイト単位での一致ではありません。

hcd-og-tenant-id は呼び出し元が設定できる業務識別子であり、テナントの認可の代わりにはなりません。複数のユーザーが 1 つの API 認証情報を共有する場合は、信頼できるアプリケーションが業務キーとテナントヘッダーを設定してください。

認証情報の形式、正規化、マッチングの詳細は技術リファレンスを参照してください。

認証情報の検証と無効化の確認

上流アドレスが設定されている場合、キャッシュ前の認証情報検証がデフォルトで有効になり、有効な検証結果はデフォルトで 5 分間キャッシュされます。キーやアカウントを無効化した後は、設定が同期されたことを確認し、本来キャッシュにヒットするリクエストと上流へ転送されるリクエストの両方で、古い認証情報が拒否されることをそれぞれ検証してください。コンソールのスイッチや検証結果のキャッシュ期間を、すべての経路で無効化が反映される保証とみなさないでください。それでも回答が取得できる場合は、管理者に同期と認証情報検証の状態を確認してもらってください。詳しくはキャッシュ前の認証情報検証を参照してください。

ライフサイクルと削除

成功した回答はバックグラウンドで書き込まれます。ストリーミングの回答は正常に終了する必要があり、中断された回答は保存されません。ヒットしても有効期間は延長されず、デフォルトの TTL を変更しても古いエントリがすぐに無効になることはありません。Gate を停止または再起動しても、バックエンドのエントリは能動的に削除されません。ストレージの再起動後にデータが保持されるかどうかは、その永続化設定によります。

キャッシュの削除

ナレッジを更新する際は、バージョン付きのキャッシュキーに切り替える（例：product-faq:v1 を product-faq:v2 に変更）か、管理者が削除を行います。

方法	範囲
エントリ ID 指定	og-cache-id に対応する回答を削除します
キャッシュキー指定	現在のネームスペース内でその業務キーに属するエントリを削除します。複数の API 認証情報にまたがる場合があります

1 件を削除した後でも、別の類似エントリにヒットする可能性があり、処理中のリクエストが再度書き込む場合もあります。完全な削除コマンドと結果の検証、設定変更と再起動時の動作は技術リファレンスを参照してください。

効果の確認とトラブルシューティング

まずレスポンスヘッダーを確認します。

レスポンスヘッダー	意味
og-cache	HIT はヒット、MISS は検索対象となったもののヒットしなかったことを示します
og-cache-type	ヒットの種類：direct または semantic
og-cache-id	ヒットしたエントリの ID、または MISS 時の書き込み候補 ID。候補 ID は保存済みであることを保証しません
og-cache-similarity	セマンティックヒット時の類似度

管理者はヒットの集計とリクエストログを確認できます。これには logging プラグインと MySQL のログストレージを有効にする必要があります。全体のヒット率は「完全一致のヒット数 + セマンティックのヒット数」を、永続化が完了したすべてのリクエスト数で割った値で、キャッシュをスキップしたリクエストも含まれます。ログや統計は非同期書き込みのため遅れて反映される場合があります。

キャッシュの Token 統計や、再生されたレスポンス内の過去の usage は今回の上流での消費量を表すものではなく、今回の課金額を直接算出することにも使えません。詳しくは監視リファレンスを参照してください。

症状別のトラブルシューティング

症状	優先して確認すること
og-cache がない	有効化されているか、インターフェース、認証情報、キャッシュキー、メッセージ数、およびプロキシがレスポンスヘッダーを保持しているか
同一リクエストが MISS のまま	バックグラウンドの書き込みが成功したか、TTL、前後のリクエストの認証情報とパラメーター、No-Store
セマンティック一致だけがヒットしない	Embedding の設定、実際の次元、マッチングの範囲としきい値。MISS 時に類似度が返されるとは限りません
HIT でも遅い	キャッシュ前の認証情報検証とエンドツーエンドの所要時間。キャッシュ検索の所要時間には認証情報の確認は含まれません
キャッシュは使えるが監視にデータがない	logging、MySQL、絞り込み範囲、書き込みの遅延
削除後も以前の回答が返される	別のエントリにヒットしていないか、処理中の書き込み、ストレージでの可視性。ナレッジ更新時はキャッシュキーのバージョンを切り替えられます

しきい値を下げると誤ヒットが増える可能性があります。まず実際の業務の質問で回答が再利用に適しているかを確認してから調整してください。設定の保存失敗などの管理面の問題は、詳細なトラブルシューティングを参照してください。

よくある質問

セマンティックキャッシュで必ずレイテンシーとコストを削減できますか？

必ずしもそうではありません。ヒットした場合は既存の回答を再利用でき、業務モデルの生成呼び出しを減らせます。しかし、セマンティック検索自体で Embedding サービスを呼び出す必要があり、ヒットしなければ業務モデルへのリクエストも引き続き必要になるため、ヒット率の低いシナリオではかえって遅く、コストが高くなる場合があります。よくある質問や回答が安定している業務に優先して適用し、ヒット率とエンドツーエンドの所要時間をあわせて効果を評価してください。

同じ質問なのに、なぜキャッシュにヒットしないのですか？

キャッシュは質問文だけでなく、API 認証情報、キャッシュキー、インターフェース、ストリーミングモード、モデル、生成パラメーターなどの影響も受けます。初回の回答はバックグラウンドで書き込まれるため、すぐに再試行しても MISS になる場合があります。エントリの有効期限切れや、リクエストで No-Store を設定した場合も、その後のヒットに影響します。まずリクエストがキャッシュの条件を満たしていることを確認し、トラブルシューティング表に沿って確認してください。

類似度しきい値が 0.8 というのは、回答の正確率が 80% という意味ですか？

いいえ。しきい値は意味的類似度のマッチングを制御するもので、回答の正確率や信頼度ではありません。しきい値を下げるとヒットが増える可能性がありますが、意味の異なる質問で同じ回答が再利用される可能性もあります。キャッシュにヒットすると以前の回答がそのまま返され、新しい質問に合わせて書き換えられることはありません。実際の業務の質問で、再利用が適切かどうかを検証してください。

特定のリクエストで回答を再生成するにはどうすればよいですか？

未使用の hcd-og-cache-key を使用するか、管理者に関連キャッシュの削除を依頼してください。hcd-og-no-store: true は今回の回答の保存を禁止するだけで、既存エントリの読み取りは引き続き許可されます。再生成したうえで保存もしたくない場合は、新しいキャッシュキーと No-Store を併用できます。キャッシュキーのリクエストヘッダーを省略しても、テナントヘッダーやデフォルトのキャッシュキーが使用される可能性があるため、キャッシュがスキップされる保証はありません。

異なるメンバー間でキャッシュは共有されますか？

異なる API 認証情報やキャッシュキーの間ではエントリは共有されません。複数のメンバーが 1 つの API 認証情報を共有し、同じキャッシュキーを使用している場合は、回答が再利用される可能性があります。分離が必要な場合は、信頼できるアプリケーションで異なる業務キャッシュキーを設定してください。テナントヘッダーは業務識別子にすぎず、認可の代わりにはなりません。詳しくはキャッシュ空間とマッチングの範囲を参照してください。

ナレッジの更新や TTL の変更後、以前の回答はすぐに無効になりますか？

いいえ。デフォルトの TTL を変更しても古いエントリがすぐに期限切れになることはなく、ヒットによって有効期間が延長されることもありません。ナレッジを更新する際は、キャッシュキーを product-faq:v1 から product-faq:v2 に切り替えるか、関連エントリを削除してください。1 件だけ削除しても、別の類似エントリにヒットする可能性があります。操作方法はキャッシュの削除を参照してください。

ストリーミングの回答が中断された場合、生成済みの部分はキャッシュされますか？

いいえ。ストリーミングの回答は正常に終了した場合にのみキャッシュに書き込まれ、中断された部分的な回答は保存されません。ストリーミングと非ストリーミングのリクエストは個別にキャッシュされるため、stream を切り替えた場合にもう一方のモードのエントリにヒットすることは期待できません。

キャッシュにヒットした場合、レスポンス内の usage は今回の消費量ですか？

いいえ。キャッシュの再生に含まれる usage は過去のレスポンスデータであり、今回の業務モデルでの上流消費量を表すものではなく、今回の課金額の算出に直接使用することもできません。キャッシュの Token 統計についても、過去の使用量と実際の課金を区別する必要があります。