すでに返した内容から応答する AI ゲートウェイ
サポートアシスタントは、一日中同じ質問を少しずつ違う言葉で尋ねられます。 そのモデルの前に置かれたゲートウェイは、モデルを再度呼び出す代わりに、 意味が十分に近い以前の質問に返した応答から質問に答えることができます。 このワークスペースは、そのようなゲートウェイを、応答を保持するストアとともに Kubernetes マニフェストへコンパイルします。
これを行う Feature は core/semantic-caching です。ある呼び出し元が、
別の呼び出し元のリクエストによって生成されたどの応答を受け取りうるかが、
このページの大半で扱う問題です。誤った呼び出し元の間で共有されたキャッシュは、
ある人のために生成された応答を別の人に渡してしまうからです。
このワークスペースは独自のカタログエンティティを一切作成しません。 ここにある 3 つのエンティティファイル — Aggregate、Manifest、Release — が、 誰かが書くもののすべてです。
構築されるもの
| インスタンス | カタログの Component | ここでの役割 |
|---|---|---|
router | core/gateway/litellm | AI ゲートウェイ: チャット用エイリアス assistant と埋め込み用エイリアス embedder を持ち、それぞれ models ソケットに接続されたモデルから提供されます |
chat | core/ai-model/openai | assistant の背後にあるチャットモデル。OpenAI 自身の API で、参照として利用されます。クラスタ内ではこのために何も実行されません |
embeddings | core/ai-model/openai-embedding | embedder の背後にある埋め込みモデル。同じ方法で利用されます |
cache | core/datastore/redis | ゲートウェイが応答を保存するストア |
uses エッジは 3 本です。2 本はゲートウェイの models ソケットに入り、それぞれのモデルに 1 本ずつつながり、
ゲートウェイがそのモデルに提示するキーを credential として運びます。
残りの 1 本は cache_store ソケットに入り、キャッシュがストアに提示するパスワードを credential として運びます。
Feature のアタッチメントはゲートウェイに 2 つあります。管理用キーである
api_key と、キャッシュである answers です。ストアには 1 つ、
必要とするパスワードである password があります。2 つのパスワードのアタッチメントは 1 つの
パラメータ cache_password を読み、2 つのモデルの認証情報は別のパラメータ openai_key を読みます。
Release がその両方を満たします。answers アタッチメントは、各プロンプトをベクトルに変換する埋め込みエイリアス、
2 つのプロンプトがどれだけ似ている必要があるか(コサイン類似度で 0.9)、
保存された応答がどれだけ持続するか(1 時間)を指定します。
scope は省略されているため、デフォルトの end_user が使われます。
サンプルを生成する
このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。
例の名前を付けた新しいフォルダーに例を書き出します。
aggrega scaffold --example ai-gateway-semantic-cacheその後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。
cd ai-gateway-semantic-cacheビルド
aggrega build --release release.yaml --auto-pullrelease はビルドの前に lockfile を必要とします。lockfile は同梱されるのではなく生成されるため、クローンした直後には存在しません。先に解決するか、ビルドに作成させてください:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildこのワークスペースは、.aggrega-config.yaml が指定するデフォルトレジストリからカタログのエンティティを解決します。キャッシュの実現では、コンパイラにもカタログにも同梱されていないプラグインを 1 つ実行します。ゲートウェイ設定ステップ pipeline-step/litellm-gateway-config で、解決時に default_registry が指定するレジストリ hub.aggrega.ai から取得されます。
ビルドは次のように出力します。<workspace> はこの例のフォルダを表します。
[… omitted: a line reporting on the gateway configuration step's plugin, five warnings, one per credential attachment, that the declared-sensitive origin reaches the target with no per-key sensitivity marking, because the realization maps it through a valuesMapping, the resolution's summary and a total build time, which differ per run, and a notice that core/referenced-secret declares origin in both of its pillars]Build completed: 13 files written to <workspace>/distAI アシスタントを使う
Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。
Aggrega のツールだけを使い、フォルダーを自分で作成しないでください。ワークスペースフォルダーにまだ `ai-gateway-semantic-cache` フォルダーがない場合は、`example` を `ai-gateway-semantic-cache` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これにより、サンプルが新しい `ai-gateway-semantic-cache` フォルダーに書き出されます。次に、`workspace_root` を `ai-gateway-semantic-cache`、`release` を `release.yaml`、`auto_pull` を true、`write` を true に設定して `build` ツールを呼び出してください。ビルドが書き出したファイルを教えてください。ファイルは `ai-gateway-semantic-cache/dist/` の下にあります。レンダリングされたツリー
dist/helm/├── cache--password--cache-secret-cache-password.yaml├── cache-default-service.yaml├── cache-deployment.yaml├── chat-service.yaml├── embeddings-service.yaml├── router--api-zukey--router-secret-router-api-key.yaml├── router--assistant-zdcredential--router-secret-router-assistant-credential.yaml├── router--embedder-zdcredential--router-secret-router-embedder-credential.yaml├── router--replies-zdcredential--router-secret-router-replies-credential.yaml├── router-default-service.yaml├── router-deployment.yaml└── router/ ├── litellm-gateway-config/ │ └── configmap.yaml └── request-guard/ └── request-guard.yamlキャッシュのアタッチメントは独自のファイルを持ち込みません。その働きはゲートウェイの設定に書き込まれます。各モデルは 1 つのファイルをレンダリングします。これはクラスタ内の名前を OpenAI の API ホストに対応付ける Service です。また、モデル接続上の各認証情報は、ゲートウェイと接続のエイリアスにちなんで名付けられた独自の Secret をレンダリングします。
提供するモデル
ルーティングテーブルは gateway の設定本体の先頭にあり、models ソケット上の接続ごとに 1 つのエントリを持ちます。各エントリは、各モデルが公開するもの、つまりそのエンドポイント、OpenAI の API ベース URL、およびそのモデル名から書き出され、
gateway の Recipe がその接続のキーを渡す変数を指定します:
model_list: - model_name: "assistant" litellm_params: model: "openai/gpt-4o" api_base: "https://api.openai.com/v1" api_key: os.environ/LITELLM_MODEL_ASSISTANT_API_KEY - model_name: "embedder" litellm_params: model: "openai/text-embedding-3-small" api_base: "https://api.openai.com/v1" api_key: os.environ/LITELLM_MODEL_EMBEDDER_API_KEYゲートウェイから見たキャッシュ
以下は、ゲートウェイの設定本体、すなわち
dist/helm/router/litellm-gateway-config/configmap.yaml の config.yaml キーの、
litellm_settings 以降の部分です。
[… omitted: the routing table]litellm_settings: callbacks: - /etc/litellm-request-guard/request_field_filter.filter cache: true cache_params: host: os.environ/SEMANTIC_CACHE_STORE_HOST port: os.environ/SEMANTIC_CACHE_STORE_PORT redis_semantic_cache_embedding_model: embedder redis_semantic_cache_index_name: router-answers semantic_cache_scope: end_user similarity_threshold: 0.9 supported_call_types: - acompletion - completion - aresponses - responses - aanthropic_messages - anthropic_messages ttl: 3600 type: redis-semanticここから読み取れることが 5 つあります。
ストアのアドレスは含まれていません。 host と port はゲートウェイ独自の間接参照によって 2 つの環境変数を指定しており、ゲートウェイの Recipe がそれらを cache_store エッジから設定します。以下は dist/helm/router-deployment.yaml にある、ゲートウェイのコンテナの env です。
env: - name: LITELLM_MASTER_KEY valueFrom: secretKeyRef: name: router-api-key key: master-key - name: REDIS_PASSWORD valueFrom: secretKeyRef: name: router-replies.credential key: password - name: LITELLM_MODEL_ASSISTANT_API_KEY valueFrom: secretKeyRef: name: router-assistant.credential key: api-key - name: LITELLM_MODEL_EMBEDDER_API_KEY valueFrom: secretKeyRef: name: router-embedder.credential key: api-key - name: SEMANTIC_CACHE_STORE_HOST value: cache-default - name: SEMANTIC_CACHE_STORE_PORT value: "6379"cache-default はストア自身の Recipe が出力する Service で、その
Recipe が公開する内容から読み取られます。6379 はそれが公開するポートです。キャッシュはストアのパスワードを REDIS_PASSWORD から読み取ります。これは cache_store エッジの credential が描画する Secret である router-replies.credential への参照であり、パスワードそのものを読むことはありません。ストアは同じパラメータ cache-password から独自の Secret を描画し、そこから読み取った --requirepass を付けて起動します。そのため、キャッシュが提示するパスワードとストアが要求するパスワードは、一度だけ書かれた同一の値になります。cache_store エッジがない場合、ストアのアドレスとパスワードを受け取る 3 つの変数はいずれも描画されず、応答を保存する場所のないキャッシュは、後述のとおりビルドを停止させます。3 番目と 4 番目のエントリはモデルのキーで、それぞれ自身の接続の認証情報が描画する Secret から、ルーティングテーブルの該当エントリが指定する変数名で参照されます。helm プロバイダは、Secret から読み取るエントリをすべて通常のエントリより前に書き出します。
埋め込みモデルはゲートウェイ自身のマップのエイリアスです。 ゲートウェイは各プロンプトを、呼び出し元のリクエストが通るのと同じマップを通じて embedder に送ります。そのため、キャッシュは独自のアドレスや認証情報を持ちません。マップが公開していないエイリアスを指定するとビルドは停止し、公開されているエイリアスが列挙されます。
有効期間はストアが管理します。 各応答は ttl を有効期限として書き込まれるため、Redis は保存から 1 時間後にそれを削除します。そのプロンプトに対する次のリクエストはモデルが応答し、改めて保存されます。
キャッシュがプロンプトを読み取る種類のリクエストだけが指定されています。 チャットリクエスト(ストリーミングの有無を問わず)と、responses API および messages API がキャッシュされます。completions リクエストはキャッシュされず、embeddings リクエストもキャッシュされません。既定のままにすると、ゲートウェイはすべての embeddings リクエストへの応答を保存し、そのために各入力をもう一度埋め込むうえ、どれも応答として返すことはありません。
インデックスはゲートウェイとアタッチメントにちなんで router-answers と名付けられています。そのため、1 つの Release 内でストアを共有する 2 つのゲートウェイは、それぞれの応答を別々のインデックスに保存します。
1 つのキャッシュエントリから誰に応答が返されるか
保存された応答が後続のリクエストに返されるのは、そのバケットを構成するすべての要素が一致し、かつプロンプトが応答元のプロンプトと少なくとも 0.9 の類似度を持つ場合に限られます。
- リクエストが提示するキー (ゲートウェイが検証したもの) と、そのキーのチームおよび組織。
end_userの場合、リクエストが指定するエンドユーザー。- リクエストが要求するモデルと、リクエストのその他のパラメーター。temperature が異なれば、バケットも異なります。
ゲートウェイは、キー、そのチームと組織、およびエンドユーザーをリクエスト自体に書き込みます。chat リクエストでは、呼び出し元がそこに送った値を上書きして、リクエストの metadata に書き込みます。responses または messages リクエストでは、それらを呼び出し元の metadata とは別に保持し、呼び出し元が書き込んだチーム、組織、エンドユーザーのフィールドをそこから削除します。さらに、その Recipe が提供するリクエストガードは、そこでキーを指定するリクエスト (metadata.user_api_key) を、そのフィールドを示す HTTP 400 で拒否します。したがって、どのリクエストも名前を指定して別のキーのバケットに入り込むことはできません。
リクエスト自身の metadata によって、提示したキーのバケット間でリクエストを移すことは引き続き可能です。responses リクエストでは、model_group がバケット内でリクエストの要求するモデルの代わりになります。responses または messages リクエストでは、caching_groups により、同じモデルエイリアスのグループを指定するリクエスト同士が、それらのエイリアスをまたいで応答を共有できます。responses または chat リクエストでは、redis_namespace により、名前空間を指定するリクエストが、指定しないリクエストとは別のバケットに保持されます。いずれも別のキーのバケットには届きません。
このゲートウェイのキーは管理キーであり、すべての呼び出し元がそれを保持します。
帳簿管理用のデータベースが接続されていないため、独自のキーを発行しません。すべての呼び出し元は api_key に接続されたキーを提示し、キーのないリクエストや、ゲートウェイが発行していないキーを持つリクエストは、何かが参照される前に拒否されます。したがって、ここではキーによって呼び出し元同士が区別されることはなく、デフォルトのスコープで 2 つの呼び出し元を分けるのは、各リクエストが指定するエンドユーザーです。
デフォルトである end_user では、エントリは同じエンドユーザーを指定するリクエストに返されます。 ゲートウェイはリクエストからエンドユーザーを読み取ります。x-litellm-end-user-id または x-litellm-customer-id ヘッダー、あるいはボディの user、metadata.user_id、litellm_metadata.user、safety_identifier フィールドです。alice のために保存された応答は、alice の似た言い回しの質問には返されますが、bob の質問には返されません。
ここから 2 つのことが導かれ、どちらも設定ではなくゲートウェイの動作です。
- ゲートウェイはそれらの名前をいずれも検証しません。 キーを保持する者は誰でも任意のエンドユーザーを指定でき、そのエンドユーザーのために保存された内容を受け取ります。キーは自らのエンドユーザーが誰かを把握しているアプリケーションに持たせ、そのアプリケーションにエンドユーザーを指定させてください。キーをエンドユーザー自身に渡さないでください。
- エンドユーザーを指定しないリクエストは 1 つのキャッシュを共有します。 同じキーを提示するそのようなリクエストはすべて、送信者が誰であっても同じエントリから応答を受け取ります。
key では、そのキーを提示するすべての呼び出し元が 1 つのキャッシュから応答を受け取ります。 アタッチメントの values に
scope: key を追加して再ビルドすると、設定の semantic_cache_scope が key になり、レンダリング出力のそれ以外は何も変わりません。このとき、ヘッダーが指定するエンドユーザーはバケットの一部ではなくなるため、x-litellm-end-user-id ヘッダーで指定された alice のために保存された応答は、同じ方法で自身を指定した bob の似た言い回しの質問にも、含まれるツール呼び出しも含めて返されます。ただし、ボディの user フィールドはリクエストのその他のパラメーターの 1 つであるため、そこで異なるエンドユーザーを指定する 2 つのリクエストは、2 つの temperature の場合と同様に、引き続き異なるバケットに入ります。これは、誰にとっても同じ回答だけを保持するキャッシュに適しています。
ビルドを停止させるもの
以下はいずれもビルドが出力する文で、変更すべき箇所を示します。
-
管理キーがない場合。
api_keyのアタッチメントを削除すると、何もレンダリングされないうちにビルドが停止します:[… omitted: a line reporting on the gateway configuration step's plugin, what resolving the lockfile prints, the same halt among it, and a notice that core/referenced-secret declares origin in both of its pillars][CATALOG_ERROR E0033]Recipe/FeatureRecipe assertionscaused by: FeatureRecipe "semantic-caching-litellm" instance "router" assertion "gateway_checks_the_caller": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: core/semantic-caching attachment "answers" on "router" needs core/gateway/litellm to check every caller's key before a cached reply is served, but its api_key credential slot is not attached, so the gateway checks no caller and a cache bucket would be made only of what each caller claims. Attach a credential to the api_key slot of "router" -
ストアがない場合。
cache_storeエッジを削除すると、ビルドは接続すべきソケットを示して停止します。 -
vector_searchを公開しないストア。 このソケットはキーバリューストアを受け入れますが、ゲートウェイの Recipe は、Redis クエリエンジンのベクトル検索(キャッシュが応答の検索に使うもの)を提供すると表明していないストアに対して停止します。リリース 8.0 より前の Redis や Valkey では、すべてのリクエストが成功し続ける一方で、何もキャッシュされません。 -
ゲートウェイ上の 2 つ目の
core/semantic-cachingアタッチメント。 ゲートウェイが持つキャッシュは 1 つです。 -
同じゲートウェイ上の
core/data-masking。 この 2 つは競合を宣言しています。キャッシュはマスキング後のリクエストをキーにするため、マスキングで置き換えられる部分だけが異なる 2 つのリクエストが、保存された 1 つの応答を共有してしまうからです。
ストアを使用できない場合
ゲートウェイがストアに接続するのは、起動時ではなく、最初にリクエストを処理するときです。ゲートウェイがストアを使用できない場合(ストアが、ゲートウェイに与えられていないパスワードを要求する場合や、与えられたパスワードを拒否する場合)、すべてのルックアップはミスとなり、何も保存されませんが、すべてのリクエストには引き続きモデルが応答します。
そのことを示すのはゲートウェイ自身のログだけです。このため、パスワードの両端、つまりストアの password スロットと cache_store エッジの credential は、1 つのパラメータを読み取ります。
コンパイラが解釈しない箇所
コンパイラは、ストアの Service 名とポートをストアの Recipe からゲートウェイの環境へ文字列として渡し、エイリアスと数値をゲートウェイの設定へ渡します。コンパイラはストアに接続せず、cache-default:6379 で何かが応答するかどうかも、エンドユーザーが何であるかも知りません。上記の各停止はカタログ自身のエンティティによって宣言されており、実現またはゲートウェイの Recipe 内のアサーションとして、あるいは 2 つの
Features が宣言する競合として宣言されます。いずれもトラフィックに対する理解には依拠していません。
応用する
- キーごとに 1 つのキャッシュを共有する。 すべての呼び出し元に同じ応答を返すべき場合は、
answersアタッチメントにscope: keyを追加します。 - パスワードなしでストアを実行する。 ストアの
passwordアタッチメントとcache_storeエッジのcredentialを、Aggregate と Release のcache_passwordパラメータとともにまとめて削除します。するとゲートウェイのREDIS_PASSWORDは空でレンダリングされ、パスワードなしで接続します。2 つのアタッチメントの一方だけを削除すると、キャッシュはストアを使用できなくなります。 - 一致させるプロンプトを増減する。 より近い一致のみを返すには
similarity_thresholdを上げ、より多くを返すには下げます。どの値が適するかは埋め込みモデルによって異なります。