본문으로 건너뛰기
Ankole

Context 압축과 compaction

AI Agent용 안내: 이 페이지의 Markdown 버전은 https://ankole.agentbull.com/ko-KR/docs/context-compression-and-caching/index.md, 전체 문서 색인은 https://ankole.agentbull.com/ko-KR/llms.txt에 있습니다.

대화가 길어지면 언젠가는 모델의 컨텍스트 윈도우 한도에 부딪히게 됩니다. AIGateway는 실행 turn에 전달할 대화 히스토리를 자동으로 압축(compaction)하여 한도를 넘어선 뒤에도 대화가 끊기지 않고 이어지게 합니다. 이 문서에서는 ai_gateway/compaction*.ex의 실제 코드를 기준으로 이 압축 메커니즘을 설명합니다.

핵심 특성부터 짚어 두면, compaction은 설계상 세부 내역 일부를 줄이는 손실 압축이지만 암묵적으로 기록을 덮어쓰지 않고 명시적인 흔적을 남깁니다. 오래된 turn들을 구조화된 요약(summary)으로 대체하고 가장 최근 turn들은 원문 그대로 유지하며, 압축 결과 자체를 대화가 참조하는 영구 아티팩트로 기록합니다. 압축된 이전 turn 원문은 모델에 전달되는 컨텍스트에서 빠지고 요약본이 새로운 기준 상태(reference state)가 되므로, 일반적인 후속 호출은 이 체크포인트를 사용합니다. Ankole은 원본 기록 행을 보존하므로 provider 연결이 바뀌거나 /compress로 복구할 때 원본에서 로컬 체크포인트를 다시 만들 수 있습니다.

AIGateway 히스토리 컴팩션

상태 보존형(stateful) Responses 대화의 자동 히스토리 압축은 AIGateway가 전담하며, 발동 조건과 요약 생성 및 원문 보존 규칙은 모두 Ankole.AIGateway.Compaction에 구현되어 있습니다.

이하에서는 기본 방식인 로컬 압축을 설명합니다. ai_gateway.compaction.upstream을 true로 설정하면 지원되는 provider의 네이티브 압축을 사용하고 필요하면 로컬 처리로 폴백합니다. AIGateway를 참조하세요.

트리거

AIGateway는 가장 최근의 프로바이더 반환 usage 수치를 기준으로 새 입력, 도구 결과, 도구 정의와 지시문의 추가 토큰을 추정합니다. 이 합계를 임계값과 비교하고 증가량과 압축 효과에 따른 억제 규칙을 적용해 효과가 작은 압축의 연속 실행을 피합니다. 각 turn의 사용량 스냅샷을 더하지는 않습니다.

임계값과 보존 예산은 ai_gateway.compaction AppConfigure 키로 제어합니다.

설정 기본값 의미
threshold 0.90 compaction을 발동시키는 모델 입력 컨텍스트 대비 사용 비율
max_threshold_tokens 400,000 계산된 발동 기준의 절대 토큰 상한으로, 대용량 컨텍스트 모델에서도 지나치게 긴 이력이 쌓이지 않게 제한함
tail_rows 4 요약본과 함께 보존할 최근 기록 행 수의 기준
user_message_budget_tokens 20,000 압축 구간 안의 사용자 요청 원문을 그대로 다시 실어 주기 위한 토큰 예산

모델의 컨텍스트 길이를 알 수 없으면 256,000 토큰을 사용합니다. 요청한 출력 예산을 뺀 뒤 threshold를 적용하고 max_threshold_tokens로 상한을 둡니다. 64,000 토큰의 최솟값이 유효 컨텍스트 한도에 도달하면 그 한도의 small_context_trigger_ratio(0.85)에서 압축합니다.

토큰 사용량만이 발동 조건은 아닙니다. 암호화된 추론 내용과 인라인 이미지는 토큰당 바이트 수가 커서, 토큰 기준에 도달하기 훨씬 전에 기록이 커질 수 있습니다. 그래서 AIGateway는 저장된 대화 기록이 도구를 사용하는 응답 한 번이 담을 수 있는 양(항목 1,024개 또는 8 MiB)의 4분의 3에 이르렀을 때도 압축을 실행합니다. 이 크기 조건에는 설정 항목이 없습니다.

summarizer가 하는 일

로컬 압축을 수행할 때 AIGateway는 light 프로필(미설정 시 primary)을 호출해 이전 turn들의 구조화된 요약을 생성합니다. 이때 압축 프롬프트는 요약본을 이어갈 대화가 아닌 **기준 상태(reference state)**로 엄격히 규정하여 “대화를 이어 가지 말고, 질문에 답하지 말고, 구조화된 요약만 출력하라”고 지시합니다. 요약본에는 사용자의 원래 의도, 내려진 결정, 발생했던 오류와 해결 내역이 정리되며, 파일 경로·함수 이름·오류 메시지·명령줄·식별자(ID)는 문구를 바꾸면 참조가 깨지므로 원문 그대로 보존합니다.

