BroadRouter

LLM API のレスポンスをキャッシュしてコスト削減:Python の完全一致キャッシュ

BroadNet Inference チーム · 約 8 分で読めます · 公開日

リクエスト全体(モデル、メッセージ、temperature、max_tokens、response_format、ツール、推論の設定、プロンプトバージョン)をハッシュしてキーにし、有効期限付きで回答を保存します。保存した回答は、決定的で副作用のないリクエストにだけ返します。まずログで同一リクエストの頻度を測ります。その割合が完全一致キャッシュの節約の上限です。

同じ LLM リクエストを 2 回送れば、2 回分の料金がかかります。レスポンスキャッシュは 1 回目に回答を保存し、次からはそれを返すので、トークンは課金されず待ち時間もありません。考え方は単純です。難しいのは、2 つのリクエストを「同一」とみなす条件、保存した回答を決して返してはいけないリクエスト、そして自分のトラフィックが意味のあるほど繰り返されるかどうかを判断することです。

この記事では、SQLite を使った小さな完全一致キャッシュを Python で作り、OpenAI 互換のモックサーバーでテストします。また、コードを 1 行も書く前に、ログからヒット率を測る方法も紹介します。

レスポンスキャッシュはプロンプトキャッシュと同じか?

違います。節約するものが異なり、両方を併用できます。

プロンプトキャッシュ(プロバイダー) レスポンスキャッシュ(自分)
再利用するもの プロンプトの繰り返される先頭部分 回答全体
実行するのは API プロバイダー 自分のコード
モデルは動くか? 動く。新しい回答を書く 動かない
節約できるもの 入力費用の一部 入力、出力、推論のトークンとレイテンシ
ヒットする条件 共通のプレフィックス、異なる質問 まったく同じリクエスト

プロバイダー側はキャッシュ入力トークンで説明しており、キャッシュのためのプロンプト構成では、プレフィックスが再利用されるようにプロンプトを配置する方法を紹介しています。費用はプロンプトキャッシュ計算ツールで計算できます。レスポンスキャッシュはそのすべての手前にあり、ヒットすればリクエストはサーバーから一切出ていきません。

キャッシュで本当にお金を節約できるか?

作る前に計測してください。多くのキャッシュのチュートリアルにある節約率は、他人のトラフィックから出た数字です。あなたの数字は 1 つのことだけで決まります。同じリクエストが有効期限内にもう一度来る頻度です。

LLM API の利用ログのように呼び出しごとにすでにログを取っているなら、フィールドを 1 つ加えてください。後述するキャッシュキーである request_hash です。プロンプトのテキストは保存しないので、コンテンツを残さないログにも合います。そのうえで繰り返しを数えます。

import json
from collections import Counter

def potential_hit_rate(log_path: str) -> float:
    """Share of calls whose request_hash was already seen: an upper bound for an exact cache."""
    hashes = [json.loads(line)["request_hash"] for line in open(log_path)]
    seen, repeats = set(), 0
    for h in hashes:
        repeats += h in seen
        seen.add(h)
    print("top repeated requests:", Counter(hashes).most_common(3))
    return repeats / len(hashes) if hashes else 0.0

print(f"potential hit rate: {potential_hit_rate('calls.jsonl'):.1%}")

20 回の呼び出しからなる合成ログ(1 つのリクエストが 5 回、別のものが 3 回、残り 12 回はすべて異なる)では、潜在的なヒット率は 30.0% と表示されました。これは上限です。有効期限を無視しており、すべての繰り返しを保存した回答で返してよいと仮定しています。

次に、その率を金額に換算します。

monthly saving = hit rate × requests per month
                 × (input tokens × input price + output tokens × output price) ÷ 1,000,000

出力トークンには推論が含まれます。BroadNet のドキュメントによると、DeepSeek V4.1 Flash、GLM 5.3、Qwen3.8 27B は回答の前に推論し、推論は max_tokens に含まれます。そのため 1 回のヒットで、回答には現れないトークンまで節約できます。回答の長さではなく、記録した usage の completion_tokens を使ってください。

