Day 20: Cost Guardrail — 비용 폭주를 막는 세 겹의 방어선

LLM API 비용은 호출 횟수 × 토큰 수 × 단가로 결정돼요. 이 세 변수 중 하나라도 통제를 놓치면 비용이 기하급수적으로 올라갑니다. 오늘 배울 세 겹의 방어선은 각각 이 세 변수를 하나씩 잡아요.

LLM 비용의 구조

카페를 생각해 볼게요. 커피 한 잔의 비용은 "주문 횟수 × 잔당 재료비 × 원두 단가"로 결정되죠.

LLM도 동일해요.

Day 19 Harness와의 연결

지난 시간에 만든 advisor chain에 오늘의 Cost Guardrail advisor들을 끼워 넣으면 전체 그림이 완성돼요.

바깥에서 안쪽으로 갈수록 "비용이 비싼 동작"에 가까워져요. Rate Limit에서 걸리면 LLM 호출 자체가 일어나지 않으니 비용 0원이에요. 캐시에서 걸리면 역시 LLM 호출 없이 응답이 나가요. 이 순서가 비용 효율의 핵심이에요.

💡 핵심 감각

세 겹의 방어선은 겹쳐야 의미가 있어요. Rate Limit만 걸면 같은 질문을 매번 LLM에 보내는 낭비를 못 잡고, 캐싱만 하면 새로운 질문의 폭주를 못 잡아요. "호출 차단 → 중복 절감 → 토큰 절감" 세 축이 동시에 움직여야 비용이 통제됩니다.

첫 번째 방어선이에요. 클라이언트별로 "분당 N회"를 넘기면 LLM 호출 자체를 차단합니다. Bucket4j 라이브러리의 토큰 버킷 알고리즘으로 구현해요.

토큰 버킷 알고리즘

양동이에 토큰이 N개 들어 있다고 생각해 보세요. API 호출이 들어올 때마다 토큰을 하나 꺼내요. 양동이가 비면 "잠시 후 다시 시도해 주세요"라고 거절합니다. 시간이 지나면 토큰이 자동으로 채워져요.

이게 토큰 버킷(Token Bucket) 알고리즘이에요. Nginx나 AWS API Gateway에서도 동일한 원리를 사용합니다.

RateLimitAdvisor 구현

// kr.spartaclub.aifriends.harness.cost.RateLimitAdvisor
public class RateLimitAdvisor implements BaseAdvisor {

    private final long capacity;
    private final Duration refillDuration;
    private final Map<String, Bucket> buckets = new ConcurrentHashMap<>();

    public RateLimitAdvisor(long capacity, Duration refillDuration) {
        this.capacity = capacity;
        this.refillDuration = refillDuration;
    }

    @Override
    public ChatClientRequest before(ChatClientRequest request, AdvisorChain advisorChain) {
        String clientKey = resolveClientKey(request);
        Bucket bucket = buckets.computeIfAbsent(clientKey, k -> createBucket());
        ConsumptionProbe probe = bucket.tryConsumeAndReturnRemaining(1);

        if (!probe.isConsumed()) {
            long retryAfterMillis = probe.getNanosToWaitForRefill() / 1_000_000;
            throw new RateLimitExceededException(clientKey, retryAfterMillis);
        }
        return request;
    }
}

핵심 동작을 하나씩 보면요.

ConcurrentHashMap<String, Bucket> — 클라이언트별로 독립된 양동이를 관리해요. user-1의 양동이가 비어도 user-2는 영향 없이 호출할 수 있어요.

resolveClientKey() — 요청의 context에서 conversationId를 꺼내 클라이언트 키로 사용해요. 없으면 "global"로 폴백합니다.

private String resolveClientKey(ChatClientRequest request) {
    Map<String, Object> context = request.context();
    if (context != null && context.containsKey("conversationId")) {
        return String.valueOf(context.get("conversationId"));
    }
    return "global";
}

tryConsumeAndReturnRemaining(1) — 토큰 1개를 소비하려고 시도해요. 성공하면 남은 토큰 수가, 실패하면 "다음 토큰이 채워지기까지 남은 시간"이 반환됩니다.

