vLLM 架构拆解

繁體中文

简体中文
English
日本語
Español
Français
Deutsch

繁體中文

简体中文
English
日本語
Español
Français
Deutsch

Appearance

vllm CLI:從終端到 AsyncLLM ​

源码版本v0.25.1

職責 ​

vllm 這個命令是使用者最常接觸的入口:敲 vllm serve Qwen/Qwen3-0.6B 啟 OpenAI 兼容伺服器,敲 vllm bench throughput 跑基準,敲 vllm run-batch 批次。它的實現在 vllm/entrypoints/cli/ 下,入口函數是 main()(main.py:17-97)。這一層職責很薄:用 argparse 把子命令 (subcommand) 註冊成一個 subparser,把 argv 解析成 argparse.Namespace,再 dispatch 到對應子命令的 cmd(args) 靜態方法。

子命令骨架抽象在 CLISubcommand(types.py:13-29):每個子命令聲明 name、實現 cmd(args) 跑活、可選重寫 validate(args) 做前置檢查、subparser_init(subparsers) 把自己的 flag 註冊到主 parser 的子 parser 上。main() 啟動時遍歷 CMD_MODULES(main.py:30-37),對每個模組調 cmd_init() 拿一個 CLISubcommand 列表,然後 cmd.subparser_init(subparsers).set_defaults(dispatch_function=cmd.cmd)(main.py:86-89)把 dispatcher 綁到 namespace 上。parser.parse_args() 之後 args.dispatch_function(args)(main.py:94-95)就把控制權交給子命令。

serve 是最重要的子命令,鏈條最長:CLI parser → make_arg_parser → AsyncEngineArgs.from_cli_args → create_engine_config → AsyncLLM.from_vllm_config → FastAPI build_app → uvicorn serve_http。整條鏈都在 v1 這邊,但每一小步都被拆得能單獨測試。CLI 這層本身不碰模型權重,它的活就是"把 argv 翻譯成 EngineArgs 並交給下游"。

設計動機 ​

  • 懶載入子命令模組:main() 頂部用 import vllm.entrypoints.cli.serve 等 import 語句(main.py:18-23)而不是頂部全局載入,因為某些子命令(比如 serve)會拉 CUDA/torch 這種重模組,vllm bench 不需要它們時就不必初始化。docstring 裡專門寫了 must be lazily loaded within main to avoid certain eager import breakage(main.py:3-6)。
  • CLISubcommand 抽象而不是 if/elif:main() 用 CMD_MODULES 列表(main.py:30-37)枚舉所有子命令模組,每個模組對外只暴露 cmd_init() -> list[CLISubcommand] 工廠函數。這樣新增子命令(比如 vllm launch render)只需要寫一個 CLISubcommand 子類、實現 cmd_init 即可,main() 完全不用改。
  • vllm bench 提前切平臺:vllm bench throughput 是純 CPU 也能跑的基準,但 vLLM 預設 current_platform 是 UnspecifiedPlatform,會讓 device type 推斷失敗。所以 main() 檢測到 sys.argv[1] == "bench" 時手動把 current_platform 換成 CpuPlatform()(main.py:58-71)。
  • --omni 整體委託:--omni flag 不是 vLLM 自己的子命令,而是把整個 argv 轉給 vllm-omni 包(main.py:42-55)。find_spec 先探測包是否安裝,沒裝就 sys.exit(1),裝了就 omni_main() 全權接管。
  • API server count 多模式:ServeSubcommand.cmd(serve.py:49-148)根據 api_server_count、data_parallel_external_lb、VLLM_RUST_FRONTEND_PATH 幾個變數選四種運行模式之一——單行程 run_server、headless 無 API server、run_multi_api_server 多 API server 行程、run_dp_supervisor 外部 LB——這是 v1 多前端架構的入口分流。
  • argparse 完全複用 EngineArgs schema:make_arg_parser(cli_args.py:339-383)只做兩件事:加幾個 server 專用 flag(--host、--port、--headless、--api-server-count、--config、--grpc),然後調 FrontendArgs.add_cli_args(parser) + AsyncEngineArgs.add_cli_args(parser)(cli_args.py:380-381)把 EngineArgs 上幾百個欄位一次性註冊好。這樣 serve 和 LLM(...) 在參數上天然一致。

關鍵檔案 ​

資料流 ​

vllm serve Qwen/Qwen3-0.6B --tensor-parallel-size 2 走的鏈路:先 main()(main.py:17)裡走 else 分支,FlexibleArgumentParser + subparsers 裝好所有子命令,parser.parse_args() 得到 args.subparser == "serve"。然後 cmds["serve"].validate(args)(main.py:91-92)跑 validate_parsed_serve_args 檢查 chat template,再 args.dispatch_function(args)(main.py:94-95)進 ServeSubcommand.cmd:

