キャッシュ入力トークンは安く、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、質問ごとに異なる検索結果の断片などです。
気づかないうちにプレフィックスを壊すものは?
- **辞書の順番。**フレームワークは
tools配列を辞書やレジストリから組み立てることがよくあります。プラグインの読み込み順が変わると、バイト列も変わります。 - JSON の書式。
json.dumps(x)とjson.dumps(x, indent=2)は別のプレフィックスです。キーの順番が異なる 2 つのシリアライザーも同様です。 - **テンプレートの空白。**ある経路から入る行末の空白や、一方は
\r\n、もう一方は\nといった違いです。 - **動的なツール一覧。**ユーザーが使えないツールを除くと、プレフィックスが変わります。OpenAI のガイドは、定義を安定させたまま、
tool_choiceや許可ツールの設定で利用を制限するよう勧めています。 - **履歴をその場で要約する。**古いターンを要約に書き換えると、システムプロンプト以降がすべてリセットされます。要約はまれに、大きな単位で行ってください。
- **指示より前の検索結果。**システムプロンプトとツールの間に置いた 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 回呼び出すテストを実行します。
- 実際のシステムプロンプト、ツール、ドキュメントでリクエストを組み立てます。
- 送信し、
usage.prompt_tokensを控えます。 - 最後のユーザーメッセージだけを変えて、もう一度送ります。
- 2 回目の呼び出しの
usage.prompt_tokens_details.cached_tokensを読みます。共有プレフィックスのほぼすべてをカバーしているはずです。 - ゼロや小さい値なら、シリアライズしたリクエスト本文をバイト単位で比較します。最初の違いが、キャッシュを壊している原因です。
ほとんどのプロバイダーでキャッシュはベストエフォートであり、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 のドキュメントには明示的なキャッシュブレークポイントやキャッシュキーのパラメーターはないので、上のレイアウトがテクニックのすべてです。無制限プランではセッションにトークンメーターがないためキャッシュは請求額を変えませんが、同じ構成はレイテンシの面で引き続き役立ちます。