createBucket() — Bucket4j API로 양동이를 생성해요.

private Bucket createBucket() {
    return Bucket.builder()
            .addLimit(Bandwidth.simple(capacity, refillDuration))
            .build();
}

Bandwidth.simple(30, Duration.ofMinutes(1))이면 "1분에 30개 토큰이 채워지는 양동이"가 만들어져요.

RateLimitExceededException

한도를 넘기면 던지는 예외예요. retryAfterMillis를 포함해서, 클라이언트에게 "몇 밀리초 후에 다시 시도하면 되는지" 알려줄 수 있어요.

// kr.spartaclub.aifriends.harness.exception.RateLimitExceededException
public class RateLimitExceededException extends RuntimeException {

    private final String clientKey;
    private final long retryAfterMillis;

    public RateLimitExceededException(String clientKey, long retryAfterMillis) {
        super("호출 한도를 초과했습니다. clientKey=%s, retryAfter=%dms"
                .formatted(clientKey, retryAfterMillis));
        this.clientKey = clientKey;
        this.retryAfterMillis = retryAfterMillis;
    }
}

GlobalExceptionHandler에서 이 예외를 잡아 HTTP 429 응답으로 변환하면, 프론트엔드가 "잠시 후 다시 시도해 주세요" 메시지를 보여줄 수 있어요.

order가 HIGHEST_PRECEDENCE + 1인 이유

Rate Limit은 모든 advisor 중 가장 바깥에 있어야 해요. 한도를 넘은 요청이 캐시 조회나 LLM 호출까지 도달하면 안 되니까요. "문 앞에서 먼저 걸러내는" 역할이에요.

두 번째 방어선이에요. 같은 프롬프트가 반복되면 LLM을 호출하지 않고 캐시에서 꺼내요. Rate Limit을 통과한 요청 중에서도 중복을 한 번 더 걸러내는 역할이에요.

왜 LLM 응답을 캐싱하나

ai-friends를 생각해 보세요. 플레이어가 채팅방에 들어갈 때마다 "이 캐릭터는 어떤 성격이야?"라는 시스템 프롬프트가 매번 날아가요. 캐릭터 설정이 바뀌지 않았다면, 이 응답은 캐싱해도 문제없어요.

검색 엔진의 캐시를 떠올리면 쉬워요. 같은 검색어를 1분 안에 두 번 입력하면, 두 번째는 DB를 다시 조회하지 않고 캐시에서 꺼내죠. LLM 응답도 동일한 원리예요.

ResponseCacheAdvisor 핵심 구조

// kr.spartaclub.aifriends.harness.cost.ResponseCacheAdvisor
public class ResponseCacheAdvisor implements BaseAdvisor {

    static final String CACHE_KEY_CONTEXT = "responseCacheKey";
    private final Map<String, ChatClientResponse> cache = new ConcurrentHashMap<>();

    @Override
    public ChatClientRequest before(ChatClientRequest request, AdvisorChain advisorChain) {
        String cacheKey = generateCacheKey(request);

        ChatClientResponse cached = cache.get(cacheKey);
        if (cached != null) {
            throw new CacheHitException(cached);
        }

        return request.mutate()
                .context(CACHE_KEY_CONTEXT, cacheKey)
                .build();
    }

    @Override
    public ChatClientResponse after(ChatClientResponse response, AdvisorChain advisorChain) {
        Map<String, Object> context = response.context();
        if (context != null && context.containsKey(CACHE_KEY_CONTEXT)) {
            String cacheKey = String.valueOf(context.get(CACHE_KEY_CONTEXT));
            cache.put(cacheKey, response);
        }
        return response;
    }
}

동작을 따라가 볼게요.

before 훅 (캐시 조회) — 요청의 프롬프트를 SHA-256 해시로 변환해 캐시 키를 만들어요. 캐시에 있으면 CacheHitException을 던져서 advisor chain을 더 타지 않고 즉시 캐시된 응답을 반환해요. 캐시에 없으면 context에 캐시 키를 심어서 다음 단계로 넘겨요.

