sglang-sota-humanize-loop

SGLang SOTA 人性化循环

概述

当用户指定模型，并希望 SGLang 服务路径能够自主持续优化，直到在相同目标环境中达到或超过所请求对比框架集合中的最佳可复现结果时，使用此技能。

此工作流有两个持久阶段：

1. 固定基线阶段，必须在任何代码补丁之前完成一次。
2. 一个 Humanize RLCR 循环，负责决定差距、分析性能、深入分析所需的层和内核、修改 SGLang、按需收集 NCU 证据，以及使用真实模型重新验证。

不要将整个过程拆分为前期性能分析阶段和后续补丁循环。固定基准测试完成后，第 2 阶段的差距判断、第 3 阶段的性能分析、llm-pipeline-analysis、内核证据和代码更改都必须包含在同一个模型级 RLCR 循环中。

运行时根目录

此技能可以在 Claude Code、Codex 或其他兼容的技能运行时中运行。按以下顺序确定配套技能根目录：

1. 在 Claude Code 中运行时，优先使用 ~/.claude/skills 下已安装的 Claude Code 技能。
2. 在 Codex 中运行时，优先使用 ${CODEX_HOME:-~/.codex}/skills 下已安装的 Codex 技能。
3. 如果技能通过符号链接连接，或为开发而保存在本地，则回退到已检出的仓库。

本地路径示例：

Humanize runtime: ${CODEX_HOME:-~/.codex}/skills/humanize
ncu-report-skill: ${CODEX_HOME:-~/.codex}/skills/ncu-report-skill/SKILL.md
Model PR history knowledge: <repo>/model-pr-optimization-history

对于 Claude Code 安装，通常对应的默认路径为：

Humanize runtime: ~/.claude/skills/humanize
ncu-report-skill: ~/.claude/skills/ncu-report-skill/SKILL.md
Model PR history knowledge: ~/.claude/skills/model-pr-history-knowledge

如果缺少 Humanize 运行时，请找到包含 scripts/setup-rlcr-loop.sh 的插件或技能目录。如果 ncu-report-skill 不可用，仍可依据 torch-profiler 或源码证据进行内核修改；但如果内核更改通常需要 Nsight Compute 诊断，则应将缺少 NCU 证据路径记录为阻碍因素。

配套技能

开始实际运行前，请阅读以下内容：

• ../llm-serving-auto-benchmark/SKILL.md
• ../llm-torch-profiler-analysis/SKILL.md
• ../llm-pipeline-analysis/SKILL.md
• ../../model-pr-optimization-history/SKILL.md
• 与 SSH、容器、GPU 和工件约定相匹配的主机或算子技能

仅当当前 RLCR 轮次正在编写或评估 CUDA、Triton、CuTe、CUTLASS、TileLang 或 torch.compile 内核路径，且需要 Nsight Compute 证据时，才阅读 ncu-report-skill/SKILL.md。

约定

收到模型级 SGLang SOTA 请求后，不要要求用户分别运行基准测试、性能分析、gen-plan、refine-plan 或 Humanize 设置命令。请自行完成设置。

只有在缺少模型、目标 GPU 环境或精度／量化策略，且无法从本地配置或当前主机技能中推断时，才询问用户。

仅将固定基准测试阶段保留在 RLCR 补丁循环之外。固定的跨框架基准测试和模型 PR 历史记录完成后，立即启动 Humanize。RLCR 循环本身必须判断是否仍有差距、收集当前性能分析证据、运行层级流水线分析、修改 SGLang 并重新验证。

将模型优化活动视为持久的工作单元，而非单次终端会话。可以从运行工件根目录、检查点文件、基准测试／性能分析工件、NCU 摘要和台账中恢复活动。

阶段 0：输入和运行目录

收集或推断以下信息：

