[Doc][Misc] Document batch invariance scheduling limitations

[wangx700]

What this PR does / why we need it?

Documents the scheduling limitations of batch invariance in the user guide: chunked prefill, prefix caching, and request preemption (eviction and recomputation) are not supported. These features are not disabled automatically, so the guide now instructs users to explicitly disable chunked prefill and prefix caching, and pairs --block-size 128 with the chunked prefill disabling. The online/offline inference examples and the batch invariance e2e test are updated with the same config.

Does this PR introduce any user-facing change?

Documentation-only update plus an e2e test configuration adjustment.

How was this patch tested?

Doc-only change; the e2e test config (test_batch_invariant_tp4.py) follows the documented settings. CI verification is sufficient.

• VLLM_WORKER_MULTIPROC_METHOD=spawn pytest -sv tests/e2e/pull_request/four_card/rlhf/consistency/test_batch_invariant_tp4.py

[DEBUG] Final model_config: {'model_name': ..Qwen3-30B-A3B', 'max_num_seqs': 144, 'gpu_memory_utilization': 0.95, 'max_model_len': 8192, 'dtype': 'bfloat16', 'tensor_parallel_size': 4, 'enable_prefix_caching': False, 'distributed_executor_backend': 'mp', 'compilation_config': {'cudagraph_capture_sizes': [1, 32, 64]}, 'extra_kwargs': {'load_format': 'dummy', 'hf_overrides': {'num_hidden_layers': 2}, 'enable_chunked_prefill': False, 'block_size': 128}}
[DEBUG] vllm_runner fixture - model_config: {'model_name': '..Qwen3-30B-A3B', 'max_num_seqs': 144, 'gpu_memory_utilization': 0.95, 'max_model_len': 8192, 'dtype': 'bfloat16', 'tensor_parallel_size': 4, 'enable_prefix_caching': False, 'distributed_executor_backend': 'mp', 'compilation_config': {'cudagraph_capture_sizes': [1, 32, 64]}, 'extra_kwargs': {'load_format': 'dummy', 'hf_overrides': {'num_hidden_layers': 2}, 'enable_chunked_prefill': False, 'block_size': 128}}
...
PASSEDINFO 09-10 20:42:39 [utils.py:620] [shutdown] Process manager: send sigterm to process EngineCore
(EngineCore pid=64849) INFO 09-10 20:42:39 [core.py:1350] [shutdown] EngineCore: trigger received signal=SIGTERM
(EngineCore pid=64849) INFO 09-10 20:42:39 [core.py:1501] [shutdown] EngineCore: start mode=abort timeout=0s
(EngineCore pid=64849) INFO 09-10 20:42:39 [core.py:1532] [shutdown] EngineCore: request processing complete; starting resource teardown
(EngineCore pid=64849) INFO 09-10 20:42:39 [core.py:1363] [shutdown] EngineCore: exiting busy loop
(EngineCore pid=64849) INFO 09-10 20:42:39 [multiproc_executor.py:472] [shutdown] Executor: waiting for worker exit count=4
(Worker_TP0 pid=65187) INFO 09-10 20:42:39 [multiproc_executor.py:836] Parent process exited, terminating worker queues
WARNING 09-10 20:42:44 [utils.py:640] [shutdown] Process manager: force killing remaining processes count=1
WARNING 09-10 20:42:44 [utils.py:645] [shutdown] Process manager: force killing remaining process EngineCore pid 64849
(EngineCore pid=64849) WARNING 09-10 20:42:44 [multiproc_executor.py:484] [shutdown] Executor: workers still running after grace period; sending SIGTERM count=3
[INFO] Model cache cleared

=============================== warnings summary ===============================
../../../../../usr/local/python3.11.10/lib/python3.11/site-packages/torch/jit/_script.py:362: 14 warnings
  /usr/local/python3.11.10/lib/python3.11/site-packages/torch/jit/_script.py:362: DeprecationWarning: `torch.jit.script_method` is deprecated. Please switch to `torch.compile` or `torch.export`.
    warnings.warn(

tests/e2e/pull_request/four_card/rlhf/consistency/test_batch_invariant_tp4.py:111
  /mnt/share/w00899129/vllm_code_0908/vllm-ascend/tests/e2e/pull_request/four_card/rlhf/consistency/test_batch_invariant_tp4.py:111: PytestUnknownMarkWarning: Unknown pytest.mark.model - is this a typo?  You can register custom marks to avoid this warning - for details, see https://docs.pytest.org/en/stable/how-to/mark.html
    @pytest.mark.model(

-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
================== 1 passed, 15 warnings in 118.88s (0:01:58) ==================
/usr/local/python3.11.10/lib/python3.11/multiprocessing/resource_tracker.py:254: UserWarning: resource_tracker: There appear to be 1 leaked shared_memory objects to clean up at shutdown
  warnings.warn('resource_tracker: There appear to be %d '

• vLLM main: vllm-project/vllm@b2f6858

[gemini-code-assist]

Summary of Changes

Hello, 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 improves the documentation and configuration consistency for the batch invariance feature in vLLM. It clarifies that certain scheduling optimizations are incompatible with batch invariance and provides explicit configuration guidance to ensure deterministic behavior. The changes ensure that users and automated tests follow the correct setup requirements.

Highlights

• Documentation Update: Added a new section to the batch invariance user guide detailing unsupported scheduling features, specifically chunked prefill, prefix caching, and request preemption.
• Configuration Requirements: Updated examples to explicitly require disabling chunked prefill and prefix caching, and enforcing a block size of 128 when using batch invariance.
• Test Configuration: Updated the batch invariance E2E test configuration to align with the new recommended settings.

New Features

🧠 You can now enable Memory (public preview) to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

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 by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

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 pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the 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 may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. 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. ↩

[gemini-code-assist]

Code Review

Suggested PR Title:

[Doc][Misc] Update batch invariance documentation and tests for scheduling limitations

Suggested PR Summary:

### What this PR does / why we need it?
This pull request updates the batch invariance documentation and tests to reflect scheduling limitations. Specifically, it documents that chunked prefill, prefix caching, and request preemption are not supported with batch invariance, and details how to explicitly disable them while setting the KV cache block size to 128. It also updates the end-to-end consistency test configuration accordingly.

However, the reviewer pointed out that the command-line options `--no-enable-chunked-prefill` and `--no-enable-prefix-caching` do not exist in vLLM. Since these features are disabled by default, they should simply be omitted from the startup command rather than explicitly passed as non-existent flags, and the documentation should be updated to reflect this.

### Does this PR introduce _any_ user-facing change?
Yes, it updates the documentation on how to configure vLLM for batch invariance.

### How was this patch tested?
The patch updates the existing end-to-end test `test_batch_invariant_tp4.py` with the correct configuration parameters.

[gemini-code-assist]

The command-line options --no-enable-chunked-prefill and --no-enable-prefix-caching do not exist in vLLM. Since both features are disabled by default, you do not need to pass any flags to disable them; simply omitting --enable-chunked-prefill and --enable-prefix-caching is sufficient. Passing unrecognized arguments will cause the vllm serve command to fail.

Suggested change

	VLLM_BATCH_INVARIANT=1 vllm serve Qwen/Qwen3-8B \
	--no-enable-chunked-prefill \
	--no-enable-prefix-caching \
	--block-size 128
	VLLM_BATCH_INVARIANT=1 vllm serve Qwen/Qwen3-8B \\
	--block-size 128

[wangx700]

--no-enable-chunked-prefill and --no-enable-prefix-caching was been tested ok.

[gemini-code-assist]

Since --no-enable-chunked-prefill and --no-enable-prefix-caching are not valid vLLM CLI options, the explanation should be updated to reflect that these features are disabled by default and should simply be omitted from the startup command.

Suggested change

These scheduling features are not disabled automatically. You must explicitly disable chunked prefill and prefix caching in your configuration, and pair the chunked prefill disabling with a KV cache block size of 128 — pass `--block-size 128` together with `--no-enable-chunked-prefill` when starting the server, or `block_size=128` together with `enable_chunked_prefill=False` for offline inference — as shown in the examples above.

These scheduling features are not disabled automatically when batch invariance is enabled. You must ensure chunked prefill and prefix caching are disabled in your configuration (they are disabled by default, so do not pass --enable-chunked-prefill or --enable-prefix-caching when starting the server, or explicitly set enable_chunked_prefill=False and enable_prefix_caching=False for offline inference) and pair this with a KV cache block size of 128 (using --block-size 128 or block_size=128).

[wangx700]

--no-enable-chunked-prefill and --no-enable-prefix-caching are valid vLLM CLI options

[github-actions]

👋 Hi! Thank you for contributing to the vLLM Ascend project. The following points will speed up your PR merge:‌‌

• A PR should do only one thing, smaller PRs enable faster reviews.
• Every PR should include unit tests and end-to-end tests ‌to ensure it works and is not broken by other future PRs.
• Write the commit message by fulfilling the PR description to help reviewer and future developers understand.

If CI fails, you can run linting and testing checks locally according Contributing and Testing.

[Ronald1995]

it's better to explain how to avoid preemption

[wangx700]

OK，how to avoid preemption is added, and can see more with preemption FAQ

[Ronald1995]

LGTM

[lijiahang226]

LGTM