弃用策略¶

本文档概述了 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）版本中移除已弃用的功能，以避免给用户带来意外。
现有弃用的宽限期：任何在此策略制定前被弃用的功能，其宽限期均从现在开始，而非追溯计算。
文档至关重要：确保流程的每个阶段都为用户提供清晰的文档说明。

最后说明¶

本策略为动态文档，可能会随着项目及其用户需求的变化而演进。我们欢迎并鼓励社区在完善此流程的过程中提供反馈。