• 模型 ID 或检查点路径、分词器、精度、量化、信任策略和最大上下文长度
• 要修改的目标 SGLang 检出目录
• GPU 类型／数量、可见 GPU ID、容器或远程 Shell、CUDA／NCCL 版本，以及是否允许多节点
• 目标框架：始终为 SGLang
• 对比框架集合：如果用户明确指定或排除对比框架，则严格遵循该集合；否则，默认使用可用的 vLLM、TensorRT-LLM 和 TokenSpeed
• 尽可能根据模型 ID、检查点或热点框架源码路径推断的模型系列历史 slug
• 工件根目录

创建一个运行目录：

runs/YYYYMMDD_<model_slug>_sota_humanize/
  manifest.md
  help/
  benchmark/
    fairness/
  profiles/
  analysis/
    root-cause.md
    layer-pipeline.md
    fairness-diagnostics.md
  history/
    model-pr-history-notes.md
  kernel/
    ncu-digests/
  patches/
  humanize/
    model-loop-checkpoint.md
  final_report.md

切勿将 Hugging Face 令牌或其他机密信息保存到工件中。

框架选择

将 SGLang 与对比框架视为不同概念：

• SGLang 始终是目标框架，因为此循环会为 SGLang 打补丁。
• comparison_frameworks 仅包含竞争框架，并使用规范名称 vllm、tensorrt_llm 和 tokenspeed。
• 如果用户说“只与 vLLM 对比”“comparison_frameworks: [vllm]” 或“不要考虑 TensorRT-LLM/TokenSpeed”，则仅运行 SGLang 和 vLLM。
• 不要因为存在配置或文档就擅自添加 TensorRT-LLM 或 TokenSpeed。
• 在 manifest.md 和 benchmark/fairness/diagnostics.md 中记录选定的对比框架和用户排除的框架。
• 仅读取所选对比框架的历史记录、启动其基准测试，并分析其跟踪数据。

阶段 0.5：模型 PR 历史知识门控

在固定基准测试和任何补丁规划之前，查询并阅读 model-pr-optimization-history 中与目标模型系列相关的内容。

规则：

• 如果 slug 不明确，请在知识库根目录运行 scripts/query.py "<model id or family>"，并选择最接近的模型系列历史记录。
• 只要存在该模型系列的 SGLang 历史记录，就必须阅读。
• 如果之后某个选定的对比框架成为主要竞争对手，或其源码/跟踪数据表明 SGLang 缺少快速路径，也要阅读该框架的历史记录。
• 创建 history/model-pr-history-notes.md，记录读取过的路径、PR 编号、不可变的源码提交、PR 状态（open、merged 或 closed-unmerged）、源码文件、符号、验证证据、已知限制、验证风险，以及每项内容影响的具体决策。
• 仅将开放 PR 视为候选基线。记录其完整的 head SHA，绝不要将其描述为记录的源码提交中已有的行为。
• 将这些说明视为有助于选择更优 SGLang 补丁的源码和 PR 参考记录，而非独立的实测证明。

如果知识库根目录不可用，请在同一说明文件中记录阻碍，并继续依据基准测试/性能分析证据开展工作。

阶段 1：固定公平基准门槛

此阶段为必需步骤，必须在 Humanize 开始前执行，且仅执行一次。

使用 llm-serving-auto-benchmark 作为候选生成、结果架构、工作负载和比较的权威依据。

硬性要求：

