[Bugfix] Fix vLLM startup to avoid a hard dependency on Outlines

[chaunceyjiang]

Follow up #15975

Before

# vllm serve Qwen/Qwen3-1.7B                                                                                       130 ↵
INFO 07-13 08:53:03 [__init__.py:253] Automatically detected platform cuda.
INFO 07-13 08:53:06 [api_server.py:1641] vLLM API server version 0.9.2rc2.dev77+gfdd52d530
INFO 07-13 08:53:06 [cli_args.py:325] non-default args: {'model': 'Qwen/Qwen3-1.7B'}
INFO 07-13 08:53:15 [config.py:1560] Using max model len 40960
INFO 07-13 08:53:15 [config.py:2374] Chunked prefill is enabled with max_num_batched_tokens=2048.
Traceback (most recent call last):
  File "/root/anaconda3/bin/vllm", line 8, in <module>
    sys.exit(main())
             ^^^^^^
  File "/root/vllm/vllm/entrypoints/cli/main.py", line 65, in main
    args.dispatch_function(args)
  File "/root/vllm/vllm/entrypoints/cli/serve.py", line 57, in cmd
    uvloop.run(run_server(args))
  File "/root/anaconda3/lib/python3.12/site-packages/uvloop/__init__.py", line 109, in run
    return __asyncio.run(
           ^^^^^^^^^^^^^^
  File "/root/anaconda3/lib/python3.12/asyncio/runners.py", line 194, in run
    return runner.run(main)
           ^^^^^^^^^^^^^^^^
  File "/root/anaconda3/lib/python3.12/asyncio/runners.py", line 118, in run
    return self._loop.run_until_complete(task)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "uvloop/loop.pyx", line 1518, in uvloop.loop.Loop.run_until_complete
  File "/root/anaconda3/lib/python3.12/site-packages/uvloop/__init__.py", line 61, in wrapper
    return await main
           ^^^^^^^^^^
  File "/root/vllm/vllm/entrypoints/openai/api_server.py", line 1677, in run_server
    await run_server_worker(listen_address, sock, args, **uvicorn_kwargs)
  File "/root/vllm/vllm/entrypoints/openai/api_server.py", line 1697, in run_server_worker
    async with build_async_engine_client(args, client_config) as engine_client:
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/root/anaconda3/lib/python3.12/contextlib.py", line 210, in __aenter__
    return await anext(self.gen)
           ^^^^^^^^^^^^^^^^^^^^^
  File "/root/vllm/vllm/entrypoints/openai/api_server.py", line 158, in build_async_engine_client
    async with build_async_engine_client_from_engine_args(
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/root/anaconda3/lib/python3.12/contextlib.py", line 210, in __aenter__
    return await anext(self.gen)
           ^^^^^^^^^^^^^^^^^^^^^
  File "/root/vllm/vllm/entrypoints/openai/api_server.py", line 189, in build_async_engine_client_from_engine_args
    from vllm.v1.engine.async_llm import AsyncLLM
  File "/root/vllm/vllm/v1/engine/async_llm.py", line 36, in <module>
    from vllm.v1.engine.processor import Processor
  File "/root/vllm/vllm/v1/engine/processor.py", line 26, in <module>
    from vllm.v1.structured_output.backend_outlines import (
  File "/root/vllm/vllm/v1/structured_output/backend_outlines.py", line 16, in <module>
    from vllm.model_executor.guided_decoding.outlines_logits_processors import (
  File "/root/vllm/vllm/model_executor/guided_decoding/outlines_logits_processors.py", line 17, in <module>
    from outlines_core import Guide, Index, Vocabulary
ImportError: cannot import name 'Guide' from 'outlines_core' (/root/anaconda3/lib/python3.12/site-packages/outlines_core/__init__.py)

After

# vllm serve Qwen/Qwen3-1.7B
...
...
INFO 07-13 08:55:52 [launcher.py:37] Route: /rerank, Methods: POST
INFO 07-13 08:55:52 [launcher.py:37] Route: /v1/rerank, Methods: POST
INFO 07-13 08:55:52 [launcher.py:37] Route: /v2/rerank, Methods: POST
INFO 07-13 08:55:52 [launcher.py:37] Route: /invocations, Methods: POST
INFO 07-13 08:55:52 [launcher.py:37] Route: /metrics, Methods: GET
INFO:     Started server process [226555]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

[github-actions]

👋 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 @chaunceyjiang, 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 critical startup bug in vLLM where the system would fail to initialize if the outlines_core library was not installed, even when its functionality was not explicitly required. The change ensures that outlines_core and related modules are loaded lazily, preventing a hard dependency and allowing vLLM to start successfully without outlines_core being present.

Highlights

• Dependency Management: Changed the import strategy for outlines_core and related modules to be lazy-loaded, resolving a hard dependency issue that prevented vLLM from starting if outlines_core was not installed.
• Bugfix: Fixed a critical startup error (ImportError) that occurred when outlines_core was not available, improving the robustness of vLLM's initialization process.

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.

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

This pull request aims to fix a startup issue by preventing a hard dependency on the outlines library. The proposed change moves an import into a TYPE_CHECKING block.

While this correctly addresses the startup dependency, it introduces a critical runtime bug (NameError) because the imported functions are needed during execution. My review provides a detailed explanation of the issue and suggests an alternative approach using local imports within the class method, which is a common pattern for this kind of lazy loading. This will fix the startup issue without introducing new bugs.