Fixing Tool-Call Accuracy in vLLM

Ubicloud는 오픈 웨이트 모델 품질이 기대에 못 미치는 원인 중 하나로 도구 호출(tool call) 정확도를 꼽아요. 도구 호출이 틀리면 모델이 엉뚱한 맥락 위에 계속 쌓아 올리고, 멀티턴 에이전트 작업에서 품질이 크게 떨어져요.

• vLLM 0.28로 Kimi K2.6을 서빙했더니 기대한 스키마를 지킨 호출이 92%뿐이었어요. 25번 중 2번은 실패한 셈이에요.

도구 호출 스키마란

1. 하네스(예: OpenCode)가 쓸 수 있는 도구 목록을 JSON으로 보내요. 예를 들어 webfetch 도구는 url(필수), format(text·markdown·html), timeout 같은 파라미터를 가져요.
2. 추론 엔진이 이 JSON을 모델별 특수 토큰으로 감싸 모델에 넣어요.
3. 모델이 특수 토큰과 인자 JSON을 출력하면, 서버 파서가 이를 표준 tool_calls JSON으로 바꿔 하네스에 돌려줘요.

호출이 스키마를 어기면 오류 메시지가 컨텍스트를 오염시키고, 재시도로 비용이 늘어요. 모델은 확률적으로 토큰을 고를 뿐 컴파일러처럼 검사하지 않아서, 학습 때 본 search_web을 지금 있는 web_search 대신 쓰거나 location 대신 city_name을 쓰는 실수가 생겨요.

Moonshot AI는 제공업체가 Kimi를 원본 품질로 서빙하는지 확인하라고 K2VV ToolCall 벤치마크(요청 2,000개)를 냈어요. 언제 도구를 부르는지(트리거 유사도)와 스키마를 지키는지(스키마 정확도)를 재요.

해결: 제약 디코딩

제약 디코딩(constrained decoding)은 결과를 나중에 검사하는 대신, 생성 단계마다 스키마상 유효한 토큰만 고를 수 있게 막아요. vLLM은 XGrammar 라이브러리의 structural tag로 이를 구현해요.

도구 호출 시작 → 도구 이름 → 호출 인덱스 → 인자 시작 → 스키마 제약 JSON → 도구 호출 끝

예를 들어 인덱스 단계에서는 정수 토큰만 허용하고 나머지는 가려요. 단계별 토큰 마스크를 미리 계산해 GPU에서 적용하므로 성능 부담은 거의 없대요. 정확도가 "최선을 다함"에서 실행 시점 보장으로 바뀌는 거예요.

그런데 왜 다시 91%로 떨어졌나

Ubicloud는 처음엔 자체 vLLM 포크에 이 기능을 넣었고, vLLM이 정식 지원한 뒤 업스트림 기능으로 옮겼어요. 얼마 뒤 정확도가 91%로 돌아갔는데, 구현은 맞았고 vLLM의 기본값이 바뀐 것이 원인이었어요. vLLM이 기본값을 끈 이유는 세 가지래요.

• 모델 자체 문제: 제약 없이 낸 출력이 형식과 많이 다른 모델은 억지로 다른 토큰을 고르다 엇나가요. gpt-oss-20b, Qwen 3.6, GLM 5.1 사용자가 문제를 보고했대요.
• 문법 변환 버그: 도구 스키마를 모델별 문법으로 옮기다 생긴 버그로 잘못된 호출, 요청 실패, 제약이 조용히 빠지는 일이 생겨요.
• 기능 간 충돌: 예를 들어 추측 디코딩(speculative decoding)과 함께 쓰면 추측 토큰이 문법에 잘못 거부돼 요청이 실패할 수 있어요.

그래서 vLLM은 범용 엔진으로서 기본값을 끄고, 대신 --tool-strict-level 플래그로 켤 수 있게 했어요.

결과와 교훈

Ubicloud는 Kimi와 DeepSeek을 1차 제공업체 수준으로 서빙하는 게 목표라 제약 디코딩을 켜고 K2VV ToolCall을 다시 돌려, 모든 모델 버전에서 스키마 정확도 100%를 확인한 뒤 배포했어요.

우리가 보는 품질은 모델만으로 정해지지 않아요. 추론 엔진과 그 설정을 바꾸면 모델의 출력 품질도 바뀌어요.