[Bugfix] Respect num-gpu-blocks-override in v1 #19503

jmswen · 2025-06-11T18:04:45Z

Purpose

This PR ensures that --num-gpu-blocks-override is respected in v1. This option is useful for testing preemption and CPU KV cache offloading via a custom KV connector.

Test Plan

Added test case to tests/v1/core/test_kv_cache_utils.py::test_get_kv_cache_config:

pytest -s -vv tests/v1/core/test_kv_cache_utils.py::test_get_kv_cache_config

Also, run vllm serve with --num-gpu-blocks-override 100 and custom CPU KV cache connector.

Test Result

Unit test tests/v1/core/test_kv_cache_utils.py::test_get_kv_cache_config passes.

vLLM logs now reflect correct GPU KV cache size, and CPU KV cache kicks in within just a few requests, as expected.

Before:

(VllmWorker rank=0 pid=3947788) INFO 06-11 10:47:43 [gpu_worker.py:227] Available KV cache memory: 81.38 GiB                             
INFO 06-11 10:47:44 [kv_cache_utils.py:660] Overriding num_gpu_blocks=333325 with num_gpu_blocks_override=100                             INFO 06-11 10:47:44 [kv_cache_utils.py:715] GPU KV cache size: 5,333,200 tokens                              
INFO 06-11 10:47:44 [kv_cache_utils.py:719] Maximum concurrency for 131,072 tokens per request: 40.69x                                    INFO 06-11 10:47:44 [kv_cache_utils.py:660] Overriding num_gpu_blocks=333325 with num_gpu_blocks_override=100
INFO 06-11 10:47:44 [kv_cache_utils.py:715] GPU KV cache size: 5,333,200 tokens                                                           INFO 06-11 10:47:44 [kv_cache_utils.py:719] Maximum concurrency for 131,072 tokens per request: 40.69x

After:

(VllmWorker rank=1 pid=125313) INFO 06-11 10:55:07 [gpu_worker.py:227] Available KV cache memory: 81.38 GiB
INFO 06-11 10:55:07 [kv_cache_utils.py:660] Overriding num_gpu_blocks=333325 with num_gpu_blocks_override=100                            
INFO 06-11 10:55:07 [kv_cache_utils.py:716] GPU KV cache size: 1,600 tokens                                                              
INFO 06-11 10:55:07 [kv_cache_utils.py:720] Maximum concurrency for 131,072 tokens per request: 0.01x                                     INFO 06-11 10:55:07 [kv_cache_utils.py:660] Overriding num_gpu_blocks=333325 with num_gpu_blocks_override=100
INFO 06-11 10:55:07 [kv_cache_utils.py:716] GPU KV cache size: 1,600 tokens                                                               INFO 06-11 10:55:07 [kv_cache_utils.py:720] Maximum concurrency for 131,072 tokens per request: 0.01x

github-actions · 2025-06-11T18:04:55Z

👋 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.

🚀

gemini-code-assist

Summary of Changes

Hello @jmswen, 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 addresses a bug in the v1 core component of VLLM where the user-provided override for the number of GPU blocks (num-gpu-blocks-override) was not being respected. The change ensures that when this override is specified, it takes precedence over the automatically calculated number of blocks, allowing users to control KV cache allocation as intended.

Highlights

Bugfix: Configuration Override: Fixed a bug in the v1 core logic where the num-gpu-blocks-override configuration was not being correctly applied, preventing users from explicitly setting the number of GPU blocks for the KV cache.

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 configureGemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request addresses a bug where num_gpu_blocks_override was not being respected in v1. The change in get_num_blocks correctly returns the override value when it's provided.

To improve the pull request and ensure its quality:

Please complete the PR description template. Sections like "Purpose", "Test Plan", and "Test Result" are essential for reviewers to understand the context, the fix, and how it was verified. This also helps with future maintenance and understanding of the change.
For bugfixes, it's particularly important to include a test plan and test results, or at least a description of how the fix was tested (e.g., manual testing steps, new or existing unit/integration tests). This helps confirm that the bug is resolved and reduces the risk of regressions.

vllm/v1/core/kv_cache_utils.py

Signed-off-by: Jon Swenson <jmswen@gmail.com>

vllm/v1/core/kv_cache_utils.py

houseroad

Looks good. Wondering if we can add some unittest to cover it.

Signed-off-by: Jon Swenson <jmswen@gmail.com>

gemini-code-assist · 2025-06-12T04:27:59Z

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

jmswen · 2025-06-12T04:46:08Z

@houseroad Done, added a test case to tests/v1/core/test_kv_cache_utils.py::test_get_kv_cache_config.

