> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 応答キャッシュ

> 繰り返し送信される非ストリーミングリクエストに対し、プロバイダーを再度呼び出さずに、まったく同じ応答を再利用します。

完全一致応答キャッシュを使用すると、project 経由でルーティングされたリクエストに対して、同一のリクエストでプロキシがすでに生成した応答を再利用できます。リクエストでキャッシュを有効にしていて、一致する応答が存在する場合、プロキシはプロバイダーに問い合わせずにその応答を返します。評価スイート、回帰テスト、リトライ、開発ループなど、同じリクエストを複数回送信するワークロードでは、プロバイダーの利用料金とレイテンシーを削減できます。

キャッシュはデフォルトで無効で、リクエスト単位で適用されます。キャッシュされた応答はバイト単位でそのまま返されるため、0 以外の temperature などのサンプリングパラメーターを指定したリクエストでも、キャッシュヒット時には同じ回答が返されます。

<h2 id="enable-caching-for-a-request">
  リクエストのキャッシュを有効にする
</h2>

`wandb-cache-mode` リクエストヘッダーに、次のいずれかのモードを設定します。

| 値 | 既存の応答を読み取る | 成功した応答を保存する |
| - | - | - |
| `readWrite` | はい | はい |
| `readOnly` | はい | いいえ |
| `writeOnly` | いいえ | はい |

キャッシュをバイパスするには、このヘッダーを省略します。

OpenPipe クライアントとの互換性を保つため、プロキシは非推奨の `op-cache` ヘッダーも受け入れます。このヘッダーでは同じモードを使用できるほか、`readWrite` のエイリアスとして `true` を、キャッシュをバイパスする値として `false` を指定できます。リクエストで両方のヘッダーを送信する場合は、両方で同じモードを指定する必要があります。異なるモードを指定すると、プロキシは `400 Bad Request` を返します。

<Tabs>
  <Tab title="Python">
    ```python theme={"system"}
    import os

    from openai import OpenAI

    client = OpenAI(
        base_url="https://proxy.training.wandb.ai/v1",
        api_key=os.environ["WANDB_API_KEY"],
    )

    raw = client.chat.completions.with_raw_response.create(
        model="ticket-classifier",
        messages=[
            {"role": "user", "content": "My package arrived damaged. What should I do?"}
        ],
        extra_body={"metadata": {"wandb.entity": "your-team"}},
        extra_headers={"wandb-cache-mode": "readWrite"},
    )

    print(raw.headers.get("wandb-cache-status"))  # "hit" または "miss"
    response = raw.parse()
    print(response.choices[0].message.content)
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={"system"}
    import OpenAI from "openai";

    const client = new OpenAI({
      baseURL: "https://proxy.training.wandb.ai/v1",
      apiKey: process.env.WANDB_API_KEY,
    });

    const { data: response, response: raw } = await client.chat.completions
      .create(
        {
          model: "ticket-classifier",
          messages: [
            { role: "user", content: "My package arrived damaged. What should I do?" },
          ],
          metadata: { "wandb.entity": "your-team" },
        },
        { headers: { "wandb-cache-mode": "readWrite" } },
      )
      .withResponse();

    console.log(raw.headers.get("wandb-cache-status")); // "hit" または "miss"
    console.log(response.choices[0].message.content);
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={"system"}
    curl -i https://proxy.training.wandb.ai/v1/chat/completions \
      -H "Authorization: Bearer $WANDB_API_KEY" \
      -H "Content-Type: application/json" \
      -H "wandb-cache-mode: readWrite" \
      -d '{
        "model": "ticket-classifier",
        "messages": [
          {"role": "user", "content": "My package arrived damaged. What should I do?"}
        ],
        "metadata": {"wandb.entity": "your-team"}
      }'
    ```
  </Tab>
</Tabs>

リクエストでキャッシュの読み取りを有効にしている場合 (`readWrite` または `readOnly`)、応答には値が `hit` または `miss` の `wandb-cache-status` ヘッダーが含まれます。プロキシは、互換用の `x-wandb-cache` ヘッダーでも同じ値を返します。`writeOnly` リクエストへの応答には、どちらのヘッダーも含まれません。

<h2 id="what-makes-two-requests-identical">
  2 つのリクエストが同一と見なされる条件
</h2>

プロキシは、project のバージョンとルーティングリビジョンを解決した後、プロバイダーを選択する前に、キャッシュされた応答を検索します。キャッシュキーは次の値を組み合わせたものです。