トークンでの計算例:入力 1,200・出力 150 トークンのリクエストが月 100,000 件、ヒット率 30% なら、入力 3,600 万トークンと出力 450 万トークンを避けられます。DeepSeek V4.1 Flash では、それぞれ 100 万あたり $0.175 と $0.52 で課金されます。自分の数字は LLM API コスト計算ツールに入れてください。その入力の大半がもともとプロバイダーのキャッシュにヒットしていたなら、入力の節約は低いキャッシュ単価(同じモデルで 100 万あたり $0.0055)で計算されるので、重要なのは出力側であることが多くなります。

キャッシュキーには何を入れるか?

回答を変えうるものはすべて入れ、それ以外は入れません。

  • 含める:model、messages リスト全体(システムプロンプトを含む)、temperature、top_p、max_tokens、seed、response_format、tools、tool_choice、reasoning_effort。
  • 自分で管理するプロンプトバージョンを加える(例:faq-v3)。プロンプトテンプレート、検索データ、後処理など、リクエスト本文には現れないものを変えたときに上げます。
  • **除外する:**回答を変えずに呼び出しごとに変わるもの。リクエスト ID、タイムスタンプ、トレース用ヘッダー、不正利用の追跡のためだけに送る user フィールドなどです。

キーの材料は毎回同じ方法でシリアライズします。Python の json.dumps に sort_keys=True と separators=(",", ":") を指定すれば、辞書の順番に関係なく 1 つの正規化された文字列が得られます。ensure_ascii=False にすれば、アラビア語などのラテン文字以外のテキストがエスケープではなく UTF-8 のまま保たれます。それを SHA-256 でハッシュします。

もっとも危険なのは、フィールドの入れ忘れです。max_tokens がキーにないと、小さい上限で途中で切れた回答が、長い回答を許すリクエストに返されてしまいます。

キャッシュ本体:SQLite、TTL、スキップのポリシー

import hashlib, json, sqlite3, time

# Every field that changes the answer belongs in the key.
KEY_FIELDS = ("model", "messages", "temperature", "top_p", "max_tokens", "seed",
              "response_format", "tools", "tool_choice", "reasoning_effort")

