弃用策略

本文档概述了 vLLM 项目中弃用功能的官方策略和流程。

概述

vLLM 采用结构化的“弃用流程”来指导已弃用功能的生命周期。此策略确保在弃用功能时向用户提供清晰充分的通知，并确保弃用过程以一致且可预测的方式进行。

我们致力于在持续创新和尊重用户对现有功能的依赖之间取得平衡。弃用与我们遵循语义版本控制 (X.Y.Z) 的次要版本 (Y) 发布相关，其中

• X 是主要版本（罕见）
• Y 是次要版本（用于重大更改，包括弃用/移除）
• Z 是补丁版本（用于修复和更安全的增强）

受此策略约束的功能至少包括以下内容

• CLI 标志
• 环境变量
• 配置文件
• OpenAI 兼容 API 服务器中的 API
• vllm 库的公共 Python API

弃用流程

弃用过程包括几个明确定义的阶段，这些阶段跨越多个 Y 版本

1. 已弃用（默认仍启用）

• 操作：功能被标记为已弃用。
• 时间表：弃用警告中明确说明了移除版本（例如，“这将在 v0.10.0 中移除”）。
• 沟通：弃用信息在以下适用情况下进行说明
• 帮助字符串
• 日志输出
• API 响应
• /metrics 输出（针对指标功能）
• 面向用户的文档
• 发布说明
• 用于反馈的 GitHub Issue (RFC)
• Python API 的文档以及 @typing_extensions.deprecated 装饰器的使用

2. 已弃用（默认关闭）

• 操作：功能默认禁用，但仍可通过 CLI 标志或环境变量重新启用。未重新启用时使用该功能会抛出错误。
• 目的：为错过早期警告的用户提供一个临时退路，同时预示即将移除。确保任何剩余的使用情况都清晰地浮出水面，并在完全移除之前阻止静默损坏。

3. 已移除

• 操作：功能已从代码库中完全移除。
• 注意：只有经过前面弃用阶段的功能才会被移除。

示例时间表

假设某功能在 v0.9.0 中被弃用。

版本	状态
v0.9.0	功能被弃用，并列出明确的移除版本。
v0.10.0	功能现在默认关闭，使用时会抛出错误，可以为旧版使用重新启用。
v0.11.0	功能被移除。

重要指南

• 补丁版本中禁止移除：禁止在补丁 (.Z) 版本中移除已弃用的功能，以避免给用户带来意外。
• 现有弃用的宽限期：在本策略生效之前弃用的任何功能，其宽限期将从现在开始，而不是追溯计算。
• 文档至关重要：确保流程的每个阶段都为用户清晰地记录下来。

最终说明

本策略是一份动态文档，可能会随着项目及其用户需求的变化而演变。我们欢迎并鼓励社区反馈，以便我们完善流程。