Prhub

#40759 [Examples] Resettle Disaggregated examples.

原始 PR 作者 noooop 合并时间 2026-05-06 16:20 文件变更 54 提交数 15 评论 5 代码增减 +29 / -31

执行摘要

将分散的 disaggregated 示例集中到 examples/disaggregated/

当前 examples 第一级按 offline_inference / online_serving 组织,用户需在多个文件夹中查找特定用途的示例(如 disaggregated prefill 的示例分散在 offline_inference/disaggregated_prefill.py、online_serving/disaggregated_serving/ 等)。Issue #29362 提议按使用场景作为第一级目录,本 PR 率先对 disaggregated 示例进行迁移。

作为 examples 目录重构的第一步,值得关注后续其他场景(如 pooling、structured_outputs)的迁移。无需深入审查代码逻辑,但可了解新目录结构以便日后查找示例。

讨论亮点

gemini-code-assist 审查后指出两处文档问题:

  • 链接标签缺少 examples/ 前缀(high priority)
  • MooncakeConnector 的描述错误地写成了 ExampleConnector(copy-paste 错误)
    作者已通过提交修复(commit b33f7eb、d17e9ed),最终获得 reviewer DarkLight1337 的 approval。

实现拆解

步骤如下:

  1. 在 examples/ 下创建 disaggregated/ 目录,下设子目录(disaggregated_serving、disaggregated_encoder、flexkv_connector、lmcache 等),与已有分类对应。
  2. 通过 git mv 将分散的文件移动到新位置,包括:
    • examples/offline_inference/disaggregated_prefill.py → examples/disaggregated/disaggregated_prefill.py
    • examples/online_serving/disaggregated_serving/* → examples/disaggregated/disaggregated_serving/
    • examples/online_serving/disaggregated_encoder/* → examples/disaggregated/disaggregated_encoder/
    • examples/offline_inference/prefix_caching_flexkv.py → examples/disaggregated/flexkv_connector/prefix_caching_flexkv.py
    • examples/offline_inference/disaggregated-prefill-v1/* → examples/disaggregated/example_connector/
    • examples/offline_inference/kv_load_failure_recovery/* → examples/disaggregated/kv_load_failure_recovery_offline/
    • examples/others/lmcache/* → examples/disaggregated/lmcache/
  3. 更新 docs/features/disagg_prefill.md 中的引用路径,保持文档与文件实际位置一致。
  4. 对移动的脚本内路径注释(如 argparse help 中的示例命令)进行相应更新,确保用户复制命令时路径正确。
  5. 无测试或其他配置变更,属于纯组织调整。
文件 模块 状态 重要度
examples/disaggregated/disaggregated_serving/disagg_proxy_demo.py 分解示例 renamed 4.73
examples/disaggregated/disaggregated_encoder/disagg_epd_proxy.py 分解示例 renamed 4.35
examples/disaggregated/disaggregated_prefill.py 分解示例 renamed 4.35
docs/features/disagg_prefill.md 文档 modified 3.0
examples/disaggregated/flexkv_connector/prefix_caching_flexkv.py 分解示例 renamed 4.33

分析完成后,这里会展示 LLM 生成的相对完整源码片段和详细注释。

评论区精华

docs/features/disagg_prefill.md 链接标签缺少 examples/ 前缀 documentation

gemini-code-assist 指出 links 标签缺少 examples/ 前缀,与其他链接不一致。

结论:作者已采纳建议并修复。 · 已解决

MooncakeConnector 描述误写为 ExampleConnector documentation

gemini-code-assist 指出描述中错误地引用了 ExampleConnector,是复制粘贴遗留。

结论:作者已采纳建议并修正。 · 已解决

风险与影响

风险极低。主要风险是文档遗漏更新,导致用户按旧路径找不到文件。但本次 PR 已全面更新关联文档和脚本内路径引用,且经过 review 确认。无运行时逻辑变更,不影响正常功能。

对用户:示例路径发生变化,如果用户之前依赖旧路径运行示例,需更新命令。对系统:无影响。对团队:按场景组织示例更易维护和发现。

路径更新遗漏 纯文件级变更

关联 Issue

#29362 [RFC]: Resettle examples.

完整报告

参与讨论