도구 호출

도구 호출 (Tool Calling)

vLLM은 현재 명명된 함수 호출과 함께, 채팅 완료 API의 tool_choice 필드에 대한 auto, required(vllm>=0.8.3 부터), none 옵션을 지원합니다.

출처: 문서

본문

퀵스타트 (Quickstart)

도구 호출을 활성화한 상태로 서버를 시작합니다. 이 예시는 Meta의 Llama 3.1 8B 모델을 사용하므로 vLLM examples 디렉터리의 llama3_json 도구 호출 채팅 템플릿을 사용해야 합니다.

vllm serve meta-llama/Llama-3.1-8B-Instruct \
    --enable-auto-tool-choice \
    --tool-call-parser llama3_json \
    --chat-template examples/tool_chat_template_llama3.1_json.jinja

그 다음 사용 가능한 도구를 사용하도록 모델을 트리거하는 요청을 보냅니다.

from openai import OpenAI
import json

client = OpenAI(base_url="http://localhost:8000/v1", api_key="dummy")

def get_weather(location: str, unit: str):
    return f"Getting the weather for {location} in {unit}..."
tool_functions = {"get_weather": get_weather}

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "City and state, e.g., 'San Francisco, CA'"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
                },
                "required": ["location", "unit"],
            },
        },
    },
]

response = client.chat.completions.create(
    model=client.models.list().data[0].id,
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
    tools=tools,
    tool_choice="auto",
)

tool_call = response.choices[0].message.tool_calls[0].function
print(f"Function called: {tool_call.name}")
print(f"Arguments: {tool_call.arguments}")
print(f"Result: {tool_functions[tool_call.name](**json.loads(tool_call.arguments))}")

예시 출력:

Function called: get_weather
Arguments: {"location": "San Francisco, CA", "unit": "fahrenheit"}
Result: Getting the weather for San Francisco, CA in fahrenheit...

이 예시는 다음을 보여줍니다.

도구 호출을 활성화한 서버 설정
도구 호출을 처리할 실제 함수 정의
tool_choice="auto" 로 요청하기
구조적 응답 처리 및 해당 함수 실행

tool_choice={"type": "function", "function": {"name": "get_weather"}} 를 설정해 명명된 함수 호출로 특정 함수를 지정할 수도 있습니다. 이는 구조적 출력 백엔드를 사용한다는 점을 유의하세요. 따라서 처음 사용하면 FSM이 처음 컴파일되고 이후 요청에 캐시되기 전까지 몇 초(또는 그 이상)의 지연이 발생합니다.

호출자의 책임임을 기억하세요:

요청에 적절한 도구를 정의하는 것
채팅 메시지에 관련 컨텍스트를 포함하는 것
애플리케이션 로직에서 도구 호출을 처리하는 것

병렬 도구 호출과 모델별 파서를 포함한 더 고급 사용법은 아래 섹션을 참고하세요.

명명된 함수 호출 (Named Function Calling)

vLLM은 채팅 완료 API에서 명명된 함수 호출을 기본적으로 지원합니다. 이는 vLLM이 지원하는 대부분의 구조적 출력 백엔드에서 동작해야 합니다. 유효하게 파싱 가능한 함수 호출이 보장됩니다(고품질은 보장하지 않음).

vLLM은 구조적 출력을 사용해 응답이 tools 파라미터의 JSON 스키마에 정의된 도구 파라미터 객체와 일치하도록 보장합니다. 최상의 결과를 위해 프롬프트에서 예상 출력 형식/스키마를 지정해 모델의 의도된 생성이 구조적 출력 백엔드가 강제하는 스키마와 정렬되도록 하는 것을 권장합니다.

명명된 함수를 사용하려면 채팅 완료 요청의 tools 파라미터에서 함수를 정의하고, tool_choice 파라미터에 도구 중 하나의 name 을 지정해야 합니다.

필수 함수 호출 (Required Function Calling)

vLLM은 채팅 완료 API에서 tool_choice='required' 옵션을 지원합니다. 명명된 함수 호출과 유사하게 구조적 출력을 사용하므로 기본적으로 활성화되어 있으며 지원되는 모든 모델에서 동작합니다. 다만 대체 디코딩 백엔드 지원은 V1 엔진의 로드맵 에 있습니다.

