[Refactor] Lazy import tool_parser

docs/features/tool_calling.md

@@ -407,7 +407,6 @@ Here is a summary of a plugin file:
     # the name list in register_module can be used
     # in --tool-call-parser. you can define as many
     # tool parsers as you want here.
-    @ToolParserManager.register_module(["example"])
     class ExampleToolParser(ToolParser):
         def __init__(self, tokenizer: AnyTokenizer):
             super().__init__(tokenizer)
@@ -439,6 +438,12 @@ Here is a summary of a plugin file:
             return ExtractedToolCallInformation(tools_called=False,
                                                 tool_calls=[],
                                                 content=text)
+    # register the tool parser to ToolParserManager
+    ToolParserManager.register_lazy_module(
+        name="example",
+        module_path="vllm.entrypoints.openai.tool_parsers.example",
+        class_name="ExampleToolParser",
+    )
 
     ```
 

tests/tool_use/test_deepseekv31_tool_parser.py

@@ -3,7 +3,9 @@
 
 import pytest
 
-from vllm.entrypoints.openai.tool_parsers import DeepSeekV31ToolParser
+from vllm.entrypoints.openai.tool_parsers.deepseekv31_tool_parser import (
+    DeepSeekV31ToolParser,
+)
 from vllm.transformers_utils.tokenizer import get_tokenizer
 
 MODEL = "deepseek-ai/DeepSeek-V3.1"

tests/tool_use/test_ernie45_moe_tool_parser.py

@@ -13,7 +13,7 @@
     FunctionCall,
     ToolCall,
 )
-from vllm.entrypoints.openai.tool_parsers import Ernie45ToolParser
+from vllm.entrypoints.openai.tool_parsers.ernie45_tool_parser import Ernie45ToolParser
 from vllm.transformers_utils.detokenizer_utils import detokenize_incrementally
 from vllm.transformers_utils.tokenizer import AnyTokenizer, get_tokenizer
 

tests/tool_use/test_glm4_moe_tool_parser.py

@@ -7,7 +7,9 @@
 import pytest
 
 from vllm.entrypoints.openai.protocol import FunctionCall, ToolCall
-from vllm.entrypoints.openai.tool_parsers import Glm4MoeModelToolParser
+from vllm.entrypoints.openai.tool_parsers.glm4_moe_tool_parser import (
+    Glm4MoeModelToolParser,
+)
 from vllm.transformers_utils.tokenizer import get_tokenizer
 
 pytestmark = pytest.mark.cpu_test

tests/tool_use/test_jamba_tool_parser.py

@@ -9,7 +9,7 @@
 from partial_json_parser.core.options import Allow
 
 from vllm.entrypoints.openai.protocol import DeltaMessage, FunctionCall, ToolCall
-from vllm.entrypoints.openai.tool_parsers import JambaToolParser
+from vllm.entrypoints.openai.tool_parsers.jamba_tool_parser import JambaToolParser
 from vllm.transformers_utils.detokenizer_utils import detokenize_incrementally
 from vllm.transformers_utils.tokenizer import AnyTokenizer, get_tokenizer
 

tests/tool_use/test_kimi_k2_tool_parser.py

@@ -7,7 +7,7 @@
 import pytest
 
 from vllm.entrypoints.openai.protocol import FunctionCall, ToolCall
-from vllm.entrypoints.openai.tool_parsers import KimiK2ToolParser
+from vllm.entrypoints.openai.tool_parsers.kimi_k2_tool_parser import KimiK2ToolParser
 from vllm.transformers_utils.tokenizer import get_tokenizer
 
 pytestmark = pytest.mark.cpu_test

tests/tool_use/test_minimax_tool_parser.py

@@ -12,7 +12,7 @@
     FunctionCall,
     ToolCall,
 )
-from vllm.entrypoints.openai.tool_parsers import MinimaxToolParser
+from vllm.entrypoints.openai.tool_parsers.minimax_tool_parser import MinimaxToolParser
 from vllm.transformers_utils.tokenizer import get_tokenizer
 
 pytestmark = pytest.mark.cpu_test

tests/tool_use/test_openai_tool_parser.py

@@ -15,7 +15,7 @@
 )
 
 from vllm.entrypoints.openai.protocol import FunctionCall, ToolCall
-from vllm.entrypoints.openai.tool_parsers import OpenAIToolParser
+from vllm.entrypoints.openai.tool_parsers.openai_tool_parser import OpenAIToolParser
 from vllm.transformers_utils.tokenizer import get_tokenizer
 
 MODEL = "gpt2"

tests/tool_use/test_seed_oss_tool_parser.py

@@ -14,7 +14,7 @@
     FunctionCall,
     ToolCall,
 )
-from vllm.entrypoints.openai.tool_parsers import SeedOssToolParser
+from vllm.entrypoints.openai.tool_parsers.seed_oss_tool_parser import SeedOssToolParser
 from vllm.transformers_utils.detokenizer_utils import detokenize_incrementally
 from vllm.transformers_utils.tokenizer import AnyTokenizer, get_tokenizer
 

tests/tool_use/test_xlam_tool_parser.py

@@ -12,7 +12,7 @@
     FunctionCall,
     ToolCall,
 )
-from vllm.entrypoints.openai.tool_parsers import xLAMToolParser
+from vllm.entrypoints.openai.tool_parsers.xlam_tool_parser import xLAMToolParser
 from vllm.transformers_utils.detokenizer_utils import detokenize_incrementally
 from vllm.transformers_utils.tokenizer import AnyTokenizer, get_tokenizer
 

vllm/entrypoints/openai/api_server.py

@@ -1928,7 +1928,7 @@ def create_server_unix_socket(path: str) -> socket.socket:
 
 
 def validate_api_server_args(args):
-    valid_tool_parses = ToolParserManager.tool_parsers.keys()
+    valid_tool_parses = ToolParserManager.list_registered()
     if args.enable_auto_tool_choice and args.tool_call_parser not in valid_tool_parses:
         raise KeyError(
             f"invalid tool call parser: {args.tool_call_parser} "

vllm/entrypoints/openai/cli_args.py

@@ -219,7 +219,7 @@ def add_cli_args(parser: FlexibleArgumentParser) -> FlexibleArgumentParser:
         frontend_kwargs["middleware"]["default"] = []
 
         # Special case: Tool call parser shows built-in options.
-        valid_tool_parsers = list(ToolParserManager.tool_parsers.keys())
+        valid_tool_parsers = list(ToolParserManager.list_registered())
         parsers_str = ",".join(valid_tool_parsers)
         frontend_kwargs["tool_call_parser"]["metavar"] = (
             f"{{{parsers_str}}} or name registered in --tool-parser-plugin"

vllm/entrypoints/openai/tool_parsers/__init__.py

@@ -1,61 +1,142 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
 
-from .abstract_tool_parser import ToolParser, ToolParserManager
-from .deepseekv3_tool_parser import DeepSeekV3ToolParser
-from .deepseekv31_tool_parser import DeepSeekV31ToolParser
-from .ernie45_tool_parser import Ernie45ToolParser
-from .glm4_moe_tool_parser import Glm4MoeModelToolParser
-from .granite_20b_fc_tool_parser import Granite20bFCToolParser
-from .granite_tool_parser import GraniteToolParser
-from .hermes_tool_parser import Hermes2ProToolParser
-from .hunyuan_a13b_tool_parser import HunyuanA13BToolParser
-from .internlm2_tool_parser import Internlm2ToolParser
-from .jamba_tool_parser import JambaToolParser
-from .kimi_k2_tool_parser import KimiK2ToolParser
-from .llama4_pythonic_tool_parser import Llama4PythonicToolParser
-from .llama_tool_parser import Llama3JsonToolParser
-from .longcat_tool_parser import LongcatFlashToolParser
-from .minimax_m2_tool_parser import MinimaxM2ToolParser
-from .minimax_tool_parser import MinimaxToolParser
-from .mistral_tool_parser import MistralToolParser
-from .olmo3_tool_parser import Olmo3PythonicToolParser
-from .openai_tool_parser import OpenAIToolParser
-from .phi4mini_tool_parser import Phi4MiniJsonToolParser
-from .pythonic_tool_parser import PythonicToolParser
-from .qwen3coder_tool_parser import Qwen3CoderToolParser
-from .qwen3xml_tool_parser import Qwen3XMLToolParser
-from .seed_oss_tool_parser import SeedOssToolParser
-from .step3_tool_parser import Step3ToolParser
-from .xlam_tool_parser import xLAMToolParser
-
-__all__ = [
-    "ToolParser",
-    "ToolParserManager",
-    "Granite20bFCToolParser",
-    "GraniteToolParser",
-    "Hermes2ProToolParser",
-    "MistralToolParser",
-    "Internlm2ToolParser",
-    "Llama3JsonToolParser",
-    "JambaToolParser",
-    "Llama4PythonicToolParser",
-    "LongcatFlashToolParser",
-    "PythonicToolParser",
-    "Phi4MiniJsonToolParser",
-    "DeepSeekV3ToolParser",
-    "DeepSeekV31ToolParser",
-    "Ernie45ToolParser",
-    "xLAMToolParser",
-    "Olmo3PythonicToolParser",
-    "MinimaxToolParser",
-    "KimiK2ToolParser",
-    "HunyuanA13BToolParser",
-    "Glm4MoeModelToolParser",
-    "Qwen3CoderToolParser",
-    "Qwen3XMLToolParser",
-    "SeedOssToolParser",
-    "Step3ToolParser",
-    "OpenAIToolParser",
-    "MinimaxM2ToolParser",
-]
+from vllm.entrypoints.openai.tool_parsers.abstract_tool_parser import (
+    ToolParser,
+    ToolParserManager,
+)
+
+__all__ = ["ToolParser", "ToolParserManager"]
+
+
+"""
+Register a lazy module mapping.
+
+Example:
+    ToolParserManager.register_lazy_module(
+        name="kimi_k2",
+        module_path="vllm.entrypoints.openai.tool_parsers.kimi_k2_parser",
+        class_name="KimiK2ToolParser",
+    )
+"""
+
+
+_TOOL_PARSERS_TO_REGISTER = {
+    "deepseek_v3": (  # name
+        "deepseekv3_tool_parser",  # filename
+        "DeepSeekV3ToolParser",  # class_name
+    ),
+    "deepseek_v31": (
+        "deepseekv31_tool_parser",
+        "DeepSeekV31ToolParser",
+    ),
+    "ernie45": (
+        "ernie45_tool_parser",
+        "Ernie45ToolParser",
+    ),
+    "glm45": (
+        "glm4_moe_tool_parser",
+        "Glm4MoeModelToolParser",
+    ),
+    "granite-20b-fc": (
+        "granite_20b_fc_tool_parser",
+        "Granite20bFCToolParser",
+    ),
+    "granite": (
+        "granite_tool_parser",
+        "GraniteToolParser",
+    ),
+    "hermes": (
+        "hermes_tool_parser",
+        "Hermes2ProToolParser",
+    ),
+    "hunyuan_a13b": (
+        "hunyuan_a13b_tool_parser",
+        "HunyuanA13BToolParser",
+    ),
+    "internlm": (
+        "internlm2_tool_parser",
+        "Internlm2ToolParser",
+    ),
+    "jamba": (
+        "jamba_tool_parser",
+        "JambaToolParser",
+    ),
+    "kimi_k2": (
+        "kimi_k2_tool_parser",
+        "KimiK2ToolParser",
+    ),
+    "llama3_json": (
+        "llama_tool_parser",
+        "Llama3JsonToolParser",
+    ),
+    "llama4_json": (
+        "llama_tool_parser",
+        "Llama4JsonToolParser",
+    ),
+    "llama4_pythonic": (
+        "llama4_pythonic_tool_parser",
+        "Llama4PythonicToolParser",
+    ),
+    "longcat": (
+        "longcat_tool_parser",
+        "LongcatFlashToolParser",
+    ),
+    "minimax_m2": (
+        "minimax_m2_tool_parser",
+        "MinimaxM2ToolParser",
+    ),
+    "minimax": (
+        "minimax_tool_parser",
+        "MinimaxToolParser",
+    ),
+    "mistral": (
+        "mistral_tool_parser",
+        "MistralToolParser",
+    ),
+    "olmo3": (
+        "olmo3_tool_parser",
+        "Olmo3PythonicToolParser",
+    ),
+    "openai": (
+        "openai_tool_parser",
+        "OpenAIToolParser",
+    ),
+    "phi4_mini_json": (
+        "phi4mini_tool_parser",
+        "Phi4MiniJsonToolParser",
+    ),
+    "pythonic": (
+        "pythonic_tool_parser",
+        "PythonicToolParser",
+    ),
+    "qwen3_coder": (
+        "qwen3coder_tool_parser",
+        "Qwen3CoderToolParser",
+    ),
+    "qwen3_xml": (
+        "qwen3xml_tool_parser",
+        "Qwen3XmlToolParser",
+    ),
+    "seed_oss": (
+        "seed_oss_tool_parser",
+        "SeedOsSToolParser",
+    ),
+    "step3": (
+        "step3_tool_parser",
+        "Step3ToolParser",
+    ),
+    "xlam": (
+        "xlam_tool_parser",
+        "xLAMToolParser",
+    ),
+}
+
+
+def register_lazy_tool_parsers():
+    for name, (file_name, class_name) in _TOOL_PARSERS_TO_REGISTER.items():
+        module_path = f"vllm.entrypoints.openai.tool_parsers.{file_name}"
+        ToolParserManager.register_lazy_module(name, module_path, class_name)
+
+
+register_lazy_tool_parsers()