• 如果目标环境支持 SGLang 和每个选定的对比框架，搜索各自的最佳部署命令。
• 不要将调优后的 SGLang 与竞争框架的默认配置进行比较。每个框架都必须进行各自有界的搜索。
• 使用相同的模型权重、分词器、精度、量化方式、GPU 类型/数量、GPU ID、端点路径、采样设置和 SLA。
• 记录 SGLang 和每个选定对比框架的软件包版本或 git 提交，以及服务端/基准测试的 --help 快照。本技能核查的不可变源代码头版本（2026-08-23）为：SGLang eec794bce0808ae26cc1dcb84a56b65d2df82af5、vLLM bbe8b23e1a2b32a96240b27f63255170d09ef144、TensorRT-LLM da38c1d2e0dffd073b7dfb6d69e15ee7b45d84a9，以及 lightseekorg/tokenspeed@2706143a8669d50a8f56466b9d340b86922b8f2d； 但应优先使用目标镜像中的 --help，而不是这些源代码说明，并在每次长时间 SOTA 运行前重新检查开放的 PR。
• 使用目标镜像当前支持的命令：sglang serve 或 python -m sglang.launch_server、 vllm serve、trtllm-serve serve --backend pytorch，以及在选用时使用 tokenspeed serve <model>（或已验证的镜像别名）。
• 除非用户明确提供生产工作负载，否则使用 llm-serving-auto-benchmark 中默认的两个数据集场景：
  • 数据集类型 random，num_prompts: 80
  • chat：随机输入 1000，输出 1000
  • summarization：随机输入 8000，输出 1000
  • 将两组输入/输出配对视为对齐场景，而不是笛卡尔积
• 不要用更简单的冒烟测试数据集替代这些场景来做实际 SOTA 决策。仅当明确标记为流程检查时，才允许运行冒烟测试。
• 若选用 TensorRT-LLM 进行比较，必须使用 trtllm-serve serve --backend pytorch；本技能不接受非 PyTorch 的 TensorRT-LLM 服务后端。
• 若选用 TokenSpeed 进行比较，使用 tokenspeed serve <model> 或目标镜像中的确切别名（例如 ts serve）；记录确切的二进制命令拼写，并验证 tokenspeed serve --help 和 tokenspeed bench serve --help。
• 若选用 TokenSpeed，且存在适用于该模型系列的 TokenSpeed 原生 Agentic 工作负载，则将其作为附加测试通道，与通用跨框架工作负载并行运行。除非用户在基准测试前明确选择该工作负载作为 SOTA 目标，否则不得以其替代通用场景。
• 在基准测试产物中保留失败、跳过以及未达到 SLA 的候选项。
• 只要有数据，就在标准化结果行中记录可选的公平性字段：推测解码接受长度、调度器前耗时/调度器耗时、缓存命中率、卸载或内存驻留情况、端点以及请求形状说明。

完成或报告阻塞问题前，只停止本次运行启动的服务端、基准测试、性能分析器、下载器和日志跟踪进程。仅移除此运行明确指定的模型快照、锁文件、镜像目录和本次运行专用的缓存条目。记录进程和 GPU 状态的运行前后信息；绝不要终止其他用户的进程，也不要删除共享模型缓存。

写入：

• benchmark/candidates.jsonl
• benchmark/summary.md
• benchmark/winning-commands.md
• benchmark/fairness/diagnostics.md
• 将框架帮助输出保存到 help/
• 记录每个获胜项的确切启动命令和基准测试命令

不要选择 RLCR 之外的代码补丁。固定获胜项表是模型循环的基线输入。

阶段 2：制定 Humanize 计划

在将要打补丁的 SGLang 检出目录中创建 Humanize 计划：

.humanize/sglang-sota-agent/refined-plan.md

以 references/refined-plan-template.md 为框架，并填入实际模型、工作负载、基准测试获胜项、 制品根目录、模型 PR 历史记录以及目标 SGLang 检出目录。

计划必须要求每一轮 RLCR：

• 保留固定的基准测试工作负载和 SLA
• 在选择特定于模型的 SGLang 源代码路径之前，保留并查阅 history/model-pr-history-notes.md
• 在将差距判定为代码瓶颈之前，保留并查阅 benchmark/fairness/diagnostics.md
• 在循环内、打补丁之前运行差距判定
• 当 SGLang 落后，或前一个补丁更改了分析路径时，在循环内运行 llm-torch-profiler-analysis
• 在分析器分流之后、选择源代码路径、代表性层或内核目标之前，在循环内运行 llm-pipeline-analysis
• 修改 SGLang 代码，而不只是基准测试参数
• 当内核编辑需要 Nsight Compute 证据时，在同一循环内使用 ncu-report-skill
• 每个已接受的补丁之后，重新运行真实模型的基准测试/分析
• 如果一个补丁只缩小了部分差距，则继续进行多次最小化补丁
• 在制品中记录每次尝试、失败的想法、部分收益、被否决的源代码方案以及最终选定的补丁