after 훅 (캐시 저장) — LLM 호출이 끝나고 돌아온 응답을 context에서 꺼낸 캐시 키로 저장해요. 다음에 같은 프롬프트가 오면 before에서 바로 히트됩니다.

캐시 키 설계

String generateCacheKey(ChatClientRequest request) {
    StringBuilder sb = new StringBuilder();
    if (request.prompt() != null && request.prompt().getInstructions() != null) {
        for (Message msg : request.prompt().getInstructions()) {
            sb.append(msg.getText());
        }
    }
    return sha256(sb.toString());
}

프롬프트의 모든 메시지 텍스트를 이어붙인 뒤 SHA-256 해시의 앞 16자를 키로 사용해요. 동일한 텍스트면 항상 같은 키가 나오고, 한 글자만 달라도 완전히 다른 키가 됩니다.

💡 프로덕션에서는 Spring Cache + Redis로

지금은 학습용 ConcurrentHashMap이에요. 프로덕션에서는 @Cacheable + RedisCacheManager로 교체하면 서버 간 캐시 공유 + TTL 자동 만료가 됩니다. 도전 과제에서 직접 전환해 볼 수 있어요.

세 번째 방어선이에요. 앞의 두 방어선이 "호출 자체를 줄이는" 전략이었다면, 컨텍스트 캐싱은 호출은 하되 토큰 비용을 줄이는 전략이에요.

왜 컨텍스트 캐싱이 필요한가

ai-friends의 채팅을 생각해 보세요. 매 호출마다 시스템 프롬프트가 함께 전송돼요. 캐릭터 설정, 호감도 규칙, 응답 형식 가이드 — 이게 수백에서 수천 토큰이에요. 사용자 메시지는 "오늘 뭐 했어?" 한 줄인데, 시스템 프롬프트는 매번 동일한 수천 토큰이 반복 전송됩니다.

컨텍스트 캐싱은 이 반복 전송되는 시스템 프롬프트를 프로바이더 서버 측에서 캐싱해서, 두 번째 호출부터는 "이미 보낸 프롬프트입니다"라고 ID만 보내는 거예요. 읽기 비용이 쓰기 비용보다 훨씬 싸서, 호출이 반복될수록 절감 효과가 커져요.

Gemini Context Caching

Gemini 2.5 이상 모델은 암시적 캐싱(implicit caching)이 기본 활성화돼 있어요. 별도 코드 없이도 프로바이더가 자동으로 반복 컨텍스트를 인식해서 캐싱합니다.

# application.yml — Gemini 프로파일
spring:
  ai:
    openai:
      chat:
        options:
          model: ${GEMINI_MODEL:gemini-2.5-flash-lite}

Gemini의 암시적 캐싱은 Spring AI에서 특별한 설정 없이 동작해요. Usage 메타데이터의 cachedContentTokenCount 필드를 확인하면 "이번 호출에서 캐싱된 토큰이 몇 개인지" 볼 수 있습니다.

Anthropic Prompt Caching

Anthropic은 명시적 캐싱을 지원해요. 캐시 breakpoint를 지정해서 "여기까지는 캐싱해 주세요"라고 요청합니다. Spring AI 1.1에서 네이티브로 지원해요.

캐시 breakpoint는 최대 4개까지 설정할 수 있고, 기본 TTL은 5분이에요. 장기 캐싱이 필요하면 1시간까지 늘릴 수 있어요.

전략 선택이 중요해요.

ai-friends처럼 시스템 프롬프트가 고정이고 대화가 길어지는 앱에서는 system-only 전략이 가장 효과적이에요.

💡 비용 감각

시스템 프롬프트 2,000토큰 × 일 1,000회 호출 = 일 200만 토큰. 컨텍스트 캐싱으로 읽기 비용이 75% 절감되면 일 150만 토큰을 아낄 수 있어요. 월로 환산하면 상당한 금액이 됩니다.

LLM API 호출이 실패했을 때 재시도하면 비용이 2배가 돼요. 3번 재시도하면 3배. Resilience4j의 지수 백오프로 재시도 횟수와 간격을 제어해서, 장애 상황에서도 비용 폭주를 막아요.