python
# vllm/entrypoints/cli/serve.py L49-L148
@staticmethod
def cmd(args: argparse.Namespace) -> None:
    # If model is specified in CLI (as positional arg), it takes precedence
    if hasattr(args, "model_tag") and args.model_tag is not None:
        args.model = args.model_tag

    if getattr(args, "grpc", False):
        from vllm.entrypoints.grpc_server import serve_grpc
        uvloop.run(serve_grpc(args))
        return

    if args.headless:
        ...
        args.api_server_count = 0

    # Detect LB mode for defaulting api_server_count.
    is_external_lb = (
        args.data_parallel_external_lb or args.data_parallel_rank is not None
    )
    ...
    if args.api_server_count is None:
        if is_multi_port or is_external_lb or envs.VLLM_RUST_FRONTEND_PATH:
            args.api_server_count = 1
        elif is_hybrid_lb:
            args.api_server_count = args.data_parallel_size_local or 1
        else:
            args.api_server_count = args.data_parallel_size
    ...
    if is_multi_port:
        run_dp_supervisor(args)
    elif args.api_server_count < 1:
        run_headless(args)
    elif args.api_server_count > 1 or envs.VLLM_RUST_FRONTEND_PATH:
        run_multi_api_server(args)
    else:
        # Single API server (this process).
        args.api_server_count = None
        uvloop.run(run_server(args))

model_tag(位置參數)被改寫成 args.model,然後 grpc / headless / multi_port / hybrid_lb / external_lb / Rust frontend 各種模式被分流。最常見的是落到最後一支 uvloop.run(run_server(args))(serve.py:146-148),裡面調 run_server_worker(api_server.py:701-723):

python
# vllm/entrypoints/openai/api_server.py L712-L721
async with build_async_engine_client(
    args,
    client_config=client_config,
) as engine_client:
    shutdown_task = await build_and_serve(
        engine_client, listen_address, sock, args, **uvicorn_kwargs
    )
# NB: Await server shutdown only after the backend context is exited
try:
    await shutdown_task
finally:
    sock.close()

build_async_engine_client(api_server.py:78-105)裡 AsyncEngineArgs.from_cli_args(args) 把 Namespace 還原成 EngineArgs,然後 build_async_engine_client_from_engine_args(api_server.py:109-154)調 engine_args.create_engine_config() 得到 VllmConfig,再 AsyncLLM.from_vllm_config(...) 起非同步引擎。引擎建好之後 build_and_serve 把 FastAPI app、路由、middleware、uvicorn 全裝上,serve_http 阻塞主執行緒直到 SIGTERM。

邊界與失敗 ​

  • --omni 包缺失:find_spec("vllm_omni") 返回 None 時 logger.error + sys.exit(1)(main.py:46-50),不會讓使用者卡在一個含糊的 ImportError 上。
  • headless 與 api_server_count 衝突:--headless 模式下傳 --api-server-count>0 直接 raise(serve.py:62-69),因為 headless 本來就是 multi-node 不起 API server 的場景。
  • LB 模式互斥:is_multi_port / is_external_lb / is_hybrid_lb 同時開兩個會直接 raise(serve.py:91-97),三種 LB 拓撲是互斥的。
  • Elastic EP 上限:enable_elastic_ep=True 且 api_server_count > 1 時強制 cap 到 1(serve.py:131-137)並 warning,因為彈性 EP 暫時只支持單 API server。
  • Rust frontend 不支持多 API server:VLLM_RUST_FRONTEND_PATH + api_server_count > 1 時被忽略並設回 1(serve.py:123-128),Rust frontend 是多執行緒而不是多行程。
  • VLLM_ALLOW_RUNTIME_LORA_UPDATING + 多 API server:run_multi_api_server 檢測到這倆組合直接 raise(serve.py:293-296),因為運行時 LoRA 更新無法跨多個獨立 API server 行程同步。
  • tool_parser / reasoning_parser 插件校驗:validate_api_server_args(api_server.py:536-551)檢查 --tool-call-parser / reasoning_parser 在已註冊列表裡,否則 KeyError。
  • bind socket 在引擎啟動之前:setup_server 在 build_async_engine_client 之前跑(api_server.py:697-698),避免和 Ray 搶連接埠(代碼註釋專門指向 issue #8204)。
  • SIGTERM 中斷初始化:run_server 在 uvicorn 安裝自己的 signal handler 之前手動掛 SIGTERM → KeyboardInterrupt(api_server.py:690-695),讓引擎還在初始化時收到 SIGTERM 能立刻退出而不是卡死。

小結 ​

vllm CLI 是一個很薄的 dispatcher:main() 用 CLISubcommand 抽象把所有子命令(serve / launch / openai / run-batch / bench / collect-env)註冊成 subparser,cmd_init() 給每個模組一個工廠入口。最重要也最常調的 vllm serve 在 ServeSubcommand.cmd 里根據 api_server_count 和 LB 模式分流到四種運行模式,最常見的一種走 run_server → build_async_engine_client → AsyncLLM.from_vllm_config,這一步把 EngineArgs 真正變成活的非同步引擎。CLI 這層不碰權重也不跑 forward,它只負責把 argv 翻譯清楚並選對運行模式。EngineArgs 是怎麼把上百個欄位組裝成 VllmConfig 的見 /startup/engine-args;AsyncLLM 起來之後內部怎麼把請求送到 EngineCore 見 /startup/llm-class 和 /engine/engine-core。

對照官方資料:vLLM 文件 · README