tool 호출 디버깅 — 100번 중 5번 망가지는 이유

LLM 의 tool use 기능을 실서비스에 붙이고 나면 처음 며칠은 잘 동작한다. 그런데 사용량이 늘면서 간헐적으로 망가지는 케이스가 나타나기 시작한다. 100번 실행했을 때 95번은 정상이고 5번은 이상한 결과가 나오는 종류의 오류다. 이 문제를 추적하면서 배운 것을 정리한다.

어디서 오류가 생기는가

tool 호출 파이프라인은 여러 단계가 직렬로 연결된다.

사용자 입력 → 모델이 tool 호출 결정 → tool 실행 → 결과 반환 → 모델이 최종 응답 생성

오류는 이 각 단계에서 발생할 수 있고, 발생 지점에 따라 원인과 대응이 다르다.

모델이 잘못된 tool 을 선택하는 경우: tool 정의(스키마, 설명)가 모호하거나, 여러 tool 의 책임 범위가 겹칠 때 발생한다. 특히 비슷한 이름이나 기능을 가진 tool 이 둘 이상 있을 때 모델이 혼동한다.

파라미터가 잘못 생성되는 경우: 모델이 올바른 tool 을 선택했지만 필수 파라미터를 빠뜨리거나, 타입이 맞지 않거나, 스키마에 없는 필드를 만들어내는 경우다. 이 오류는 스키마 검증을 추가하면 즉시 잡힌다.

tool 실행 결과를 모델이 잘못 해석하는 경우: tool 이 에러를 반환했을 때 모델이 에러 메시지를 그대로 정상 데이터처럼 처리하거나, 빈 결과를 “결과 없음”이 아닌 “오류”로 해석하는 경우다.

5% 오류의 실제 원인들

우리 팀이 추적한 케이스에서 가장 자주 발견된 원인들이다.

tool 설명의 모호성: “데이터를 조회한다” 같은 설명은 너무 추상적이다. 모델이 어떤 상황에서 이 tool 을 써야 하는지 명확하지 않으면 간헐적으로 잘못된 선택을 한다. tool 설명에 “언제 써야 하는지”와 “언제 쓰지 말아야 하는지”를 명시적으로 쓰는 것이 효과적이었다.

컨텍스트 누적 오염: 대화가 길어질수록 이전 tool 호출 결과들이 컨텍스트에 쌓인다. 오래된 tool 결과가 새로운 tool 선택에 영향을 미쳐서 뜻밖의 결정을 유도하는 경우가 있었다. 관련 없는 이전 tool 결과는 컨텍스트에서 제거하거나 요약하는 방식으로 개선했다.

비결정적 동작: 같은 입력이라도 temperature 설정에 따라 출력이 달라진다. tool 선택처럼 결정적이어야 하는 부분에서는 temperature 를 낮추거나 0으로 설정하는 것이 안정성을 높인다.

디버깅을 가능하게 하는 로깅

간헐적 오류는 재현이 어렵다. 발생했을 때 원인을 찾으려면 충분한 로그가 있어야 한다.

우리가 기록하는 항목들:

- 입력 메시지 전체
- 모델이 생성한 tool 호출 (tool 이름 + 파라미터 원본)
- tool 실행 결과 (성공/실패, 반환값)
- 최종 모델 응답
- 처리 시간 (각 단계별)

특히 모델이 생성한 파라미터 원본을 저장하는 것이 중요하다. 파싱 전 원본 JSON 을 남겨두면 스키마 위반 패턴을 분석할 수 있다. 우리는 이 로그를 분석해서 특정 사용자 입력 패턴이 파라미터 오류를 유발한다는 것을 발견했고, tool 스키마 설명을 수정해서 해결했다.

간헐적 오류를 0으로 만들 수 없다

현실적인 이야기를 하자면, LLM 기반 파이프라인에서 간헐적 오류를 완전히 없애는 것은 어렵다. 모델이 확률적으로 동작하기 때문이다. 목표는 0% 가 아니라 허용 가능한 수준으로 낮추고, 오류가 발생했을 때 복구할 수 있는 구조를 만드는 것이다. 재시도 로직, 폴백 경로, 사용자에게 명확한 오류 메시지를 제공하는 것이 tool 파이프라인 안정화의 마지막 단계다.

— by mings