跳到内容

工具调用

vLLM 目前支持命名函数调用，以及在 chat completion API 的 tool_choice 字段中的 auto、required (从 vllm>=0.8.3 版本开始) 和 none 选项。

快速入门

启动启用了工具调用的服务器。此示例使用 Meta 的 Llama 3.1 8B 模型，因此我们需要使用 vLLM 示例目录中的 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="https://: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 会在首次编译后被缓存以供后续请求使用。

请记住，调用者有责任

  1. 在请求中定义适当的工具
  2. 在聊天消息中包含相关上下文
  3. 在您的应用程序逻辑中处理工具调用

有关更高级的用法，包括并行工具调用和不同的模型特定解析器，请参阅下面的部分。

命名函数调用

vLLM 默认在 chat completion API 中支持命名函数调用。这应该适用于 vLLM 支持的大多数结构化输出后端。您保证会获得一个可解析的有效函数调用——但不保证其质量。

vLLM 将使用结构化输出来确保响应与 tools 参数中 JSON schema 定义的工具参数对象匹配。为了获得最佳结果，我们建议确保在提示中指定预期的输出格式/ schema，以确保模型的预期生成与结构化输出后端强制其生成的 schema 对齐。

要使用命名函数，您需要在 chat completion 请求的 tools 参数中定义函数，并在 chat completion 请求的 tool_choice 参数中指定其中一个工具的 name。

必需函数调用

vLLM 支持 chat completion API 中的 tool_choice='required' 选项。与命名函数调用类似，它也使用结构化输出，因此这是默认启用的，并且适用于任何支持的模型。然而，V1 引擎的 路线图 上支持其他解码后端。

当设置 tool_choice='required' 时，模型保证会根据 tools 参数中指定的工具列表生成一个或多个工具调用。工具调用的数量取决于用户的查询。输出格式严格遵循 tools 参数中定义的 schema。

无函数调用

vLLM 支持 chat completion API 中的 tool_choice='none' 选项。当设置此选项时，模型不会生成任何工具调用，并且只会以常规文本内容响应，即使请求中定义了工具。

注意

当请求中指定了工具时，vLLM 默认会在提示中包含工具定义，而不管 tool_choice 的设置。要排除 tool_choice='none' 时的工具定义，请使用 --exclude-tools-when-tool-choice-none 选项。

自动函数调用

要启用此功能，您应该设置以下标志

  • --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 文件中有与工具兼容的聊天模板，但您可以指定自定义模板。此参数可以设置为 tool_use，如果您的模型在 tokenizer_config.json 中配置了特定于工具使用的聊天模板。在这种情况下，它将按照 transformers 规范使用。更多信息 在此 来自 HuggingFace；您可以在 tokenizer_config.json 中找到一个示例。

如果您喜欢的工具调用模型不受支持，请随时贡献解析器和工具使用聊天模板！

Hermes Models (hermes)

所有比 Hermes 2 Pro 更新的 Nous Research Hermes 系列模型都应该得到支持。

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

请注意，Hermes 2 **Theta** 模型由于在创建过程中进行了合并，已知其工具调用质量和能力有所下降。.

Flags: --tool-call-parser hermes

Mistral Models (mistral)

支持的模型

  • mistralai/Mistral-7B-Instruct-v0.3 (已确认)
  • 其他 Mistral 函数调用模型也兼容。

已知问题

  1. Mistral 7B 在正确生成并行工具调用方面存在困难。

  2. **仅限 Transformers 分词后端**：Mistral 的 tokenizer_config.json 聊天模板需要完全是 9 位数字的工具调用 ID，这比 vLLM 生成的要短得多。由于当此条件不满足时会抛出异常，因此提供了以下附加聊天模板

推荐的标志

  1. 使用官方 Mistral AI 格式

    --tool-call-parser mistral

  2. 在可用时使用 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 官方发布的模型有两种可能的格式

  1. 使用 auto 或 mistral 参数默认使用的官方格式

    --tokenizer_mode mistral --config_format mistral --load_format mistral 此格式使用 mistral-common，即 Mistral AI 的分词器后端。

  2. 可用时使用 hf 参数的 Transformers 格式

    --tokenizer_mode hf --config_format hf --load_format hf --chat-template examples/tool_chat_template_mistral_parallel.jinja