tool_choice='required' 가 설정되면 모델은 tools 파라미터의 지정된 도구 목록을 기반으로 하나 이상의 도구 호출을 생성하는 것이 보장됩니다. 도구 호출 수는 사용자 쿼리에 따라 달라집니다. 출력 형식은 tools 파라미터의 스키마를 엄격히 따릅니다.

없음 함수 호출 (None Function Calling)

vLLM은 채팅 완료 API에서 tool_choice='none' 옵션을 지원합니다. 이 옵션이 설정되면 요청에 도구가 정의되어 있어도 모델은 도구 호출을 생성하지 않고 일반 텍스트 콘텐츠로만 응답합니다.

참고: 요청에 도구가 지정되면 vLLM은 tool_choice 설정과 무관하게 기본적으로 도구 정의를 프롬프트에 포함합니다. tool_choice='none' 일 때 도구 정의를 제외하려면 --exclude-tools-when-tool-choice-none 옵션을 사용하세요.

제약 디코딩 동작 (Constrained Decoding Behavior)

Structural-tag 파서는 호출 의무(call obligation), 문법 활성화, 인자 스키마 강제를 각각 따로 해결합니다. Structural-tag 강제가 활성화되면:

`tool_choice` 값	호출 의무	Structural-tag 활성화
Named function	선택한 함수 호출	항상
`"required"`	최소 하나의 도구 호출 생성	항상
`"auto"`	도구 호출은 선택 사항	최소 하나의 도구가 `strict: true` 로 설정되거나, `--tool-strict-level` 이 `function` 또는 `parameter` 인 경우
`"none"`	도구 호출 비활성화	비활성화

Structural tag가 적용되면 각 도구의 선언된 파라미터 스키마는 해당 도구가 strict: true 로 설정했거나 서버가 --tool-strict-level parameter 를 사용할 때만 강제됩니다. strict 를 생략하거나 false로 설정한 도구는 auto 및 function 수준에서 넓은 인자-구문 제약을 받습니다(required 및 named 호출 포함).

스키마 유래 JSON 제약을 사용하는 파서에서는 required 및 named 호출이 계속 선언된 파라미터 스키마를 강제합니다.

Strict 모드 (Strict Mode)

Structural-tag 제약에는 두 개의 레이어가 있습니다. 도구 호출 엔벨로프(마크업과 함수 이름)는 structural tag가 적용될 때마다 제약됩니다. tool_choice="required" 와 명명된 함수 호출에서는 항상, tool_choice="auto" 에서는 최소 하나의 도구가 strict: true 를 설정하거나 서버가 기준선(floor)을 올릴 때 제약됩니다. 개별 도구의 인자 스키마 는 해당 도구가 strict: true 를 설정했을 때만(또는 --tool-strict-level parameter 아래에서) 고정됩니다. strict 를 생략한 도구는 같은 요청의 다른 도구가 strict여도 인자가 제약되지 않습니다. strict 필드는 Chat Completion, Responses, Anthropic Messages의 세 가지 API 표면 모두에서 지원됩니다.

엄격한 스키마 강제와의 최상의 호환성을 위해 OpenAI strict-schema 스타일로 도구 파라미터 스키마를 정의하세요.

parameters 의 각 객체에 additionalProperties 를 false 로 설정합니다.
properties 의 모든 필드를 required로 표시합니다.
선택 필드는 null 을 허용해 표현합니다(예: {"type": ["string", "null"]}).

vLLM은 VLLM_ENFORCE_STRICT_TOOL_CALLING 환경 변수(기본 true)로 전역 토글도 제공합니다. false 로 설정하면 per-tool strict 필드와 무관하게 vLLM이 도구 호출에 structural tag를 붙이지 않습니다. 이 환경 변수는 structural-tag 기반 도구 호출에만 영향을 주며, 명명된 함수 호출이나 tool_choice="required" 에 사용되는 스키마 유래 구조적 출력은 바꾸지 않습니다.

VLLM_ENFORCE_STRICT_TOOL_CALLING=false vllm serve ...

서버 측 엄격성 기준선 (Server-Side Strictness Floor)

