执行摘要

本 PR 为 AsyncLLM.generate() 方法的 docstring 添加了一个最小示例，展示如何通过 Renderer.render_cmpl() 手动渲染提示，以避免直接传递原始字符串时触发的弃用警告。变更仅限于文档，无功能性影响，旨在提升 API 使用的清晰度，帮助高级用户理解正确用法。

功能与动机

当用户直接将原始提示字符串传递给 generate() 时，会触发弃用警告，建议改用 Renderer.render_cmpl() 或 Renderer.render_chat()。然而，正确使用这些方法需要多个非显而易见的步骤（如调用 parse_model_prompt()、包装结果、构建 tok_params），而文档中未提供示例。PR body 中明确提到：'A repo-wide search of examples/, docs/, and tests/ found zero usages of render_cmpl/render_chat outside of internal unit tests'，因此添加示例以填补空白，遵循弃用警告的建议。

实现拆解

1. 变更入口：修改文件 vllm/v1/engine/async_llm.py，定位到 AsyncLLM.generate() 方法的 docstring。
2. 核心逻辑改造：在现有 docstring 中添加一个 Note 部分，提供代码示例。示例包括四个关键步骤：
   • 导入 parse_model_prompt 并解析提示文本。
   • 获取渲染器的默认补全令牌参数 renderer.default_cmpl_tok_params。
   • 调用 renderer.render_cmpl() 生成 EngineInput 对象。
   • 将 EngineInput 传递给 generate() 方法。
3. 配套改动：无测试、配置或部署配套变更，仅为纯文档更新。
4. 影响说明：此变更仅影响文档，旨在指导用户避免弃用警告，对运行时行为、性能或安全无影响。

vllm/v1/engine/async_llm.py

添加 docstring 示例，展示手动渲染提示以避免弃用警告。

"""
Main function called by the API server to kick off a request
    * 1) Making an AsyncStream corresponding to the Request.
    * 2) Processing the Input.
    * 3) Adding the Request to the Detokenizer.
    * 4) Adding the Request to the EngineCore (separate process).
​
A separate output_handler loop runs in a background AsyncIO task,
pulling outputs from EngineCore and putting them into the
per-request AsyncStream.
​
The caller of generate() iterates the returned AsyncGenerator,
returning the RequestOutput back to the caller.
​
Note:
    Passing a raw prompt string directly to this method is deprecated.
    Advanced power-users can manually bypass the raw-prompt fallback
    path using the Engine's underlying Renderer pipeline:
​
    >>> from vllm.inputs import parse_model_prompt
    >>> parsed = parse_model_prompt(self.model_config, "Prompt text")
    >>> params = self.renderer.default_cmpl_tok_params
    >>> (engine_input,) = self.renderer.render_cmpl([parsed], params)
    >>> gen = self.generate(engine_input, sampling_params, request_id)
"""

评论区精华

• DarkLight1337 最初质疑 PR 的必要性，认为只有 AsyncLLM 高级用户会直接使用该方法，因此示例可能不必要。
• null-Exception1 回应指出在 LLM.generate() 中也出现警告，但后续承认 LLM.generate() 实际未触发该警告，建议聚焦于 AsyncLLM。
• DarkLight1337 最终建议将示例作为 AsyncLLM.generate() 的 docstring，避免创建独立文件。
• 讨论突出了示例的受众（高级用户）和最佳放置位置（docstring），最终 PR 获得批准。

风险与影响

• 技术风险：极低。文档变更不涉及代码逻辑，仅添加注释性内容。潜在风险包括示例代码不准确，但 PR 已在隔离环境中测试并确认无弃用警告。
• 影响范围：
  • 用户：为高级用户提供清晰的手动渲染示例，减少弃用警告困惑，提升 API 使用体验。
  • 系统：无功能性变更，不影响性能、安全或兼容性。
  • 团队：降低用户支持负担，通过文档预防常见问题。

关联脉络

本 PR 与仓库近期历史 PR 无直接关联。它独立解决了文档空白问题，聚焦于异步引擎（vllm/v1）的 API 使用指导。在近期 PR 中，有多个涉及 kv-connector、performance 和 kernel 的变更，但本 PR 属于文档维护范畴，未涉及跨模块演进。