vllm-sota-humanize-loop

vLLM SOTA Humanize 循环

概述

当用户指定模型，并希望 vLLM 服务路径自主持续改进，直至达到或超过相同目标环境中最佳可复现 SGLang 或 TensorRT-LLM 结果时，使用此技能。

此工作流包含两个持久阶段：

1. 固定基准测试阶段，必须在任何代码补丁之前完成一次。
2. 一个 Humanize RLCR 循环，负责差距判定、性能分析、必要的层／内核深入分析、vLLM 补丁、可选的 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。

约定

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

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

只有固定基准测试阶段可以置于 RLCR 补丁循环之外。固定的跨框架基准测试和模型 PR 历史记录完成后，立即启动 Humanize。RLCR 循环本身必须判断差距是否仍然存在、收集当前性能分析证据、运行层流水线分析、为 vLLM 打补丁并重新验证。

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

阶段 0：输入和运行目录

收集或推断以下信息：

• 模型 ID 或检查点路径、分词器、精度、量化、信任策略和最大上下文长度
• 要修改的 vLLM 检出版本
• GPU 类型／数量、可见 GPU ID、容器或远程 Shell、CUDA／NCCL 版本，以及是否允许多节点
• 框架集合；如果可用，默认为 vLLM、SGLang 和 TensorRT-LLM
• 尽可能根据模型 ID、检查点或活跃的 vLLM／SGLang 源代码路径推断的模型系列历史标识
• 工件根目录

创建一个运行目录：

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

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

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

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

规则：

• 如果 slug 不明确，从知识库根目录运行 scripts/query.py "<model id or family>"，并选择最接近的模型系列历史记录。
• 只要存在该系列的 vLLM 历史记录，就必须阅读。
• 如果 SGLang 在对比范围内、之后成为主要竞争对手，或其源码／跟踪信息表明 vLLM 缺少快速路径，也要阅读 SGLang 历史记录。
• 在 history/model-pr-history-notes.md 中记录读取过的路径、PR 编号、不可变源码提交、PR 状态（open、merged 或 closed-unmerged）、源码文件、符号、验证证据、已知限制、验证风险，以及每项内容影响的具体决策。
• 仅将未关闭的 PR 视为候选基线。记录其完整的 head SHA，绝不可将其描述为记录的源码提交中已有的行为。
• 将这些笔记视为源码和 PR 记忆，用于帮助选择更好的 vLLM 补丁；其本身不构成实测证据。

如果知识库根目录不可用，在同一笔记文件中记录阻碍，并继续使用基准测试／性能分析证据。

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

此阶段为必做，且必须在 Humanize 开始前恰好执行一次。

使用 llm-serving-auto-benchmark 作为候选项生成、结果架构、工作负载和对比的事实来源。

硬性要求：

• 如果目标环境支持 vLLM、SGLang 和 TensorRT-LLM，分别搜索它们的最佳部署命令。
• 不要将调优后的 vLLM 与竞争对手的默认配置进行比较。每个框架都要进行各自范围受限的搜索。
• 使用相同的模型权重、分词器、精度、量化方式、GPU 类型／数量、GPU ID、端点路径、采样设置和 SLA。
• 记录每个选定框架的软件包版本或 git commit，以及服务端和基准测试的 --help 快照。本技能检查过的不可变源码提交（2026-08-23）为：vLLM bbe8b23e1a2b32a96240b27f63255170d09ef144、SGLang eec794bce0808ae26cc1dcb84a56b65d2df82af5，以及 TensorRT-LLM da38c1d2e0dffd073b7dfb6d69e15ee7b45d84a9。优先采用目标镜像当前的 --help 输出，重新检查未关闭的 PR；除非端到端验证其可执行的基准测试路径，否则不要将 TokenSpeed 加入此限定工作流。
• 使用目标镜像当前的命令：vllm serve、 sglang serve 或 python -m sglang.launch_server，以及 trtllm-serve serve --backend pytorch。
• 除非用户明确提供了生产工作负载，否则使用 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 服务端后端。
• 在基准测试产物中保留失败、跳过和未达到 SLA 的候选项。

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

写入：

• benchmark/candidates.jsonl
• benchmark/summary.md
• benchmark/winning-commands.md
• help/ 下的框架帮助输出
• 每个胜出项的确切启动和基准测试命令

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

阶段 2：制定 Humanize 计划

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

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

使用 references/refined-plan-template.md 作为框架，并填写实际模型、工作负载、基准测试优胜者、 产物根目录、模型 PR 历史记录，以及目标 vLLM 检出目录。

计划必须要求每一轮 RLCR 都：

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

阶段 3：启动 RLCR

在 vLLM 检出目录中启动 Humanize 之前：

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

在 vLLM 检出目录中运行：

"$HUMANIZE_RUNTIME_ROOT/scripts/setup-rlcr-loop.sh" \
  .humanize/vllm-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. 提交 vLLM 更改。
7. 编写要求的 Humanize 轮次摘要。
8. 正常停止，让原生 Humanize Stop 钩子进行审查。

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

在每一轮 RLCR 中

差距判定

每轮开始时，针对每个固定场景，计算当前 vLLM 与 SLA 达标框架中最佳者之间的差距。

将 1% 作为默认的稳定噪声阈值。如果当前结果处于 +/-1% 范围内，请充分重新运行优胜者的命令，以判断差距是否稳定，然后再选择补丁。

仅当 vLLM 比最佳框架慢超过 1%、未达到 SLA 而其他框架达标，或在固定工作负载下存在能够解释剩余差距的分析瓶颈时，才应用补丁。