阶段 3：启动 RLCR

从 SGLang 检出目录启动 Humanize 之前：

• 确保 SGLang 检出目录是一个至少包含一次提交的 git 仓库，并且工作树干净；唯一例外是被 gitignore 忽略的 Humanize 运行时状态。
• 确保 .humanize* 被 gitignore 忽略，避免 RLCR 状态、轮次摘要和本地检查点被意外暂存。
• 确保预期的审查基准分支已在本地存在。如果 Humanize 的自动检测可能有歧义，请传入 --base-branch <branch>。
• 如果 SGLang 检出目录中有任何现存的 .humanize/rlcr/*/state.md 处于活动状态，请勿启动新循环。应先恢复、完成或取消旧的模型循环。

在 SGLang 检出目录中运行：

"$HUMANIZE_RUNTIME_ROOT/scripts/setup-rlcr-loop.sh" \
  .humanize/sglang-sota-agent/refined-plan.md --yolo

如果客户端/插件环境尚未设置 HUMANIZE_RUNTIME_ROOT， 请先将其解析为已安装的 Humanize 运行时。在 Codex 中，通常是 ${CODEX_HOME:-~/.codex}/skills/humanize；在 Claude Code 中，通常是 ~/.claude/skills/humanize 或插件提供的 Humanize 运行时。如果设置过程以非零状态退出，请停止并报告错误。不得绕过此门槛。

设置成功后：

1. 使用 find .humanize/rlcr -maxdepth 2 -name state.md -print 查找活动状态文件。
2. 验证状态文件存在、包含 current_round: 0，并且使用 --yolo 时包含 ask_codex_question: false。
3. 验证 .humanize/rlcr/<timestamp>/round-0-prompt.md 存在，且包含生成的 Round Contract Setup 指令。
4. 阅读 .humanize/rlcr/<timestamp>/round-0-prompt.md。
5. 执行当前轮次。
6. 提交 SGLang 更改。
7. 编写所需的 Humanize 轮次摘要。
8. 正常停止，以便原生 Humanize Stop hook 进行审查。

如果不存在活动状态文件，或缺少 round-0-prompt.md，请停止并报告 RLCR 未能正确启动。不要在 Humanize 循环之外继续进行 SGLang 补丁工作。如果 hook 阻止退出，请严格按照生成的下一轮提示执行。

在每个 RLCR 轮次内

差距判定

每轮开始时，针对每个固定场景，计算当前 SGLang 与通过 SLA 的最佳入选对比框架之间的差距。

默认使用 1% 作为稳定噪声阈值。如果当前结果在 +/-1% 范围内，应将胜出命令重新运行足够次数，以判断差距是否稳定，然后再决定是否提交补丁。

仅当 SGLang 比最佳入选对比框架慢超过 1%、未通过 SLA 而某个入选竞品通过了 SLA，或在固定工作负载下存在能够解释剩余差距的已分析瓶颈时，才提交补丁。

提交补丁前，根据当前基准测试结果和固定的 benchmark/fairness/diagnostics.md，更新 analysis/fairness-diagnostics.md。检查：

• GPU 数量、可见 GPU ID、模型权重、分词器、精度、量化、端点、采样设置和请求形状是否相同
• 对于启用 drafter/MTP/EAGLE 风格路径的每个框架，其推测解码状态、算法、步数和平均接受长度
• 服务器日志或基准测试输出中提供的调度前、调度器、队列、分词器和反分词器耗时
• 前缀/KV 缓存状态和命中率，尤其是针对重复提示词或多轮工作负载的情况
• GPU 内存利用率、KV 数据类型、卸载情况和模型权重驻留情况
• 选用 TokenSpeed 时特有的服务参数，例如 attn_tp_size、moe_tp_size、enable_expert_parallel、后端选项和通信融合标志

如果当前领先者的胜出原因是使用了不等效的工作负载、不等效的缓存/推测解码设置、不同的驻留权重，或框架特有的端点捷径，应先修正基准测试的标准化设置并重新运行。在通过此公平性检查之前，不要修改 SGLang 代码。

如果 SGLang 已经领先，或与领先者的差距在稳定阈值内，则撰写最终报告，并按照常规 Humanize 审核流程停止。

必需的性能分析

当 SGLang 落后时，使用 llm-torch-profiler-analysis 分析当前表现最佳的 SGLang 命令和领先竞品命令。

规则：

• SGLang 落后时，始终分析 SGLang。
• 始终至少分析当前表现最佳的入选对比框架。
• 如果多个竞品在稳定结果中领先 SGLang 超过 1%，则分析每个能够生成跟踪记录的领先竞品。对于 TokenSpeed，分析部署生成的现有 torch-profiler 跟踪记录或运行目录跟踪记录；如果目标镜像仅支持离线跟踪记录，不要伪造实时性能分析端点。
• 使用耗时较长的基准测试场景长度，而非性能分析工具的默认值：
  • prefill 性能分析：较长的输入长度 -> 1 个输出令牌
  • decode 性能分析：1 个输入令牌 -> 较长的输出长度
• 对于混合数据集或生产数据集，使用基准测试产物中已记录的最慢代表性 p50 或 p95 分桶。
• 如果框架支持，分别采集或分析 prefill 和 decode 的证据。

对于每个已分析的框架，保存相同的三张表：

• kernel 表
• overlap-opportunity 表
• fuse-pattern 表

然后，在 analysis/root-cause.md 中撰写或更新当前的跨框架比较：指出哪个阶段较慢、哪些表格行能够解释这一情况，以及哪些 SGLang 源码路径或 kernel 系列可能是补丁目标。

在当前差距对应的报告生成之前，不要修改 SGLang。

深入了解层级流水线

在每轮 RLCR 中，完成 profiler 排查后、选择补丁目标前，运行 llm-pipeline-analysis。

报告必须明确指出：

• 所选前向传播及其代表性原因
• 相关层类型，尤其是 MoE、哈希层或 compress_ratios 等异构层
• 补丁目标的代表性层
• 这些代表性层中的主要热点内核
• 检查时需要的任何 Perfetto 时间范围

使用经 profiler 分析的 SGLang 跟踪和已部署模型配置。将所选前向传播、层类型耗时表、代表性层、主要热点内核以及检查时使用的任何 Perfetto 时间范围写入 analysis/layer-pipeline.md。当前轮次的这份报告生成前，不要选择 SGLang 补丁。

内核证据辅助

仅当当前 RLCR 轮次正在编写具体内核补丁或小型内核族补丁，且 torch-profiler 证据不足以选择或验证下一步修改时，才使用 ncu-report-skill。

资格门槛：

• 在完成要求的重复运行和 profiler 检查后，对于固定基准场景，SGLang 仍比选定的最佳对比框架慢 1% 以上。
• 慢速阶段的内核表中有一个具体的 SGLang 内核或范围明确的内核族，其 GPU 累计耗时占比至少为 1%。除非某个共享实现会影响占比超过 1% 的聚合内核族，否则不要为占比低于 1% 的单个内核投入内核专家精力。
• llm-pipeline-analysis 已针对当前轮次确定代表性层/前向传播和主要热点内核。
• 拟选内核目标有明确的正确性参照、来自模型运行的代表性形状/数据类型/布局，以及将候选实现接入当前 SGLang 服务代码的途径。

对于每个符合资格的内核目标：

1. 阅读 ncu-report-skill/SKILL.md，并遵循其中的 Nsight Compute 工作流，完成测试框架构建、ncu 数据采集、报告解析、停顿诊断，以及基于证据选择下一步修改。
2. 将 NCU 输出存放在 kernel/ncu-digests/<version>/ 或主机的等效产物根目录下。每份摘要都必须比较基线与候选实现，并以且仅以一项具体的下一步修改结尾。
3. 直接在 SGLang 检出目录中修改 SGLang 内核或调用路径，并在条件允许时进行有针对性的正确性测试和微基准测试。
4. 将候选实现接入生成原始 profiler 记录的当前模型服务路径。
5. 候选实现正确后，重新运行相同的真实模型基准测试和 profiler。仅微基准测试或 NCU 取得性能提升并不算成功。

如果没有合适的专用测试框架，则构建最小测试框架，并保留源自模型的形状/数据类型/布局。如果主机无法运行 NCU，则在摘要路径中记录阻碍，并根据现有的 torch-profiler、层级流水线和源码证据确定下一步修改。

不要为内核目标启动任何独立的 .humanize/rlcr 会话。内核工作必须留在当前模型 RLCR 循环中。

模型循环检查点

每轮结果获接受后，更新 humanize/model-loop-checkpoint.md，记录：

• 原始模型、分词器、精度、量化、硬件、工作负载、SLA、产物根目录和基准测试胜出命令
• 当前 SGLang 分支、提交、已应用补丁、已运行测试和当前最佳 SGLang 基准记录
• 剩余差距、profiler 记录、模型 PR 历史备注、层级流水线备注、NCU 摘要路径、已否决的源码方案，以及计划中的下一项 SGLang 补丁

此检查点用于在同一模型级工作流中恢复优化活动。它应记录足够的上下文，以便恢复优化活动时不丢失基准测试和性能分析的关联信息。

循环记录

根据宿主环境的约定，将这些文件保存在运行产物根目录或 SGLang 检出目录下：

humanize/attempt-ledger.md
humanize/optimization-ledger.md
humanize/source-idea-ledger.md
humanize/lineage.jsonl
humanize/profile-digests/

每次补丁尝试都要记录一行尝试记录。只有正确且经测量确认有提升的补丁，才记录优化项。源代码研究思路必须包含分析器记录、层流水线证据、使用时的 NCU 报告路径，以及代码来源信息，以便后续轮次避免重复阅读相同代码。若模型 PR 历史证据影响了补丁，应将其与 SGLang、选定的对比框架以及 NCU 源代码研究思路的相关记录放在一起。

如果连续两轮相较于此前最佳 SGLang 结果的几何平均提升均不足 1%，则应在再次编辑前扩大以代码为先的研究范围。优先参考 SGLang、选定的对比框架以及相关内核源代码指南中的代码和 PR 证据，而非仅参考文章内容。

停止条件

只有符合以下任一条件时才停止：

• 在固定工作负载上，SGLang 的表现优于通过 SLA 的选定对比框架的最佳结果。
• 多次运行后，SGLang 在稳定的 1% 阈值内持平。
• 已证明剩余差距由 SGLang 之外的因素导致，例如硬件不支持、缺少框架依赖、TensorRT-LLM PyTorch 后端不受支持、TokenSpeed 构建不受支持，或模型权重无法公平加载。
• 分析证据表明，剩余热点路径已接近相关硬件或算法的极限，且没有可行的低风险 SGLang 补丁。

最终报告必须包含固定基准测试表、补丁后基准测试表、所有获胜命令、模型 PR 历史路径、分析结果路径、使用时的层流水线路径、使用时的 NCU 摘要路径、SGLang 已更改文件、测试，以及 SGLang 是否达到目标环境中的 SOTA。