LLM 도구 호출 오류를 자동으로 축소하는 toolcall-doctor

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

LLM 도구 호출 오류를 재현하기 위해 매번 요청 일부를 수동으로 지우고 모델을 다시 호출하던 작업을 toolcall-doctor가 자동화합니다. 사용자가 지정한 실패 조건과 보존 조건을 계약으로 입력하면, 도구는 요청의 일부를 제거하고 OpenAI 호환 서버에 재요청한 뒤 두 조건이 모두 유지되는 후보만 남기는 DDMin 루프를 반복합니다. Ollama 0.4.6과 llama3.2:3b에서 검증한 결과 tool_choice 사례는 583 B에서 185 B로 68.27%, 인자 구조 사례는 468 B에서 234 B로 50.00% 줄었으며, 최종 후보도 기본 3회 재검증합니다. 다만 지원 검증은 단일 Ollama 버전과 모델에 한정되고, 이 도구는 근본 원인을 진단하거나 계약에 적지 않은 의미를 보존하지 않습니다.

섹션별 상세

LLM 도구 호출 오류를 재현할 때는 도구 하나나 스키마 필드를 지운 뒤 모델을 다시 호출하고, 오류가 사라지면 되돌리는 작업을 반복하게 됩니다. toolcall-doctor는 원본 요청에서 일부를 제거한 후보를 만들고 OpenAI 호환 서버에 다시 보내 지정한 실패 조건이 계속 발생하는지 확인합니다. 이 반복을 자동화하면 수동 비교보다 작은 재현 요청을 일관된 절차로 만들 수 있지만, 어떤 동작을 오류로 볼지는 사용자가 계약에 직접 적어야 합니다.

bash

pip install -e .
toolcall-doctor demo

모델 호출 없이 기록된 실행 결과를 재생하는 데모를 설치하고 실행합니다.

최소화 과정은 실패 조건과 보존 조건을 동시에 통과한 후보만 유지하는 방식으로 작동합니다. 예를 들어 원본에서 도구나 스키마 필드를 제거한 뒤 모델을 호출하고, 도구 호출이 계속 발생하면서 tool_choice가 none이고 get_weather, weather, Paris가 남아 있을 때만 해당 제거를 채택합니다. 이 구조는 결과가 단순히 작아졌다는 이유가 아니라 지정한 재현 조건과 핵심 요소가 함께 남았다는 이유로 후보를 통과시킵니다.

bash

toolcall-doctor minimize request.json --contract contract.json -o out

입력 요청과 실패·보존 조건 계약을 받아 라이브 모델 호출로 최소 재현 요청을 생성합니다.

대표적인 tool_choice 사례는 583 B 요청을 185 B로 줄여 68.27% 감소를 기록했고, argument shape 사례는 468 B에서 234 B로 50.00% 감소했습니다. 두 사례 모두 Ollama 0.4.6과 llama3.2:3b에서 기본 -n 3 설정으로 검증했으며, 라이브 실행에서 원본 실패를 3/3회 재현하고 최종 후보도 다시 확인합니다. 이 수치는 여러 모델이나 서버를 비교한 벤치마크가 아니라 하나의 런타임에서 수행한 검증 결과입니다.

json

{
  "failure": { "condition": "has_tool_call" },
  "preserve": [
    {"type": "request_equals", "key": "tool_choice", "value": "none"},
    {"type": "tool_name", "value": "get_weather"},
    {"type": "contains", "value": "weather"},
    {"type": "contains", "value": "Paris"}
  ]
}

모델이 도구 호출을 계속 생성하고 tool_choice, 도구 이름, 사용자 텍스트의 핵심 단어를 보존하도록 지정하는 계약입니다.

json