def cache_key(params: dict, prompt_version: str) -> str:
    material = {k: params[k] for k in KEY_FIELDS if k in params}
    material["prompt_version"] = prompt_version
    canon = json.dumps(material, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
    return hashlib.sha256(canon.encode("utf-8")).hexdigest()

class ResponseCache:
    def __init__(self, path="llm_cache.sqlite", ttl_s=7 * 86400):
        self.db, self.ttl = sqlite3.connect(path), ttl_s
        self.db.execute("CREATE TABLE IF NOT EXISTS cache (k TEXT PRIMARY KEY, created REAL,"
                        " body TEXT, prompt_tokens INT, completion_tokens INT)")
        self.hits = self.misses = self.skips = self.saved_in = self.saved_out = 0

    def create(self, client, prompt_version: str, **params):
        if params.get("stream") or params.get("temperature", 1) > 0:
            self.skips += 1                       # not cacheable: call the model directly
            return client.chat.completions.create(**params)
        k = cache_key(params, prompt_version)
        row = self.db.execute("SELECT body, created, prompt_tokens, completion_tokens"
                              " FROM cache WHERE k = ?", (k,)).fetchone()
        if row and time.time() - row[1] < self.ttl:
            self.hits += 1; self.saved_in += row[2]; self.saved_out += row[3]
            return json.loads(row[0])             # a plain dict, not an SDK object
        self.misses += 1
        r = client.chat.completions.create(**params)
        choice = r.choices[0]
        if choice.finish_reason == "stop" and not choice.message.tool_calls:
            self.db.execute("INSERT OR REPLACE INTO cache VALUES (?, ?, ?, ?, ?)",
                            (k, time.time(), r.model_dump_json(),
                             r.usage.prompt_tokens, r.usage.completion_tokens))
            self.db.commit()
        return r.model_dump()

そして実行してみます。

import os
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
cache = ResponseCache("demo.sqlite", ttl_s=86400)
SYSTEM = {"role": "system", "content": "Answer questions about our refund policy in one sentence."}
questions = ["How long do refunds take?", "Can I refund a gift card?",
             "How long do refunds take?", "How long do refunds take?", "Can I refund a gift card?"]
for q in questions:
    r = cache.create(client, "faq-v3", model="broadnet/deepseek-v4.1-flash", temperature=0,
                     max_tokens=1200, messages=[SYSTEM, {"role": "user", "content": q}])
    print(r["choices"][0]["message"]["content"])
# a personalised, sampled request is never cached
cache.create(client, "faq-v3", model="broadnet/deepseek-v4.1-flash", temperature=0.7,
             messages=[SYSTEM, {"role": "user", "content": "Write me a friendly reminder"}])
# a new prompt version is a new key
cache.create(client, "faq-v4", model="broadnet/deepseek-v4.1-flash", temperature=0,
             max_tokens=1200, messages=[SYSTEM, {"role": "user", "content": "How long do refunds take?"}])
print(f"hits={cache.hits} misses={cache.misses} skipped={cache.skips} "
      f"saved_input={cache.saved_in} saved_output={cache.saved_out}")

これを OpenAI Python SDK 3.51.0 で、上流への呼び出しを数え、回答ごとにプロンプト 1,200・出力 150 トークンを報告するローカルのモックサーバーに対して実行しました(実際の API は呼んでいません)。7 件のリクエストで、上流への呼び出しは 4 回でした。スクリプトの出力は hits=3 misses=3 skipped=1 saved_input=3600 saved_output=450 です。同じデータベースファイルでもう一度実行すると、キャッシュ可能な 6 件のリクエストはすべてヒットしました(hits=6 misses=0)。SQLite は再起動をまたいでキャッシュを保持します。同じフィールドを異なる順番で組み立てたキーも一致しました。

コードについての補足:

  • max_tokens=1200 は、回答前の推論の余地を残すためです。上限が小さいと、推論モデルは空の回答を返すことがあります(理由)。そうした回答は finish_reason が stop ではなく length なので保存されません。
  • **ヒット時は dict を返します。**ミス時も model_dump() を返すので、呼び出し側は同じ形を受け取ります。コードが SDK のオブジェクトを前提にしているなら、両方をラップしてください。
  • **temperature の指定がない場合はサンプリング扱いです。**その場合サーバーは独自のデフォルト値を使い、それが 0 より大きいこともあるので、明示的に 0 を指定しない限りラッパーはキャッシュをスキップします。
  • **SQLite は 1 つか少数のプロセス向きです。**複数のサーバーがある場合は、同じキーと TTL のロジックを Redis や自分のデータベースに置いてください。

キャッシュから返してはいけないものは?

  • **サンプリングした回答(temperature が 0 より大きい)。**多様性を選んだのはあなたです。キャッシュはそれを消してしまい、「再生成」を押したユーザーは同じテキストを受け取ります。
  • 個人に合わせた回答。ユーザー ID がキーに入っていない限り不可です。「私のアカウントを要約して」と送る 2 人のユーザーのアカウントは別物です。より良い方法は、メッセージにユーザーごとのデータを含まないリクエストだけをキャッシュすることです。
  • ツール呼び出し。ツール呼び出しは行動の指示です。「注文 1182 を返金」を保存から再生すると副作用が繰り返されるおそれがあり、正しい次の手は現在の状態によります。このラッパーは tool_calls を含む回答を保存しません。
  • ストリーミングの回答。stream=True ではラッパーはキャッシュを迂回します。ストリームをキャッシュするにはバッファリングし、終了を確認し、再生する必要があり、チャット UI ではほとんど割に合いません。
  • **途中で切れた回答や失敗した回答。**保存するのは finish_reason == "stop" のものだけです。途中で切れた回答やエラーが 1 週間キャッシュされると、モデルの問題に見えるバグになります。
  • 時間に依存する回答。「今日の為替レートは?」には短い TTL を設定するか、キャッシュしないでください。

キャッシュに向いているのは、決まった入力集合の分類、再処理するドキュメントからの抽出、固定プロンプトによる FAQ の回答、繰り返し実行するテストスイートや評価、同じリクエストを何度も送る開発中のループです。

キャッシュした回答はいつ期限切れにすべきか?

3 種類の無効化を使います。

  1. **TTL。**エントリーごとの時間制限です。安定した FAQ の回答なら数日、ライブデータを読むものなら数分です。
  2. **キーに含めたバージョン。**システムプロンプト、検索インデックス、出力スキーマが変わったらプロンプトバージョンを変えます。古いエントリーは一致しなくなり、やがて期限切れになります。
  3. **キーに含めたモデル。**すでに含まれているので、別のモデルに移ると新しいキャッシュから始まります。切り替えを評価する間は、まさにそれが望ましい動作です。

期限切れの行は定期的に削除してください(DELETE FROM cache WHERE created < ?)。そうしないとファイルは増える一方です。

副次的な利点もあります。推論エンジンは、同一の入力に同一の出力を約束しません。vLLM のドキュメントには “does not guarantee the reproducibility of the results by default”(訳:デフォルトでは結果の再現性を保証しません)とあります。キャッシュがあれば、エントリーが有効な間、同じ質問には全ユーザーに同じ回答が返ります。

セマンティックキャッシュはどうか?

セマンティックキャッシュは各質問を埋め込み、新しい質問が十分に近ければ保存した回答を返します。そのため「返金はどれくらいかかる?」が「返金にはどれくらい時間がかかりますか?」にヒットできます。もっとも有名なオープンソースの例が GPTCache です。その README によると、類似検索にはベクトルストアを、ヒットの判定には類似度評価器を使い、“you may encounter false positives during cache hits and false negatives during cache misses”(訳:キャッシュヒット時に偽陽性、キャッシュミス時に偽陰性が起こることがあります)と注意を促し、埋め込みを無効にするとキーワード照合のキャッシュになると述べています。

実務上のポイントが 2 つあります。第一に、埋め込みモデルとベクトルストアが必要です。BroadNet Inference は埋め込みを提供していないので、この層には別のプロバイダーかローカルモデルを使うことになります。選択肢の費用は埋め込みコスト計算ツールで計算できます。第二に、誤ったヒットは別の質問に自信ありげな回答を返します。厳しい類似度のしきい値を使い、実際の紛らわしい質問のペアでテストし、セマンティックキャッシュは影響の小さい回答に限ってください。いずれにしても完全一致キャッシュを手前に置きます。確認は無料で、何を聞かれたかを取り違えることがありません。

キャッシュはプライバシーにとって何を意味するか?

キャッシュはプロンプトと回答の保存場所です。それによって、データの所在が変わります。

BroadNet の推論プライバシー声明(2026-11-15 確認)によると、ゲートウェイはプロンプト、メッセージ、レスポンス、文字起こしを保持せず、コンテンツを含まないトラフィックと利用の記録(トークン数、費用、所要時間)は保持します。推論のコンテンツは保持されません。必要なアカウント、課金、セキュリティのメタデータは声明の記載どおりに保持されます。レスポンスキャッシュを加えると、プロバイダーが保持しないコンテンツをあなたのシステムが保持することになります。他のユーザーデータの保存場所と同じように扱ってください。

  • 可能なら個人データを含まないリクエストだけをキャッシュします。これでヒット率も上がります。
  • 保持ポリシーに見合う短さの TTL を設定し、定期的に削除します。
  • ファイルやテーブルを保存時に暗号化し、読める人を限定します。
  • キャッシュにユーザーのテキストが入りうるなら、データ削除の依頼の対象に含めます。

チェックリストの残りは機密データを LLM API に送るで扱っています。

キャッシュは他のコスト管理とどう組み合わせるか?

キャッシュは繰り返しの呼び出しをなくしますが、一度きりの呼び出しには何もしません。そのため他の管理手段を置き換えるのではなく、並べて使います:短いプロンプト、プロバイダーのプロンプトキャッシュ、リクエストごとの max_tokens の上限、そして LLM API の支出管理の予算とループの制限です。大規模な一回きりのジョブでは、送る前に入力を重複排除してください。キャッシュと同じ考え方を 1 回だけ行うものです。ジョブ側は Batch API なしで大規模ジョブを処理するで紹介しています。

定額プランでは計算が変わります。BroadNet の DeepSeek セッションにはトークンメーターがないので、そこではキャッシュがヒットしてもお金は節約できません。それでも時間は節約できます。セッションは一度に 1 リクエストずつ処理するので、繰り返しを 1 回省くたびに、セッションが新しい作業に使えるようになります。

BroadNet Inference が向いているケース

BroadRouter は BroadNet 自身のサイトです。BroadNet Inference は DeepSeek V4.1 Flash、GLM 5.3、Qwen3.8 27B、Gemma 4 VL 26B を OpenAI 互換の /v1/chat/completions エンドポイントで提供しているので、上のラッパーはベース URL を変えるだけで OpenAI Python SDK と一緒に使えます。BroadNet 自体にはレスポンスキャッシュの機能はなく、この記事のキャッシュはあなたのものです。API リファレンスによると、プロバイダー側のキャッシュヒットは usage.prompt_tokens_details.cached_tokens で報告され、キャッシュ入力単価で課金されます。モデルごとの料金は料金ページにあります。

よくある質問

プロンプトキャッシュとレスポンスキャッシュの違いは何ですか?

プロンプトキャッシュはプロバイダーが行うもので、繰り返されるプロンプトのプレフィックスが低いキャッシュ入力単価で課金され、モデルは新しい回答を書きます。レスポンスキャッシュは自分で行うもので、回答をまるごと保存し、同一のリクエストにはモデルを呼ばずにそれを返します。

temperature 0 の LLM レスポンスはキャッシュすべきですか?

リクエストに副作用がなく、送ってきた全員に同じ回答を返して問題ないなら、キャッシュすべきです。temperature 0 でも推論エンジンが同一の出力を返す保証はないので、キャッシュには回答を一貫させる効果もあります。temperature が 0 より大きいか指定がない場合はキャッシュしないでください。

LLM のレスポンスキャッシュでどれだけ節約できますか?

有効期限内に完全に繰り返されるリクエストの割合に、それらのリクエストの費用を掛けた額です。その割合は、自分のログで繰り返されるリクエストハッシュを数えれば得られます。自由形式のチャットではほぼゼロ、決まった FAQ や分類の入力では高くなることがあります。

セマンティックキャッシュは完全一致キャッシュより優れていますか?

似た質問も一致するのでヒットは増えますが、別の質問への回答を返すことがあります。埋め込みモデルとベクトルストアも必要です。まず完全一致キャッシュから始め、誤ったヒットの代償が小さい箇所にだけセマンティックの層を加えてください。

ストリーミングのレスポンスはキャッシュできますか?

この記事の簡単なラッパーではできません。ストリーム全体を集め、正常に終わったか確認し、保存し、あとでストリームとして再生する必要があります。ほとんどのチームは、分類、抽出、FAQ の回答など、ストリーミングしない呼び出しだけをキャッシュしています。

Markdown で読むChatGPT に聞くClaude に聞くPerplexity に聞く