대부분의 OpenAI 호환 클라이언트와 에이전트 프레임워크는 도구에 strict 를 설정하지 않으므로 tool_choice="auto" 에서 모델은 문법 없이 도구 호출을 생성하고 잘못된 마크업이 응답에 누출될 수 있습니다. --tool-strict-level 옵션을 사용하면 서버 운영자가 클라이언트가 선언한 것과 무관하게 도구를 담은 모든 요청에 대한 기준선을 올릴 수 있어요.

값	동작
`auto` (기본값)	요청의 tool choice와 per-tool 엄격성을 따릅니다. required/named 선택은 structural tag를 활성화하고, `tool_choice="auto"` 는 최소 하나의 도구가 `strict: true` 를 설정하면 활성화합니다.
`function`	도구를 담은 모든 요청에 대해 도구 호출 엔벨로프(마크업과 함수 이름)를 제약하고, 클라이언트가 도구를 `strict: true` 로 표시하지 않는 한 인자 내용은 자유로 둡니다.
`parameter`	모든 도구에 대해 모든 도구가 `strict: true` 인 것처럼 인자 스키마도 추가로 고정합니다.

vllm serve ... --tool-strict-level function

기준선은 요청이 이미 받을 제약을 완화하지 않습니다. 클라이언트가 strict: true 로 표시한 도구는 모든 수준에서 스키마를 유지합니다. tool_choice="auto" 에서 문법은 도구 호출을 강제하지 않으므로 일반 텍스트 응답은 유효합니다. VLLM_ENFORCE_STRICT_TOOL_CALLING=false 는 structural tag를 완전히 비활성화하며 이 옵션보다 우선합니다.

자동 함수 호출 (Automatic Function Calling)

이 기능을 활성화하려면 다음 플래그를 설정해야 합니다.

--enable-auto-tool-choice — 필수. 자동 도구 선택. 모델이 적절하다고 판단할 때 자체 도구 호출을 생성할 수 있게 하려고 한다는 것을 vLLM에 알립니다.
--tool-call-parser — 사용할 도구 파서를 선택합니다(아래 나열). 앞으로 추가 도구 파서가 계속 추가될 것입니다. --tool-parser-plugin 에서 자체 도구 파서를 등록할 수도 있습니다.
--tool-parser-plugin — 선택. 사용자 정의 도구 파서를 vllm에 등록하는 데 사용하는 도구 파서 플러그인입니다. 등록된 도구 파서 이름은 --tool-call-parser 에서 지정할 수 있습니다.
--chat-template — 선택(자동 도구 선택용). tool 역할 메시지와 이전에 생성된 도구 호출을 담은 assistant 역할 메시지를 처리하는 채팅 템플릿의 경로입니다. Hermes, Mistral, Llama 모델은 tokenizer_config.json 파일에 도구 호환 채팅 템플릿이 있지만 커스텀 템플릿을 지정할 수 있습니다. 모델이 tokenizer_config.json 에 tool use 전용 채팅 템플릿이 구성되어 있으면 이 인자를 tool_use 로 설정할 수 있습니다. 이 경우 transformers 사양에 따라 사용됩니다. 이에 대한 자세한 내용은 HuggingFace의 여기 를 참고하고, 예시는 tokenizer_config.json 여기 에서 찾을 수 있습니다.

좋아하는 tool-calling 모델이 지원되지 않으면 파서와 tool use 채팅 템플릿을 기여해 주세요!

참고: tool_choice="auto" 에서 structural-tag 제약은 VLLM_ENFORCE_STRICT_TOOL_CALLING=true(기본값)와 함께 최소 하나의 strict: true 도구 또는 --tool-strict-level 로 설정된 서버 측 기준선이 필요합니다. 이 조건이 충족되고 선택한 파서가 structural tag를 지원하면 vLLM은 도구 호출 엔벨로프를 제약하고 strict: true 를 설정한 각 도구(또는 --tool-strict-level parameter 아래의 모든 도구)의 인자 스키마를 고정합니다. 그렇지 않으면 vLLM이 원시 텍스트에서 도구 호출을 추출하므로 인자가 때때로 잘못 형성되거나 함수의 파라미터 스키마를 위반할 수 있습니다.

Hermes 모델 (`hermes`)

Nous Research의 Hermes 2 Pro보다 최신인 모든 Hermes 시리즈 모델이 지원되어야 합니다.

