응답 캐싱 - CoreWeave Docs

정확한 응답 캐싱(exact-response caching)을 사용하면 프로젝트로 라우팅된 요청에 대해, 프록시가 동일한 요청에 이미 생성한 응답을 재사용할 수 있습니다. 요청에서 캐싱을 사용하도록 설정했고 일치하는 응답이 있으면, 프록시는 공급자에 요청을 보내지 않고 해당 응답을 반환합니다. 따라서 평가 스위트, 회귀 테스트, 재시도, 개발 루프처럼 동일한 요청을 여러 번 보내는 워크로드에서 공급자 비용과 지연 시간을 줄일 수 있습니다. 캐싱은 기본적으로 꺼져 있으며 요청별로 적용됩니다. 캐시된 응답은 바이트 단위까지 그대로 재생되므로, 0이 아닌 temperature 같은 샘플링 매개변수를 사용하는 요청이라도 캐시 적중 시에는 동일한 답변이 반환됩니다.

요청에 캐싱 활성화하기

Forge-Cache-Mode 요청 헤더를 다음 모드 중 하나로 설정하세요.

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

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

Python
JavaScript
cURL

import os

from openai import OpenAI

client = OpenAI(
    base_url="https://proxy.training.coreweave.com/v1",
    api_key=os.environ["WANDB_API_KEY"],
    project="your-team/ticket-classifier",  # OpenAI-Project로 전송됨
)

raw = client.chat.completions.with_raw_response.create(
    model="router",
    messages=[
        {"role": "user", "content": "My package arrived damaged. What should I do?"}
    ],
    extra_headers={"Forge-Cache-Mode": "readWrite"},
)

print(raw.headers.get("forge-cache-status"))  # "hit" 또는 "miss"
response = raw.parse()
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://proxy.training.coreweave.com/v1",
  apiKey: process.env.WANDB_API_KEY,
  project: "your-team/ticket-classifier", // OpenAI-Project로 전송됨
});

const { data: response, response: raw } = await client.chat.completions
  .create(
    {
      model: "router",
      messages: [
        { role: "user", content: "My package arrived damaged. What should I do?" },
      ],
    },
    { headers: { "Forge-Cache-Mode": "readWrite" } },
  )
  .withResponse();

console.log(raw.headers.get("forge-cache-status")); // "hit" 또는 "miss"
console.log(response.choices[0].message.content);

curl -i https://proxy.training.coreweave.com/v1/chat/completions \
  -H "Authorization: Bearer $WANDB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Project: your-team/ticket-classifier" \
  -H "Forge-Cache-Mode: readWrite" \
  -d '{
    "model": "router",
    "messages": [
      {"role": "user", "content": "My package arrived damaged. What should I do?"}
    ]
  }'

요청에서 캐시 읽기를 활성화하면(readWrite 또는 readOnly) 응답에 Forge-Cache-Status 헤더가 포함되며, 값은 hit 또는 miss입니다. writeOnly 요청의 응답에는 이 헤더가 포함되지 않습니다.

두 요청을 동일한 요청으로 판단하는 기준

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

프록시가 OpenAI-Project 헤더와 forge.project_version 메타데이터에서 확인한 Weights & Biases entity, 프로젝트, 프로젝트 버전
요청이 도착한 시점에 해당 버전에 적용되는 라우팅 리비전
요청 경로와 쿼리 문자열
객체 키를 정렬된 순서로 직렬화하고 아래 값을 제외한 요청 본문의 SHA-256 해시

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

라우팅된 요청의 원시 model 문자열. 확인된 프로젝트, 버전, 라우팅 리비전이 이미 키에 포함되어 있으므로 "router", 빈 model, 생략된 model은 항목을 공유합니다. 서로 다른 버전은 항목을 공유하지 않습니다.
forge. 또는 wandb.로 시작하는 메타데이터 키(forge.project_version 포함)
gen_ai.conversation.id의 대화 식별자
stream: false. 프록시는 이를 stream을 생략한 것과 동일하게 처리합니다.
빈 metadata 객체. 프록시는 이를 metadata를 생략한 것과 동일하게 처리합니다.