재시도의 비용 함정

네트워크 순간 장애로 LLM 호출이 실패했어요. 바로 재시도하면 높은 확률로 또 실패해요. 서버가 과부하 상태라면 재시도 요청이 오히려 부하를 가중시키고, 결국 모든 요청이 실패하는 썬더링 허드(Thundering Herd) 현상이 벌어져요.

지수 백오프(Exponential Backoff)는 재시도 간격을 점점 늘려서 서버가 회복할 시간을 확보해요.

RetryableAdvisor

// kr.spartaclub.aifriends.harness.cost.RetryableAdvisor
public class RetryableAdvisor implements BaseAdvisor {

    private final int maxRetries;
    private final Duration initialBackoff;
    private final double backoffMultiplier;

    public Duration calculateBackoff(int attempt) {
        if (attempt <= 0) {
            return initialBackoff;
        }
        long millis = (long) (initialBackoff.toMillis() * Math.pow(backoffMultiplier, attempt));
        long capped = Math.min(millis, Duration.ofMinutes(1).toMillis());
        return Duration.ofMillis(capped);
    }
}

calculateBackoff()가 핵심이에요. initialBackoff=500ms, backoffMultiplier=2.0이면 이런 계산이 돼요.

maxRetries=3이면 최대 4회 호출(첫 시도 + 재시도 3)로 비용이 제한돼요. 상한은 1분으로 cap 해서 과도하게 긴 대기를 방지합니다.

Resilience4j application.yml 설정

Resilience4j는 어노테이션 기반으로 서비스 메서드에 적용할 수도 있어요.

# application.yml
resilience4j:
  retry:
    instances:
      llm-call:
        max-attempts: 4
        wait-duration: 500ms
        enable-exponential-backoff: true
        exponential-backoff-multiplier: 2.0
  circuitbreaker:
    instances:
      llm-call:
        failure-rate-threshold: 50
        slow-call-duration-threshold: 10s
        sliding-window-size: 10

Circuit Breaker는 연속 실패율이 50%를 넘으면 일정 시간 동안 요청 자체를 차단해요. "서버가 죽어 있는데 계속 요청을 보내는" 무의미한 과금을 막는 거예요.

💡 재시도 = 비용 × 횟수

재시도 정책을 설계할 때 "최악의 경우 비용이 몇 배가 되는가"를 항상 계산해야 해요. maxRetries=3이면 최악 4배, maxRetries=5면 6배예요. Rate Limit과 조합하면 "분당 30회 × 최대 4배 = 분당 최대 120회 LLM 호출"이 상한이 됩니다.

세 겹의 방어선(Rate Limit + 캐싱 + 재시도)을 하나의 설정 클래스로 조립해요. Day 19의 HarnessAdvisorChainConfig와 같은 패턴으로, application.yml 한 장에 비용 한도를 모아서 관리합니다.

CostGuardrailProperties — 설정 외부화

// kr.spartaclub.aifriends.harness.cost.CostGuardrailProperties
@ConfigurationProperties(prefix = "ai-friends.cost-guardrail")
public class CostGuardrailProperties {

    private long rateLimitCapacity = 30;
    private Duration rateLimitDuration = Duration.ofMinutes(1);
    private int maxRetries = 3;
    private Duration retryInitialBackoff = Duration.ofMillis(500);
    private double retryBackoffMultiplier = 2.0;
    private boolean cacheEnabled = true;
}

Day 19에서 HarnessProperties를 만들 때와 동일한 패턴이에요. application.yml에서 이렇게 설정합니다.

ai-friends:
  cost-guardrail:
    rate-limit-capacity: 30
    rate-limit-duration: 1m
    max-retries: 3
    retry-initial-backoff: 500ms
    retry-backoff-multiplier: 2.0
    cache-enabled: true

운영 환경에서는 application-prod.yml에 더 엄격한 값을, application-dev.yml에 느슨한 값을 넣으면 프로파일별로 비용 정책을 분리할 수 있어요.