* プロキシが `model` の値から解決する W\&B の entity、project、および project のバージョン。
* リクエストの到着時にそのバージョンに適用されている[ルーティングリビジョン](/ja/model-distillation/studio/routing-and-versions#save-to-an-existing-or-new-version)。
* リクエストのパスとクエリ文字列。
* オブジェクトキーをソートしてシリアライズし、次に示す値を除外したリクエストボディの SHA-256 ハッシュ。

プロキシはハッシュ化の前にボディから次の値を削除するため、これらの値はキーに影響しません。

* 生の `model` 文字列。解決後の project、バージョン、ルーティングリビジョンはすでにキーに含まれているため、エントリを共有するのは同等の参照どうしに限られます。たとえば、`ticket-classifier` と `ticket-classifier@v1` はどちらもバージョン 1 に解決されます。異なるバージョン間でエントリが共有されることはありません。
* `wandb.` で始まるメタデータキー (`wandb.entity` や `wandb.thread_id` など)。
* `stream: false`。プロキシはこれを `stream` を省略した場合と同じように扱います。
* 空の `metadata` オブジェクト。プロキシはこれを `metadata` を省略した場合と同じように扱います。

プロキシのホスト名やクエリパラメーターの順序も、キーには影響しません。

バージョンのルーティングを保存するたびに、Model Distillation は新しいルーティングリビジョンをパブリッシュするため、キーが変わります。既存のエントリは一致しなくなりますが、有効期限が切れるまで残ります。プロキシは、ルーティングターゲットに設定されたパラメーターのオーバーライドをハッシュ化しません。ただし、オーバーライドの変更も他のルーティング変更と同じ扱いになるため、やはりキーが変わります。

ボディ内のその他のフィールドは、プロバイダーが使用するかどうかにかかわらず、すべてハッシュの対象になります。対象となるフィールドには、`messages`、`tools`、`tool_choice`、`response_format`、`temperature`、`top_p`、`max_tokens`、`seed`、`n`、`stop`、`user`、プロバイダー固有のフィールド、および `gen_ai.conversation.id` や `user.id` など `wandb.` で始まらないメタデータキーがあります。オブジェクト内のキーの順序は影響しませんが、`messages` などの配列内の項目の順序は影響します。

エントリのスコープは、お使いの W\&B の entity と project に限定されます。別の entity からの同一リクエストや、同じ entity 内の別の project に対するリクエストが、お使いのエントリと一致することはありません。

キャッシュされた応答には、その応答を生成したルーティングターゲットが記録されます。キャッシュヒット時、プロキシは重み付けルーティングやスティッキールーティングを適用せず、そのターゲットの応答を返します。

`provider/model` を直接指定するリクエストでもキャッシュヘッダーを設定できます。これらのエントリのキーは、entity、プロバイダー、モデル参照、および呼び出し元の W\&B アイデンティティごとに個別に生成されます。これらのエントリが project のエントリと一致することはありません。

<h2 id="limits">
  制限
</h2>

キャッシュには次の制限があります。

* **非ストリーミングリクエストのみが対象です。** `stream: true` を指定したリクエストでキャッシュヘッダーを設定すると、`400 Bad Request` が返されます。
* **成功した応答のみが対象です。** プロキシが保存するのは、8 MiB までの 2xx 応答のみです。
* **保持期間は 7 日間です。** エントリは書き込まれてから 7 日後に削除されます。キャッシュヒットしても保持期間は延長されません。
* **無効なモードは拒否されます。** `wandb-cache-mode` に記載以外の値を指定した場合や、`wandb-cache-mode` と `op-cache` でモードが競合している場合は、`400 Bad Request` が返されます。

キャッシュの障害時はフェイルオープンで動作します。キャッシュの読み取りまたは書き込みができない場合、プロキシは通常どおりリクエストをプロバイダーに転送します。

プロキシは同時リクエストを統合しません。プロキシが最初の応答を保存する前に同一のリクエストが複数届いた場合、それぞれがプロバイダーに送信され、最後に書き込まれた応答が保存されます。

<h2 id="traces-and-analytics">
  トレースと Analytics
</h2>

キャッシュヒットの場合も、プロキシはそれを project のトレースとして記録します。このトレースには元の応答とそのトークン使用量が保持され、`cache_hit=true` が付与されます。プロバイダーのレイテンシーは記録されません。キャッシュ読み取りを有効にしていても、リクエストがプロバイダーに転送された場合は `cache_hit=false` が付与されます。

キャッシュヒットでは推論が実行されないため、Analytics ではプロバイダーの利用料金がゼロとして計上されます。一方、トークンの合計には再利用された使用量も含まれます。データセットの作成時には同一の入力が重複排除されるため、再利用された応答によってトレーニング用の行が重複して追加されることはありません。

<h2 id="browser-clients">
  ブラウザークライアント
</h2>

プロキシは、クロスオリジンリクエストで `wandb-cache-mode` および `op-cache` リクエストヘッダーを許可し、`wandb-cache-status`、`x-wandb-cache`、`x-proxy-request-id` をブラウザー側のコードに公開します。

<Card title="チャット補完" href="/ja/model-distillation/proxy/chat-completions" arrow="true">
  プロキシによるプロバイダーへのリクエストの構築、ストリーミングの処理、ツールと構造化出力の転送の仕組みについて説明します。
</Card>