프록시 호스트 이름과 쿼리 매개변수의 순서도 키에 영향을 주지 않습니다. 버전의 라우팅을 저장할 때마다 Model Distillation은 새 라우팅 리비전을 게시하며, 이에 따라 키가 바뀝니다. 기존 항목은 더 이상 일치하지 않지만 만료될 때까지 유지됩니다. 프록시는 라우팅 대상의 매개변수 재정의를 해싱하지 않습니다. 하지만 재정의를 변경하는 것도 일반적인 라우팅 변경에 해당하므로 역시 키가 바뀝니다. 본문의 나머지 필드는 공급자가 사용하는지 여부와 관계없이 모두 해시에 포함됩니다. 여기에는 messages, tools, tool_choice, response_format, temperature, top_p, max_tokens, seed, n, stop, user, 모든 공급자별 필드, 그리고 user.id처럼 forge. 또는 wandb.로 시작하지 않는 메타데이터 키가 포함됩니다. 객체 내 키의 순서는 영향을 주지 않지만, messages와 같은 배열 내 항목의 순서는 영향을 줍니다. 항목의 범위는 사용자의 Weights & Biases entity와 프로젝트로 제한됩니다. 다른 entity에서 보낸 동일한 요청이나 같은 entity 내 다른 프로젝트에 대한 동일한 요청은 사용자의 항목과 절대 일치하지 않습니다. 캐시된 응답에는 해당 응답을 생성한 라우팅 대상이 기록됩니다. 캐시 적중 시 프록시는 가중치 기반 라우팅이나 고정(sticky) 라우팅을 적용하지 않고 해당 대상의 응답을 서빙합니다. 모델 재정의는 OpenAI-Project 헤더와 함께 model에 provider/model 값을 담아 보냅니다. 프록시는 이를 라우팅된 트래픽과 마찬가지로 선택된 프로젝트 버전에 캐시합니다. 다만 키에 공급자, 모델 참조, 공급자 설정도 포함되므로 재정의 요청은 라우팅된 항목이나 다른 모델의 항목과 절대 일치하지 않습니다.

제한 사항

캐시에는 다음과 같은 제한 사항이 있습니다.

비스트리밍 요청만 지원됩니다. 캐시 헤더를 설정한 stream: true 요청은 400 Bad Request를 반환합니다.
성공한 응답만 저장됩니다. 프록시는 최대 8 MiB 크기의 2xx 응답만 저장합니다.
보존 기간은 7일입니다. 항목은 기록된 지 7일이 지나면 삭제됩니다. 캐시 적중이 발생해도 보존 기간은 연장되지 않습니다.
잘못된 모드는 거부됩니다. 위에 나열된 값 이외의 Forge-Cache-Mode 값을 사용하면 400 Bad Request를 반환합니다.

캐시 오류는 페일 오픈(fail open) 방식으로 처리됩니다. 캐시를 조회하거나 기록할 수 없으면 프록시는 평소처럼 요청을 공급자에게 전달합니다. 프록시는 동시 요청을 병합하지 않습니다. 프록시가 첫 번째 응답을 저장하기 전에 동일한 요청이 여러 개 도착하면 각 요청이 모두 공급자에게 전달되며, 프록시는 마지막으로 기록된 응답을 저장합니다.

트레이스 및 분석

프록시는 캐시 적중도 프로젝트 트레이스로 기록합니다. 이 트레이스에는 원래 응답과 해당 토큰 사용량이 그대로 남고, cache_hit=true로 표시되며, 공급자 지연 시간은 기록되지 않습니다. 캐시 읽기를 활성화했지만 공급자로 전달된 요청은 cache_hit=false로 표시됩니다. 캐시 적중 시에는 추론이 실행되지 않으므로 분석에서 공급자 비용을 0으로 집계합니다. 다만 토큰 합계에는 재사용된 사용량이 그대로 포함됩니다. 데이터셋을 생성할 때는 동일한 입력의 중복이 제거되므로, 재사용된 응답 때문에 트레이닝 행이 중복으로 추가되지 않습니다.

브라우저 클라이언트

프록시는 교차 출처 요청에서 OpenAI-Project 및 Forge-Cache-Mode 요청 헤더를 허용하며, Forge-Cache-Status 및 x-proxy-request-id 헤더를 브라우저 코드에 노출합니다.

Chat Completion

프록시가 공급자 요청을 구성하고 스트리밍을 처리하며 도구와 구조화된 출력을 전달하는 방식을 알아보세요.

​요청에 캐싱 활성화하기

​두 요청을 동일한 요청으로 판단하는 기준

​제한 사항

​트레이스 및 분석

​브라우저 클라이언트