Qwen4 프롬프트 캐시: 에이전트 컨텍스트 재사용과 캐시 미스 해결

Qwen4 캐시 중단점을 설정하고 두 요청을 비교해 사용량을 읽는 방법. 로컬 요청 생성기와 캐시 미스 점검표를 제공합니다.

재사용하는 인쇄판이 일정한 무늬를 찍고 작은 주황색 요소만 달라집니다.

에이전트가 같은 참고 자료를 반복해서 읽는다면 고정 컨텍스트를 캐시 중단점 앞에, 바뀌는 질문을 뒤에 배치하세요. 그런 다음 보고된 캐시 읽기 사용량을 확인합니다. 비슷한 프롬프트를 보내고 응답이 빨라졌다는 사실만으로 캐시가 작동했다고 판단할 수는 없습니다.

이 글은 2026년 11월 16일 확인한 QwenCloud의 Qwen4 직접 API를 다루며 Qwen4-Max 연결 및 마이그레이션 가이드에서 이어집니다. 아래 요청 생성기는 키 없이 로컬에서 실행됩니다. 이 글을 위해 유료 캐시 요청을 실행하지 않았으므로 예시는 실측 절감액이나 지연 시간이 아니라 재현 가능한 실험 방법입니다.

동일하게 유지할 부분 정하기

매번 같은 제품 설명서를 받고 고객마다 다른 질문에 답하는 지원 분석 에이전트를 생각해 보세요. 설명서는 재사용하기 좋은 대상입니다. 설명서 앞에 타임스탬프, 무작위 ID, 바뀌는 질문을 넣으면 요청의 시작 부분이 달라질 수 있습니다.

입력을 두 부분으로 명확하게 나누세요.

고정 컨텍스트바뀌는 작업
승인된 설명서 버전현재 고객 질문
고정된 도구 정의현재 작업의 도구 결과
일관된 지시문 순서이번 턴에 요구하는 출력
고정된 문서 직렬화 방식분석을 바꾸는 새로운 근거

캐시 적중률을 높이려고 잘못된 정보를 고정하지 마세요. 설명서가 바뀌면 새 접두부를 쓰는 것이 맞습니다. 문서 버전과 해시를 기록하면 의도한 업데이트로 발생한 미스와 우발적인 서식 변경을 구분할 수 있습니다.

Qwen4 공식 캐시 가이드는 최소 캐시 접두부 1,024토큰, 동일 사용자 범위 내 정확한 접두부 일치, Chat Completions·Responses·Anthropic Messages 지원을 명시합니다. Qwen4 명시적 캐시는 DashScope에서 지원되지 않습니다. 단어나 문자 수는 정확한 토큰 수가 아닙니다.

요청 두 개를 로컬에서 만들기

선택한 제공업체에 전송할 권한이 있는 합성 자료나 민감하지 않은 참고 문서를 reference.txt로 저장하세요. 첫 요청과 두 번째 요청 사이에 내용을 변경하지 않습니다.

다음 코드를 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을 확인하세요. 첫 콘텐츠 블록과 중단점은 완전히 같고 두 번째 블록의 질문만 달라야 합니다. 이 스크립트는 참고 자료의 토큰 수를 측정하지 않습니다. 유료 요청을 보내기 전에 제공업체의 토큰 계산 기능이나 검증된 해당 모델용 토크나이저로 최소 조건을 확인하세요.

중단점은 콘텐츠 블록에 속하므로 메시지의 content는 배열입니다. 이 예시는 중단점 마커 하나를 사용합니다. 같은 요청에 다른 캐시 마커 문법을 섞지 마세요. 첫 호출은 재사용할 컨텍스트를 만들고 두 번째 호출은 이를 재사용하려는 목적입니다. 실제로 그렇게 됐는지는 응답 사용량으로 판단합니다.

올바른 경로에서 순서대로 요청 보내기

공식 키 가이드에 따라 선택한 지역의 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으로 남습니다. 스크립트는 보고되지 않은 값을 몰래 0으로 바꾸지 않습니다. 두 원본 응답은 비공개로 보관하세요. 제공업체가 다른 프로토콜의 사용량 구조를 반환한다면 작동하는 것처럼 보일 때까지 필드명을 바꾸지 말고 해당 프로토콜 문서를 따르세요.

예를 들어 QwenCloud의 Responses 캐시 상세 정보는 input_tokens_details에 있으며 Anthropic 호환 사용량에는 별도의 읽기·생성 필드가 있습니다. 일부 필드는 별칭입니다. 별칭과 그에 대응하는 값을 모두 더하면 사용량을 과대 계산하게 됩니다. 캐시 사용량 문서의 프로토콜별 표를 확인하세요.

한 번에 하나씩 바꾸며 캐시 미스 진단하기

