# PR #54265 完整报告

- 仓库：`vllm-project/vllm`
- 标题：[Docs] Add example for Renderer.render_cmpl() usage
- 合并时间：2026-09-04 14:35
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/54265

---

## 执行摘要
本 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 示例，展示手动渲染提示以避免弃用警告。

```python
"""
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 属于文档维护范畴，未涉及跨模块演进。