# PR #36464 完整报告

- 仓库：`vllm-project/vllm`
- 标题：[Examples] Resettle generate examples.
- 合并时间：2026-04-27 15:48
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/36464

---

# 执行摘要

- 一句话：重组 examples 目录为场景化分类
- 推荐动作：建议开发者和文档编写者关注新的示例目录结构，后续添加示例时应参考此分类。对于已部署的文档站点，需检查所有示例链接并更新。此 PR 体现了以用户使用场景为中心的设计思路，值得在项目其他部分推广。

# 功能与动机

Issue #29362 指出旧的 examples 组织结构迫使用户跨多个文件夹搜索特定用例。此 PR 按照该 RFC 提议，按实际使用场景重新组织示例，提高可发现性。

# 实现拆解

1. **创建新目录结构**：在 `examples/` 下新建 `generate`、`speech_to_text`、`tool_calling`、`reasoning` 等一级目录，`generate` 内细分 `multimodal`、`text` 等子目录。

2. **移动示例文件**：将原 `examples/offline_inference/` 和 `examples/online_serving/` 中的生成相关示例移至对应新路径，例如 `vision_language.py` → `examples/generate/multimodal/vision_language_offline.py`。大部分文件仅移动，内容不变。

3. **更新内部引用**：修正移动后文件内注释中的相对路径，例如 `vision_language_offline.py` 中将 `audio_language.py` 引用改为 `audio_language_offline.py`。

4. **更新文档链接**：在 `docs/serving/openai_compatible_server.md` 中修正转录客户端示例的链接路径。

5. **更新 CI 配置**：在 `.buildkite/test_areas/misc.yaml` 中更新离线推理示例的执行路径，确保 CI 测试能正确找到示例文件。

关键文件：
- `examples/generate/multimodal/vision_language_offline.py`（模块 生成示例；类别 source；类型 rename-or-move）: 作为多模态生成示例的主要入口，移动后更新了一条内部注释中的文件引用
- `examples/generate/batched_chat_completions_online.py`（模块 生成示例；类别 source；类型 rename-or-move）: 批量聊天补全示例，移动后无内容变化
- `docs/serving/openai_compatible_server.md`（模块 文档；类别 docs；类型 documentation）: 文档中的示例路径更新，review 中发现了错误
- `.buildkite/test_areas/misc.yaml`（模块 CI 配置；类别 config；类型 configuration）: CI 配置中的示例执行路径需同步更新
- `examples/generate/multimodal/audio_language_offline.py`（模块 生成示例；类别 source；类型 rename-or-move）: 音频语言示例，移动后无内容变化
- `examples/generate/multimodal/encoder_decoder_multimodal_offline.py`（模块 生成示例；类别 source；类型 rename-or-move）: 编码器 - 解码器多模态示例，移动后无内容变化

关键符号：未识别


# 评论区精华

* **分类命名讨论**：作者 noooop 在 issue 评论中询问 function calling、responses 等是否应归入 generate，DarkLight1337 建议暂时放在 generate 下，待未来支持离线推理中的对应功能后再单独成类。
* **路径错误修正**：gemini-code-assist[bot] 审查发现 `docs/serving/openai_compatible_server.md` 中转录客户端示例路径重复 / 错误，以及 `examples/generate/demo/gradio_webserver.py` 中的使用示例路径出现重复。
* **CI 路径更新**：DarkLight1337 在 review 中要求更新 `.buildkite/test_areas/misc.yaml` 中的路径以匹配新结构。

- 示例分类命名讨论 (design): 决定将 function calling、structured outputs 等暂时归入 generate 大类。
- 文档路径错误 (correctness): 作者已修正这些路径错误（PR 合并时已修复）。
- CI 配置路径更新 (testing): 作者已更新相应的路径。

# 风险与影响

- 风险：
 * **文档链接失效**：文档中部分示例路径可能因疏忽未正确更新（review 已发现并修正），若其他文档存在类似问题可能导致用户访问 404。
 * **CI 测试破坏**：若 CI 配置文件中的执行路径未同步更新，对应的测试步骤将因找不到文件而失败。
 * **外部依赖**：其他团队或用户 fork 后若依赖旧路径，升级后需手动迁移。
- 影响：
 * **用户影响**：示例文件路径改变，用户需适应新位置；但按场景分类后更易发现所需示例。文档中示例链接需注意是否已更新。
 * **系统影响**：无运行时功能影响，纯文件组织变更。
 * **团队影响**：后续新增示例需遵循新目录规范，提高了可维护性；代码 review 时需确保文件放置位置正确。
 - 风险标记：路径更新不完整 , 文档链接失效 , CI 测试路径需同步

# 关联脉络

- 暂无明显关联 PR