BroadRouter

プレフィックスがキャッシュされるプロンプトの組み立て方

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

リクエストは安定したものから順に並べます:システムプロンプト、ツール定義、参照ドキュメント、会話履歴、最後に新しいメッセージ。各層は呼び出し間でバイト単位まで同一に保ちます。先頭にタイムスタンプや ID を置かず、ツールは並べ替え、JSON は決定的にシリアライズし、履歴は追記のみ。最後に cached_tokens で再利用を確認します。

キャッシュ入力トークンは安く、BroadNet Inference の DeepSeek V4.1 Flash では 100 万あたり $0.175 ではなく $0.0055 で課金されます。料金と usage フィールドの読み方はキャッシュトークンの解説で扱っています。この記事のテーマは設計です。キャッシュが実際にヒットするようにプロンプトをどう配置するか、そしてヒットしていることをどう証明するかです。

なぜプロンプトの順番がキャッシュヒット率を決めるのか?

主要なプロバイダーはどこもプレフィックスでキャッシュします。OpenAI のガイドによると、再利用にはレンダリング後のプレフィックス全体が一致する必要があります。DeepSeek のドキュメントも同じルールを説明しています。保存されたプレフィックスと完全に一致した場合にのみヒットし、途中で食い違うものはヒットしません。Anthropic は、ツール、システム、メッセージの順にキャッシュを構築します。

内部では、サーバーはそのプレフィックスのために作った KV キャッシュを再利用します。つまりキャッシュは最初のトークンからの一直線です。前回の呼び出しと異なる最初の 1 バイトで、再利用できる部分は終わります。50,000 トークンのプロンプトの先頭に 1 行のタイムスタンプがあるだけで、50,000 トークンすべてが満額になります。

正しい層の順番は?

層 変わる頻度 例 ルール
1. システムプロンプト デプロイごと 役割、ルール、出力形式 日付、ID、ユーザー名を入れない
2. ツール定義 デプロイごと 関数スキーマ 並べ替えた決定的な JSON
3. 参照資料 セッションまたはタスクごと リポジトリのファイル、契約書、製品ドキュメント 順番を固定、ラベルを安定させる
4. 会話履歴 ターンごと、追記のみ 過去のユーザーとアシスタントのターン 編集せず、追加だけする
5. 新しいメッセージ 毎回の呼び出し 質問と、必要なら現在時刻 変わりやすいデータはここに置く

変わりやすいものはすべて第 5 層に置きます。現在の日付、ユーザーのロケール、リクエスト ID、質問ごとに異なる検索結果の断片などです。

気づかないうちにプレフィックスを壊すものは?

  1. **辞書の順番。**フレームワークは tools 配列を辞書やレジストリから組み立てることがよくあります。プラグインの読み込み順が変わると、バイト列も変わります。
  2. JSON の書式。json.dumps(x) と json.dumps(x, indent=2) は別のプレフィックスです。キーの順番が異なる 2 つのシリアライザーも同様です。
  3. **テンプレートの空白。**ある経路から入る行末の空白や、一方は \r\n、もう一方は \n といった違いです。
  4. **動的なツール一覧。**ユーザーが使えないツールを除くと、プレフィックスが変わります。OpenAI のガイドは、定義を安定させたまま、tool_choice や許可ツールの設定で利用を制限するよう勧めています。
  5. **履歴をその場で要約する。**古いターンを要約に書き換えると、システムプロンプト以降がすべてリセットされます。要約はまれに、大きな単位で行ってください。
  6. **指示より前の検索結果。**システムプロンプトとツールの間に置いた RAG の断片はクエリごとに異なり、ツールの層まで壊してしまいます。

キャッシュに優しいリクエストをコードでどう組み立てるか?

各層を安定した入力だけの関数にし、決定的にシリアライズします。

import json, os
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

SYSTEM = open("prompts/system.md").read()  # versioned file, no templating

def stable_tools(registry: dict) -> list:
    # Sort by name, sort keys inside each schema.
    return [json.loads(json.dumps(registry[name], sort_keys=True)) for name in sorted(registry)]

def docs_block(paths: list[str]) -> str:
    parts = [f"=== {p} ===\n{open(p).read()}" for p in sorted(paths)]
    return "\n\n".join(parts)

def build_messages(history: list, user_text: str, now_iso: str, doc_paths: list[str]):
    return (
        [{"role": "system", "content": SYSTEM},
         {"role": "user", "content": docs_block(doc_paths)}]
        + history                                   # append-only
        + [{"role": "user", "content": f"(now: {now_iso})\n{user_text}"}]
    )

