[Core] Move multimodal placeholder from chat utils to model definition #20355

DarkLight1337 · 2025-07-02T06:52:15Z

Essential Elements of an Effective PR Description Checklist

The purpose of the PR, such as "Fix some issue (link existing issues this PR will resolve)".
The test plan, such as providing test command.
The test results, such as pasting the results comparison before and after, or e2e results
(Optional) The necessary documentation update, such as updating supported_models.md and examples for a new model.

Purpose

This PR introduces SupportsMultiModal.get_placeholder_str so we don't have to add the placeholder token in chat_utils.py separately (which is very easy to forget) for new models to work in online serving.

Follow-up to #20105

Test Plan

Test Result

(Optional) Documentation Update

Update the New Model guide with instructions to implement SupportsMultiModal.get_placeholder_str.

Signed-off-by: DarkLight1337 <tlleungac@connect.ust.hk>

DarkLight1337 · 2025-07-02T06:52:57Z

vllm/config.py

@@ -661,7 +661,7 @@ def architecture(self) -> str:
        return self._architecture

    @property
-    def model_info(self) -> dict[str, Any]:


The type annotation is incorrect, so I removed it

gemini-code-assist

Summary of Changes

Hello @DarkLight1337, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a significant refactoring effort aimed at improving the modularity and maintainability of multimodal and transcription model logic. The core change involves decentralizing model-specific placeholder string generation and transcription utility methods from shared utility files into their respective model class definitions. This approach makes it easier to add new models and ensures that model-specific behaviors are co-located with their implementations.

Highlights

Refactoring Multimodal Placeholder Logic: The centralized _placeholder_str function in vllm/entrypoints/chat_utils.py, which contained the logic for determining multimodal placeholder strings (e.g., <image>, <audio>) for all models, has been removed.
Model-Specific Placeholder Definition: Each model class that implements the SupportsMultiModal interface now includes a new @classmethod called get_placeholder_str. This method is responsible for returning the correct placeholder string specific to that model and its supported modalities, encapsulating the logic directly within the model definition.
Updated MultiModal Interface: The SupportsMultiModal protocol in vllm/model_executor/models/interfaces.py has been updated to include the get_placeholder_str method, enforcing that all conforming multimodal models provide this functionality.
Refactoring Transcription Logic: Following a similar pattern, the validate_language and get_decoder_prompt methods for transcription models (specifically the Whisper model) have been moved from vllm/entrypoints/openai/speech_to_text.py into the WhisperForConditionalGeneration model class itself, improving modularity and consistency.
New Model Class Helper: A new helper function, get_model_cls, has been introduced in vllm/model_executor/model_loader/utils.py to simplify the process of retrieving the model class from a ModelConfig.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

vllm/entrypoints/chat_utils.py

gemini-code-assist

Code Review

This pull request is a significant and valuable refactoring that moves the responsibility of providing multimodal placeholder strings from a centralized utility in chat_utils.py to the individual model definitions. This greatly improves modularity and makes the codebase cleaner and easier to maintain, especially for adding new multimodal models.

My review focuses on ensuring the correctness of this refactoring. I've found one likely bug where a placeholder string seems to have been copied incorrectly, and I've also pointed out a couple of areas where the changes, while simplifying the code, might reduce type safety or robustness. Overall, the changes are a positive step forward for the project's architecture.

gemini-code-assist · 2025-07-02T06:55:10Z

vllm/model_executor/models/glm4v.py

+    @classmethod
+    def get_placeholder_str(cls, modality: str, i: int) -> Optional[str]:
+        if modality.startswith("image"):
+            return "<|begin_of_image|><|endoftext|><|end_of_image|>"


gemini-code-assist · 2025-07-02T06:55:11Z

vllm/config.py

@@ -661,7 +661,7 @@ def architecture(self) -> str:
        return self._architecture

    @property
-    def model_info(self) -> dict[str, Any]:
+    def model_info(self):


The type hint for the model_info property was removed. For better code clarity and type safety, it's recommended to restore it. The property returns self._model_info, which is a dictionary, so -> dict[str, Any] would be the correct type hint.

Suggested change

def model_info(self):

def model_info(self) -> dict[str, Any]:

gemini-code-assist · 2025-07-02T06:55:11Z

vllm/model_executor/models/llava.py

+        if modality.startswith("image"):
+            return "<image>"


This change hardcodes the image placeholder to <image>. The previous implementation dynamically resolved it from the tokenizer using hf_config.image_token_index. While this simplification removes the dependency on the tokenizer instance, it introduces a risk of incorrect behavior if a LLaVA variant uses a different special token for images. This is a behavior change that reduces robustness.

Signed-off-by: DarkLight1337 <tlleungac@connect.ust.hk>

