> ## 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.

# 응답 캐싱

> 반복되는 비스트리밍 요청에 대해 공급자를 다시 호출하는 대신 이전과 동일한 응답을 재사용합니다.

정확한 응답 캐싱(exact-response caching)을 사용하면 프로젝트로 라우팅된 요청에 대해, 프록시가 동일한 요청에 이미 생성한 응답을 재사용할 수 있습니다. 요청에서 캐싱을 사용하도록 설정했고 일치하는 응답이 있으면, 프록시는 공급자에 요청을 보내지 않고 해당 응답을 반환합니다. 따라서 평가 스위트, 회귀 테스트, 재시도, 개발 루프처럼 동일한 요청을 여러 번 보내는 워크로드에서 공급자 비용과 지연 시간을 줄일 수 있습니다.

캐싱은 기본적으로 꺼져 있으며 요청별로 적용됩니다. 캐시된 응답은 바이트 단위까지 그대로 재생되므로, 0이 아닌 temperature 같은 샘플링 매개변수를 사용하는 요청이라도 캐시 적중 시에는 동일한 답변이 반환됩니다.

<h2 id="enable-caching-for-a-request">
  요청에 캐싱 활성화하기
</h2>

`wandb-cache-mode` 요청 헤더를 다음 모드 중 하나로 설정하세요.

| 값 | 기존 응답 조회 | 성공한 응답 저장 |
| - | - | - |
| `readWrite` | 예 | 예 |
| `readOnly` | 예 | 아니요 |
| `writeOnly` | 아니요 | 예 |

캐시를 우회하려면 헤더를 생략하세요.

OpenPipe 클라이언트와의 호환성을 위해 프록시는 사용 중단된 `op-cache` 헤더도 허용합니다. 이 헤더는 동일한 모드를 지원하며, 추가로 `true`는 `readWrite`의 별칭으로, `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">
  두 요청을 동일한 요청으로 판단하는 기준
</h2>

프록시는 프로젝트 버전과 라우팅 리비전을 확인한 후, 공급자를 선택하기 전에 캐시된 응답을 조회합니다. 캐시 키는 다음 값을 조합하여 만들어집니다.

* 프록시가 `model` 값에서 확인한 W\&B entity, 프로젝트, 프로젝트 버전
* 요청이 도착한 시점에 해당 버전에 적용되는 [라우팅 리비전](/ko/model-distillation/studio/routing-and-versions#save-to-an-existing-or-new-version)
* 요청 경로와 쿼리 문자열
* 객체 키를 정렬된 순서로 직렬화하고 아래 값을 제외한 요청 본문의 SHA-256 해시

프록시는 해싱 전에 본문에서 다음 값을 제거하므로, 이 값들은 키에 영향을 주지 않습니다.

* 원시 `model` 문자열. 확인된 프로젝트, 버전, 라우팅 리비전이 이미 키에 포함되어 있으므로 동등한 레퍼런스끼리만 항목을 공유합니다. 예를 들어 `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와 프로젝트로 제한됩니다. 다른 entity에서 보낸 동일한 요청이나 같은 entity 내 다른 프로젝트에 대한 동일한 요청은 사용자의 항목과 절대 일치하지 않습니다.

캐시된 응답에는 해당 응답을 생성한 라우팅 대상이 기록됩니다. 캐시 적중 시 프록시는 가중치 기반 라우팅이나 고정(sticky) 라우팅을 적용하지 않고 해당 대상의 응답을 서빙합니다.

`provider/model` 직접 요청에서도 캐시 헤더를 설정할 수 있습니다. 프록시는 이러한 요청의 항목을 entity, 공급자, 모델 레퍼런스, 호출자의 W\&B ID를 기준으로 별도의 키로 관리합니다. 이러한 항목은 프로젝트 항목과 절대 일치하지 않습니다.

<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`를 반환합니다.

캐시 오류는 페일 오픈(fail open) 방식으로 처리됩니다. 캐시를 조회하거나 기록할 수 없으면 프록시는 평소처럼 요청을 공급자에게 전달합니다.

프록시는 동시 요청을 병합하지 않습니다. 프록시가 첫 번째 응답을 저장하기 전에 동일한 요청이 여러 개 도착하면 각 요청이 모두 공급자에게 전달되며, 프록시는 마지막으로 기록된 응답을 저장합니다.

<h2 id="traces-and-analytics">
  트레이스 및 분석
</h2>

프록시는 캐시 적중도 프로젝트 트레이스로 기록합니다. 이 트레이스에는 원래 응답과 해당 토큰 사용량이 그대로 남고, `cache_hit=true`로 표시되며, 공급자 지연 시간은 기록되지 않습니다. 캐시 읽기를 활성화했지만 공급자로 전달된 요청은 `cache_hit=false`로 표시됩니다.

캐시 적중 시에는 추론이 실행되지 않으므로 분석에서 공급자 비용을 0으로 집계합니다. 다만 토큰 합계에는 재사용된 사용량이 그대로 포함됩니다. 데이터셋을 생성할 때는 동일한 입력의 중복이 제거되므로, 재사용된 응답 때문에 트레이닝 행이 중복으로 추가되지 않습니다.

<h2 id="browser-clients">
  브라우저 클라이언트
</h2>

프록시는 교차 출처 요청에서 `wandb-cache-mode` 및 `op-cache` 요청 헤더를 허용하며, `wandb-cache-status`, `x-wandb-cache`, `x-proxy-request-id` 헤더를 브라우저 코드에 노출합니다.

<Card title="Chat Completion" href="/ko/model-distillation/proxy/chat-completions" arrow="true">
  프록시가 공급자 요청을 구성하고 스트리밍을 처리하며 도구와 구조화된 출력을 전달하는 방식을 알아보세요.
</Card>


## Related topics

- [서버 응답 캐싱](/ko/products/wandb/weave/guides/platform/server-caching.md)