SummarizationCompactor

SummarizationCompactor

SummarizationCompactor 는 오래된 대화 턴과 Agent 스텝을 LLM이 생성한 요약으로 점진적으로 대체해 에이전트의 컨텍스트를 줄여 주는 컴팩터예요. 내용을 그냥 버리는 전략과 달리, 이전의 목표·결정·완료된 작업·식별자·미완료 작업에 대한 압축 요약을 보존해요.

출처: 문서

본문

실험적 기능: SummarizationCompactor 는 실험 단계라 예고 없이 바뀔 수 있어요. 요약은 손실이 있으며, 품질은 설정한 Chat Generator와 지침에 따라 달라져요.

CompactionHook이 이 컴팩터를 사용해요. 필수 초기화 변수는 chat_generator(대화 요약을 작성하는 Chat Generator)예요. 임포트 경로는 haystack.hooks.compaction.SummarizationCompactor 예요.

사용법 (Usage)

요약 전용 Chat Generator를 별도로 만들고 컴팩터를 CompactionHook 에 전달해요:

from haystack.components.generators.chat import OpenAIResponsesChatGenerator
from haystack.hooks.compaction import CompactionHook, SummarizationCompactor

summary_generator = OpenAIResponsesChatGenerator(model="gpt-5.4-nano")

compaction_hook = CompactionHook(
    compactor=SummarizationCompactor(
        chat_generator=summary_generator,
        min_keep_steps=2,
        approximate_summary_tokens=1_024,
    ),
    context_window=400_000,
    compact_at=0.7,
    compact_to=0.4,
)

compaction_hook 를 Agent의 before_llm 훅 포인트에 등록하세요. CompactionHook 은 언제 컴팩션할지 정하고 context_window 와 compact_to 에서 목표치를 도출해요. SummarizationCompactor 는 대화의 어느 부분을 요약할지를 결정해요.

점진적 요약은 어떻게 동작하나요?

컴팩터는 대화를 두 영역으로 나눠요:

  • 기록(History): 앞쪽 시스템 메시지 이후 시작해 가장 최근 실제 사용자 메시지 앞에서 끝나요.
  • 현재 작업(Current task): 가장 최근 실제 사용자 메시지로 시작해 끝까지 이어져요.

항상 현재 작업 이전의 기록을 먼저 소모해요. 각 라운드는 아래 계층 중 먼저 적용되는 것을 사용해, 목표치에 도달하는 만큼의 가장 오래된 내용만 선택해요:

  1. 과거 턴: 완결된 과거 사용자 턴부터, 오래된 것부터 요약해요.
  2. 과거 요약: 완결된 과거 턴이 남지 않으면, 가장 오래된 과거 요약들을 결합해요. 모델 호출이 요약 하나를 그냥 다시 쓰는 일이 없도록 최소 두 개를 선택해요.
  3. 현재 작업 스텝: min_keep_steps 개의 최신 스텝을 보존하면서 가장 오래된 적격 Agent 스텝을 요약해요. Agent 스텝은 어시스턴트 메시지와 그 직후의 모든 도구 결과를 포함해요.
  4. 현재 작업 요약: 더 요약할 스텝이 없으면, 현재 작업을 위해 이미 만든 가장 오래된 요약들을 결합해요.

각 성공적인 모델 호출 후 결과 요약이 선택된 메시지를 대체해요. 측정된 대화가 여전히 목표치보다 크면 다음 라운드를 계획해요. 앞쪽 시스템 메시지와 가장 최근 사용자 메시지는 항상 유지돼요.

요약 프롬프트 (Summary prompt)

기본 지침은 모델에게 다음을 위한 간결한 섹션을 만들도록 요청해요:

  • 목표 (Objective)
  • 결정과 제약 (Decisions and constraints)
  • 완료된 작업 (Work completed)
  • 식별자 (Identifiers)
  • 미완료 작업 (Unresolved work)

대체 중인 메시지만 요약 생성기에 보내져요. 가장 최근 요청과 그 밖에 유지된 메시지는 대화에 남지만 그 모델 호출에는 포함되지 않아요. 예를 들어 이전 요약, 첨부, 도구 상호작용을 포함한 선택 부분은 다음과 같이 렌더링돼요:

