执行摘要

• 一句话：新增环境变量延迟解码阶段性能采集，提升 batch-size 基准测试的代表性。
• 推荐动作：这是一个小而精的工具增强，值得所有关注性能分析或使用 profile_by_stage 的开发者快速浏览。它展示了一个简单但有效的设计模式：通过引入一个带安全默认值的配置来控制已有行为，以增强工具的适用场景。代码逻辑清晰，实现直接，可以快速审阅。

功能与动机

PR body 明确指出动机：'With profile_by_stage, the scheduler starts the decode-stage trace on the very first decode batch. On a batch-size benchmark that first decode batch is still ramping up toward full admission, so the captured decode steps are not representative of steady state.' 变更旨在让性能分析器能够捕获更准确的稳态解码性能。

实现拆解

1. 定义新配置键：在 python/sglang/srt/environ.py 的 Envs 类中，于性能分析相关配置段落下新增 SGLANG_PROFILE_BY_STAGE_DECODE_MIN_BS = EnvInt(0)，并附有清晰的注释说明其用途和默认值（0 保持现有行为）。
2. 实现延迟启动逻辑：在 python/sglang/srt/managers/scheduler_components/profiler_manager.py 的 _profile_batch_predicate 方法中，当 profile_by_stage 启用且进入解码阶段（batch.forward_mode.is_decode()）、profiler_decode_ct == 0（首次解码批次）时，增加判断逻辑。新增代码读取环境变量值，若值大于0且当前批次大小（batch.batch_size()）小于该值，则直接 return，不启动解码阶段的性能采集，同时也不递增 profiler_decode_ct，确保后续批次会继续检查直到满足条件。
3. 更新注释与无默认路径变更：同步更新了原有强制刷新 prefill 追踪的注释，使其更清晰。整个变更严格限定在 profile_by_stage 路径内，不影响默认分析路径、SGLANG_PROFILE_V2 或非分阶段分析器。
4. 测试配套说明：PR 中未包含对应的单元测试。作者在 checklist 中注明此为分析器专用变更，无数值准确性影响，且已在内部环境验证。变更范围小且逻辑明确，风险可控。

关键文件：

• python/sglang/srt/managers/scheduler_components/profiler_manager.py（模块 调度分析器；类别 source；类型 core-logic；符号 _profile_batch_predicate）: 包含核心逻辑变更，在性能分析谓词函数中加入了基于最小批次大小的延迟启动判断。
• python/sglang/srt/environ.py（模块 环境配置；类别 source；类型 configuration；符号 SGLANG_PROFILE_BY_STAGE_DECODE_MIN_BS）: 新增了 SGLANG_PROFILE_BY_STAGE_DECODE_MIN_BS 环境变量定义，是本次功能的基础配置。

关键符号：_profile_batch_predicate

关键源码片段

python/sglang/srt/managers/scheduler_components/profiler_manager.py

包含核心逻辑变更，在性能分析谓词函数中加入了基于最小批次大小的延迟启动判断。

    def _profile_batch_predicate(self, batch: ScheduleBatch):
        if envs.SGLANG_PROFILE_V2.get():
            self._profile_manager.step(forward_mode=batch.forward_mode)
            return
​
        if self.profile_by_stage:
            if batch.forward_mode.is_prefill():
                # ... (prefill logic unchanged)
                pass
            elif batch.forward_mode.is_decode():
                if self.profiler_decode_ct == 0: # 首次解码批次
                    if self.profile_in_progress:
                        # force trace flush (a prefill capture must not absorb decode steps)
                        self._stop_profile(stage=ForwardMode.EXTEND)
                    # 获取新的最小批次大小配置
                    min_bs = envs.SGLANG_PROFILE_BY_STAGE_DECODE_MIN_BS.get()
                    # 如果设置了最小值且当前批次未达到，则直接返回，不启动解码采集
                    if min_bs > 0 and batch.batch_size() < min_bs:
                        return
                    # 满足条件，启动解码阶段采集
                    self._start_profile(batch.forward_mode)
                self.profiler_decode_ct += 1
                # ... (subsequent decode logic unchanged)
            # ... (idle and else branches unchanged)
        else:
            # ... (non-stage profiler logic unchanged)
            pass

评论区精华

本次 PR 无外部 review 评论，讨论主要体现在作者与提交信息中。作者在 PR body 和 commit message 中清晰地阐述了问题背景和解决方案，属于对现有性能分析工具链的补充和优化。没有发现设计权衡或未解决的争议点。

• 暂无高价值评论线程

风险与影响

• 风险：风险较低。变更范围极小（仅两个文件，9行增加/1行删除），且严格封装在现有的 profile_by_stage 功能开关之后，默认行为（SGLANG_PROFILE_BY_STAGE_DECODE_MIN_BS=0）未改变，不影响任何生产或默认分析路径。唯一需要考虑的是用户设置的最小批次大小值（min_bs）可能不合理（如设得过大），导致永远无法启动解码追踪，但这属于用户配置责任，且默认值是安全的。
• 影响：影响范围非常有限，仅面向使用 profile_by_stage 功能进行深度性能分析的开发者或性能工程师。对于普通用户、默认分析路径以及系统稳定性、性能、安全性均无影响。改进提升了该特定分析模式下的数据质量，有助于更精准地诊断解码阶段的性能瓶颈。
• 风险标记：配置依赖正确使用

关联脉络

• PR #37636 [Metrics] Export scheduler stage wall time: 同为增强调度器与性能分析可观测性的改进，PR #37636 导出调度阶段耗时指标，本 PR 优化分阶段追踪的数据捕获时机，共同提升性能诊断能力。
• PR #37461 [Metrics] Add rolling scheduler utilization counters: 同属于对调度器和系统运行状态的可观测性增强系列工作，本 PR 聚焦于性能分析器的精准触发。