[CLI] Improve CLI arg parsing for `-O`/`--compilation-config` #20156

ProExpertProg · 2025-06-26T23:23:36Z

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

While #18208 added really neat support for nested keys (--hf-overrides.key1.key2=val1 instead of --hf-overrides='{"key1":{"key2":"val1"}}', they were not supported for -O. This PR adds that support and makes the following additional improvements:

Converts -O1 to -O.level=1 in the FlexibleArgumentParsing to support merging with other -O.<...> flags
Warning on duplicates
Parsing array elements using + at the end of the value.

Test Plan

Added Python unit tests.

Test Result

All passing.

(Optional) Documentation Update

All CLI documentation is in the vllm --help message, which comes from docstrings, which I updated.

github-actions · 2025-06-26T23:23:43Z

👋 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 @ProExpertProg, 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 significantly enhances the command-line interface's argument parsing capabilities, particularly for compilation configuration flags. My changes introduce support for nested key-value pairs, streamline the handling of compilation levels, and add a valuable warning system for duplicate arguments, making the CLI more flexible, user-friendly, and robust.

Highlights

Enhanced CLI Argument Parsing for -O: I've extended the FlexibleArgumentParsing to support nested key-value pairs for the -O/--compilation-config flag, similar to how --hf-overrides works. This allows for more granular control over compilation settings directly from the command line (e.g., -O.use_inductor=true).
Automatic -O<level> Conversion: The CLI now automatically converts shorthand compilation level flags like -O1 into -O.level=1. This ensures that these level settings can be properly merged with other detailed -O.<key>=<value> flags, providing a more consistent parsing experience.
Duplicate Argument Warning: I've implemented a new feature that detects and warns users when duplicate dictionary keys are provided via CLI arguments (e.g., --hf-overrides.key1 val1 --hf-overrides.key1 val2). This improves user feedback and helps prevent unexpected behavior due to overwritten settings.
Improved CompilationConfig Handling: The CompilationConfig.from_cli method has been simplified by removing its internal logic for parsing -O<level> flags, as this is now handled upstream by the FlexibleArgumentParser. This centralizes the parsing logic and makes the CompilationConfig class more focused on validation.
Comprehensive Unit Tests: New unit tests have been added to tests/test_utils.py to cover the new -O parsing capabilities, including nested keys, level conversions, and the duplicate argument warning mechanism, ensuring the robustness of the CLI changes.

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

gemini-code-assist

Code Review

This pull request enhances the command-line argument parsing for compilation configurations (-O/--compilation-config). It introduces support for nested keys, shorthand for optimization levels (e.g., -O1), and warnings for duplicate arguments. The changes are well-tested.

My review identified a potential issue with the handling of non-numeric -O arguments and a minor inconsistency in a docstring. I've provided suggestions to address these points to improve the robustness and clarity of the code.

vllm/utils.py

aarnphm

This makes sense.

One thing that I'm not entirely sure about is the +,- syntax. At this point, I felt like it might be better to just input as list?

ProExpertProg · 2025-06-27T00:25:54Z

There's no minus, but inputting as a list would require the parser to know that the arg is expecting a list. Right now the parser is agnostic to expected types, so + tells it to use a list. If we input as a JSON list, we need a bunch of quotes again, which is not ideal.

tests/engine/test_arg_utils.py

ProExpertProg · 2025-06-27T16:54:33Z

Will add back the -O 3 support to avoid breaking people's workflows. Perhaps we can deprecate it in the future.

…gumentParser Signed-off-by: luka <luka@neuralmagic.com>

Signed-off-by: luka <luka@neuralmagic.com>

This reverts commit d3c8f31. Signed-off-by: luka <luka@neuralmagic.com>

Signed-off-by: luka <luka@neuralmagic.com>

mgoin

This looks solid to me, thanks for the work! Looking forward to using it

…roject#20156) Signed-off-by: luka <luka@neuralmagic.com>

…roject#20156) Signed-off-by: luka <luka@neuralmagic.com> Signed-off-by: avigny <47987522+avigny@users.noreply.github.com>

…roject#20156) Signed-off-by: luka <luka@neuralmagic.com>

gemini-code-assist bot reviewed Jun 26, 2025

View reviewed changes

vllm/utils.py Outdated Show resolved Hide resolved

vllm/utils.py Outdated Show resolved Hide resolved

ProExpertProg force-pushed the luka/cli-parsing branch 2 times, most recently from 19e18b2 to 5ee2e5a Compare June 26, 2025 23:33

aarnphm approved these changes Jun 27, 2025