vLLM v0.9.1 contains a bug that causes vllm-spyre to hang on boot-up. The bug is not respecting `num_gpu_blocks_overrides`. It was introduced in vllm-project/vllm#17996 and fixed in vllm-project/vllm#19503. --------- Signed-off-by: Travis Johnson <tsjohnso@us.ibm.com>

Signed-off-by: Jon Swenson <jmswen@gmail.com> Signed-off-by: minpeter <kali2005611@gmail.com>

Signed-off-by: Jon Swenson <jmswen@gmail.com>

Signed-off-by: Jon Swenson <jmswen@gmail.com> Signed-off-by: avigny <47987522+avigny@users.noreply.github.com>

Signed-off-by: Jon Swenson <jmswen@gmail.com>

gemini-code-assist bot reviewed Jun 11, 2025

View reviewed changes

mergify bot added the v1 label Jun 11, 2025

gemini-code-assist bot reviewed Jun 11, 2025

View reviewed changes

vllm/v1/core/kv_cache_utils.py Outdated Show resolved Hide resolved

[Bugfix] Respect num-gpu-blocks-override in v1

79fcfc9

Signed-off-by: Jon Swenson <jmswen@gmail.com>

jmswen force-pushed the block-override branch from 857d1f6 to 79fcfc9 Compare June 11, 2025 18:07

jmswen marked this pull request as ready for review June 11, 2025 18:15

jmswen requested review from WoosukKwon, robertgshaw2-redhat, njhill, ywang96, comaniac and alexm-redhat as code owners June 11, 2025 18:15

houseroad reviewed Jun 12, 2025

View reviewed changes

vllm/v1/core/kv_cache_utils.py Outdated Show resolved Hide resolved

houseroad approved these changes Jun 12, 2025

View reviewed changes

houseroad added the ready ONLY add when PR is ready to merge/full CI is needed label Jun 12, 2025

address comment, add test

6e6ac8f

Signed-off-by: Jon Swenson <jmswen@gmail.com>

houseroad enabled auto-merge (squash) June 12, 2025 06:47

houseroad merged commit c9280e6 into vllm-project:main Jun 12, 2025
66 checks passed

jmswen deleted the block-override branch June 12, 2025 12:50

tjohnson31415 mentioned this pull request Jun 12, 2025

Exclude vllm v0.9.1 as an allowed version due to breaking bug vllm-project/vllm-spyre#232

Merged

minpeter pushed a commit to minpeter/vllm that referenced this pull request Jun 24, 2025

[Bugfix] Respect num-gpu-blocks-override in v1 (vllm-project#19503)

849eb1f

Signed-off-by: Jon Swenson <jmswen@gmail.com> Signed-off-by: minpeter <kali2005611@gmail.com>

xjpang pushed a commit to xjpang/vllm that referenced this pull request Jun 30, 2025

[Bugfix] Respect num-gpu-blocks-override in v1 (vllm-project#19503)

d1c2f8a

Signed-off-by: Jon Swenson <jmswen@gmail.com>

wseaton pushed a commit to wseaton/vllm that referenced this pull request Jun 30, 2025

[Bugfix] Respect num-gpu-blocks-override in v1 (vllm-project#19503)

bc2991c

Signed-off-by: Jon Swenson <jmswen@gmail.com>

avigny pushed a commit to avigny/vllm that referenced this pull request Jul 31, 2025

[Bugfix] Respect num-gpu-blocks-override in v1 (vllm-project#19503)

d262a0f

Signed-off-by: Jon Swenson <jmswen@gmail.com> Signed-off-by: avigny <47987522+avigny@users.noreply.github.com>

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

[Bugfix] Respect num-gpu-blocks-override in v1 (vllm-project#19503)

f336772

Signed-off-by: Jon Swenson <jmswen@gmail.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

[Bugfix] Respect num-gpu-blocks-override in v1 #19503

[Bugfix] Respect num-gpu-blocks-override in v1 #19503

Uh oh!

jmswen commented Jun 11, 2025 •

edited by github-actions bot

Loading

Uh oh!

github-actions bot commented Jun 11, 2025

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

Uh oh!

Uh oh!

houseroad left a comment

Uh oh!

gemini-code-assist bot commented Jun 12, 2025

Uh oh!

jmswen commented Jun 12, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

[Bugfix] Respect num-gpu-blocks-override in v1 #19503

[Bugfix] Respect num-gpu-blocks-override in v1 #19503

Uh oh!

Conversation

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

Uh oh!

Purpose

Test Plan

Test Result

Uh oh!

github-actions bot commented Jun 11, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

houseroad left a comment

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot commented Jun 12, 2025

Uh oh!

jmswen commented Jun 12, 2025

Uh oh!

Uh oh!

Uh oh!

jmswen commented Jun 11, 2025 •

edited by github-actions bot

Loading