Isotr0py

Overall LGTM! Thanks for cleaning up this!

vllm/entrypoints/chat_utils.py

Signed-off-by: DarkLight1337 <tlleungac@connect.ust.hk>

github-actions · 2025-07-02T07:24:29Z

👋 Hi! Thank you for contributing to the vLLM project.

💬 Join our developer Slack at https://slack.vllm.ai to discuss your PR in #pr-reviews, coordinate on features in #feat- channels, or join special interest groups in #sig- channels.

Just a reminder: PRs would not trigger full CI run by default. Instead, it would only run fastcheck CI which starts running only a small and essential subset of CI tests to quickly catch errors. You can run other CI tests on top of those by going to your fastcheck build on Buildkite UI (linked in the PR checks section) and unblock them. If you do not have permission to unblock, ping simon-mo or khluu to add you in our Buildkite org.

Once the PR is approved and ready to go, your PR reviewer(s) can run CI to test the changes comprehensively before merging.

To run CI, PR reviewers can either: Add ready label to the PR or enable auto-merge.

🚀

huachenheli · 2025-07-02T16:04:57Z

vllm/entrypoints/openai/speech_to_text.py

@@ -88,12 +92,14 @@ async def _preprocess_speech_to_text(
        request: SpeechToTextRequest,
        audio_data: bytes,
    ) -> tuple[list[PromptType], float]:
+        model_cls = self.model_cls


Is this change needed?

It avoids the need to type: ignore

Signed-off-by: DarkLight1337 <tlleungac@connect.ust.hk>

Signed-off-by: Kyle Huang <kylhuang@nvidia.com>

vllm-project#20355) Signed-off-by: DarkLight1337 <tlleungac@connect.ust.hk>

vllm-project#20355) Signed-off-by: DarkLight1337 <tlleungac@connect.ust.hk> Signed-off-by: avigny <47987522+avigny@users.noreply.github.com>

vllm-project#20355) Signed-off-by: DarkLight1337 <tlleungac@connect.ust.hk>

vllm-project#20355) Signed-off-by: DarkLight1337 <tlleungac@connect.ust.hk> Signed-off-by: Jinzhen Lin <linjinzhen@hotmail.com>

vllm-project#20355) Signed-off-by: DarkLight1337 <tlleungac@connect.ust.hk>

[Core] Move multimodal placeholder from chat utils to model definition

2ff7f01

Signed-off-by: DarkLight1337 <tlleungac@connect.ust.hk>

DarkLight1337 requested review from simon-mo, WoosukKwon, youkaichao, robertgshaw2-redhat, mgoin, tlrmchlsmth, houseroad, hmellor and aarnphm as code owners July 2, 2025 06:52

DarkLight1337 requested a review from Isotr0py July 2, 2025 06:52

DarkLight1337 added this to Multi-modality Core Jul 2, 2025

DarkLight1337 moved this to In Progress in Multi-modality Core Jul 2, 2025

mergify bot added frontend llama Related to Llama models qwen Related to Qwen models labels Jul 2, 2025

DarkLight1337 commented Jul 2, 2025

View reviewed changes

gemini-code-assist bot reviewed Jul 2, 2025

View reviewed changes

DarkLight1337 commented Jul 2, 2025

View reviewed changes

vllm/entrypoints/chat_utils.py Outdated Show resolved Hide resolved

gemini-code-assist bot reviewed Jul 2, 2025

View reviewed changes

DarkLight1337 added 2 commits July 2, 2025 06:59

Update docs

5d17de9

Signed-off-by: DarkLight1337 <tlleungac@connect.ust.hk>

Fix

8edeafb

Signed-off-by: DarkLight1337 <tlleungac@connect.ust.hk>

mergify bot added the documentation Improvements or additions to documentation label Jul 2, 2025

Fix

d6eaa0f

Signed-off-by: DarkLight1337 <tlleungac@connect.ust.hk>

Isotr0py approved these changes Jul 2, 2025

View reviewed changes

vllm/entrypoints/chat_utils.py Show resolved Hide resolved

DarkLight1337 added 2 commits July 2, 2025 07:02

Fix missing impl in glm4_1v.py

a7dfbb4

Signed-off-by: DarkLight1337 <tlleungac@connect.ust.hk>

Fix

bf85182

Signed-off-by: DarkLight1337 <tlleungac@connect.ust.hk>

mergify bot added the deepseek Related to DeepSeek models label Jul 2, 2025

huachenheli reviewed Jul 2, 2025

View reviewed changes

DarkLight1337 added 2 commits July 2, 2025 16:06

Remove --mm-placeholder-str-override

b0f7895