NousResearch/Hermes-2-Pro-*
NousResearch/Hermes-2-Theta-*
NousResearch/Hermes-3-*

※ Hermes 2 Theta 모델은 생성 시 병합 단계 때문에 도구 호출 품질과 능력이 저하된 것으로 알려져 있습니다.

플래그: --tool-call-parser hermes

Mistral 모델 (`mistral`)

지원 모델:

mistralai/Mistral-7B-Instruct-v0.3 (확인됨)
추가 Mistral function-calling 모델도 호환됩니다.

알려진 이슈:

Mistral 7B는 병렬 도구 호출을 올바르게 생성하는 데 어려움이 있습니다.
Transformers 토크나이제이션 백엔드 전용: Mistral의 tokenizer_config.json 채팅 템플릿은 정확히 9자리인 도구 호출 ID를 요구하는데, 이는 vLLM이 생성하는 것보다 훨씬 짧습니다. 이 조건이 충족되지 않으면 예외가 발생하므로 다음 추가 채팅 템플릿이 제공됩니다.
- examples/tool_chat_template_mistral.jinja — "공식" Mistral 채팅 템플릿이지만 vLLM의 도구 호출 ID(tool_call_id 필드가 마지막 9자리로 잘림)와 동작하도록 조정됨.
- examples/tool_chat_template_mistral_parallel.jinja — 도구가 제공될 때 tool-use 시스템 프롬프트를 추가하는 "더 나은" 버전으로, 병렬 도구 호출 작업 시 훨씬 더 나은 신뢰성을 제공합니다.

권장 플래그:

공식 Mistral AI 형식 사용: --tool-call-parser mistral
Transformers 형식 사용 가능 시: --tokenizer_mode hf --config_format hf --load_format hf --tool-call-parser mistral --chat-template examples/tool_chat_template_mistral_parallel.jinja

참고: Mistral AI가 공식 출시한 모델에는 두 가지 가능한 형식이 있습니다.

auto 또는 mistral 인자로 기본 사용되는 공식 형식: --tokenizer_mode mistral --config_format mistral --load_format mistral. 이 형식은 Mistral AI의 토크나이저 백엔드인 mistral-common 을 사용합니다.

사용 가능할 때 hf 인자로 사용되는 Transformers 형식: --tokenizer_mode hf --config_format hf --load_format hf --chat-template examples/tool_chat_template_mistral_parallel.jinja

Llama 모델 (`llama3_json`)

지원 모델: 모든 Llama 3.1, 3.2, 4 모델이 지원되어야 합니다.

meta-llama/Llama-3.1-*
meta-llama/Llama-3.2-*
meta-llama/Llama-4-*

지원되는 도구 호출은 JSON 기반 도구 호출 입니다. Llama-3.2 모델이 도입한 pythonic tool calling 은 아래의 pythonic 도구 파서를 참고하세요. Llama 4 모델은 llama4_pythonic 도구 파서를 권장합니다. 내장 python 도구 호출이나 커스텀 도구 호출 같은 다른 도구 호출 형식은 지원되지 않습니다.

알려진 이슈:

Llama 3에서는 병렬 도구 호출이 지원되지 않지만 Llama 4 모델에서는 지원됩니다.
모델이 배열을 배열 대신 문자열로 직렬화하는 등 잘못된 형식의 파라미터를 생성할 수 있습니다.

vLLM은 Llama 3.1과 3.2용 두 가지 JSON 기반 채팅 템플릿을 제공합니다.

examples/tool_chat_template_llama3.1_json.jinja — Llama 3.1 모델의 "공식" 채팅 템플릿이지만 vLLM과 더 잘 동작하도록 조정됨.
examples/tool_chat_template_llama3.2_json.jinja — Llama 3.1 채팅 템플릿에 이미지 지원을 추가해 확장.

권장 플래그: --tool-call-parser llama3_json --chat-template {see_above}

vLLM은 Llama 4용 pythonic 및 JSON 기반 채팅 템플릿도 제공하지만 pythonic 도구 호출이 권장됩니다.

examples/tool_chat_template_llama4_pythonic.jinja — Llama 4 모델의 공식 채팅 템플릿 에 기반.
Llama 4 모델은 --tool-call-parser llama4_pythonic --chat-template examples/tool_chat_template_llama4_pythonic.jinja 사용.

