SlidingWindowCompactor

SlidingWindowCompactor

SlidingWindowCompactor 는 에이전트의 지침과 현재 작업, 그리고 토큰 목표치가 허용하는 만큼의 최근 대화를 보존하면서 오래된 대화 기록을 제거하는 컴팩터예요. 완결된 과거 턴을 먼저 제거하고, 그걸로 부족할 때만 현재 작업의 Agent 스텝을 다듬어요.

출처: 문서

본문

실험적 기능: SlidingWindowCompactor 는 실험 단계라 예고 없이 바뀔 수 있어요. 컴팩션은 손실이 있는 동작이라, 이 전략으로 제거된 메시지는 복구되거나 요약되지 않아요.

CompactionHook이 이 컴팩터를 사용해요. 필수 초기화 변수는 없어요. 임포트 경로는 haystack.hooks.compaction.SlidingWindowCompactor 예요.

사용법 (Usage)

컴팩터를 CompactionHook 에 전달해요:

from haystack.hooks.compaction import CompactionHook, SlidingWindowCompactor

compaction_hook = CompactionHook(
    compactor=SlidingWindowCompactor(
        min_keep_steps=1,
        omission_note=(
            "[{num_removed} earlier messages were removed to free up context.]"
        ),
    ),
    context_window=200_000,
    compact_at=0.7,
    compact_to=0.4,
)

CompactionHook 은 컴팩션이 언제 실행될지 정하고 목표 토큰 수를 제공해요. SlidingWindowCompactor 는 어떤 메시지를 유지할지를 결정해요.

슬라이딩 윈도우는 어떻게 선택되나요?

컴팩터는 대화를 보호 컨텍스트, 과거 턴, 현재 작업의 Agent 스텝으로 나눠요:

  • 모든 앞쪽 시스템 메시지를 에이전트 지침으로 보존해요.
  • 가장 최근 사용자 메시지를 현재 작업으로 보존해요.
  • 그 작업 이전의 기록을 완결된 과거 턴으로 묶는데, 각 턴은 한 사용자 메시지에서 다음 메시지까지예요.
  • 각 어시스턴트 메시지와 그 직후의 모든 도구 결과 메시지를 하나의 완결된 Agent 스텝으로 묶어요.
  • 가장 최근 것부터 거꾸로, 목표치에 맞는 만큼 완결된 과거 턴을 유지해요.
  • 현재 작업만으로도 목표치를 넘을 때만 그 작업 자체의 스텝을 오래된 것부터 제거하기 시작해요.
  • 제거한 자리를 omission note로 대체해요(노트를 비활성화한 경우 제외).

완결된 스텝을 유지하는 것은 어시스턴트의 도구 호출이 병렬 도구 호출 배치를 포함해 그 결과와 분리되지 않게 하기 위함이에요. 불완전한 도구 호출 교환은 채팅 제공자들이 거부하기 때문이죠. 과거 턴도 같은 이유로 통째로 유지하거나 제거해요 — 어시스턴트 답변은 그에 답한 사용자 메시지 없이 남지 않아요.

목표치는 보장이 아니라 목표라서, 대화가 목표치보다 위에서 끝날 수도 있어요. 앞쪽 시스템 메시지와 현재 작업은 절대 제거되지 않고, min_keep_steps 는 크기와 무관하게 가장 최근 Agent 스텝을 붙잡아 두므로, 긴 시스템 프롬프트나 큰 단일 도구 결과 하나가 대화를 목표치를 훌쩍 넘게 만들 수 있어요.

설정 (Configuration)

파라미터 기본값 설명
min_keep_steps 1 목표치를 넘더라도 보존할 완결된 최근 Agent 스텝의 최소 개수. 0으로 설정하면 완결된 스텝을 모두 제거할 수 있어요.
omission_note "[{num_removed} earlier messages were removed from this conversation to free up context and cannot be recovered.]" 기록이 제거된 자리에 삽입되는 사용자 메시지. {num_removed} 로 제거된 메시지 수를 포함하거나, 플레이스홀더 없이 커스텀 텍스트를 주거나, None으로 설정해 조용히 제거할 수 있어요.

min_keep_steps 는 음수일 수 없어요.

Omission note

omission note는 모델에게 이전 컨텍스트가 빠져 있음을 알려줘요. 이게 없으면 줄어든 대화가 완전해 보여서, 모델이 작업을 반복하거나 제거된 정보를 여전히 가진 것처럼 행동할 수 있어요.

노트는 제거된 메시지가 있던 자리에 남아요: 과거 턴만 제거됐다면 앞쪽 시스템 메시지 바로 뒤에, 현재 작업 자체의 스텝이 제거됐다면 가장 최근 사용자 메시지 바로 뒤에 놓여요. 반복된 컴팩션은 이전 노트를 새 노트로 접어서(fold), 대화에 최대 하나만 남아요.

컴팩션 메타데이터는 노트에 저장돼요 — 전략 이름과 제거·유지된 메시지 수를 포함해서요.

대화가 바뀌지 않는 경우

다음 경우 컴팩터는 대화를 바꾸지 않고 None을 반환해요:

  • 대화가 이미 target_tokens 안에 들어맞는 경우
  • 보호 메시지 밖에 제거 가능한 기록이 없고, 유지한 기록이 남지 않는 경우

더 알아보기 (Learn more)