AIGateway는 보존한 사용자 원문과 최근 기록에 요약을 함께 전달하며, 답변할 발화가 아니라 배경 상태로 제시합니다.

그대로 보존되는 것

요약본과 함께 다음 두 가지 원문 데이터가 그대로 유지됩니다.

  • 최근 기록 행(tail_rows, 기본값 4) — 보존 행 수의 기준이며, 도구 호출과 결과 쌍을 유지하고 컨텍스트 예산에 맞도록 조정합니다.
  • 사용자 메시지 원문 — CompactionRetention이 user_message_budget_tokens 안에서 텍스트를 다시 전달하며 필요하면 잘라 냅니다. 압축 대상 이미지 페이로드는 길이가 제한된 자리표시자로 바꾸고, 최근 보존 대상 이미지는 그대로 유지합니다.

이렇게 보존한 내용은 모델이 작업을 따라가는 데 도움이 되지만, 요약 과정에서 과거 작업의 세부 정보는 사라집니다.

Compaction 아티팩트

매 압축이 완료될 때마다 AIGateway는 영구 CompactionArtifact 레코드를 저장합니다. 이후 대화 히스토리는 가장 최근에 생성된 압축 아티팩트를 기준점(앵커)으로 가리키며 후속 turn을 이어 갑니다.

컴팩션과 콜드 복귀 세션 순환의 연계

ai_gateway.compaction과 sessions.wake_recycle은 캐시가 살아 있는 연속 대화와 캐시가 식은 뒤의 복귀 상황을 상호 보완적으로 처리합니다.

  • 캐시가 유지되는 활성 대화(ai_gateway.compaction): 상위 프로바이더의 프롬프트 캐시 유효 시간 안에 turn이 이어지는 동안 Ankole은 동일한 AIGateway 대화 체인을 계속 연장해 프리픽스 캐시 적중률을 높이고, 누적 컨텍스트가 threshold / max_threshold_tokens를 넘거나 저장된 기록이 위의 크기 조건에 이를 때만 컴팩션을 수행합니다.
  • 콜드 복귀(sessions.wake_recycle): min_cold_gap_seconds(기본값 3,600초) 이상 유휴 상태였고 누적 컨텍스트가 min_context_tokens(기본값 128,000 토큰) 이상인 Session이 재개되거나, 외부 IM 채널에서 im_max_idle_seconds(기본값 259,200초 / 72시간) 이상 유휴 후 다시 깨어날 때는 Ankole.Sessions.WakeRecycle이 전체 기록을 재전송하는 대신 기존 AIGateway 모델 대화를 닫고 최대 8,000 o200k_base 토큰 한도의 결정론적 <wake-briefing>이 주입된 후속 브랜치를 엽니다. 자세한 내용은 Sessions를 참조하세요.

튜닝

  • 에이전트가 비교적 짧은 대화 위주로 처리하는데 압축이 너무 일찍 자주 돈다면 threshold를 높이세요(기본값 0.90은 여유를 많이 둔 보수적 기준입니다).
  • 압축 직후 모델이 바로 직전 작업 맥락을 놓친다면 tail_rows를 늘리세요(원문으로 남는 최근 turn이 늘어나는 대신 요약에 쓸 수 있는 여유 공간은 줄어듭니다).
  • 대화가 길어졌을 때 초반에 사용자가 지시한 세부 요구 사항을 모델이 빠뜨린다면 user_message_budget_tokens를 늘리세요.

세 항목 모두 AppConfigure 키이므로 Console에서 실시간으로 변경할 수 있으며, 현재 진행 중인 turn이 아니라 다음 compaction 실행 시점부터 적용됩니다.

이 가이드가 다루지 않는 것

이 문서는 업스트림 프로바이더의 프롬프트 캐싱(prompt caching) 가이드를 다루지 않습니다. 프로바이더 측 프롬프트 캐싱은 업스트림 서비스의 영역이며, 이를 지원하는 프로바이더에서는 promptCacheKey 설정으로 제어합니다. 또한 무손실 아카이브 기능도 아니어서 압축된 이전 turn 원문은 모델 컨텍스트에서 제외됩니다. 마지막으로 작업 단위 분리를 대신할 수도 없습니다. compaction 덕분에 컨텍스트 한도를 넘겨 대화를 이어 갈 수는 있지만, 몇 턴마다 계속 압축이 반복될 만큼 비대해진 작업은 새 대화 세션으로 나누거나 Background Agent Job으로 위임하는 편이 훨씬 효율적입니다.

다음 단계

  • 전체 AIGateway 인터페이스와 상태 보존형 세션 구조는 AIGateway를 참조하세요.