Qwen4のプロンプトキャッシュ:エージェントの文脈を再利用し、未命中を調べる

Qwen4のキャッシュ境界を設定し、2回のリクエストと使用量を比較。ローカルで動くリクエスト生成スクリプトと未命中の確認手順を紹介します。

再利用できる版木が同じ図柄を印刷し、小さなオレンジの要素だけが変わっている。

同じ資料を繰り返し読むエージェントでは、固定する文脈をキャッシュ境界より前に、変わる質問を後ろに置き、返されたキャッシュ読み取り量を確認します。 似たプロンプトを送り、回答が速くなっただけでは、キャッシュが動いた証拠になりません。

2026年11月16日に確認したQwenCloudのQwen4直接APIを扱います。Qwen4-Maxの接続・移行ガイドに続く内容です。以下のリクエスト生成スクリプトはキーなしでローカル実行できます。有料キャッシュリクエストは実施していないため、再現可能な実験手順を示すもので、測定済みの節約率や遅延ではありません。

同一に保つ内容を決める

毎回同じ製品マニュアルを読み、異なる顧客質問に答えるサポート分析エージェントを考えます。マニュアルは再利用候補です。ただし、その前に時刻、ランダムID、変化する質問を入れると、リクエスト先頭が変わってしまいます。

入力を次の二つに分けます。

固定する文脈変化するタスク
承認済みマニュアルの版今回の顧客質問
固定したツール定義現在のタスクのツール結果
一貫した指示の順序今回要求する出力
固定した文書のシリアライズ方法分析を変える新しい根拠

ヒット率のために誤った情報を固定してはいけません。マニュアル更新時には新しいプレフィックスが適切です。文書版とハッシュを記録し、意図的な更新による未命中と、偶発的な書式変更を区別できるようにします。

Qwen4公式キャッシュガイド(英語)は、最低1,024トークンのキャッシュ対象プレフィックス、同じユーザー内での完全一致、Chat Completions・Responses・Anthropic Messages対応を説明しています。DashScopeではこのQwen4明示キャッシュは使えません。単語数や文字数は正確なトークン数ではありません。

二つのリクエストをローカルで作る

合成した文書、または選んだプロバイダーへ送る権限がある非機密の参考文書をreference.txtに保存します。1回目と2回目の間で内容を変更しません。

次をbuild_cache_requests.pyに保存してください。

import hashlib
import json
from pathlib import Path

reference = Path("reference.txt").read_text(encoding="utf-8")
if not reference.strip():
    raise SystemExit("reference.txt is empty")

questions = [
    "List the three main responsibilities described in the reference.",
    "Which responsibilities in the reference require an explicit approval?"
]
for number, question in enumerate(questions, 1):
    payload = {
        "model": "qwen4-max",
        "messages": [{
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": reference,
                    "prompt_cache_breakpoint": {"mode": "explicit"}
                },
                {"type": "text", "text": question}
            ]
        }],
        "enable_thinking": False,
        "max_completion_tokens": 1024
    }
    Path(f"request-{number}.json").write_text(
        json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8"
    )
print("Reference SHA256:", hashlib.sha256(reference.encode()).hexdigest())
print("Created two request files; no network requests were sent.")

python3 build_cache_requests.pyを実行し、生成JSONを確認します。最初の内容ブロックと境界指定は完全に同じで、2番目の質問だけが異なる必要があります。このスクリプトはトークン数を測りません。課金リクエストの前に、プロバイダーのトークン計数機能、または対象モデルで使えると確認済みのトークナイザーで最低長を確認します。

境界は内容ブロックに付けるので、メッセージのcontentは配列です。この例では一種類の境界マーカーを使い、同じリクエストに別のキャッシュマーカー構文を混在させません。1回目は再利用する文脈の作成、2回目はその利用を意図しています。実際にそうなったかはレスポンスの使用量で判断します。

正しい経路で順番に送る

公式キーガイド(英語)に従い、選択リージョンのQwenCloud従量課金キーを設定します。以下はシンガポールのChat Completionsエンドポイントです。OfoxキーやToken Planキーを自由に置き換えて使うものではありません。

curl --silent --show-error --fail-with-body --max-time 120 \
  https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request-1.json -o response-1.json

続ける前にHTTP結果、レスポンス本文、使用量を確認します。最初の処理が正常完了したら、ファイル名をrequest-2.jsonとresponse-2.jsonへ変えて実行してください。文書にある有効期間内に行います。この実験では同時送信せず、作成と再利用を区別しやすい逐次実行にします。

タイムアウトは処理されなかった証拠ではありません。再試行前に記録を確認し、実験予算を明確にします。本記事が代わりにコマンドを実行することはありません。

既定の有効期間は5分で、公式ガイドには1時間の選択肢もあります。最初の実験では既定値を維持してください。有効期間とプレフィックスを同時に変えると、未命中の原因を切り分けにくくなります。回答生成時間も有効期間に含まれます。