Llama Models (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 工具调用，请参阅下方的 pythonic 工具解析器。至于 Llama 4 模型，推荐使用 llama4_pythonic 工具解析器。

不支持其他工具调用格式，如内置的 python 工具调用或自定义工具调用。

已知问题

  1. Llama 3 不支持并行工具调用，但 Llama 4 模型支持。
  2. 模型可能会生成格式不正确的参数，例如将数组生成为字符串而不是数组。

VLLM 为 Llama 3.1 和 3.2 提供了两个基于 JSON 的聊天模板

推荐的标志: --tool-call-parser llama3_json --chat-template {see_above}

VLLM 还为 Llama 4 提供了 pythonic 和基于 JSON 的聊天模板，但推荐使用 pythonic 工具调用。

对于 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 hermes

  • 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: 这是对 Hugging Face 上原始模板的修改，它不兼容 vLLM。它融合了 Hermes 模板中的函数描述元素，并遵循 论文 中“响应生成”模式相同的系统提示。支持并行函数调用。

InternLM Models (internlm)

支持的模型

  • internlm/internlm2_5-7b-chat (已确认)
  • 其他 internlm2.5 函数调用模型也兼容。

已知问题

  • 虽然此实现也支持 InternLM2，但在使用 internlm/internlm2-chat-7b 模型进行测试时，工具调用结果不稳定。

推荐的标志: --tool-call-parser internlm --chat-template examples/tool_chat_template_internlm2_tool.jinja

Jamba Models (jamba)

AI21 的 Jamba-1.5 模型得到支持。

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

Flags: --tool-call-parser jamba

xLAM Models (xlam)

xLAM 工具解析器旨在支持生成各种 JSON 格式工具调用的模型。它可以检测多种不同输出风格的函数调用。

  1. 直接 JSON 数组: 输出字符串为 JSON 数组，以 [ 开头，以 ] 结尾。
  2. 思考标签: 使用包含 JSON 数组的 <think>...</think> 标签。
  3. 代码块: JSON 在代码块中 (json ...)。
  4. 工具调用标签: 使用 [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

Flags

  • 对于基于 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 Models

对于 Qwen2.5，tokenizer_config.json 中的聊天模板已经包含了对 Hermes 风格工具使用的支持。因此，您可以使用 hermes 解析器来启用 Qwen 模型的工具调用。有关更详细的信息，请参阅官方 Qwen 文档。

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

Flags: --tool-call-parser hermes

MiniMax Models (minimax_m1)

支持的模型

Flags: --tool-call-parser minimax --chat-template examples/tool_chat_template_minimax_m1.jinja

DeepSeek-V3 Models (deepseek_v3)

支持的模型

Flags: --tool-call-parser deepseek_v3 --chat-template {see_above}

DeepSeek-V3.1 Models (deepseek_v31)

支持的模型

Flags: --tool-call-parser deepseek_v31 --chat-template {see_above}

Kimi-K2 Models (kimi_k2)

支持的模型

  • moonshotai/Kimi-K2-Instruct

Flags: --tool-call-parser kimi_k2

Hunyuan Models (hunyuan_a13b)

支持的模型

  • tencent/Hunyuan-A13B-Instruct (聊天模板已包含在 Hugging Face 模型文件中。)

Flags

  • 对于非推理: --tool-call-parser hunyuan_a13b
  • 对于推理: --tool-call-parser hunyuan_a13b --reasoning-parser hunyuan_a13b

LongCat-Flash-Chat Models (longcat)

支持的模型

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

Flags: --tool-call-parser longcat

GLM-4.5 Models (glm45)

支持的模型

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

Flags: --tool-call-parser glm45

GLM-4.7 Models (glm47)

支持的模型

  • zai-org/GLM-4.7

Flags: --tool-call-parser glm47

Qwen3-Coder Models (qwen3_xml)

支持的模型

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

Flags: --tool-call-parser qwen3_xml

Olmo 3 Models (olmo3)

Olmo 3 模型以与 pythonic 解析器预期格式非常相似的格式输出工具调用（见下文），但有一些区别。每个工具调用都是一个 pythonic 字符串，但并行工具调用由换行符分隔，调用被包装在 XML 标签内，如 <function_calls>..</function_calls>。此外，除了 pythonic 字面量 (True, False, 和 None) 之外，解析器还允许 JSON 布尔值和 null 字面量 (true, false, 和 null)。

支持的模型

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

Flags: --tool-call-parser olmo3

Gigachat 3 Models (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

Flags: --tool-call-parser gigachat3

Models with Pythonic Tool Calls (pythonic)

越来越多的模型使用 Python 列表来表示工具调用，而不是使用 JSON。这具有内在支持并行工具调用并消除 JSON schema 对工具调用的歧义的优势。pythonic 工具解析器可以支持此类模型。

作为具体示例，这些模型可以通过生成以下内容来查找旧金山和西雅图的天气：

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

限制

  • 模型在同一次生成中不得同时生成文本和工具调用。这对于特定模型来说可能不难更改，但社区目前在开始和结束工具调用时应发出哪些 token 方面缺乏共识。（特别是，Llama 3.2 模型不发出任何此类 token。）
  • Llama 的较小模型在有效使用工具方面存在困难。

支持的示例模型

Flags: --tool-call-parser pythonic --chat-template {see_above}

警告

Llama 的较小模型经常无法以正确的格式发出工具调用。结果可能因模型而异。

如何编写工具解析器插件

工具解析器插件是一个包含一个或多个 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) -> ChatCompletionRequest:
        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> \