vLLM 제약 디코딩, Kimi 및 DeepSeek의 도구 호출 정확도를 100%로 수정

핵심 요점

vLLM 0.31에서 도입된 제약 디코딩 플래그를 활성화하면 Kimi K2.6 및 DeepSeek V4 Flash의 도구 호출 스키마 준수율이 100% 보장되어, 이전에 정확도를 92%로 낮추던 잘못된 호출이 제거됩니다.

도구 호출 스키마 정확도가 중요한 이유

  • 도구 호출은 모델에 제공된 JSON 스키마를 따라야 하며, 이를 벗어나면 호출이 실패하고 컨텍스트 창이 오염됩니다.
  • 다중 턴 에이전트 워크로드에서 잘못된 호출 하나가 재시도를 강제하고, 지연 시간을 높이며, 전반적인 모델 품질을 저하시킵니다.
  • Moonshot AI의 K2VV ToolCall 벤치마크는 두 가지 주요 지표를 측정합니다:
    • 트리거 유사도 – 서비스가 참조 구현과 비교하여 도구를 호출하기로 결정하는 빈도.
    • 스키마 정확도 – 선언된 스키마를 준수하는 생성 호출의 비율. 스키마 정확도가 50%라는 것은 모든 호출의 절반이 사용 불가능함을 의미합니다.
  • Ubicloud가 vLLM 0.28로 Kimi K2.6을 서비스할 때 스키마 정확도는 92% (25회 호출당 2회 실패)에 불과했으며, 이는 프로덕션 에이전트에게 허용할 수 없는 수준입니다.

제약 디코딩: 작동 방식

  • 표준 디코딩은 모델이 확률에 따라 모든 토큰을 샘플링하도록 허용하며, 이는 구문적으로 유효하지 않은 JSON을 생성할 수 있습니다.
  • 제약 디코딩은 각 생성 단계에서 토큰 집합을 도구의 JSON 스키마에 따라 출력을 유효하게 유지하는 토큰으로만 제한합니다.
  • vLLM은 XGrammar 구조 태그를 사용하여 이를 구현합니다. 문법은 결정적 시퀀스를 정의합니다:
    1. <|tool_call_begin|>{function.name}:{index}
    2. <|tool_call_argument_begin|>
    3. JSONSchemaFormat – 제공된 스키마를 준수하는 JSON을 생성합니다.
    4. <|tool_call_end|>
  • 유효하지 않은 토큰은 즉시 마스킹되며, 마스크는 각 단계에 대해 사전 계산되므로 GPU가 무시할 수 있는 오버헤드로 적용할 수 있습니다.

"이것은 스키마 정확도를 최선 노력 방식에서 런타임 보장으로 바꿉니다. 모델은 여전히 어떤 토큰을 생성할지 결정하지만, 이제 토큰은 제한되고 구문적으로 올바른 집합에서 선택됩니다." – Ubicloud 블로그

vLLM 0.31에서 변경된 사항

  • 제약 디코딩은 vLLM 0.31에서 서버 측 플래그 (--tool-strict-level)로 추가되었습니다.
  • 0.31 이전에는 이 기능이 이전 릴리스(예: 0.25)에 존재했지만, 예상된 도구 호출 형식을 따르지 않는 모델의 회귀를 피하기 위해 대부분의 모델에서 기본적으로 비활성화되었습니다.
  • Kimi 및 DeepSeek에 대해 플래그를 활성화하면 엔진이 XGrammar 마스크를 적용하도록 강제하여 K2VV 벤치마크에서 스키마 정확도를 100% 로 높였습니다.

기본값이 비활성화된 이유

  • vLLM은 다양한 모델을 제공합니다. 일부 모델(예: gpt-oss-20b, Qwen 3.6, GLM 5.1)은 예상 형식에서 벗어난 도구 호출을 생성하여 제약 디코딩이 너무 많은 토큰을 거부하고 성능을 저하시킬 수 있습니다.
  • 세 가지 문제 범주가 식별되었습니다:
    1. 일반 모델 문제 – 모델이 제약 없이 예상 스키마에서 벗어납니다.
    2. 문법 변환 버그 – 모델의 도구 스키마를 XGrammar 태그로 변환하는 오류.
    3. 기능 상호작용 버그 – 예: 제약 디코딩과 추측 디코딩 간의 충돌로 유효한 토큰이 잘못 마스킹되는 경우.
  • 이러한 회귀 때문에 vLLM 유지 관리자는 모델에 구애받지 않는 기본 비활성화를 선택하고, 엄격한 적용이 필요한 사용자를 위해 명시적 --tool-strict-level 플래그를 도입했습니다.

커뮤니티 통찰

"제약 디코딩은 vLLM에 오랫동안 있었고, 제약 도구 호출 디코딩도 vLLM에 한동안 있었습니다. 블로그 게시물은 다소 혼란스러운데, 전체 상황을 이해하기 전까지는 vLLM을 수정했다는 인상을 주지만(제목이 암시하는 바), 실제로는 올바르게 구성하기만 하면 되었습니다." – @Aurornis (HN 댓글)

  • 토론은 실제 수정 사항이 코드 변경이 아닌 구성이었음을 강조하며, 회귀를 발견한 벤치마크를 유지한 Ubicloud를 인정합니다.
  • 다른 댓글 작성자들은 제약 디코딩이 이제 다른 런타임(예: llama.cpp, HuggingFace transformers.js)에서 일반적이며, 100% 도구 호출 정확도가 프로덕션 에이전트의 기본 기대치라고 언급합니다.

배포를 위한 실용적 지침

  1. 안정적인 도구 호출 형식을 가진 모델(예: Kimi K2.6, DeepSeek V4 Flash)을 서비스할 때 플래그를 활성화하세요:
    vllm serve model_path --tool-strict-level=2   # 또는 vLLM 문서에 따라 적절한 수준
  2. Moonshot AI의 K2VV ToolCall과 같은 벤치마크로 검증하여 엔진 업그레이드 후에도 스키마 정확도가 100%로 유지되는지 확인하세요.
  3. 모델별 회귀를 모니터링하세요. 제약 디코딩으로 성능이 저하되는 모델이 있으면 해당 모델에 대해서만 플래그를 비활성화하는 것을 고려하세요.
  4. 도구를 추가하거나 이름을 변경할 때 XGrammar 정의를 최신 상태로 유지하세요. 문법은 모델이 사용하는 정확한 JSON 스키마를 반영해야 합니다.

결론

도구 호출 스키마 정확도는 에이전트 LLM 품질의 중요한 결정 요인입니다. vLLM 0.31의 제약 디코딩을 활성화함으로써 Ubicloud는 잘못된 도구 호출을 제거하여 Kimi 및 DeepSeek 모델의 벤치마크 정확도를 92%에서 100% 로 높였습니다. 이는 추론 엔진 구성이 안정적이고 고품질의 AI 서비스를 제공하는 데 모델 선택만큼 중요할 수 있음을 보여줍니다.

Sources