使用したプロトコルに合う使用量を読む

上記のChat Completions実験ではusage.prompt_tokens_detailsを確認します。キャッシュ読み取り、書き込み、通常入力を区別してください。キャッシュのフィールドがあるだけでは、文書全体が再利用されたとは限りません。

import json
from pathlib import Path

for name in ["response-1.json", "response-2.json"]:
    response = json.loads(Path(name).read_text(encoding="utf-8"))
    usage = response.get("usage") or {}
    details = usage.get("prompt_tokens_details") or {}
    print(name, {
        "input_tokens": usage.get("prompt_tokens"),
        "cache_read_tokens": details.get("cached_tokens"),
        "cache_write_tokens": details.get("cache_write_tokens"),
        "output_tokens": usage.get("completion_tokens")
    })

欠けている値はNoneのままで、報告されなかった情報をゼロへ変換しません。両方の生レスポンスを非公開で保存します。別プロトコルの使用量構造が返った場合、スクリプトを動かすために名前だけ変えるのではなく、そのプロトコルの文書を使ってください。

例えば、QwenCloudのResponsesはinput_tokens_details配下にキャッシュ詳細があり、Anthropic互換の使用量は独自の読み取り・作成フィールドを使います。同じ値の別名もあるため、両方を足すと過大計上になります。キャッシュ使用量の参照(英語)のプロトコル別表を確認してください。

未命中を調べるときは、一度にすべてを変えない

観測結果確認すること次の比較実験
初回に再利用可能なプレフィックスが報告されない最低トークン数、境界位置、対応プロトコル経路を固定し、シリアライズ済みリクエストを確認
2回目にキャッシュ読み取りがない完全一致、ユーザー範囲、経過時間最初の内容ブロックをバイト単位で比較
入力の一部だけがヒットする境界の終端、変更された内容固定文書と現在の質問を分ける
正常だった連続呼び出しが未命中になる文書版、ツール定義、クライアントの直列化最後に動いたリクエストと比較
使用量の項目がないプロトコル、レスポンス形式、ストリーミング完全な非ストリーミング応答から始める
パラメーターエラーが出る経路ごとの対応、JSON構造文書にある単一マーカーの例まで縮小

長いエージェント会話には追加の制限があります。公式ガイドでは、各境界から遡る範囲は最大20内容ブロックで、保持されるのは最後の有効な境界4個までです。自動境界を使う場合はその1個も含みます。履歴の成長で再利用するプレフィックスが検索範囲を外れたら、ブロック構成を見直し、固定内容の終端に意図した境界を設定します。ヒットさせるためだけに必要なツール結果や推論履歴を削除してはいけません。変更前後のリクエストを保存し、使用量で結果を検証してください。

すべての未命中をモデルの劣化と捉えないでください。実行基盤がツール順序を変えたり、動的なシステム文を前置したり、文書書式を変えたりする場合があります。プロバイダーの問題と判断する前に、機密情報を除いた固定プレフィックスとハッシュを記録します。

識別子やエンドポイントの問題はモデルが見つからない場合のガイド(英語)を参照してください。キャッシュが動いても複数ターンでツール結果を失うなら、別の履歴問題です。複数ターンのツール履歴保持も確認できます。

合格したタスク全体で節約額を計算する

キャッシュ書き込みは、読み取りや通常入力とは単価が異なる場合があります。初回書き込みとすべての生成回答を含む連続処理を、キャッシュなしの同じ処理と比較します。QwenCloudの現行地域別価格(英語)を使い、別地域の価格やプレビュー特典の値を流用しないでください。

呼び出しごとに、文書版、入力トークン、キャッシュ読み取り、キャッシュ書き込み、通常入力、出力トークン、所要時間、合否を記録します。別名のフィールドを二重に数えないでください。入力キャッシュの割引率がタスク全体の割引率になるわけではありません。出力や外部ツールが総費用の大半を占めることもあります。

請求額だけでなく回答も確認します。二つの質問例では、列挙された責務と承認条件が本当に資料にあるかを独立して照合してください。安くても根拠のない回答は合格ではありません。

これはQwenCloudへの直接接続の手順です。 11月16日のOfoxカタログにはQwen4がありませんでした。既存のOfox経路は正確なモデル掲載情報を確認し、Ofox認証とエラー処理に従います。これらの文書は、QwenCloudの新キャッシュパラメーターがOfoxで利用できることを証明しません。

よくある質問

同じプロンプトを送ればキャッシュの使用を確認できますか?
いいえ。プロバイダーが返すキャッシュ読み取り量を確認します。応答が速くなったことやテキストの繰り返しだけでは、ヒットしたとは判断できません。
このキャッシュ設定をOfoxで使えますか?
本記事はQwenCloudのQwen4直接APIを扱います。11月16日のOfoxカタログ確認ではQwen4は掲載されておらず、同じモデルやキャッシュ仕様が利用できるとは限りません。