프롬프트 캐시 핑거프린팅(Prompt cache fingerprinting)의 함정: 완전 일치(exact-match) 캐싱의 적중률을 실제로

실제 운영 트래픽에서 완전 일치(exact-match) LLM 캐시가 약속하는 적중률(hit rate)은 5-15%입니다. 이를 도입한 대부분의 팀은 처음 몇 주 동안 적중률이 0에 가깝게 나타나는 것을 보고 캐싱이 자신들의 워크로드에는 작동하지 않는다고 가정합니다. 하지만 캐싱은 거의 항상 작동합니다. 단지 동일한 키를 찾아야 함에도 불구하고, 핑거프린팅(fingerprinting) 결과가 달라지게 만드는 사소한 요청 변형들이 캐시를 무력화하고 있을 뿐입니다. 이 포스트는 그 격차를 줄이는 규율, 즉 단순한 캐시 구현을 망가뜨리는 7가지 정규화(normalisation) 함정과 운영 트래픽에서도 견고하게 유지되는 해결 패턴을 다룹니다.

AI API 캐싱에 관한 상위 가이드에서는 캐시 계층과 경제성을 다룹니다. 이 글은 1계층(Layer 1, 완전 일치)이 실제로 작동하게 만드는 핑거프린팅 규율에 대해 한 단계 더 깊이 들어갑니다.

핑거프린팅이 수행해야 하는 역할

완전 일치 캐시는 결정론적 식별자(deterministic identifier)를 키로 하여 응답을 저장합니다. 이 식별자는 거의 항상 요청의 정규화된 표현(canonicalised representation)에 대한 SHA-256 해시입니다. 새로운 요청이 도착하면 동일한 해시를 계산하고, 키가 존재하면 캐시된 응답을 반환합니다. 핑거프린팅이 입력값의 바이트 동일성(byte-equivalence)을 보장하기 때문에 이 캐시는 증명 가능한 정확성을 가집니다.

핑거프린팅은 _응답에 영향을 미치는 모든 것_을 포착하고, _영향을 미치지 않는 모든 것_은 제외해야 합니다. 이 두 경계 지점에서 대부분의 팀이 문제에 직면합니다. 너무 적게 포함하면 실제 캐시 적중을 놓치게 되고, 너무 많이 포함하면 적중해야 할 캐시 적중을 놓치게 됩니다. 잘못된 요소(타임스탬프, 요청 ID, 사용자 메타데이터 등)를 포함하면 캐시가 각각 하나의 항목만 가진 파편(shards)으로 쪼개지게 됩니다.

첫 번째 원칙: 동일한 응답을 생성할 두 요청은 동일한 해시로 핑거프린팅되어야 합니다. 아래의 모든 내용은 이 단 하나의 규칙을 따릅니다.

함정 1 — 비결정론적 JSON 직렬화 (Non-deterministic JSON serialisation)

가장 흔한 버그입니다. Python의 json.dumps는 기본적으로 필드 순서(field ordering)를 보장하지 않습니다. JavaScript의 JSON.stringify는 객체가 생성된 방식에 따라 달라지는 삽입 순서(insertion order)대로 객체 키를 정렬합니다. 동일한 내용을 담고 있지만 필드 삽입 순서가 다른 두 요청은 서로 다른 문자열로 직렬화(serialise)되며, 결과적으로 서로 다른 키로 해싱(hash)됩니다.

# 의미론적으로 동일한 두 요청
req_a = {"model": "claude-sonnet", "messages": [...], "temperature": 0.7}
req_b = {"temperature": 0.7, "messages": [...], "model": "claude-sonnet"}
...

해결책: json.dumps를 호출할 때 항상 sort_keys=True를 전달하십시오. JavaScript에서는 정준 JSON (canonical-JSON) 라이브러리를 사용하거나, 문자열화(stringifying)하기 전에 명시적으로 키를 정렬하십시오. 캐시 핑거프린트(cache fingerprint)를 계산하는 모든 코드 경로에서 이를 타협 불가능한 규칙으로 취급해야 합니다.

canonical = json.dumps(req, sort_keys=True, separators=(",", ":"))
fingerprint = hashlib.sha256(canonical.encode("utf-8")).hexdigest()

