11/6

Spring AI 챗봇 오류 트러블슈팅 기록

프로젝트 진행 중 발생했던 `tool_use_failed` 오류와 시간대(Timezone) 불일치로 인한 경기 조회 누락 문제를 정리했다.

---

tool_use_failed 오류

문제 상황

챗봇 개선 중 서버에서 모델 툴 호출 실패 오류가 발생했다.

"code": "tool_use_failed", "failed_generation": "<function=query_schedule{"when":"오늘"}..."

원인 분석

[툴 사용 원칙]
일정/승률/예측 등 사실 확인이 필요하면 제공된 툴을 사용한다.
한 번에 여러 툴이 필요하지 않다면 호출을 최소화한다.

[툴 사용 예시]
사용자: 오늘 경기 있어요?
도구호출: query_schedule({"when":"오늘"})

 

1. few-shot prompt에 들어간 툴 사용 예시 텍스트를 모델이 그대로 응답 본문에 붙여 출력

2. Groq이 `<function=...>` 형태를 함수 호출 시도로 잘못 인식 → 파싱 실패

3. HTTP 400 (`tool_use_failed`) 발생

4. Spring AI에서 예외를 전파하면서 Postman에서는 500 서버 오류로 노출됨

해결 방법

few-shot prompt를 모델이 혼동하지 않도록 명확한 규칙 기반으로 재작성했다.

[툴 사용 원칙]
경기 일정이 필요하면 query_schedule 또는 query_schedule_by_date를 사용한다.
팀·리그의 승률이 필요하면 analyze_winning_rate를 사용한다.
최근 인기 있는 팀/리그를 묻는다면 query_hot_keywords를 사용한다.
한 번에 여러 툴이 필요하지 않다면 호출을 최소화한다.

[툴 사용 예시]
사용자: 안녕하세요! → 툴 호출 없이 최종 답만 생성
사용자: 오늘 경기 있어요? → query_schedule({"when":"오늘"})
사용자: 11월 4일 경기 일정 알려줘 → query_schedule_by_date({"month":11,"day":4})
사용자: Nexus 승률 알려줘 → analyze_winning_rate({"teamA":"Nexus"})
사용자: 요즘 인기 있는 팀은 어디야? → query_hot_keywords()

그 결과, 모델이 예시 문장을 그대로 출력하지 않고 실제 툴 호출을 수행하여 정상처리되어 서버 500 오류가 해결됐다.

---

Timezone 불일치 문제

문제 상황

경기 일정 조회 시 DB에는 데이터가 존재함에도 챗봇은 “오늘 경기가 없습니다”라고 응답하는 현상 발생했다.

로컬에서는 정상적으로 조회되는 것을 확인했다.

원인 분석

1. DB에는 UTC 기준으로 `start_time` 저장

2. 조회 로직은 KST(`LocalDateTime.now()`) 기준으로 실행

3. DB 조회 시 `between` 조건의 기준 시각이 서로 달라 조회 누락 발생

 ※ 예: KST 기준 `2025-11-04T00:00` → UTC 기준 `2025-11-03T15:00`

해결 방법

조회 전, KST → UTC 변환 로직을 추가해 DB 기준과 일치시켜줬다.

private List findMatchesByKstRange(LocalDateTime startKst, LocalDateTime endKst) {
	ZoneId UTC = ZoneOffset.UTC;
	LocalDateTime startUtc = startKst.atZone(KST).withZoneSameInstant(UTC).toLocalDateTime();
	LocalDateTime endUtc = endKst.atZone(KST).withZoneSameInstant(UTC).toLocalDateTime();

	return matchRepository.findByStartTimeBetweenOrderByStartTimeAsc(startUtc, endUtc);
}

그 결과, UTC/KST 간 시간대 일관성 확보해서 실제 DB와 조회 범위가 일치함으로써 경기 일정이 정상적으로 반환된다.

---

마치며

이번 두 가지 오류는 모두 AI 통합 환경에서 자주 발생하는 전형적인 문제였다.

`tool_use_failed` → 프롬프트 설계 단계에서의 모델 오인식

Timezone 불일치 → 시스템 간 데이터 일관성 문제

두 사례를 통해 모델이 어떻게 해석하고 동작하는가에 대한 이해를 넓힐 수 있었으며, 프롬프트 설계와 시스템 시간대 관리가 안정적인 챗봇 운영에 핵심적임을 확인했다.