如果 vLLM 已经是最佳，或与最佳者的差距处于稳定阈值内，则编写最终报告，并按照正常的 Humanize 审查流程停止。

必需的性能分析

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

规则：

• vLLM 落后时，始终对 vLLM 进行性能分析。
• 始终至少对当前表现最佳的框架进行性能分析。
• 如果在稳定结果中，SGLang 和 TensorRT-LLM 均领先 vLLM 超过 1%，则对两者都进行性能分析。
• 使用慢速基准测试场景的长度，而不是性能分析器的默认值：
  • 预填充性能分析：慢速输入长度 -> 1 个输出 token
  • 解码性能分析：1 个输入 token -> 慢速输出长度
• 对于混合数据集或生产数据集，使用基准测试产物中已有记录的、最慢且有代表性的 p50 或 p95 桶。
• 如果框架支持，分别捕获或分析预填充和解码证据。

对于每个经过性能分析的框架，保存相同的三张表：

• 内核表
• 重叠机会表
• 融合模式表

然后编写或更新 analysis/root-cause.md，记录当前的跨框架比较：哪个阶段较慢、哪些表格行能解释这一点，以及哪些 vLLM 源码路径或内核系列可能是补丁目标。

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

分层流水线深入分析

在每轮 RLCR 中，于性能分析分诊之后、选择补丁目标之前运行 llm-pipeline-analysis。

报告必须指出：

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

使用经过性能分析的 vLLM 跟踪记录和服务模型配置。编写 analysis/layer-pipeline.md，记录所选的前向传播、层类型计时表、代表性层、热门内核，以及检查时使用的任何 Perfetto 时间范围。在当前轮次对应的报告生成之前，不要选择 vLLM 补丁。

Kernel Evidence Assist

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

只有满足以下所有条件，才允许进行 kernel 级辅助：

• 针对固定基准测试场景，完成必需的重复测试和 profiler 检查后，vLLM 的表现仍比最佳框架落后超过 1%。
• kernel 表中，性能较慢阶段对应的具体 vLLM kernel 或范围严格限定的 kernel 系列，其 GPU 累计耗时占比至少为 1%。除非某个共享实现影响到占比超过 1% 的聚合系列，否则不要将 kernel 专项精力花在占比低于 1% 的单个 kernel 上。
• llm-pipeline-analysis 已识别当前轮次的代表性层/前向传递和最热的 kernel。
• 拟定的 kernel 目标有明确的正确性参考、来自模型运行的代表性形状/数据类型/布局，以及接入当前 vLLM 服务代码的途径。

对于每个符合条件的 kernel 目标：

1. 阅读 ncu-report-skill/SKILL.md，并遵循其中的 Nsight Compute 工作流，完成测试框架构建、ncu 采集、报告解析、停顿诊断，以及基于证据选择下一处修改。
2. 将 NCU 输出存放在 kernel/ncu-digests/<version>/ 或主机的对应产物根目录下。每份摘要都必须比较基线与候选方案，并以且仅以一项具体的下一步修改结尾。
3. 直接在 vLLM 检出目录中修改 vLLM kernel 或调用路径，并在可用时进行针对性的正确性和微基准测试。CUDA 和 C++ kernel 代码位于 csrc/ 下，Triton kernel 以及 attention/quantization 封装位于 vllm/ 下，由 torch.compile 驱动的路径位于 vllm/compilation/ 下。
4. 将候选方案接入生成原始 profiler 行的当前模型服务路径。
5. 候选方案通过正确性验证后，重新运行相同的真实模型基准测试和 profiler。仅有微基准或 NCU 性能提升不算成功。

如果不存在针对性的测试框架，就构建能够保留模型派生形状/数据类型/布局的最小测试框架。如果主机无法运行 NCU，就在摘要路径中记录阻碍，并根据现有的 torch-profiler、层流水线和源码证据确定下一处修改。

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

模型循环检查点

每轮通过验收后，更新 humanize/model-loop-checkpoint.md，其中包含：

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

此检查点用于在同一模型级工作流中恢复工作进度。它记录了足够的上下文，以便恢复工作时不丢失基准测试和性能分析的沿革。

循环台账

根据主机惯例，将这些文件保存在运行产物根目录或 vLLM 检出目录下：

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

每次补丁尝试都要记录一行尝试记录。只有正确且经测量确认有所提升的补丁，才记录为优化条目。源码思路必须包含 profiler 行、层流水线证据、使用时的 NCU 报告路径，以及代码来源信息，以便后续轮次无需重复阅读相同源码。如果模型 PR 历史证据影响了补丁，应将其与 vLLM、SGLang、TensorRT-LLM 和 NCU 的源码思路一并记录。

如果连续两轮相较此前最佳 vLLM 结果的几何平均值提升均低于 1%，则在再次编辑前扩大以代码为先的研究范围。应优先参考 vLLM、SGLang、TensorRT-LLM 的代码与 PR 证据，以及相关 kernel 源码指南，而非仅参考文章内容。

停止条件

仅当满足以下任一条件时停止：

• 在固定工作负载下，vLLM 的表现优于达到 SLA 的 SGLang/TensorRT-LLM 最佳结果。
• 多次运行后，vLLM 与最佳结果的差距处于稳定的 1% 阈值以内。
• 已证明剩余差距源于 vLLM 之外，例如硬件支持不可用、缺少框架依赖、不支持 TensorRT-LLM PyTorch 后端，或无法公平加载模型权重。
• 性能分析证据表明，剩余热点路径已接近相关硬件或算法的极限，且 vLLM 没有可实施的低风险补丁。

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