클라이언트 SDK에서의 프롬프트 캐싱
클라이언트 SDK에서의 프롬프트 캐싱 (Caching of Prompts in Client SDKs)
Langfuse 프롬프트는 SDK에서 클라이언트 측으로 캐시되므로, 첫 사용 이후에는 지연 영향이 없고 가용성 위험이 없어요. 또한 시작 시 프롬프트를 미리 가져와(pre-fetch) 캐시를 채우거나 폴백 프롬프트를 제공할 수도 있어요.
출처: 문서
본문
캐시 히트
SDK 캐시에 최신 프롬프트가 있으면 네트워크 요청 없이 즉시 반환돼요.
백그라운드 재검증
캐시 TTL이 만료되면 오래된(stale) 프롬프트를 즉시 제공하면서 백그라운드에서 재검증해요. 이렇게 하면 높은 가용성이 보장돼요. 사용자가 네트워크 요청을 기다리지 않으면서도 캐시는 계속 최신 상태를 유지하죠.
캐시 미스
캐시된 프롬프트가 없으면(예: 첫 애플리케이션 시작) API에서 프롬프트를 가져와요. API는 Redis 캐시에 프롬프트를 캐시해 낮은 지연을 보장해요. 여러 폴백 계층이 복원력을 보장해요. Redis를 사용할 수 없으면 데이터베이스가 백업 역할을 해요.
선택: 사전 페치 (Pre-fetch)
애플리케이션 시작 중 프롬프트를 사전 페치하면 런타임 요청 전에 캐시가 채워져요. 이 단계는 선택 사항이며 보통 필요하지 않아요. 일반적으로 서비스 시작 후 첫 사용 때 겪는 미미한 지연은 감당할 만해요. 설정 방법은 아래 예시를 참고하세요.
선택: 폴백 (Fallback)
로컬 캐시가 비어 있고 Langfuse API도 사용할 수 없을 때, 폴백 프롬프트를 사용해 100% 가용성을 보장할 수 있어요. 프롬프트 API는 가용성이 매우 높고 성능을 면밀히 모니터링하기 때문에(status page) 이는 거의 필요하지 않아요. 짧은 서비스 중단의 경우 SDK 수준 프롬프트 캐시가 애플리케이션에 영향이 없도록 보장하는 경우가 보통이에요.
선택: 캐싱 기간(TTL) 커스터마이징
Langfuse 클라이언트의 네트워크 오버헤드를 줄이고 싶다면 캐싱 기간을 구성할 수 있어요. 기본 캐시 TTL(Time To Live)은 60초예요. TTL이 만료되면 SDK가 백그라운드에서 프롬프트를 다시 가져와 캐시를 업데이트해요. 다시 가져오는 것은 비동기로 수행되며 애플리케이션을 차단하지 않아요.
Python SDKJS/TS SDK
# Get current `production` prompt version and cache for 5 minutes
prompt = langfuse.get_prompt("movie-critic", cache_ttl_seconds=300)
import { LangfuseClient } from "@langfuse/client";
const langfuse = new LangfuseClient();
// Get current `production` version and cache prompt for 5 minutes
const prompt = await langfuse.prompt.get("movie-critic", {
cacheTtlSeconds: 300,
});
선택: 캐싱 비활성화
cacheTtlSeconds를 0으로 설정하면 캐싱을 비활성화할 수 있어요. 이렇게 하면 매 호출마다 Langfuse API에서 프롬프트를 가져와요. 프롬프트가 항상 Langfuse의 최신 버전과 일치하도록 하고 싶은 비프로덕션 사용 사례에 권장돼요.
Python SDKJS/TS SDK
prompt = langfuse.get_prompt("movie-critic", cache_ttl_seconds=0)
# Common in non-production environments, no cache + latest version
prompt = langfuse.get_prompt("movie-critic", cache_ttl_seconds=0, label="latest")
const prompt = await langfuse.prompt.get("movie-critic", {
cacheTtlSeconds: 0,
});
// Common in non-production environments, no cache + latest version
const prompt = await langfuse.prompt.get("movie-critic", {
cacheTtlSeconds: 0,
label: "latest",
});
선택: 프롬프트의 보장된 가용성
보통 필요하지 않지만, 애플리케이션 시작 시 프롬프트를 사전 페치하고 폴백 프롬프트를 제공하면 100% 가용성을 보장할 수 있어요. 자세한 내용은 이 가이드를 참고하세요.
초기 조회의 성능 측정
캐싱을 완전히 비활성화한 상태에서 다음 스니펫의 실행 시간을 측정했어요. 결과를 직접 검증하려면 이 노트북을 실행해 보세요.
prompt = langfuse.get_prompt("perf-test", cache_ttl_seconds=0)
prompt.compile(input="test")
Langfuse Cloud를 사용한 1000회 순차 실행 결과(네트워크 지연 포함):
count 1000.000000
mean 0.039335 sec
std 0.014172 sec
min 0.032702 sec
25% 0.035387 sec
50% 0.037030 sec
75% 0.041111 sec
99% 0.068914 sec
max 0.409609 sec