CostGuardrailConfig — 조립 팩토리

// kr.spartaclub.aifriends.harness.cost.CostGuardrailConfig
@Configuration
@EnableConfigurationProperties(CostGuardrailProperties.class)
public class CostGuardrailConfig {

    public List<Advisor> costGuardrailAdvisors(CostGuardrailProperties props) {
        props.validate();

        List<Advisor> advisors = new ArrayList<>();
        advisors.add(new RateLimitAdvisor(
                props.getRateLimitCapacity(),
                props.getRateLimitDuration()
        ));
        if (props.isCacheEnabled()) {
            advisors.add(new ResponseCacheAdvisor());
        }
        advisors.add(new RetryableAdvisor(
                props.getMaxRetries(),
                props.getRetryInitialBackoff(),
                props.getRetryBackoffMultiplier()
        ));
        return List.copyOf(advisors);
    }
}

세 가지 포인트가 있어요.

props.validate() — advisor를 생성하기 전에 설정값이 올바른지 검증해요. rateLimitCapacity가 0이면 IllegalArgumentException을 던져서 서버 기동 시점에 빠르게 실패합니다.

cacheEnabled 토글 — 캐싱을 끄고 싶을 때 yml 한 줄만 바꾸면 돼요. 코드 수정 없이 동작을 제어할 수 있습니다.

List.copyOf() — 불변 리스트를 반환해서 외부에서 advisor 목록을 조작할 수 없게 해요.

전체 advisor chain 조립

Day 19의 4가드와 오늘의 Cost Guardrail을 합치면 이런 코드가 됩니다.

List<Advisor> guards = harnessConfig.guardAdvisors(harnessProps);
List<Advisor> costGuards = costConfig.costGuardrailAdvisors(costProps);

ChatClient client = builder
        .defaultAdvisors(costGuards.toArray(Advisor[]::new))
        .defaultAdvisors(guards.toArray(Advisor[]::new))
        .defaultAdvisors(filter, tracker)
        .build();

defaultAdvisors를 세 번 호출하고 있어요. Spring AI의 ChatClient.Builder는 호출할 때마다 advisor가 누적되고, order 값 순서대로 chain이 형성됩니다.

세 겹의 방어선을 ai-friends에 실제로 적용해요. 핵심은 캐릭터 대화와 지식 검색(RAG)의 비용 정책이 달라야 한다는 점이에요.

왜 차별 정책이 필요한가

캐릭터 대화는 temperature가 높고 매번 새로운 맥락이 추가되니까 캐시 히트율이 낮아요. 대신 사용자가 자연스럽게 대화하려면 Rate Limit을 너무 엄격하게 걸면 안 돼요.

반면 지식 검색은 "이 캐릭터의 생일이 언제야?"처럼 정해진 답이 있는 질문이 많아서 캐시 히트율이 높아요. 이쪽에 캐싱을 집중하면 비용 절감 효과가 커요.

프로파일별 설정 분리

# application-chat.yml — 캐릭터 대화 프로파일
ai-friends:
  cost-guardrail:
    rate-limit-capacity: 60
    rate-limit-duration: 1m
    cache-enabled: false
    max-retries: 2

# application-rag.yml — 지식 검색 프로파일
ai-friends:
  cost-guardrail:
    rate-limit-capacity: 20
    rate-limit-duration: 1m
    cache-enabled: true
    max-retries: 3

대화용은 분당 60회, 캐싱 꺼짐, 재시도 2회. 지식 검색용은 분당 20회, 캐싱 켜짐, 재시도 3회. 같은 CostGuardrailConfig 코드로 두 가지 정책을 만들 수 있어요.

Before/After — Day 19 vs Day 20

Day 19에서는 "에이전트가 한 사이클에서 토큰을 얼마나 쓰는지"만 관리했어요. Day 20을 거치면 "클라이언트별 호출 횟수, 중복 요청, 재시도 비용"까지 통제 범위가 확장됩니다.

💡 인프라 추가는 최소한으로