[conversation_summary]The user asked for an analysis of the Q3 report. The report was downloaded but has not yet been reviewed.[user] Review the report and compare it with this chart.[user] [assistant -> tool_call id=call_1] web_search({"query": "Q3 industry benchmarks"})[tool:web_search id=call_1] Saved the benchmark chart:

기존 요약은 라벨이 붙어서 모델이 새 정보와 병합할 수 있고, 일치하는 ID가 도구 호출과 그 결과를 연결해요. 첨부 내용은 요약 생성기에 보내지지 않으며 컴팩션 후 복구할 수 없어요. 첨부의 식별 세부 정보만 <> 와 <> 플레이스홀더에 나타나요.

summary_instruction 을 설정하면 기본 지침을 완전히 대체할 수 있어요:

compactor = SummarizationCompactor(
    chat_generator=summary_generator,
    summary_instruction=(
        "Write a concise project handoff. Preserve decisions, file paths, commands, errors, and remaining work."
    ),
)

커스텀 지침은 더 짧은 결과를 명시적으로 요청하도록 만드세요. 컴팩터는 선택된 메시지를 그 요약으로 대체해도 측정된 대화 크기가 줄어들지 않으면 생성된 요약을 거부해요.

설정 (Configuration)

파라미터 기본값 설명
chat_generator 기본값 없음 요약을 작성하는 Chat Generator. 생성 설정은 이 객체에서 구성해요.
min_keep_steps 1 보존할 완결된 최근 Agent 스텝의 최소 개수. 유지하면 추가 컴팩션이 막히더라도 보존해요. 0 으로 설정하면 모든 완결 스텝이 적격이 돼요.
approximate_summary_tokens 1024 생성될 요약의 예상 크기. 계획 추정치이지 모델 출력 제한이 아니에요. 높을수록 라운드당 더 많은 컨텍스트를 선택하고, 낮을수록 컨텍스트를 더 유지하지만 라운드가 더 필요할 수 있어요.
summary_instruction 구조화된 기본 지침 요약 생성기에 보내는 전체 시스템 지침. 기본값에 덧붙이는 게 아니라 그걸 대체해요.
raise_on_failure False 요약 생성·검증 실패를 로그로 남기고 마지막 성공 컴팩션을 보존하는 대신, 예외를 던질지 여부.

min_keep_steps 는 음수일 수 없고, approximate_summary_tokens 는 양수여야 해요.

실패와 부분 진행 (Failures and partial progress)

요약 라운드는 Chat Generator가 예외를 던지거나, 쓸 만한 텍스트를 반환하지 않거나, 측정된 대화를 더 작게 만들지 않는 요약을 만들 때 실패해요.

기본적으로 컴팩터는 실패를 로그로 남기고 멈춰요. 이전 라운드가 성공했다면 그 부분적으로 컴팩션된 대화를 반환하고, 성공한 라운드가 없다면 None 을 반환해 입력 대화를 그대로 둬요. 호출하는 애플리케이션이 대신 오류를 처리해야 할 때 raise_on_failure=True 로 설정하세요.

컴팩터는 동기·비동기 컴팩션을 모두 구현해요. compact_async() 는 Chat Generator의 비동기 실행 경로를 사용해서, 비동기 Agent 실행이 동기 요약 생성으로 블로킹되지 않아요. 웜업과 종료 연산도 요약 생성기가 구현하면 위임돼요.

컴팩션 메타데이터 (Compaction metadata)

생성된 모든 요약은 <> 태그로 감싼 사용자 메시지예요. 그 context_compaction 메타데이터는 다음을 기록해요:

  • strategy: "summarization"
  • summarized_messages: 그 요약이 직접 대체한 메시지 수

컴팩션 하한 (Compaction floor)

이 전략이 만들 수 있는 가장 작은 대화는 다음을 포함해요:

  • 앞쪽 시스템 메시지
  • 최대 하나의 과거 요약
  • 가장 최근 사용자 메시지
  • 최대 하나의 현재 작업 요약
  • min_keep_steps 개의 최신 Agent 스텝

이 보호 컨텍스트만 남으면 컴팩터는 대화를 더 줄일 수 없어요. 이 하한에서의 컴팩션 호출은 None 을 반환해요.

더 알아보기 (Learn more)