执行摘要

• 一句话：新增 msProbe 调试工具集成，支持 forward 数据 dump
• 推荐动作：该 PR 展示了低侵入性调试集成的优秀实践：通过 CLI 参数控制、惰性导入、默认零开销。建议团队在类似场景中参考此模式。值得一读。

功能与动机

SGLang 目前缺乏精度分析能力，PR body 指出："Address the shortcomings in precision analysis: Resolve SGLang's pain point of 'only collection available, no analysis possible' through msProbe's professional analysis capabilities"。参考 issue #18162。

实现拆解

1. 添加配置参数：在 server_args.py 中新增 msprobe_dump_config: Optional[str] = None 字段，注册 CLI 参数 --msprobe-dump-config。在 _handle_other_validations 中，启用时自动关闭 CUDA Graph 和 warmup（因为 msProbe 仅支持 eager 模式）。

2. 惰性初始化调试器：在 model_runner.py 的 __init__ 中，若参数指定则调用 init_msprobe() 创建 msprobe_debugger。导入失败时只 warning，不阻塞服务。

3. 插入 forward 采集点：在 ModelRunner.forward() 入口调用 self.msprobe_debugger.start()，出口调用 stop() 和 step()，覆盖整个前向过程。

4. 配套文档：新增 docs/developer_guide/msprobe_debugging_guide.md（598 行），包含安装、配置示例、E2E 调试流程；更新 server_arguments.md 参数表。

关键文件：

• python/sglang/srt/model_executor/model_runner.py（模块 模型执行器；类别 source；类型 core-logic；符号 init_msprobe）: 核心实现：在 ModelRunner 的 init 中初始化 msprobe_debugger，在 forward 方法中插入采集点（start/stop/step）。
• python/sglang/srt/server_args.py（模块 服务参数；类别 source；类型 core-logic）: 新增 msprobe_dump_config 参数和对应 CLI 注册，并在启用时自动禁用 CUDA Graph 和 warmup。
• docs/developer_guide/msprobe_debugging_guide.md（模块 开发者文档；类别 docs；类型 documentation）: 完整的 msProbe 使用指南，包含安装、参数说明、E2E 示例和注意事项。
• docs/advanced_features/server_arguments.md（模块 高级特性文档；类别 docs；类型 documentation）: 在 server_args 参数表中添加 --msprobe-dump-config 条目。

关键符号：init_msprobe

关键源码片段

python/sglang/srt/server_args.py

新增 msprobe_dump_config 参数和对应 CLI 注册，并在启用时自动禁用 CUDA Graph 和 warmup。

# 在 ServerArgs 类中新增字段
msprobe_dump_config: Optional[str] = None
​
# 在 _handle_other_validations 中
if self.msprobe_dump_config is not None:
    logger.warning(
        'When msProbe is enabled, '
        'cuda graph is disabled(disable_cuda_graph=True) because msProbe only supports dump in eager mode, '
        'warmup is disabled(skip_server_warmup=True) because there is no need to dump data for this stage.'
    )
    self.disable_cuda_graph = True
    self.skip_server_warmup = True

评论区精华

• 文档重组建议：@ping1jing2 建议文档结构改为 What/Use Cases/基础参数/E2E 示例/常见问题，@Zhuohao-Li 也认为应精简冗余。作者采纳并重构。
• pandas 版本兼容：@Zhuohao-Li 指出 msprobe 依赖 pandas==2.0.3 在 Python >=3.12 下不兼容。作者回应新版本 26.0.0-alpha.2 已修复，维护者等待发布后合并。
• 参数命名统一：@ping1jing2 要求统一使用 msprobe（而非 mindstudio-probe），作者完成修改。

• 日志格式优化：@ping1jing2 建议使用 f-string 使禁用原因更清晰，作者调整日志。

  • 文档结构重组 (documentation): 作者采纳建议，大幅重构了文档，增加了 E2E 示例并精简了冗余内容。
  • pandas 版本兼容性 (other): 作者回应新版本 26.0.0-alpha.2 已修复此问题，维护者等待发布后合并。
  • 参数命名统一 (style): 作者将所有相关注释和文档改为 msprobe。
  • 日志信息改进 (style): 作者调整了日志信息格式。
  • 文档排版问题 (documentation): 作者修复排版并采用折叠块组织示例配置。

风险与影响

• 风险：
  • 依赖风险：msProbe 在 import 失败时仅 warning，服务仍可正常推理，但用户可能忽略 warning 而误以为已启用。
  • 性能影响：启用 msprobe 会强制 disable_cuda_graph=True 和 skip_server_warmup=True，推理性能显著下降（仅 eager 模式），应仅用于调试。
  • 版本兼容：msprobe 早期版本与 Python >=3.12 不兼容，需确保用户安装的版本已修复（>=26.0.0-alpha.2）。
  • 数据安全：dump 路径需用户配置，无访问控制，敏感数据可能落盘。
• 影响：
  • 用户角度：提供了零侵入的精度调试能力，降低定位 NaN/Inf 等问题的门槛。
  • 系统角度：默认关闭，对现有系统无任何影响；开启后仅影响单次推理的性能和 CUDA Graph 可用性。
  • 团队角度：增加了外部依赖（msprobe）的维护负担，需跟踪兼容性和文档更新。
  • 风险标记：依赖惰性加载, 强制禁用 CUDA Graph, 仅支持 eager 模式, 外部依赖版本兼容风险

关联脉络

• 暂无明显关联 PR