Redis 하나를 추가했을 뿐인데, Rate Limit과 응답 캐싱 두 가지 역할을 동시에 수행해요. 새 인프라를 도입할 때는 "이미 있는 걸 재활용할 수 없나?"를 먼저 따져보는 습관이 중요합니다.

오늘 만든 세 겹의 방어선에는 각각 트레이드오프가 있어요. 면접에서 "Cost Guardrail을 어떻게 설계하셨나요?"라는 질문에 이 5가지를 언급할 수 있으면, 프로덕션 경험이 드러납니다.

트레이드오프 5종

1. Rate Limit 엄격도 vs 사용자 경험

분당 10회로 걸면 비용은 확실히 통제되지만, 사용자가 조금만 활발하게 대화하면 금방 한도에 걸려요. 분당 100회로 풀면 사용자 경험은 좋지만, 한 사용자가 예산을 독차지할 수 있어요. Step 7에서 봤듯이 "대화는 느슨, 검색은 엄격"처럼 시나리오별 차등 적용이 현실적이에요.

2. 캐시 히트율 vs 응답 신선도

TTL을 길게 잡으면 히트율이 올라가지만, 캐릭터 설정이 바뀌었을 때 오래된 응답이 나갈 수 있어요. TTL을 짧게 잡으면 신선도는 보장되지만 히트율이 떨어져요. "설정이 자주 바뀌는 데이터는 짧게, 고정 지식은 길게" — 이 기준으로 TTL을 분리하세요.

3. 컨텍스트 캐싱 절감 vs 캐시 비용

Gemini의 컨텍스트 캐싱도 무료가 아니에요. 쓰기 비용($0.50/M 토큰)이 있고, 읽기 비용($0.20/M 토큰)이 별도예요. 호출 횟수가 적으면 캐시 쓰기 비용이 오히려 비용을 늘릴 수 있어요. "시스템 프롬프트가 길고, 호출이 빈번한" 시나리오에서만 효과적이에요.

4. 재시도 횟수 vs 장애 복구 시간

maxRetries=3이면 장애 시 최대 약 7초(500 + 1000 + 2000 + 실제 호출 시간)가 걸려요. 사용자는 7초를 기다린 끝에 실패 응답을 받을 수 있어요. 재시도를 1회로 줄이면 빠르게 실패하지만, 순간 장애를 넘길 기회를 잃어요.

5. 인메모리 vs 분산 저장소

지금은 ConcurrentHashMap으로 인메모리에 관리하고 있어요. 서버 1대로 충분한 학습 환경에서는 이게 가장 간단해요. 서버가 2대 이상이 되면 Redis ProxyManager로 전환해야 양동이 상태가 공유돼요. "지금 서버가 몇 대인가"가 결정 기준이에요.

Day 21로 이어지는 다리

오늘 비용을 제어하는 방어선을 완성했어요. Rate Limit으로 호출을 잡고, 캐싱으로 중복을 잡고, 재시도 제어로 장애 비용을 잡았어요.

다음 시간은 Agent Client + Agent Bench예요. Day 14에서 MaxIterationsAdvisor, DurationTimeoutAdvisor, UsageBudgetAdvisor, ToolInvocationCounterAdvisor를 손으로 구현했던 거 기억나시죠? Day 21에서는 Spring AI Agent Client가 이 4가드를 선언 한 줄로 처리하는 모습을 체감하게 돼요.

그리고 Agent Bench로 "캐릭터가 설정을 위반하지 않는지, 호감도 규칙이 정확한지"를 배포 전에 자동으로 검증하는 회귀 테스트 시나리오를 작성해요.

안녕하세요, 홍순구 튜터입니다.

오늘 Day 20에서 한 일을 정리해 볼게요.

Day 19에서 Harness 6구성요소의 껍데기를 만들었고, 오늘 5번 Cost Guardrail을 실체로 채웠어요. Harness 6구성요소 중 5.5개가 코드로 존재하는 상태예요. (0.5는 Observability Hook — Day 19에서 인메모리 추적까지 만들었고, Day 22에서 Micrometer 영속 메트릭으로 확장할 예정이에요.)