separators 인수는 기본적으로 삽입되는 모든 공백을 제거합니다. 이는 Python 버전 및 직렬화기(serialiser) 설정 간의 불일치를 야기하는 또 다른 원인입니다.

함정 2 — 선택적 필드(Optional fields)의 불일치한 등장

대부분의 LLM SDK 클라이언트는 호출자가 명시적으로 설정한 필드만 전송합니다. OpenAI SDK의 경우, 호출자가 temperature: 1.0을 전달하지 않으면 1.0이 암시적 기본값(implicit default)임에도 불구하고 이를 포함하지 않습니다. 한 요청은 {"model": "gpt-5-4", "messages": [...]}를 가지고, 다른 요청은 {"model": "gpt-5-4", "messages": [...], "temperature": 1.0}를 가집니다. 모델 입장에서는 동일한 유효 요청이지만, 핑거프린트는 서로 다릅니다.

req_a = {"model": "gpt-5-4", "messages": [...]}                    # temperature 생략
req_b = {"model": "gpt-5-4", "messages": [...], "temperature": 1.0} # temperature 명시
# 둘 다 동일한 모델 출력을 생성하지만, 해시 값은 다르게 생성됨

해결책: 핑거프린팅(fingerprinting)을 수행하기 전에, 모든 관련 필드에 기본값(defaults)을 적용하여 정규화된 형태(canonical form)로 변환하십시오. 만약 temperature가 설정되지 않았다면 1.0으로 설정하십시오. 만약 top_p가 설정되지 않았다면 1.0으로 설정하십시오. 만약 max_tokens가 설정되지 않았다면 귀하의 기본값(OpenAI의 경우 일반적으로 4096이며, 제공자마다 다름)으로 설정하십시오. 핑거프린팅은 정규화가 완료된 요청을 대상으로 실행됩니다.

기본값 테이블을 눈에 잘 띄는 곳에 문서화하십시오. 기본값이 여러 파일에 흩어져 있으면 이 규율(discipline)은 유지되기 어렵습니다.

함정 3 — 기능과 무관한 필드 포함

OpenAI 요청에는 남용 탐지(abuse-detection)를 위한 user 필드가 포함될 수 있습니다. 일부 애플리케이션은 내부 추적 데이터를 담은 metadata 객체를 첨부하기도 합니다. 많은 라이브러리는 요청 ID(request ID)나 타임스탬프(timestamp)를 자동으로 주입합니다. 이 중 어느 것도 모델의 출력에는 영향을 주지 않지만, 만약 이 중 하나라도 핑거프린트에 포함된다면 모든 요청이 고유한 핑거프린트를 갖게 되어 캐시 적중률(cache hit rate)이 0으로 급락합니다.