IBM Granite

지원 모델 및 권장 플래그:

ibm-granite/granite-4.0-h-small 및 기타 Granite 4.0 모델: --tool-call-parser granite4
ibm-granite/granite-3.0-8b-instruct: --tool-call-parser granite --chat-template examples/tool_chat_template_granite.jinja — examples/tool_chat_template_granite.jinja 는 Hugging Face의 원본에서 수정된 채팅 템플릿입니다. 병렬 함수 호출이 지원됩니다.
ibm-granite/granite-3.1-8b-instruct: --tool-call-parser granite — Huggingface 채팅 템플릿을 직접 사용할 수 있고 병렬 함수 호출이 지원됩니다.
ibm-granite/granite-20b-functioncalling: --tool-call-parser granite-20b-fc --chat-template examples/tool_chat_template_granite_20b_fc.jinja — examples/tool_chat_template_granite_20b_fc.jinja 는 vLLM과 호환되지 않는 Hugging Face의 원본에서 수정된 채팅 템플릿입니다. Hermes 템플릿의 함수 설명 요소를 혼합하고 논문 의 "Response Generation" 모드와 같은 시스템 프롬프트를 따릅니다. 병렬 함수 호출이 지원됩니다.

InternLM 모델 (`internlm`)

지원 모델:

internlm/internlm2_5-7b-chat (확인됨)
추가 internlm2.5 function-calling 모델도 호환됩니다.

알려진 이슈:

이 구현은 InternLM2도 지원하지만 internlm/internlm2-chat-7b 모델로 테스트했을 때 도구 호출 결과가 안정적이지 않습니다.

권장 플래그: --tool-call-parser internlm --chat-template examples/tool_chat_template_internlm2_tool.jinja

Jamba 모델 (`jamba`)

AI21의 Jamba-1.5 모델이 지원됩니다.

ai21labs/AI21-Jamba-1.5-Mini
ai21labs/AI21-Jamba-1.5-Large

플래그: --tool-call-parser jamba

xLAM 모델 (`xlam`)

xLAM 도구 파서는 다양한 JSON 형식으로 도구 호출을 생성하는 모델을 지원하도록 설계됐습니다. 여러 출력 스타일에서 함수 호출을 감지합니다.

직접 JSON 배열: [ 로 시작해 ] 로 끝나는 JSON 배열인 출력 문자열
Thinking 태그: JSON 배열을 담은 `thinking...` 태그
코드 블록: 코드 블록(`json ...`) 안의 JSON
도구 호출 태그: [TOOL_CALLS] 또는 <tool_call>...</tool_call> 태그 사용

병렬 함수 호출이 지원되며 파서는 텍스트 콘텐츠에서 도구 호출을 효과적으로 분리할 수 있습니다.

지원 모델:

Salesforce Llama-xLAM 모델: Salesforce/Llama-xLAM-2-8B-fc-r, Salesforce/Llama-xLAM-2-70B-fc-r
Qwen-xLAM 모델: Salesforce/xLAM-1B-fc-r, Salesforce/xLAM-3B-fc-r, Salesforce/Qwen-xLAM-32B-fc-r

플래그:

Llama 기반 xLAM 모델: --tool-call-parser xlam --chat-template examples/tool_chat_template_xlam_llama.jinja
Qwen 기반 xLAM 모델: --tool-call-parser xlam --chat-template examples/tool_chat_template_xlam_qwen.jinja

Qwen 모델

Qwen2.5의 경우 tokenizer_config.json 의 채팅 템플릿이 이미 Hermes 스타일 tool use를 지원합니다. 따라서 hermes 파서로 Qwen 모델의 도구 호출을 활성화할 수 있어요. 자세한 내용은 공식 Qwen 문서 를 참고하세요.

Qwen/Qwen2.5-*
Qwen/QwQ-32B

플래그: --tool-call-parser hermes

DeepSeek-V3 모델 (`deepseek_v3`)

지원 모델:

deepseek-ai/DeepSeek-V3-0324 (examples/tool_chat_template_deepseekv3.jinja 와 함께 사용)
deepseek-ai/DeepSeek-R1-0528 (examples/tool_chat_template_deepseekr1.jinja 와 함께 사용)