Signed-off-by: DarkLight1337 <tlleungac@connect.ust.hk>

Merge branch 'main' into placeholder-str-cls

80f0728

DarkLight1337 requested a review from njhill as a code owner July 2, 2025 16:07

DarkLight1337 enabled auto-merge (squash) July 2, 2025 16:07

github-actions bot added the ready ONLY add when PR is ready to merge/full CI is needed label Jul 2, 2025

DarkLight1337 and others added 4 commits July 3, 2025 03:10

Update

b59c3cc

Signed-off-by: DarkLight1337 <tlleungac@connect.ust.hk>

Merge branch 'main' into placeholder-str-cls

3eb629e

Update speech_to_text.py

28bc6ed

Update chat_utils.py

8c8e279

DarkLight1337 merged commit b024a42 into vllm-project:main Jul 3, 2025
78 checks passed

DarkLight1337 deleted the placeholder-str-cls branch July 3, 2025 08:18

github-project-automation bot moved this from In Progress to Done in Multi-modality Core Jul 3, 2025

DarkLight1337 mentioned this pull request Jul 3, 2025

[VLM] Add Nemotron-Nano-VL-8B-V1 support #20349

Merged

kylehh added a commit to kylehh/vllm that referenced this pull request Jul 3, 2025

update the model according to vllm-project#20355

705a72e

Signed-off-by: Kyle Huang <kylhuang@nvidia.com>

sfeng33 pushed a commit to sfeng33/vllm that referenced this pull request Jul 6, 2025

[Core] Move multimodal placeholder from chat utils to model definition (

34c79e0

vllm-project#20355) Signed-off-by: DarkLight1337 <tlleungac@connect.ust.hk>

huydhn pushed a commit to huydhn/vllm that referenced this pull request Jul 8, 2025

[Core] Move multimodal placeholder from chat utils to model definition (

c51ec66

vllm-project#20355) Signed-off-by: DarkLight1337 <tlleungac@connect.ust.hk>

LyrisZhong pushed a commit to LyrisZhong/vllm that referenced this pull request Jul 23, 2025

[Core] Move multimodal placeholder from chat utils to model definition (

e7b6fb9

vllm-project#20355) Signed-off-by: DarkLight1337 <tlleungac@connect.ust.hk>

Pradyun92 pushed a commit to Pradyun92/vllm that referenced this pull request Aug 6, 2025

[Core] Move multimodal placeholder from chat utils to model definition (

6fd4648

vllm-project#20355) Signed-off-by: DarkLight1337 <tlleungac@connect.ust.hk>

googlercolin pushed a commit to googlercolin/vllm that referenced this pull request Aug 29, 2025

[Core] Move multimodal placeholder from chat utils to model definition (

318787a

vllm-project#20355) Signed-off-by: DarkLight1337 <tlleungac@connect.ust.hk>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

[Core] Move multimodal placeholder from chat utils to model definition #20355

[Core] Move multimodal placeholder from chat utils to model definition #20355

Uh oh!

DarkLight1337 commented Jul 2, 2025 •

edited by github-actions bot

Loading

Uh oh!

DarkLight1337 Jul 2, 2025

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot Jul 2, 2025

Uh oh!

gemini-code-assist bot Jul 2, 2025

Uh oh!

gemini-code-assist bot Jul 2, 2025

Uh oh!

Isotr0py left a comment

Uh oh!

Uh oh!

github-actions bot commented Jul 2, 2025

Uh oh!

huachenheli Jul 2, 2025

Uh oh!

DarkLight1337 Jul 2, 2025

Uh oh!

Uh oh!

Uh oh!

	return "<\|begin_of_image\|><\|endoftext\|><\|end_of_image\|>"
	return "<\|begin_of_image\|><\|image\|><\|end_of_image\|>"

	def model_info(self):
	def model_info(self) -> dict[str, Any]:

Uh oh!

[Core] Move multimodal placeholder from chat utils to model definition #20355

[Core] Move multimodal placeholder from chat utils to model definition #20355

Uh oh!

Conversation

DarkLight1337 commented Jul 2, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Essential Elements of an Effective PR Description Checklist

Purpose

Test Plan

Test Result

(Optional) Documentation Update

Uh oh!

DarkLight1337 Jul 2, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Summary of Changes

Highlights

Footnotes

Uh oh!

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Jul 2, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jul 2, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jul 2, 2025

Choose a reason for hiding this comment

Uh oh!

Isotr0py left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Jul 2, 2025

Uh oh!

huachenheli Jul 2, 2025

Choose a reason for hiding this comment

Uh oh!

DarkLight1337 Jul 2, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

DarkLight1337 commented Jul 2, 2025 •

edited by github-actions bot

Loading