ToolResultPruningCompactor

ToolResultPruningCompactor

ToolResultPruningCompactor 는 오래된 도구 결과를 짧은 플레이스홀더로 대체해 에이전트의 컨텍스트를 줄이는 컴팩터예요. 모든 도구 호출을 결과와 쌍으로 유지해서, 모델이 어떤 도구를 호출했는지 보고 필요하면 다시 호출할 수 있게 해요.

출처: 문서

본문

실험적 기능: ToolResultPruningCompactor 는 실험 단계라 예고 없이 바뀔 수 있어요. 프루닝은 손실이 있어서, 제거된 도구 출력은 별도로 저장하지 않는 한 복구할 수 없어요.

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

사용법 (Usage)

컴팩터를 CompactionHook 에 전달해요:

from haystack.hooks.compaction import CompactionHook, ToolResultPruningCompactor

compaction_hook = CompactionHook(
    compactor=ToolResultPruningCompactor(
        min_keep_steps=1,
        min_tokens=200,
    ),
    context_window=200_000,
    compact_at=0.7,
    compact_to=0.4,
)

CompactionHook 은 컴팩션이 언제 실행될지 정하고 목표 토큰 수를 제공해요. ToolResultPruningCompactor 는 목표에 도달하는 데 필요한 만큼의 적격 결과만 대체해요.

프루닝은 어떻게 동작하나요?

컴팩터는 도구 결과를 가장 오래된 것부터 처리해요:

  • 이미 목표치 안에 들면 대화를 바꾸지 않아요.
  • 설정된 수의 최근 도구 호출 Agent 스텝의 결과를 보호해요. 최소 하나의 스텝은 유지해야 하므로, 모델이 그 결과를 처리하기 전까지 현재 결과 배치는 온전하게 남아요.
  • 컨텍스트 컴팩션이 이미 표시한 결과, 토큰 임계값 아래의 결과, 그리고 오프로드된 결과 참조 같은 보호 메타데이터를 실은 결과는 건너뛰어요.
  • 예상 대화 크기가 목표에 도달할 때까지 적격 결과를 설정된 플레이스홀더로 대체해요.

대체는 원래 도구 호출, 오류 플래그, 메시지 메타데이터를 보존해요. 이렇게 하면 비싼 결과 콘텐츠를 버리면서도 채팅 제공자가 수용하는 도구 호출 교환을 유지할 수 있어요.

목표치는 보장이 아니라 목표예요. 보호된 최근 결과와 프루닝 규칙을 충족하지 못하는 결과가 대화를 요청한 목표치보다 위에 남게 할 수 있어요.

설정 (Configuration)

파라미터 기본값 설명
min_keep_steps 1 설정된 토큰 카운터가 측정했을 때 결과가 그대로 남는 최근 도구 호출 Agent 스텝의 최소 개수. 한 스텝의 병렬 결과는 함께 보호돼요.
min_tokens 200 이 토큰 수보다 더 쓸 때만 도구 결과 메시지를 프루닝해요.
placeholder "[Tool result removed to free up context. Call \{tool_name}` again if you need it.]"` 프루닝된 결과를 대체하는 텍스트. {tool_name} 으로 원래 도구 이름을 넣어요. 다른 중괄호는 그대로 보존돼요.
skip_meta_keys ("tool_result_offloaded",) 메타데이터에 나열된 키가 있으면 결과를 그대로 두어요. 기본값은 ToolResultOffloadHook 이 만든 포인터를 보호해요.

min_keep_steps 는 최소 1 이어야 하고, min_tokens 은 음수일 수 없어요.

커스텀 플레이스홀더 (Custom placeholders)

커스텀 플레이스홀더는 짧게 유지해서 결과를 대체하는 것이 컨텍스트를 아끼게 하세요. 플레이스홀더가 원래 결과만큼 많은 토큰을 쓰면 컴팩터는 그 결과를 바꾸지 않아요.

compactor = ToolResultPruningCompactor(
    placeholder="Previous output from {tool_name} was removed. Call the tool again if needed.",
)

컴팩터는 다시 쓴 각 결과에 전략 이름과 원래 도구 결과 메시지의 토큰 수를 담은 context_compaction 메타데이터를 기록해요.

토큰 계산 (Token counting)

컴팩터는 CompactionHook 이 제공하는 TokenCounter를 사용해 결과가 min_tokens 을 초과하는지, 대체가 컨텍스트를 아끼는지 판단해요.

전체 대화를 한 번 세고, 적격 결과 각각에 대해 카운터는 원래 결과 메시지와 짧은 대체본만 측정해요. 컴팩터는 이 두 수치의 차이로 실행 총량을 갱신해요.

도구 결과 오프로딩과의 상호작용 (Interaction with tool result offloading)

ToolResultOffloadHook 은 도구 결과를 대화 밖에 저장하고 참조로 대체해요. 그 참조를 프루닝하면 모델이 저장된 콘텐츠를 조회하지 못하게 돼요.

기본적으로 ToolResultPruningCompactor 는 tool_result_offloaded 메타데이터가 있는 메시지를 건너뛰어요. 이런 포인터 메시지는 이미 작아서, 프루닝해도 컨텍스트를 거의 아끼지 못하면서 모델이 전체 저장 결과에 접근할 수 있는 유일한 참조를 제거해 버려요. 다른 훅이나 애플리케이션 기능이 유지되어야 할 참조를 남길 때는 그 메타데이터 키를 skip_meta_keys 에 추가하세요.

대화가 바뀌지 않는 경우 (When the conversation is unchanged)

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

  • 대화가 이미 target_tokens 안에 들어맞는 경우
  • 보호된 스텝보다 오래된 결과가 없는 경우
  • 모든 오래된 결과가 이미 컴팩션되었거나, 메타데이터로 보호되거나, min_tokens 보다 크지 않은 경우
  • 대체가 결과의 측정된 토큰 수를 줄이지 않는 경우

더 알아보기 (Learn more)