使用 uv 字节码编译缩短 vLLM 启动时间

通过提供预编译的 Python 字节码，全新的 vLLM 容器可以实现显著的启动时间缩短，从而避免在运行时导入期间进行重复编译。

在安装运行时包之前设置 UV_COMPILE_BYTECODE=1 环境标志，uv 构建工具会在构建过程中将 Python 源代码编译为字节码。这种做法避免了在跨模型共享的导入过程中发生的昂贵重复编译，从而带来可测量的启动时间节省。

H100 服务器上的性能提升

在 H100 服务器上运行时，提供预编译字节码带来了显著的启动时间节省，展示了不同模型规模下的一致性能改进。

对于 Qwen3-8B 和 Qwen3-32B，中位配对启动节省时间分别为 17.6 秒和 17.8 秒。这些测量是在 Xeon Platinum 8480+ / H100 SXM 80GB 服务器上进行的，比较了带有预编译字节码的包与移除缓存的包。需要注意的是，这些时间不包括镜像拉取和模型下载时间。

启动时间的百分比减少对于 8B 模型（17.6%）大于 32B 模型（13.9%），这与避免两个模型共享的 Python 导入工作是一致的。

实现与官方支持

用户可以通过在镜像构建期间安装运行时包之前设置 UV_COMPILE_BYTECODE=1 标志来实现这一性能改进。这指示 uv 在构建阶段将 Python 源文件编译为字节码。

对于依赖官方 vLLM 镜像的用户，必要的更改已包含在 CUDA 夜间构建中（例如，vllm/vllm-openai:nightly-8cbd5d03006c33185f402249ff2b448efd594986）。从 v0.32.0 版本开始，此功能将在官方发布镜像中原生支持，用户无需手动设置构建标志。

启动时间缩短的技术机制

启动时间缩短是因为 Python 默认在执行前将源代码编译为代码对象。有效的 .pyc 文件存储了这种编译后的代码，允许 Python 在后续导入时直接加载，从而跳过编译步骤。

像 pip 这样的标准包管理器在安装期间会编译字节码，但 uv 默认跳过此步骤。当镜像中提供字节码时，Python 解释器可以立即加载预编译文件。这显著减少了在服务 CLI 导入过程中花费在源代码编译器调用上的时间。

在诊断测试中，使用预编译镜像时，服务 CLI 导入时间从 5,257 次源代码编译器调用降至零。此外，在 Docker 外部的独立安装中，有效字节码将插桩的服务 CLI 导入时间从 12.20 秒减少到 5.01 秒，节省了 7.19 秒。

跨硬件性能观察

在消费级硬件上也观察到了性能提升，但由于硬件和运行时环境不同，结果被分开记录。

在 i9-13900HX / RTX 4090 笔记本电脑上，涉及 Qwen3-0.6B、Qwen3-1.7B 和 SmolLM2-1.7B 的匹配镜像研究表明，中位配对节省时间在 12.8 到 13.5 秒之间，所有 18 个测试对都倾向于预编译。

在另一个非 Docker 安装中，当已安装的文件已驻留在内存中时，预编译的包缓存每次服务器启动节省了 9–12 秒。即使文件保留在操作系统页面缓存中，这一测量也确认了节省效果。

实现注意事项与权衡

虽然有益，但启用字节码编译会引入镜像构建和部署方面的特定考虑。

• 镜像大小： 预编译镜像增加了约 153 MB 的压缩大小（在一次测试中占总大小的 1.8%），这在初始镜像拉取缓慢时可能相关。
• 构建过程： 构建自定义镜像时，必须在 uv 命令安装运行时包之前设置 UV_COMPILE_BYTECODE=1 标志。用户还必须验证最终镜像，并使用运行时 Python 的 compileall 函数准备任何缺失的缓存。
• 节省范围： 主要节省来自导入期间编译器时间的减少。模块初始化和其它设置任务仍然存在，完整的服务器启动节省并非仅归因于编译器。

有关详细环境、运行顺序和控制条件，完整的方法和测量数据可在补充数据中获取。