{"failure": {"condition": "http_status_is", "value": 400}}
{"failure": {"condition": "missing_tool_call"}

HTTP 상태 코드나 도구 호출 부재를 실패 조건으로 지정하는 대체 계약 형식입니다.

모델 응답의 비결정성 때문에 검색 단계에서 통과한 후보가 마지막 반복 검증에서 실패할 수 있습니다. toolcall-doctor는 이런 경우 축소 결과를 성공으로 보고하지 않고 실패 상태로 종료해 재검증되지 않은 결과의 오용을 막습니다. 특히 enum 사례는 검색 중에는 실패가 유지돼도 최종 반복 검증에 실패할 수 있어 안정적인 일반 사례로 취급하지 말아야 합니다.

계약에 넣지 않은 의미는 보호되지 않으며, 예를 들어 특정 enum 문자열이 keeper로 지정되지 않으면 다른 짧은 값으로 줄어들 수 있습니다. 현재 keeper는 중첩 객체 속성 아래의 pattern 같은 필드를 기존 primitive로 지정하지 못하고, 라이브 최소화에는 모델을 여러 번 호출하는 시간이 필요합니다. 따라서 이 도구의 산출물은 버그의 근본 원인이나 수정안을 확정하는 진단 결과가 아니라, 사용자가 작성한 검사 조건을 계속 만족하는 더 작은 재현 요청입니다.

용어 해설

델타 디버깅(Delta Debugging): — 실패를 재현하는 입력을 여러 부분으로 나누고 일부를 제거한 뒤 같은 실패가 유지되는지 반복 확인해 원인을 포함할 가능성이 있는 더 작은 입력을 찾는 축소 기법입니다. toolcall-doctor는 이 과정을 문자 단위 DDMin으로 수행하지만, 결과가 유일한 근본 원인이라는 뜻은 아닙니다.
DDMin: — 입력 집합을 부분 집합으로 나눠 제거하고, 지정한 실패 조건과 보존 조건이 계속 성립하는 후보만 다음 단계로 넘기는 최소화 알고리즘입니다. 이 도구에서는 LLM 요청을 여러 차례 호출해 더 작은 재현 입력을 찾는 엔진으로 사용됩니다.
도구 호출(Tool Calling): — LLM이 메시지와 도구 스키마를 바탕으로 외부 함수를 호출할지를 결정하고 인자 구조를 생성하는 방식입니다. 이 글의 도구는 도구 호출 실패가 유지되는 동안 요청의 도구, 스키마 필드, 텍스트 일부를 제거해 재현 가능한 축소본을 만듭니다.
OpenAI 호환 API(OpenAI-compatible API): — OpenAI API와 호환되는 요청 형식과 엔드포인트를 제공하는 서버 인터페이스입니다. toolcall-doctor는 이 인터페이스의 POST /v1/chat/completions를 통해 후보 요청을 모델에 보내고 응답에서 실패 조건과 보존 조건을 검사합니다.
모델 비결정성(Model Nondeterminism): — 같은 요청을 반복해도 모델 응답이 항상 동일하지 않을 수 있는 특성입니다. 이 도구는 기본적으로 각 후보를 3회 호출하고 마지막 후보도 반복 검증하며, 검색 중 통과한 후보가 최종 검증에서 실패하면 성공한 축소 결과로 보고하지 않습니다.

기술

toolcall-doctor
Ollama 0.4.6
llama3.2:3b
Python 3.10+
OpenAI-compatible POST /v1/chat/completions
DDMin

활용 사례

LLM 도구 호출 오류의 최소 재현 요청 생성
tool_choice 제약 오류의 재현 입력 축소
도구 인자 구조와 enum 제약 오류의 반복 검증
HTTP 상태 코드나 응답 문자열을 기준으로 하는 API 실패 축소

LLM 도구 호출 오류를 자동으로 축소하는 toolcall-doctor

TL;DR

섹션별 상세

용어 해설

기술

활용 사례

관련 토론

댓글

관련 기사

에이전트 실행 Trace를 결정적으로 검사하는 Linter

LLM과 도구 사이를 통제하는 toolbroker

RedThread로 LLM 도구 호출 회귀 재현

관련 토론

댓글

관련 기사

에이전트 실행 Trace를 결정적으로 검사하는 Linter

LLM과 도구 사이를 통제하는 toolbroker

RedThread로 LLM 도구 호출 회귀 재현