[Agent] LLM 토큰 계측 신설 + prompt caching·대화 윈도우로 요청 본문 82% 감소 [ #343 ]

[Danto7632]

요약

LLM 토큰을 얼마나 쓰는지 아무도 몰랐다 — 응답의 usage 를 파싱·저장하는 코드가 저장소에 하나도 없었다(#343). 계측을 먼저 넣고, 그 위에서 줄였다.

실측 (목 서버로 나가는 실제 요청 본문 측정)

	값
8-2 CODE 10라운드 전송 96,290 B 중 다음 라운드에 캐시 접두로 들어가는 양	79,389 B (82.4%)
8-3 120턴 대화 요청 본문	41,571 → 7,131 B (82.8% 감소)
8-1 10라운드 usage 집계	목 응답 합계와 정확히 일치(172,000 토큰), DB 태스크 합산 쿼리도 검증

실제 LLM 키가 없어 실호출은 못 했다. 캐시 적중률 자체는 실키 환경에서 cache_read_input_tokens 로 확인해야 하고, 그 계측이 이번에 들어갔다.

8-1 저장 설계 — 신규 llm_usage 테이블(V63), 호출 한 건당 행 하나

agent_runs 누적 컬럼을 택하지 않은 이유 넷:

1. 배포 실패 분석은 태스크 없이 돈다 — NOT NULL FK 면 기록 자체가 불가
2. agent_runs 는 보존 스케줄러(Issue BF: [DB] 성능 U3 — 웹훅마다 projects 풀스캔, webhook_deliveries 무한 성장, 중복 인덱스 #338)가 지운다. 비용 이력이 함께 사라지면 "지난달 대비" 에 답할 수 없다
3. 호출 단위라야 라운드별 캐시 적중이 보인다. 누적 컬럼은 "캐싱이 실제로 사는가" 에 답하지 못한다
4. CODE 루프는 라운드마다 쓴다 — 누적 컬럼이면 워커도 쓰는 뜨거운 행을 40번 UPDATE 한다

FK 는 걸지 않았다(잠금 그래프 격리 + 2번).

귀속은 LlmPort 시그니처가 아니라 실행 스레드 스코프(LlmUsageScope)로 했다. 호출부가 전부 병렬 접촉 파일이고, 시그니처에 실으면 새 호출부가 빠뜨릴 수 있다. 스코프 없는 호출도 UNSCOPED 로 기록된다 — 귀속만 없고 합계에서 사라지지 않는다.

8-2 캐시가 실제로 사는 근거 — 접두가 고정이다

SYSTEM_PROMPT·TOOLS 가 static final 상수이고 트랜스크립트는 덧붙기만 한다. 이걸 추측하지 않고 테스트로 못박았다 — 5라운드 동안 tools+system+model 직렬화 바이트가 동일함, 그리고 라운드 N+1 의 앞부분이 라운드 N 과 cache_control 마커를 빼고 완전 일치함(append-only).

배치는 tools 마지막 1 + system 1 + 굴러가는 user 2 = 정확히 상한 4개.

⚠️ 알아둘 것: 지금 설정된 claude-opus-4-5-20251101 은 최소 캐시 접두가 4096 토큰이다. CODE 시스템 프롬프트는 4,280자(≈1.1K 토큰), Decision 은 14,848자(≈3.8K 토큰) — 둘 다 그 미만이라 system/tools 단독 지점은 캐시 항목을 만들지 못한다(오류도 과금도 없다). 실제로 값을 하는 것은 굴러가는 user 지점이고, 트랜스크립트가 4096 토큰을 넘는 2~3라운드째부터 시스템·도구까지 함께 캐시된다(더 긴 접두가 앞을 포함하므로). 최소 접두가 낮은 모델(512)로 설정을 바꾸면 코드 변경 없이 1라운드부터 적중한다.

8-3 윈도우로 잃는 것 (동작 변경)

최근 20턴 + 24,000자. 창 밖 앞부분을 에이전트가 못 본다 — 긴 대화에서 초반에만 나온 전제(예: "이 앱은 사내용")는 사용자가 다시 말해야 할 수 있다. 마지막 턴은 상한을 넘어도 남긴다(그것이 지금 처리할 요청).

getUserIntentHistory 는 표시를 먼저 붙이고 자른다 — 순서가 반대면 창 안 마지막 턴에 "[지금 처리할 요청]" 이 붙어 옛 요청이 새 요청으로 둔갑한다.

규칙은 새 클래스 ConversationWindow, 호출부는 AgentMessageService 한 곳만.

8-5 모델 고정 해제 · 되돌리는 법

배포 실패 분석이 ANTHROPIC + claude-opus-4-5 로 박혀 있었고 설정의 defaultProvider 는 GLM 이었다. 12,000자 로그를 한 번 요약하는 데 최상위 모델을 쓸 근거가 없다.

되돌리려면: qeploy.ai.failure-analysis.provider=ANTHROPIC, .model=claude-opus-4-5-20251101(또는 QEPLOY_AI_FAILURE_ANALYSIS_* 환경변수). 재배포 없이 설정만으로 복귀. 기본 동작과 되돌린 동작 양쪽을 테스트로 고정했다.

8-6 상한 초과 시 사용자가 보는 것

채팅에 TASK_FAILED 로 그대로 뜬다:

이 작업이 AI 토큰 예산 상한에 도달해 중단했습니다 (1,004,200 / 1,000,000 토큰). 요청을 더 작은 단위로 나눠 다시 시도하거나, 관리자에게 상한 조정을 요청해주세요.

catch-all 의 "작업 중 오류가 발생했습니다" 접두가 붙지 않도록 전용 분기를 뒀고, 빌드실패 복구(재시도) 경로로도 보내지 않는다. 누적은 llm_usage 에서 읽어 재시도를 건너 이어 세므로 재시도로 상한을 우회할 수 없다. 기본 1,000,000(0이면 끔).

계약·동작 변화

신규 설정 키 5개(ai.completion-max-tokens, ai.code-agent.max-task-tokens, ai.failure-analysis.provider/model, ai.anthropic.base-url), 신규 테이블 1개.

노출 API 스키마 변화 없음 — 다만 배포 실패 분석 응답의 provider/model 값이 ANTHROPIC/claude-opus-4-5 → GLM/z-ai/glm-4.6 으로 바뀐다. 새 실패 사유 문구 1종(토큰 상한).

검증

• 기준선 1488 전체 / 1476 통과 → 1534 전체 / 1522 통과 / 실패 0 / 스킵 12
• 3차 웨이브 5개 통합 후 1678 전체 / 1666 통과 / 실패 0
• Flyway V63, develop 최신 V62 확인 — 머지 직전 재확인 필요

안 한 것

1. LlmPort.complete 반환형 변경 — 호출부 6곳이 전부 병렬 접촉 파일. 스코프 방식이 충돌도 적고 누락 위험도 낮다
2. 요약으로 대화 접두 대체(8-3 대안) — 요약용 LLM 호출을 하나 더 늘리는 일이라 비용 작업에서 역행
3. Anthropic Java SDK 전환 — 이 저장소는 3개 제공자를 RestClient 원시 HTTP 공유 추상화로 다룬다. 범위 밖 대공사
4. llm_usage 보존 정책 — 지금 붙이면 비용 이력이 사라져 8-1 목적과 충돌. 증가량은 태스크당 수십 행. 후속 과제
5. cache_control TTL 1h — 기본 5분 유지. CODE 라운드 간격은 수초~수십초라 충분하고 1h 는 쓰기 프리미엄이 더 비싸다
6. 토큰 사용량 FE 노출 — api.md 계약 변경이라 별도 과제

Closes #343

https://claude.ai/code/session_01APAyBZVYxUZzZsVyEXy6Qr