캐시된 입력 토큰은 저렴합니다. BroadNet Inference에서 DeepSeek V4.1 Flash는 캐시된 입력을 100만 토큰당 $0.175 요금 대신 $0.0055 요금으로 과금합니다. 가격과 usage 필드 읽는 법은 캐시된 토큰 설명에서 다룹니다. 이 글은 설계 작업에 관한 것입니다. 캐시가 실제로 적중하도록 프롬프트를 배치하는 방법과, 적중하는지 증명하는 방법입니다.
왜 프롬프트 순서가 캐시 적중률을 결정하나요?
주요 제공업체는 모두 접두부 단위로 캐시합니다. OpenAI 가이드는 재사용하려면 렌더링된 접두부 전체가 일치해야 한다고 합니다. DeepSeek 문서도 같은 규칙을 설명합니다. 요청이 저장된 접두부와 완전히 일치해야만 적중하며, 중간에 달라지면 적중하지 않습니다. Anthropic은 도구, 시스템, 메시지 순서로 캐시를 만듭니다.
내부적으로 서버는 해당 접두부에 대해 만들어 둔 KV 캐시를 재사용합니다. 그래서 캐시는 첫 토큰에서 시작하는 일직선입니다. 직전 호출과 처음 달라지는 바이트에서 재사용 가능한 부분이 끝납니다. 50,000토큰짜리 프롬프트 맨 위에 타임스탬프 한 줄을 두면 50,000토큰 전체를 정가로 내게 됩니다.
올바른 계층 순서는 무엇인가요?
| 계층 | 바뀌는 시점 | 예시 | 규칙 |
|---|---|---|---|
| 1. 시스템 프롬프트 | 배포할 때 | 역할, 규칙, 출력 형식 | 날짜, ID, 사용자 이름 금지 |
| 2. 도구 정의 | 배포할 때 | 함수 스키마 | 정렬된 결정적 JSON |
| 3. 참고 자료 | 세션 또는 작업마다 | 저장소 파일, 계약서, 제품 문서 | 고정된 순서, 고정된 레이블 |
| 4. 대화 이력 | 턴마다, 덧붙이기만 | 이전 사용자·어시스턴트 턴 | 수정 금지, 추가만 |
| 5. 새 메시지 | 매 호출 | 질문, 필요하면 현재 시각 | 자주 바뀌는 데이터는 여기에 |
자주 바뀌는 것은 모두 5번 계층에 두세요. 현재 날짜, 사용자 로캘, 요청 ID, 질문마다 달라지는 검색 결과 조각입니다.
모르는 사이에 접두부를 깨뜨리는 것은 무엇인가요?
- 딕셔너리 순서. 프레임워크는 흔히 딕셔너리나 레지스트리로
tools배열을 만듭니다. 플러그인이 다른 순서로 로드되면 바이트가 바뀝니다. - JSON 형식.
json.dumps(x)와json.dumps(x, indent=2)는 서로 다른 접두부입니다. 키 순서가 다른 직렬화기 두 개도 마찬가지입니다. - 템플릿 공백. 뒤에 붙은 공백 하나, 또는 한 코드 경로에서는
\r\n, 다른 경로에서는\n. - 동적 도구 목록. 사용자가 쓸 수 없는 도구를 빼면 접두부가 바뀝니다. OpenAI 가이드는 정의를 고정해 두고
tool_choice나 허용 도구 설정으로 사용을 제한하라고 권합니다. - 이력을 제자리에서 요약하기. 오래된 턴을 요약으로 다시 쓰면 시스템 프롬프트 뒤의 모든 것이 초기화됩니다. 요약은 드물게, 큰 단위로 하세요.
- 지시문 앞의 검색 결과. 시스템 프롬프트와 도구 사이에 놓인 RAG 조각은 질의마다 달라지므로 도구 계층까지 깨뜨립니다.
캐시 친화적인 요청을 코드로 어떻게 만드나요?
각 계층을 고정된 입력만으로 만들고, 결정적으로 직렬화하세요.
import json, os
from openai import OpenAI
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
SYSTEM = open("prompts/system.md").read() # versioned file, no templating
def stable_tools(registry: dict) -> list:
# Sort by name, sort keys inside each schema.
return [json.loads(json.dumps(registry[name], sort_keys=True)) for name in sorted(registry)]
def docs_block(paths: list[str]) -> str:
parts = [f"=== {p} ===\n{open(p).read()}" for p in sorted(paths)]
return "\n\n".join(parts)
def build_messages(history: list, user_text: str, now_iso: str, doc_paths: list[str]):
return (
[{"role": "system", "content": SYSTEM},
{"role": "user", "content": docs_block(doc_paths)}]
+ history # append-only
+ [{"role": "user", "content": f"(now: {now_iso})\n{user_text}"}]
)
resp = client.chat.completions.create(
model="broadnet/deepseek-v4.1-flash",
messages=build_messages(history, question, now_iso, files),
tools=stable_tools(TOOLS),
)
history += [{"role": "user", "content": question}, resp.choices[0].message.model_dump(exclude_none=True)]
세부 사항 두 가지. 현재 시각은 시스템 프롬프트가 아니라 마지막 메시지에 넣습니다. 그리고 이력에는 어시스턴트 메시지를 반환된 그대로 저장하므로, 다음 호출에서 똑같은 바이트를 다시 보냅니다.
접두부가 캐시되는지 어떻게 증명하나요?
CI나 노트북에서 호출 두 번짜리 테스트를 실행하세요.
- 실제 시스템 프롬프트, 도구, 문서로 요청을 만드세요.
- 보내고
usage.prompt_tokens를 기록하세요. - 마지막 사용자 메시지만 바꿔서 다시 보내세요.
- 두 번째 호출의
usage.prompt_tokens_details.cached_tokens를 읽으세요. 공유된 접두부를 거의 다 덮어야 합니다. - 0이거나 작다면 직렬화된 요청 본문을 바이트 단위로 비교하세요. 처음 달라지는 곳이 캐시를 깨뜨리는 원인입니다.
대부분의 제공업체에서 캐싱은 최선 노력 방식이며, DeepSeek 문서도 이를 직접 밝힙니다. 그러니 한 번 빗나갔다고 버그의 증거는 아닙니다. 계속 빗나간다면 버그입니다. 사용량 로그에서 요청별로 프롬프트 토큰 대비 캐시된 토큰 비율을 추적하고, 적중률을 높이면 얼마나 아끼는지는 프롬프트 캐싱 계산기로 확인하세요.
에이전트와 긴 컨텍스트에서는 무엇이 달라지나요?
에이전트는 작업 하나에서 같은 큰 접두부를 수십 번 다시 보내므로 효과가 가장 큽니다. 두 가지 습관이 중요합니다.
- 작업 하나에 대화 하나. 하위 단계마다 새 대화를 시작하면 접두부를 버리게 됩니다.
- 파일은 위쪽에서 한 번만 읽기. 에이전트가 파일을 다시 읽는다면, 파일이 바뀌지 않은 한 이전 사본을 교체하지 말고 새 사본을 뒤에 덧붙이세요.
100만 토큰 컨텍스트 윈도우라면 3번 계층에 저장소 전체를 담을 수 있습니다. 토큰당 과금 키에서 이를 감당할 수 있는 것은 캐시될 때뿐이며, 그래서 프롬프트가 커질수록 계층 순서가 더 중요해집니다. 캐시된 접두부는 첫 토큰까지의 시간도 줄이는 경향이 있습니다. TTFT vs 처리량을 참고하세요.
BroadNet Inference는 어디에 적합한가요?
BroadNet Inference에서는 모델이 보고하는 경우 usage 블록에 prompt_tokens_details.cached_tokens가 담기며, DeepSeek V4.1 Flash, GLM 5.3, Qwen3.8 27B의 캐시된 입력은 가격 페이지에 나온 낮은 단가로 과금됩니다. BroadNet 문서에는 명시적인 캐시 중단점이나 캐시 키 파라미터가 없으므로, 위의 배치가 기법의 전부입니다. 무제한 플랜에서는 세션에 토큰 계량이 없어 캐시가 청구액을 바꾸지 않지만, 같은 구조가 여전히 지연 시간에 도움이 됩니다.