플래그: --tool-call-parser deepseek_v3 --chat-template {see_above}

DeepSeek-V3.1 모델 (`deepseek_v31`)

지원 모델:

deepseek-ai/DeepSeek-V3.1 (examples/tool_chat_template_deepseekv31.jinja 와 함께 사용)

플래그: --tool-call-parser deepseek_v31 --chat-template {see_above}

OpenAI OSS 모델 (`openai`)

지원 모델:

openai/gpt-oss-20b
openai/gpt-oss-120b

플래그: --tool-call-parser openai

Kimi-K2 모델 (`kimi_k2`)

지원 모델:

moonshotai/Kimi-K2-Instruct

플래그: --tool-call-parser kimi_k2

Hunyuan 모델 (`hunyuan_a13b`)

지원 모델:

tencent/Hunyuan-A13B-Instruct (채팅 템플릿은 Hugging Face 모델 파일에 이미 포함됨)

플래그:

비추론: --tool-call-parser hunyuan_a13b
추론: --tool-call-parser hunyuan_a13b --reasoning-parser hunyuan_a13b

Cohere Command (`cohere_command3` / `cohere_command4`)

지원 모델:

CohereLabs/command-a-reasoning-08-2025 (cohere_command3)
CohereLabs/command-a-plus-05-2026 및 CohereLabs/North-Mini-Code-1.0 (cohere_command4)

플래그: --tool-call-parser cohere_command4 --reasoning-parser cohere_command4

참고: Cohere 파서는 기본적으로 설치되지 않는 cohere_melody 패키지가 필요합니다. 이 파서를 사용하기 전에 cohere_melody 패키지를 설치하세요.

LongCat-Flash-Chat 모델 (`longcat`)

지원 모델:

meituan-longcat/LongCat-Flash-Chat
meituan-longcat/LongCat-Flash-Chat-FP8

플래그: --tool-call-parser longcat

GLM-4.5 모델 (`glm45`)

지원 모델:

zai-org/GLM-4.5
zai-org/GLM-4.5-Air
zai-org/GLM-4.6

플래그: --tool-call-parser glm45

GLM-4.7 모델 (`glm47`)

지원 모델:

zai-org/GLM-4.7
zai-org/GLM-4.7-Flash

플래그: --tool-call-parser glm47

FunctionGemma 모델 (`functiongemma`)

Google의 FunctionGemma는 함수 호출 전용으로 설계된 가벼운(270M 파라미터) 모델입니다. Gemma 3 위에 구축되었으며 랩톱과 폰 같은 엣지 디바이스 배포에 최적화되어 있습니다.

지원 모델:

google/functiongemma-270m-it

FunctionGemma는 <start_function_call> 와 <end_function_call> 태그가 있는 독특한 출력 형식을 사용합니다.

<start_function_call>call:get_weather{location:<escape>London<escape>}<end_function_call>

이 모델은 최상의 결과를 위해 특정 함수 호출 작업에 미세 튜닝되도록 설계되었습니다.

플래그: --tool-call-parser functiongemma --chat-template examples/tool_chat_template_functiongemma.jinja

참고: FunctionGemma는 특정 함수 호출 작업에 미세 튜닝하도록 의도되었습니다. 기본 모델은 일반 함수 호출 기능을 제공하지만 최상의 결과는 작업별 미세 튜닝으로 얻습니다. 미세 튜닝 가이드는 Google의 FunctionGemma 문서 를 참고하세요.

Qwen3-Coder 모델 (`qwen3_xml`)

지원 모델:

Qwen/Qwen3-Coder-480B-A35B-Instruct
Qwen/Qwen3-Coder-30B-A3B-Instruct

플래그: --tool-call-parser qwen3_xml

Olmo 3 모델 (`olmo3`)

Olmo 3 모델은 아래 pythonic 파서가 기대하는 형식과 매우 유사한 형식으로 도구 호출을 출력하며 몇 가지 차이가 있습니다. 각 도구 호출은 pythonic 문자열이지만 병렬 도구 호출은 줄바꿈으로 구분되고 호출은 <function_calls>..</function_calls> XML 태그로 감쌉니다. 또한 파서는 pythonic 리터럴(True, False, None) 외에 JSON boolean과 null 리터럴(true, false, null)도 허용합니다.