# 해시에 요청 ID가 포함됨. 모든 요청이 고유해짐.
req = {
    "model": "claude-sonnet",
...

해결책: 핑거프린트에 포함될 필드에 대해 명시적인 허용 목록(allowlist)을 유지하십시오. 허용 목록에 없는 모든 것은 제외됩니다. 채팅 완성(chat completions)을 위한 허용 목록은 일반적으로 다음과 같습니다:

FINGERPRINT_FIELDS = {
    "model", "messages", "temperature", "top_p", "max_tokens",
    "stop", "tools", "tool_choice", "response_format",
...

차단 목록(denylist)보다는 허용 목록(allowlist)을 사용하십시오. 차단 목록은 취약합니다. 새로운 SDK 버전이 예상치 못한 메타데이터 필드를 추가하면 갑자기 캐시가 분산됩니다. 허용 목록은 실패 시 차단(fail closed) 방식입니다(새로운 필드가 추가되어도 명시적으로 추가하기 전까지는 무시됩니다).

함정 4 — 정렬되지 않은 도구(Tools) 배열

함수 호출(Function-calling) / 도구 사용(tool-use) 요청에는 tools 배열이 포함됩니다. 모델은 도구의 순서에 상관하지 않습니다. 모델은 순서와 관계없이 전체 도구 세트를 보기 때문에 [A, B]와 [B, A]는 동일한 모델 동작을 생성합니다. 하지만 JSON 직렬화(serialization)는 순서에 따라 달라지므로, 핑거프린트도 달라지게 됩니다.

req_a = {"messages": [...], "tools": [tool_search, tool_calculator]}
req_b = {"messages": [...], "tools": [tool_calculator, tool_search]}
# 동일한 유효 요청이지만, 핑거프린트(fingerprints)는 다름

해결책: 핑거프린팅을 하기 전에, 도구(tools) 배열을 도구 이름(또는 각 도구별 정형 식별자(canonical identifier))에 따라 정렬하십시오. stop 배열에도 동일하게 적용됩니다. 만약 stop이 문자열 리스트라면 정렬하십시오. 집합(set) 형태의 데이터 구조이지만 배열로 표현되는 모든 것은 결정론적 순서(deterministic ordering)가 필요합니다.

def canonicalise(req: dict) -> dict:
    out = dict(req)
    if "tools" in out:
...

함정 5 — 핑거프린트에 스트리밍 플래그(Streaming flag)가 포함됨

흔히 발생하는 미묘한 버그입니다. stream 파라미터는 모델의 콘텐츠를 변경하지 않습니다. 토큰을 스트리밍(streaming)하든 단일 응답으로 버퍼링(buffer)하든 동일한 프롬프트는 동일한 토큰을 생성합니다. 만약 핑거프린트에 stream이 포함되어 있다면, 모든 스트리밍 호출은 모든 비스트리밍 호출과 해시(hash) 값이 달라지며, 캐시가 스트리밍 절반과 비스트리밍 절반으로 나뉘게 됩니다. 절반이 비어 있는 절반은 곧 적중률(hit rate)이 절반임을 의미합니다.

req_streaming = {"messages": [...], "stream": True}
req_buffered = {"messages": [...], "stream": False}
# 동일한 콘텐츠; 동일하게 해시되어야 함

해결책: 핑거프린트에서 stream을 제외하십시오. 요청의 stream 플래그와 관계없이 캐시된 응답은 항상 비스트리밍 JSON으로 제공하십시오. 캐시에서 가짜 스트림(fake stream)을 제공하는 것은 운영상 복잡합니다. stream_options 및 이와 유사한 스트리밍 제어 필드에도 동일한 규칙이 적용됩니다.

이는 또한 관련 버그를 해결합니다. 원래 스트림으로 캡처된 응답을 스트림으로 캐시 응답을 제공하는 것은 캐시 항목당 전체 SSE 이벤트 로그를 저장해야 함을 의미하며, 이는 이득 없이 저장 공간을 2~3배 부풀립니다.

함정 6 — 공백(Whitespace) 및 마지막 줄 바꿈(trailing newlines)

실제 운영 트래픽(production traffic)은 사용자 메시지에 마지막 공백(trailing whitespace)을 포함하는 경우가 많습니다. userInput.trim()을 수행하는 프론트엔드는 이를 제거하지만, userInput을 그대로 사용하는 프론트엔드는 이를 남겨둡니다. 의도는 같지만, 바이트(byte)가 다르고, 결과적으로 핑거프린트(fingerprint)가 달라집니다. 이는 "내부 공백(internal whitespace)"에도 동일하게 적용됩니다. 즉

해결책: 핑거프린팅(fingerprinting)을 수행하기 전에 확장 필드(extension fields, 일반적으로 _로 시작하는 모든 것)를 필터링합니다. 도구 정렬(tool-sorting) 및 기본 애플리케이션(default-application)을 처리하는 것과 동일한 정규화(canonicalisation) 단계를 적용합니다:

def canonicalise(req: dict) -> dict:
    out = {k: v for k, v in req.items() if not k.startswith("_")}
    # ... 나머지 정규화 과정
...

중첩된 구조(예: 메시지의 _prism_cache_control 마커)의 경우, 동일한 필터를 재귀적으로 적용합니다.

구성된 정규화기 (The composed canonicaliser)

실제 운영 환경에서 유효한 패턴은 모든 정규화 과정을 한 곳에 모으는 것입니다:

def fingerprint_request(req: dict) -> str:
    canonical = canonicalise(req)
    serialised = json.dumps(canonical, sort_keys=True, separators=(",", ":"))
...

단 하나의 함수, 단 하나의 업데이트 지점, 그리고 요청을 해싱(hash)하는 모든 코드 경로에서 결정론적(deterministic)으로 동작합니다. 여기서 규율(discipline)은 추상화(abstraction)입니다. 모든 캐시 쓰기(cache write)와 모든 캐시 조회(cache lookup)는 fingerprint_request를 거쳐야 합니다. 만약 두 호출자가 동일한 함수를 공유하지 않는다면, 그들은 동일한 캐시를 공유하지 않는 것입니다.

작동 여부를 확인하는 방법

운영 환경에서 올바른 핑거프린팅이 이루어지고 있다는 징후는 다음과 같습니다:

캐시 워밍업(cache warm-up) 후 며칠 이내에 적중률(hit rate)이 0%에 가까운 수준에서 예상 범위인 5-15%로 상승합니다. 결정론적인 패턴을 가진 워크로드(cron, 평가 실행 등)에서 가장 빠르게 상승합니다.
핑거프린트당 저장 용량이 무한정 늘어나지 않습니다. 만약 캐시가 요청당 하나의 항목을 저장하고 있다면(즉, 전체 캐시 크기가 트래픽에 따라 선형적으로 증가한다면), 핑거프린트가 지나치게 구체적(over-specific)인 것입니다.
캐시 적중(cache hit) 시 결코 잘못된 응답을 반환하지 않습니다. 만약 잘못된 응답을 반환한다면, 핑거프린트가 너무 일반적(under-specific)인 것입니다(응답에 영향을 미치는 무언가가 해시에 포함되지 않아 서로 다른 응답들이 동일한 키를 공유하는 경우). 배포 후 첫날에 수동으로 샘플 검증을 수행하십시오.
SDK 업그레이드 시에도 안정적입니다. 만약 OpenAI SDK 업그레이드로 인해 기본 동작(default behaviour)이 변경되어 캐시 적중률이 떨어진다면, 정규화기(canonicaliser)가 새로운 기본값을 놓친 것입니다. 이를 감사(audit)하고 수정하십시오.

이러한 규율은 일주일 만에 비용을 회수하는 캐시와 수익 없이 오버헤드(overhead)만 발생하는 캐시 사이의 차이를 만들어내기 때문에 그만한 가치가 있습니다. "캐싱을 시도해 봤지만 효과가 없었다"라고 말하는 대부분의 프로덕션(production) 팀은 위에서 언급한 7가지 함정 중 하나에 빠진 것입니다. 해결책은 기계적이며, 그 결과는 문헌에서 약속하는 수준의 적중률(hit rate)로 나타납니다.

Prism이 이를 처리하는 방식

Prism의 services/cache.py는 모든 요청에 대해 위에서 설명한 정규화(canonicalisation) 과정을 실행합니다. 즉, 화이트리스트(allowlisted) 필드, 정렬된 도구(tools), 정규화된 공백(normalised whitespace), 제거된 확장(stripped extensions), 기본값이 적용된 파라미터(parameters) 등을 처리합니다. 핑거프린트(fingerprint)는 정규화된 요청을 대상으로 실행되므로, SDK의 특이사항이나 고객 측의 변동 사항에 관계없이 캐시 쓰기(writes)와 조회(lookups)가 일관되게 유지됩니다.

v1.1 캐시 구축 당시 우리를 괴롭혔던(그리고 이 글을 쓰게 만든 동기가 된) 규율의 부재는 다음과 같습니다. _prism_cache_control 확장 마커가 원래 핑거프린트에 포함되어 있었고, 이로 인해 해당 마커가 있는 요청과 없는 요청 사이에서 캐시가 분리되었습니다. 해결책은 정규화기(canonicaliser)에 한 줄의 필터를 추가하는 것이었습니다. 그 결과 적중률은 약 4%포인트 회복되었습니다. 작은 버그였지만 실제적인 영향이 있었으며, 이는 실제 시스템에서 이러한 함정들이 나타나는 전형적인 모습입니다.

전체 캐싱 프레임워크에 대해서는 상위 가이드인 AI API caching guide를 참조하십시오. 관련 용어 사전 항목은 cache fingerprinting을 참조하십시오. 완전 일치(exact-match) 방식과 의미론적(semantic) + 제공자 네이티브 패스스루(provider-native passthrough) 방식을 결합해야 하는 시점에 대해서는 exact vs semantic caching을 참조하십시오.