SGLang Torch Profiler 源码地图从入口到分布式 Trace 的完整剖析链路【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglangSGLang 内置了一套完整的在线性能剖析live profiling能力允许在服务运行期间对 prefill、decode 等 forward 阶段进行采样并输出 Chrome Trace 格式.trace.json.gz的分布式 profile 文件。本文以仓库内.claude/skills/llm-torch-profiler-analysis/references/source-map.md为骨架结合当前仓库源码逐层拆解客户端入口 → Scheduler 侧 trace 写入 → 分布式合并的完整调用链并给出可直接复制的命令与参数说明。读完本文你将掌握如何通过三种客户端入口发起剖析、如何理解TP/DP/PP/EP与阶段后缀组成的输出文件名、如何用SGLANG_PROFILE_V2获得按阶段stage-scoped的独立 trace以及如何基于真实测试用例验证整个流程。一、概览剖析功能的源码分层从源码结构看SGLang 的剖析功能大致分为三层客户端入口层负责构造参数并向服务端 HTTP 接口发起请求包括 python/sglang/profiler.py交互式 CLI、python/sglang/test/send_one.py最小请求路径、python/sglang/benchmark/serving.py基准测试路径对应旧入口python/sglang/bench_serving.py。Scheduler 侧 trace 写入层负责真正的 profiler 启停与文件落盘包括 python/sglang/srt/managers/scheduler_components/profiler_manager.pyv1 管理器、python/sglang/srt/utils/profile_utils.pyv2 阶段式管理器、python/sglang/srt/utils/profile_merger.py多卡 trace 合并。验证与文档层docs/docs/developer_guide/benchmark_and_profiling.mdx 为官方规范文档test/registered/profiling/test_start_profile.py 验证/start_profile行为。需要说明的是source-map 中记录的python/sglang/srt/managers/scheduler_profiler_mixin.py在当前仓库中已迁移为python/sglang/srt/managers/scheduler_components/profiler_manager.pybench_serving.py也已重构为 python/sglang/benchmark/serving.py 的兼容入口阅读源码时请以迁移后的路径为准。二、客户端入口一sglang.profiler交互式 CLIpython/sglang/profiler.py 是面向人工交互的最小剖析入口用法为python3 -m sglang.profiler其核心逻辑集中在run_profile()函数中完整参数如下参数默认值说明--urlhttp://localhost:30000服务端地址--output-dir$SGLANG_TORCH_PROFILER_DIR默认/tmptrace 输出目录--num-steps5剖析的 forward 步数--profile-by-stageFalse是否对 prefill 与 decode 分别剖析--profile-prefix无输出文件名的前缀--cpuTrue是否采集 CPU 活动--gpuTrue是否采集 GPU 活动--memFalse是否记录内存快照torch.cuda.memory 快照--rpdFalse是否使用 ROCm 的 rpd profilerrocmProfileData--merge-profilesFalse是否将各 rank 的 trace 合并为单个文件从源码看run_profile()的执行流程是输出目录取--output-dir未指定时回退到环境变量SGLANG_TORCH_PROFILER_DIR默认/tmp并在其后追加time.time()子目录profiler.py第 31-35 行调用GET {url}/server_info拉取服务端参数落盘为server_args.json方便后续复现启动配置第 42-49 行构造 JSON 请求体含output_dir、num_steps、activities、profile_by_stage、merge_profiles、profile_prefix可选start_stepPOST {url}/start_profile第 53-64 行。接口会阻塞到指定步数处理完毕、文件生成后才返回因此命令结束即可直接到目录取 trace。由于 CLI 的--cpu/--gpu/--mem/--rpd会被组装成activities列表传给后端第 140-148 行这也决定了后端实际启动哪些 profiler详见第四节。三、客户端入口二sglang.test.send_one最小请求路径当你想一条命令同时完成发请求与剖析时python/sglang/test/send_one.py 是最合适的入口。它的 docstring 直接给出了三个剖析示例python3 -m sglang.test.send_one --profile --profile-steps 5 python3 -m sglang.test.send_one --profile --profile-by-stage python3 -m sglang.test.send_one --stop |separator| |eos| --max-new-tokens 2048关键机制send_one.py第 199-208 行当--profile开启时脚本会先调用sglang.profiler中的run_profile()启动剖析默认采集[CPU, GPU]再向/generate发送真实请求。由于/start_profile会阻塞到num_steps个 forward 步完成剖析窗口天然覆盖了随后的生成过程。可用--random-input-len生成指定 token 长度的随机 prompt避免 radix cache 命中确保完整的 prefill 被采集到。四、客户端入口三sglang.benchmark.serving基准测试路径在基准测试场景下使用 python/sglang/benchmark/serving.py旧路径python/sglang/bench_serving.py仅为兼容转发表见其第 1-19 行。它对应的剖析参数族第 2485-2524 行附近包括参数说明--profile开启剖析注释明确提示需配合SGLANG_TORCH_PROFILER_DIR使用--profile-activities采集活动可选CPU GPU CUDA_PROFILER XPU MEM默认[CPU,GPU]MEM会导出 torch.cuda.memory 快照--profile-start-step经过多少个 forward 步后开始剖析用于跳过 warmup--profile-steps/--profile-num-steps剖析步数指定后剖析会自动停止--profile-by-stage对 prefill / decode 分别剖析--profile-stages配合按阶段剖析时指定感兴趣的阶段如prefill decode--profile-output-dirtrace 输出目录--profile-prefix文件名前缀基准脚本内部通过async_request_profile()第 843-896 行构造请求体转发activities、profile_by_stage、profile_stages、profile_prefix等字段与 source-map 的描述一致。特别地PD 分离prefill/decode disaggregation模式下可通过--profile-prefill-url/--profile-decode-url分别指定 prefill worker 与 decode worker 的地址脚本会用_build_profile_urls()与_call_profile_pd()第 898-936 行对两类 worker 独立执行 start/stop。五、Scheduler 侧真正的 trace 启停与落盘无论从哪个入口发起请求最终都落到 python/sglang/srt/managers/scheduler_components/profiler_manager.py 的SchedulerProfilerManager。它通过_init_profile/_start_profile/_stop_profile三个方法完成状态管理并由_profile_batch_predicate在每个 forward 批处理时驱动启停判定第 408-450 行start_step语义profiler_start_forward_ct max(start_step, get_forward_ct() 1)第 142 行即在 warmup 若干步后才开始num_steps语义若同时给了start_step则target start num_steps否则target 当前步数 num_steps 1第 144-155 行按阶段剖析profile_by_stageTrue时分别维护profiler_prefill_ct与profiler_decode_ctprefill 采样结束后强制 flush避免 prefill 采集吸收 decode 步第 424-425 行decode 阶段则支持SGLANG_PROFILE_BY_STAGE_DECODE_MIN_BS环境变量——当批大小低于该阈值时等待满载再开始采集第 426-429 行。5.1 输出文件名模式TP/DP/PP/EP 与阶段后缀这是理解输出结果的关键。_stop_profile中第 338-354 行按如下规则构造文件名[{profile_prefix}-]{profile_id}-TP-{tp_rank}[-DP-{dp_rank}][-PP-{pp_rank}][-EP-{ep_rank}][-{stage}].trace.json.gz其中profile_id由run_profile传入time.time()目录名DP/PP/EP段仅在对应并行度大于 1 时追加保持向后兼容stage段仅在按阶段剖析时出现如-EXTEND、-DECODE。每张卡的 trace 通过export_chrome_trace()落盘随后torch.distributed.barrier(cpu_group)确保所有 rank 完成写盘第 359 行。5.2 活动类型与对应 profileractivities列表决定启动哪些底层 profiler_start_profile第 180-276 行活动底层实现输出CPU/GPUtorch.profiler.profile.trace.json.gzChrome TraceMEMtorch.cuda.memory._record_memory_history-memory.pickle可用 torch memory_viz 可视化CUDA_PROFILERtorch.cuda.cudart().cudaProfilerStart/Stop供nsys等外部工具配合使用的 CUDA profiler 开关RPDROCmrpdTracerControlrpd-{timestamp}-TP-{rank}.trace.json.gz先写trace.rpd再转换XPUtorch.profiler.ProfilerActivity.XPU同上CUDA_PROFILER活动在 test/registered/profiling/test_start_profile.py 中通过TestStartProfileWithNsys单独验证该测试类会先检查nsys是否可用并注意 ROCm 平台因 HIP runtime 在 CUDA graph replay 下可能死锁测试启动时默认追加--disable-cuda-graph测试第 50-64 行。_start_profile中 torch profiler 的with_stack与record_shapes默认值分别来自环境变量SGLANG_PROFILE_WITH_STACK默认True与SGLANG_PROFILE_RECORD_SHAPES默认True定义于 python/sglang/srt/environ.py 第 433-439 行。5.3 直接调用 HTTP API不依赖任何客户端脚本也可直接发 HTTP 请求官方文档benchmark_and_profiling.mdx中的 HTTP 端点章节# 立即开始剖析 10 步步数到达后自动停止并落盘 curl -X POST http://localhost:30000/start_profile \ -H Content-Type: application/json \ -d {num_steps: 10, activities: [CPU, GPU]} # 先 warmup 5 步再剖析 10 步 curl -X POST http://localhost:30000/start_profile \ -H Content-Type: application/json \ -d {start_step: 5, num_steps: 10} # 不指定 num_steps手动停止 curl -X POST http://localhost:30000/start_profile curl -X POST http://localhost:30000/stop_profile # 开启详细标注在 step span 中折叠各阶段聚合指标 curl -X POST http://localhost:30000/start_profile \ -H Content-Type: application/json \ -d {num_steps: 10, detailed_annotations: true}后端入口位于 python/sglang/srt/entrypoints/http_server.pystart_profile请求经SchedulerProfilerManager._profile分发见profiler_manager.py第 452-485 行。六、分布式 trace 合并ProfileMerger多卡并行TP/DP/PP/EP时每张 rank 各产出一个 trace 文件逐文件分析非常不便。python/sglang/srt/utils/profile_merger.py 的ProfileMerger解决这一问题--merge-profiles开启后_merge_profile_traces()profiler_manager.py第 281-311 行会在 rank 0且 DP/PP/EP rank 均为 0上执行合并产出merged-{profile_id}.trace.json.gz。合并逻辑要点文件发现用{profile_id}*.trace.json.gz通配并排除合并产物与-memory.pickleprofile_merger.py第 84-101 行rank 标注从文件名正则提取TP/DP/PP/EP信息将每个事件的pid重写为[DP00-EP00-PP00-TP00]形式的标签第 103-122、143-159 行方便在 trace viewer 中区分各 rank排序权重通过sort_index让 DP 优先级最高、TP 最低乘数依次为1e8 / 1e6 / 1e4 / 1e2第 29-34 行保证 viewer 中的视觉顺序稳定。source-map 特别提醒合并后的 trace 与单 rank 的 trace 应区别对待——合并文件聚合了多 rank 事件并改写了 PID做单卡性能归因时仍应以 rank-local trace 为准。七、Profile v2按阶段输出独立 trace设置环境变量SGLANG_PROFILE_V21后SchedulerProfilerManager会切换到 python/sglang/srt/utils/profile_utils.py 中的ProfileManagerv1/v2 分支见profiler_manager.py第 59-64 行。两者核心差异v2 采用_StageBasedTriggerprofile_utils.py第 191-241 行按 prefill/decode 阶段分别计数与启停每个阶段独立达到num_steps目标后触发on_stop并允许通过profile_stages只关注感兴趣阶段默认[prefill, decode]第 133 行每个阶段通过output_suffixf-{stage}生成带阶段后缀的独立文件第 160 行v2 的configure()当前断言start_step is None、profile_by_stageTrue、merge_profilesFalse第 111-115 行即该路径聚焦于阶段式剖析尚未支持部分 v1 参数阶段判定由_get_stage_from_forward_mode完成is_prefill()→prefillis_decode()→decodeidle 返回None第 177-185 行。此外profile_utils.py还包含两个独立能力CUDA graph 捕获 trace设置SGLANG_ENABLE_CUDA_GRAPH_CAPTURE_TRACE1后export_cuda_graph_capture_trace()会把 CUDA graph 捕获期的 profiler 记录要求record_shapesTrue导出为graph_capture_profile/cuda_graph_capture-{runner_name}-TP-{tp_rank}.json.gz第 52-70 行按 runner 类与 TP rank 命名以避免并发覆盖step span 命名build_step_span_name()生成step[EXTEND bs{bs} toks{toks}]或step[{mode.name} bs{bs}]形式的 span 名第 463-488 行开启detailed_annotations时还会折叠各阶段聚合指标直接对应/start_profile请求体中的detailed_annotations字段。八、验证与测试/start_profile的行为契约test/registered/profiling/test_start_profile.py 是剖析链路的官方行为验证覆盖了 v1 路径的关键语义test_start_profile_1以start_step15, num_steps5发起验证延迟到第 15 步后开始、采集 5 步并落盘test_start_profile_2不带参数启动验证停止前目录为空、/stop_profile后目录非空test_start_profile_3仅num_steps5验证自动停止语义TestStartProfileWithNsys.test_start_profile_cuda_profiler验证CUDA_PROFILER活动依赖nsys可用性。测试通过envs.SGLANG_TORCH_PROFILER_DIR.set(OUTPUT_DIR)把输出导向测试目录运行方式test_start_profile.py第 1-11 行cd test/srt python3 -m unittest test_start_profile.TestStartProfile python3 -m unittest test_start_profile.TestStartProfileWithNsys.test_start_profile_cuda_profiler九、完整工作流与实用建议综合上述链路一次典型的剖析流程是# 1. 启动服务trace 输出目录由环境变量控制默认 /tmp SGLANG_TORCH_PROFILER_DIR./profiles python3 -m sglang.launch_server \ --model-path model --host 0.0.0.0 --port 30000 # 2. 方式 A最小验证单请求 剖析 python3 -m sglang.test.send_one --profile --profile-steps 5 --random-input-len 2048 # 方式 B按阶段分别采样 python3 -m sglang.test.send_one --profile --profile-by-stage # 方式 C基准负载 剖析多卡合并 python3 -m sglang.benchmark.serving --model model --num-prompts 100 \ --profile --profile-activities CPU GPU --profile-num-steps 10 \ --merge-profiles --profile-output-dir ./profiles # 3. 分析产物 ls ./profiles/*/ # server_args.json *.trace.json.gz # 用 chrome://tracing 或 Perfetto 打开 .trace.json.gz实用要点保留server_args.json它记录了服务启动参数profiler.py自动写入复现与比对实验必备prefill/decode 分别采样二者批大小、计算模式差异巨大混采难以定位瓶颈优先--profile-by-stagedecode 阶段可用SGLANG_PROFILE_BY_STAGE_DECODE_MIN_BS控制最小批大小等待负载满载再采样warmup 与随机 prompt用--profile-start-step跳过首段不稳定步用--random-input-len规避 radix cache 命中确保真实计算被采样多卡场景先分析 rank-local trace 做单卡归因再用--merge-profiles查看全局时间线ROCm/NPU 适配ROCm 用RPD活动--rpdNPU 平台会自动 patch 到torch_npu.profiler见profiler_manager.py第 33-43 行。十、结语从profiler.py的run_profile()到SchedulerProfilerManager的步数判定再到ProfileMerger的多 rank 合并与ProfileManager的阶段式 v2 路径SGLang 的剖析链路是一条完整、可观测、可验证的闭环。官方文档 docs/docs/developer_guide/benchmark_and_profiling.mdx 是总入口本文所引源码与测试即为该文档的落地实现。遇到 trace 文件无法解释的问题时建议对照 python/sglang/srt/managers/scheduler_components/profiler_manager.py 与 python/sglang/srt/utils/profile_utils.py 的启停逻辑逐段核对通常能快速定位是采样窗口、活动类型还是文件名解析的问题。【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考