지원 모델:

allenai/Olmo-3-7B-Instruct
allenai/Olmo-3-32B-Think

플래그: --tool-call-parser olmo3

Gigachat 3 모델 (`gigachat3`)

Hugging Face 모델 파일의 채팅 템플릿을 사용하세요.

지원 모델:

ai-sage/GigaChat3-702B-A36B-preview
ai-sage/GigaChat3-702B-A36B-preview-bf16
ai-sage/GigaChat3-10B-A1.8B
ai-sage/GigaChat3-10B-A1.8B-bf16

플래그: --tool-call-parser gigachat3

Apertus 모델 (`apertus`)

examples 폴더의 채팅 템플릿을 사용하세요. 여러 OpenAI 호환성 이슈를 수정합니다: --chat-template /vllm-workspace/examples/tool_chat_template_apertus.jinja

지원 모델:

swiss-ai/Apertus-8B-Instruct-2509
swiss-ai/Apertus-70B-Instruct-2509

플래그: --tool-call-parser apertus

Pythonic 도구 호출 모델 (`pythonic`)

점점 더 많은 모델이 JSON 대신 Python 목록으로 도구 호출을 출력합니다. 이는 병렬 도구 호출을 본질적으로 지원하고 도구 호출에 필요한 JSON 스키마에 대한 모호성을 제거하는 이점이 있습니다. pythonic 도구 파서가 이런 모델들을 지원할 수 있습니다.

구체적인 예로, 이 모델들은 다음을 생성해 샌프란시스코와 시애틀의 날씨를 조회할 수 있습니다.

[get_weather(city='San Francisco', metric='celsius'), get_weather(city='Seattle', metric='celsius')]

제한 사항:

모델은 같은 생성에서 텍스트와 도구 호출을 모두 생성해선 안 됩니다. 특정 모델에서는 바꾸기 어려울 수 있지만, 커뮤니티가 현재 도구 호출의 시작/종료 시 방출할 토큰에 대한 합의가 부족합니다. (특히 Llama 3.2 모델은 그런 토큰을 방출하지 않습니다.)
Llama의 소형 모델은 도구를 효과적으로 사용하는 데 어려움이 있습니다.

예시 지원 모델:

meta-llama/Llama-3.2-1B-Instruct ⚠️ (examples/tool_chat_template_llama3.2_pythonic.jinja 와 함께)
meta-llama/Llama-3.2-3B-Instruct ⚠️ (examples/tool_chat_template_llama3.2_pythonic.jinja 와 함께)
Team-ACE/ToolACE-8B (examples/tool_chat_template_toolace.jinja 와 함께)
fixie-ai/ultravox-v0_4-ToolACE-8B (examples/tool_chat_template_toolace.jinja 와 함께)
meta-llama/Llama-4-Scout-17B-16E-Instruct ⚠️ (examples/tool_chat_template_llama4_pythonic.jinja 와 함께)
meta-llama/Llama-4-Maverick-17B-128E-Instruct ⚠️ (examples/tool_chat_template_llama4_pythonic.jinja 와 함께)

플래그: --tool-call-parser pythonic --chat-template {see_above}

경고: Llama의 소형 모델은 올바른 형식으로 도구 호출을 방출하는 데 자주 실패합니다. 모델에 따라 결과가 다를 수 있습니다.

도구 호출 성능 벤치마킹 (Benchmarking Tool-Calling Performance)

실제적인 도구 호출 트래픽에서 서빙 지연과 처리량을 측정하려면 BFCL(Berkeley Function Calling Leaderboard) 데이터셋을 vllm bench serve 와 함께 사용하세요. 전체 서버 + 클라이언트 명령은 BFCL 벤치마크 예시 를 참고하세요.

도구 파서 플러그인 작성법 (How to Write a Tool Parser Plugin)

도구 파서 플러그인은 하나 이상의 ToolParser 구현을 담은 Python 파일입니다. vllm/tool_parsers/hermes_tool_parser.py 의 Hermes2ProToolParser 와 유사한 ToolParser를 작성할 수 있어요.

플러그인 파일의 요약입니다.

# import the required packages