resp = client.chat.completions.create(
    model="broadnet/deepseek-v4.1-flash",
    messages=build_messages(history, question, now_iso, files),
    tools=stable_tools(TOOLS),
)
history += [{"role": "user", "content": question}, resp.choices[0].message.model_dump(exclude_none=True)]

ポイントは 2 つです。現在時刻はシステムプロンプトではなく最後のメッセージに入れます。そして履歴にはアシスタントのメッセージを返されたとおりに保存するので、次の呼び出しでもまったく同じバイト列が送り直されます。

プレフィックスがキャッシュされていることをどう証明するか?

CI やノートブックで、2 回呼び出すテストを実行します。

  1. 実際のシステムプロンプト、ツール、ドキュメントでリクエストを組み立てます。
  2. 送信し、usage.prompt_tokens を控えます。
  3. 最後のユーザーメッセージだけを変えて、もう一度送ります。
  4. 2 回目の呼び出しの usage.prompt_tokens_details.cached_tokens を読みます。共有プレフィックスのほぼすべてをカバーしているはずです。
  5. ゼロや小さい値なら、シリアライズしたリクエスト本文をバイト単位で比較します。最初の違いが、キャッシュを壊している原因です。

ほとんどのプロバイダーでキャッシュはベストエフォートであり、DeepSeek のドキュメントもそう明言しているので、1 回のミスはバグの証拠になりません。一貫したミスはバグの証拠です。利用ログでリクエストごとのキャッシュトークンとプロンプトトークンの比率を追い、プロンプトキャッシュ計算ツールでヒット率が上がるとどれだけ節約できるかを確かめてください。

エージェントや長いコンテキストでは何が変わるか?

エージェントは、タスクごとに同じ大きなプレフィックスを何十回も送り直すので、いちばん恩恵を受けます。大事な習慣が 2 つあります。

  • **1 タスクに 1 会話。**サブステップごとに新しい会話を始めると、プレフィックスを捨てることになります。
  • **ファイルは 1 回、先頭近くで読む。**エージェントがファイルを読み直す場合、ファイルが変わっていない限り、古いものを置き換えずに新しいコピーを追記してください。

100 万トークンのコンテキストウィンドウがあれば、第 3 層にリポジトリ全体を入れられます。トークン課金のキーでそれが現実的な費用になるのはキャッシュされる場合だけで、プロンプトが大きくなるほど層の順番が重要になるのはそのためです。キャッシュされたプレフィックスは、最初のトークンまでの時間も短くする傾向があります。TTFT とスループットを参照してください。

BroadNet Inference が向いているケース

BroadNet Inference では、モデルが報告する場合に usage ブロックが prompt_tokens_details.cached_tokens を返し、DeepSeek V4.1 Flash、GLM 5.3、Qwen3.8 27B のキャッシュ入力は料金ページに記載された低い単価で課金されます。BroadNet のドキュメントには明示的なキャッシュブレークポイントやキャッシュキーのパラメーターはないので、上のレイアウトがテクニックのすべてです。無制限プランではセッションにトークンメーターがないためキャッシュは請求額を変えませんが、同じ構成はレイテンシの面で引き続き役立ちます。

よくある質問

プロンプトキャッシュのヒット率が低いのはなぜですか?

プロンプトの先頭近くで、呼び出しのたびに何かが変わっています。よくある原因は、システムプロンプト内のタイムスタンプやリクエスト ID、異なる順番でシリアライズされたツール、指示より前に置かれた検索結果のドキュメント、要約されて書き換えられる履歴です。

ユーザーの質問は長いドキュメントの前と後のどちらに置くべきですか?

後です。ドキュメントを先に、質問を最後に置きます。そうするとドキュメントが再利用できるプレフィックスになり、多くのモデルは質問が資料のあとに来るほうがよく答えます。

ツール定義はプロンプトキャッシュを壊しますか?

変わったときだけです。ツールはプレフィックスの一部なので、同じセットを、同じ順番で、同じ JSON のまま保ってください。1 回の呼び出しでツールを制限するには、一覧を編集するのではなく tool_choice を使います。

few-shot 例の順番はキャッシュに影響しますか?

はい。シャッフルされた例は毎回異なるプレフィックスを生みます。順番を固定するか、リクエストごとに変わる例は安定部分のあとに置いてください。

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