OpenAI Responses: prompt_cache_key 送出によるキャッシュ有効化

背景

codex-oauth 経由 (ChatGPT backend) の OpenAI Responses API において、プロンプトキャッシュが事実上効いていない。実セッションログ (019de419-..., 171 turn / 累計入力 22.2M token) で cache_read_tokens が全 turn 0、最新セッション (019de48f-..., 5 turn) でも 0。

直近のパース修正 (events.rs の ResponsesUsage に input_tokens_details.cached_tokens を追加) で計測経路は復旧したが、それでも 0 が観測される → server 側でそもそもキャッシュが効いていない。

原因は codex-rs の実装で確定:

// codex-rs/core/src/client.rs:853
let prompt_cache_key = Some(self.client.state.conversation_id.to_string());

ChatGPT backend では prompt_cache_key をリクエストに含めないとプロンプトキャッシュが期待通りに動かない (org/project ハッシュが別 conversation と衝突しやすく、ヒット率が著しく落ちる)。Codex は conversation 単位の安定キーを毎リクエスト付けて、その名前空間内で prefix をキャッシュさせている。

insomnia 側の ResponsesRequest には prompt_cache_key フィールドが存在せず、Request 構造体にも会話/セッション単位の安定キー概念が無い。このため codex-oauth で長尺の Run を走らせると毎 turn 全 prefix を従量課金している。

方針

Request に provider-agnostic な cache_key: Option<String> を足し、OpenAIResponsesScheme がそれを prompt_cache_key として送る。pod 側は LLM 呼び出し時に SessionId をキーとして渡す。他 scheme (Anthropic / Gemini / OpenAI Chat / Ollama) はフィールドを無視する。既存の cache_anchor (Anthropic 用 prefix anchor) と同じ「キャッシュヒントを Request に載せ、効く provider だけ拾う」規約に揃える。

Fork との関係

session-store::fork / fork_at はいずれも新 SessionId を発行する。本チケットでは 新 fork = 新 cache_key とする (素直に SessionId.to_string() を渡す)。fork 直後の cache 明示ヒットは失われるが、OpenAI Responses は automatic prefix matching も走るため完全に冷えるわけではない。fork 越しに親の cache_key を継承して明示ヒットも残す最適化は別チケットで検討する (本ticketの範囲外)。

要件

llm-worker 側

Request に cache_key: Option<String> を追加 (types.rs:442 の cache_anchor の隣)。doc コメントで「会話単位の安定キー。 prompt_cache_key として送られる (OpenAI Responses)。 prefix anchor を持たない provider は無視」を明記
ビルダ Request::cache_key(impl Into<String>) を追加
OpenAIResponsesScheme::build_request で request.cache_key.clone() を ResponsesRequest::prompt_cache_key にセット
ResponsesRequest に prompt_cache_key: Option<String> を追加 (#[serde(skip_serializing_if = "Option::is_none")])
他 scheme (anthropic, gemini, openai_chat) は touch しない (Request の新フィールドを未参照のまま残す)

pod 側

LLM クライアントに渡す Request を組み立てる箇所で cache_key(session_id.to_string()) を入れる。少なくとも以下:
- 主 Run の LLM 呼び出し (pod.rs の Run / Worker 経路)
- compactor worker
- memory extract worker
SessionId は SharedState::session_id から取得できる (shared_state.rs:21)
compactor / extract のように pod の中で派生する worker でも同じ session_id を使う。これにより pod 内のすべての LLM 呼び出しが同一 cache_key 名前空間で動き、prefix が共有されるところでヒットが期待できる

docs

docs/research/ 配下に openai_responses_prompt_cache_key.md (仮) を追加し、「ChatGPT backend では prompt_cache_key 必須」「codex-rs の挙動」「insomnia での Fork 方針」を残す。既存の openai_responses_max_output_tokens.md と並びで置く

完了条件

Request::cache_key("abc") で組んだリクエストが、 OpenAIResponsesScheme::build_request で prompt_cache_key: "abc" を含む body を生成する (unit test)
cache_key = None のときは body に prompt_cache_key キーが載らない (skip_serializing_if) (unit test)
pod の Run で codex-oauth + Responses を使ったとき、2 turn 目以降の cache_read_tokens が 0 でない (実セッションログで確認)
cargo check / cargo test が llm-worker, provider, pod で通る

範囲外

Fork 越しのキャッシュ継承 (forked_from を辿って root の cache_key を継承する最適化)。別チケット
公式 OpenAI Responses API (非 ChatGPT backend) での prompt_cache_key 必要性検証。少なくとも害は無いので両経路で同じ値を送って良い
compaction で prefix が大きく書き換わる経路の cache_key 戦略 (compaction 後は prefix がほぼ別物なので、ヒット率を最大化するなら compaction 直後だけ別 key にする手もあるが、まずは単純に session_id 一本で動かす)
cache_anchor (Anthropic 用) と cache_key (Responses 用) の統合。両者は別概念 (前者は prefix の境界 index、後者は名前空間キー) なので並立させる

Review

状態: Approve
レビュー詳細: ./responses-prompt-cache-key.review.md
日付: 2026-05-02

5.6 KiB Raw Blame History