View reviewed changes

ProExpertProg marked this pull request as ready for review June 27, 2025 00:26

ProExpertProg requested review from simon-mo, WoosukKwon, youkaichao, robertgshaw2-redhat, mgoin, tlrmchlsmth, houseroad and hmellor as code owners June 27, 2025 00:26

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

mgoin reviewed Jun 27, 2025

View reviewed changes

tests/engine/test_arg_utils.py Outdated Show resolved Hide resolved

ProExpertProg marked this pull request as draft June 27, 2025 16:53

ProExpertProg removed the ready ONLY add when PR is ready to merge/full CI is needed label Jun 27, 2025

ProExpertProg added 6 commits June 30, 2025 19:50

Allow -O for nested arg, move parsing of -O1/-O2/etc. into FlexibleAr…

950e243

…gumentParser Signed-off-by: luka <luka@neuralmagic.com>

Update help string for CompilationConfig

e7d4645

Signed-off-by: luka <luka@neuralmagic.com>

fix values with - and . in value

7d4973d

Signed-off-by: luka <luka@neuralmagic.com>

Warn on CLI duplicates

7ceaf1c

Signed-off-by: luka <luka@neuralmagic.com>

Add array value handling CLI

b6fc0b1

Signed-off-by: luka <luka@neuralmagic.com>

Remove test for -O 3 (space no longer supported)

f00ba70

Signed-off-by: luka <luka@neuralmagic.com>

ProExpertProg force-pushed the luka/cli-parsing branch from d3c8f31 to c5007fd Compare June 30, 2025 19:51

ProExpertProg added 2 commits June 30, 2025 19:52

Revert "Remove test for -O 3 (space no longer supported)"

a785e55

This reverts commit d3c8f31. Signed-off-by: luka <luka@neuralmagic.com>

Restore support for -O=3 and -O, and add comments.

ebcde56

Signed-off-by: luka <luka@neuralmagic.com>

ProExpertProg force-pushed the luka/cli-parsing branch from c5007fd to ebcde56 Compare June 30, 2025 19:52

ProExpertProg marked this pull request as ready for review June 30, 2025 19:52

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

More realistic custom op values

e8f1a9b

Signed-off-by: luka <luka@neuralmagic.com>

mgoin approved these changes Jun 30, 2025

View reviewed changes

mgoin enabled auto-merge (squash) June 30, 2025 21:40

mgoin merged commit 6d42ce8 into vllm-project:main Jul 1, 2025
76 checks passed

CSWYF3634076 pushed a commit to CSWYF3634076/vllm that referenced this pull request Jul 2, 2025

[CLI] Improve CLI arg parsing for -O/--compilation-config (vllm-p…

64980a9

…roject#20156) Signed-off-by: luka <luka@neuralmagic.com>

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

[CLI] Improve CLI arg parsing for -O/--compilation-config (vllm-p…

2e48a17

…roject#20156) Signed-off-by: luka <luka@neuralmagic.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

[CLI] Improve CLI arg parsing for -O/--compilation-config (vllm-p…

5e69c6c

…roject#20156) Signed-off-by: luka <luka@neuralmagic.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

[CLI] Improve CLI arg parsing for `-O`/`--compilation-config` #20156

[CLI] Improve CLI arg parsing for `-O`/`--compilation-config` #20156

Uh oh!

ProExpertProg commented Jun 26, 2025 •

edited by github-actions bot

Loading

Uh oh!

github-actions bot commented Jun 26, 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!

aarnphm left a comment

Uh oh!

ProExpertProg commented Jun 27, 2025 •

edited

Loading

Uh oh!

Uh oh!

ProExpertProg commented Jun 27, 2025

Uh oh!

mgoin left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

[CLI] Improve CLI arg parsing for -O/--compilation-config #20156

[CLI] Improve CLI arg parsing for -O/--compilation-config #20156

Uh oh!

Conversation

ProExpertProg commented Jun 26, 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!

github-actions bot commented Jun 26, 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!

aarnphm left a comment

Choose a reason for hiding this comment

Uh oh!

ProExpertProg commented Jun 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

ProExpertProg commented Jun 27, 2025

Uh oh!

mgoin left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

[CLI] Improve CLI arg parsing for `-O`/`--compilation-config` #20156

[CLI] Improve CLI arg parsing for `-O`/`--compilation-config` #20156

ProExpertProg commented Jun 26, 2025 •

edited by github-actions bot

Loading

ProExpertProg commented Jun 27, 2025 •

edited

Loading

mgoin left a comment •

edited

Loading