# define a tool parser and register it to vllm
# the name list in register_module can be used
# in --tool-call-parser. you can define as many
# tool parsers as you want here.
class ExampleToolParser(ToolParser):
    def __init__(self, tokenizer: TokenizerLike):
        super().__init__(tokenizer)

    # adjust request. e.g.: set skip special tokens
    # to False for tool call output.
    def adjust_request(self, request: ChatCompletionRequest | ResponsesRequest) -> ChatCompletionRequest | ResponsesRequest:
        return request

    # implement the tool call parse for stream call
    def extract_tool_calls_streaming(
        self,
        previous_text: str,
        current_text: str,
        delta_text: str,
        previous_token_ids: Sequence[int],
        current_token_ids: Sequence[int],
        delta_token_ids: Sequence[int],
        request: ChatCompletionRequest,
    ) -> DeltaMessage | None:
        return delta

    # implement the tool parse for non-stream call
    def extract_tool_calls(
        self,
        model_output: str,
        request: ChatCompletionRequest,
    ) -> ExtractedToolCallInformation:
        return ExtractedToolCallInformation(tools_called=False,
                                            tool_calls=[],
                                            content=text)
# register the tool parser to ToolParserManager
ToolParserManager.register_lazy_module(
    name="example",
    module_path="vllm.tool_parsers.example",
    class_name="ExampleToolParser",
)

그런 다음 이 플러그인을 명령줄에서 이렇게 사용할 수 있습니다.

    --enable-auto-tool-choice \
    --tool-parser-plugin <absolute path of the plugin file>
    --tool-call-parser example \
    --chat-template <your chat template> \

도구 호출

도구 호출 (Tool Calling)

본문

퀵스타트 (Quickstart)

명명된 함수 호출 (Named Function Calling)

필수 함수 호출 (Required Function Calling)

없음 함수 호출 (None Function Calling)

제약 디코딩 동작 (Constrained Decoding Behavior)

Strict 모드 (Strict Mode)

서버 측 엄격성 기준선 (Server-Side Strictness Floor)

자동 함수 호출 (Automatic Function Calling)

Hermes 모델 (hermes)

Mistral 모델 (mistral)

Llama 모델 (llama3_json)

IBM Granite

InternLM 모델 (internlm)

Jamba 모델 (jamba)

xLAM 모델 (xlam)

Qwen 모델

DeepSeek-V3 모델 (deepseek_v3)

DeepSeek-V3.1 모델 (deepseek_v31)

OpenAI OSS 모델 (openai)

Kimi-K2 모델 (kimi_k2)

Hunyuan 모델 (hunyuan_a13b)

Cohere Command (cohere_command3 / cohere_command4)

LongCat-Flash-Chat 모델 (longcat)

GLM-4.5 모델 (glm45)

GLM-4.7 모델 (glm47)

FunctionGemma 모델 (functiongemma)

Qwen3-Coder 모델 (qwen3_xml)

Olmo 3 모델 (olmo3)

Gigachat 3 모델 (gigachat3)

Apertus 모델 (apertus)

Pythonic 도구 호출 모델 (pythonic)

도구 호출 성능 벤치마킹 (Benchmarking Tool-Calling Performance)

도구 파서 플러그인 작성법 (How to Write a Tool Parser Plugin)

더 알아보기 (Learn more)

Hermes 모델 (`hermes`)

Mistral 모델 (`mistral`)

Llama 모델 (`llama3_json`)

InternLM 모델 (`internlm`)

Jamba 모델 (`jamba`)

xLAM 모델 (`xlam`)

DeepSeek-V3 모델 (`deepseek_v3`)

DeepSeek-V3.1 모델 (`deepseek_v31`)

OpenAI OSS 모델 (`openai`)

Kimi-K2 모델 (`kimi_k2`)

Hunyuan 모델 (`hunyuan_a13b`)

Cohere Command (`cohere_command3` / `cohere_command4`)

LongCat-Flash-Chat 모델 (`longcat`)

GLM-4.5 모델 (`glm45`)

GLM-4.7 모델 (`glm47`)

FunctionGemma 모델 (`functiongemma`)

Qwen3-Coder 모델 (`qwen3_xml`)

Olmo 3 모델 (`olmo3`)

Gigachat 3 모델 (`gigachat3`)

Apertus 모델 (`apertus`)

Pythonic 도구 호출 모델 (`pythonic`)