관찰한 현상확인할 것다음 통제 실험
첫 요청에 재사용 가능한 접두부가 보고되지 않음최소 토큰 수, 마커 위치, 지원 프로토콜경로를 고정하고 직렬화한 요청 확인
두 번째 요청에 캐시 읽기가 없음정확한 접두부, 사용자 범위, 경과 시간첫 콘텐츠 블록을 바이트 단위로 비교
입력 일부만 캐시됨중단점이 끝나는 위치와 변경 사항고정 문서를 현재 질문과 분리
이전에 되던 요청 순서에서 미스 발생참고 문서 버전, 도구 정의, 클라이언트 직렬화저장한 요청을 마지막 정상 요청 쌍과 비교
사용량 필드가 없음프로토콜, 응답 형식, 스트리밍 동작완전한 비스트리밍 응답부터 확인
매개변수 오류 반환경로별 지원과 JSON 구조문서화된 단일 마커 예제로 축소

긴 에이전트 대화에는 추가 경계가 있습니다. 공식 가이드는 각 중단점에서 최대 20개의 이전 콘텐츠 블록을 살펴보고, 자동 중단점을 사용하는 경우 이를 포함해 마지막 유효 중단점 4개만 유지한다고 설명합니다. 대화 이력이 늘어나 유용한 접두부가 이 탐색 범위를 벗어나면 블록 배치를 검토하고 고정 컨텍스트 경계에 중단점을 명시적으로 두세요. 적중시키기 위해 필요한 도구 결과나 추론 이력을 삭제해서는 안 됩니다. 변경 전후 요청 스냅샷을 남기고 실제 사용량을 확인하세요.

모든 캐시 미스를 모델 성능 저하로 해석하지 마세요. 실행 환경이 도구 순서를 바꾸거나, 동적 시스템 문구를 앞에 추가하거나, 문서 서식을 바꿀 수 있습니다. 제공업체 문제로 판단하기 전에 민감한 정보를 제거한 고정 접두부 표현과 해시를 기록하세요.

ID나 엔드포인트 오류는 model not found 문제 해결 가이드 (영문)를 참고하세요. 캐시는 작동하지만 멀티턴 에이전트가 도구 결과를 잃는다면 별도의 이력 문제입니다. 멀티턴 도구 호출 보존에서 확인할 수 있습니다.

검수를 통과한 전체 작업 기준으로 절감액 계산하기

캐시 쓰기 비용은 읽기나 일반 입력 비용과 다를 수 있습니다. 최초 쓰기와 생성된 모든 답변을 포함한 전체 요청 순서를 캐시를 쓰지 않은 동일한 순서와 비교하세요. 다른 지역의 가격이나 프리뷰 프로모션을 복사하지 말고 QwenCloud 가격에서 현재 지역별 요금을 사용합니다.

호출마다 문서 버전, 입력 토큰, 캐시 읽기 토큰, 캐시 쓰기 토큰, 일반 입력, 출력 토큰, 소요 시간, 합격 여부를 기록하세요. 별칭을 중복 합산하지 마세요. 출력과 외부 도구가 전체 비용에서 큰 비중을 차지할 수 있으므로 캐시 입력 할인율을 전체 에이전트 작업의 할인율이라고 표현하면 안 됩니다.

청구 비용뿐 아니라 답변도 확인하세요. 두 질문 예시에서는 답변에 나온 책임과 승인 요건이 참고 문서에 실제로 있는지 독립적으로 확인합니다. 비용이 싸더라도 근거 없는 답변은 합격한 결과물이 아닙니다.

이 글은 QwenCloud 직접 연결 워크플로입니다. 11월 16일 확인한 Ofox 카탈로그에는 Qwen4가 없었습니다. 기존 Ofox 경로를 사용한다면 정확한 모델 항목을 확인하고 Ofox 인증과 Ofox 오류 처리를 따르세요. 이 문서들이 QwenCloud의 새 캐시 매개변수를 Ofox에서 사용할 수 있다는 근거가 되지는 않습니다.

자주 묻는 질문

같은 프롬프트를 반복하면 Qwen4가 캐시를 썼다는 뜻인가요?
아닙니다. 제공업체가 반환한 캐시 읽기 사용량 필드를 확인하세요. 응답이 빨라지거나 텍스트가 반복됐다는 사실만으로 적중을 입증할 수 없습니다.
이 캐시 매개변수를 Ofox에서도 쓸 수 있나요?
이 글은 QwenCloud의 Qwen4 직접 API를 설명합니다. 11월 16일 Ofox 카탈로그 확인에서는 Qwen4가 없었으므로 같은 모델이나 캐시 규격이 Ofox에서도 지원된다고 가정하지 마세요.