执行摘要

• 一句话：改进 sweep 推荐配置与短别名解析
• 推荐动作：建议精读 recipe_json_to_vllm_config.py 的短别名解析重写和 sweep_recommendation.py 的合规率推荐逻辑：前者是 Issue #53137 的针对性修复，展示了如何系统化处理“值、标志、字典”三类别名与点号内联赋值；后者体现了“多层过滤（失败请求 → 中位 P99 SLA → 合规率阈值）再按吞吐择优”的推荐设计，值得作为工具链中“从实验结果到建议配置”的参考模式。同时注意该 PR 未附带测试，阅读时可顺手补上 issue 中给出的复现用例作为回归测试。

功能与动机

PR body 明确指出两点动机：第一，之前的 sweep 只对 max-num-seqs 和 max-num-batched-tokens 做“一次只动一个参数”的小范围搜索，缺乏调度并发与 batch 预算之间的交互覆盖；第二，修复 Issue #53137——recipe_json_to_vllm_config.py 对 -cc.pass_config.fuse_rope_kvcache=True 这类点号短别名静默解析错误，生成的 config.yml 会把 attention-backend 变成包含三个元素的列表，且不报任何错误或警告。issue 作者特别强调这是纯参数解析逻辑 bug，发生在独立离线脚本中。

实现拆解

1. 扩展 sweep 采样点（tools/recipes/sweep_generation.py）：在 build_serve_params 中新增 middle_seqs（约为初始 seqs 的 3/4）和 smaller_batch（再下探一个 2 的幂），将候选从 5 点扩为 8 点：初始点、同并发下的小/低/高 batch 预算、3/4 与 1/2 并发下的低/高 batch 预算，并继续用 seen 集合去重，避免与最低 batch 约束（禁用 chunked prefill 时取 max_model_len）冲突。
2. 重写推荐逻辑（tools/recipes/sweep_recommendation.py）：新增 _percentile_summary 返回 mean/median/max 三值；_aggregate_candidates 接受 ttft_sla_ms、tpot_sla_ms、minimum_compliance 参数，按候选组计算 duration 加权综合合规率（sum(request_goodput * duration) / sum(completed)），要求中位 P99 TTFT/TPOT 达标且合规率不低于阈值（默认 0.99），再从合格候选中选最高 mean output_throughput；同时记录每个候选的 mean/median/worst P99、combined compliance 与 request throughput。
3. 修复短别名解析（tools/recipes/recipe_json_to_vllm_config.py）：将原 SHORT_ALIASES 拆为 VALUE_SHORT_ALIASES（如 -q/-n/-r/-tp/-dcp/-pcp/-dp*）、FLAG_SHORT_ALIASES（-dph/-dpe/-dpm/-ep）、DICT_SHORT_ALIASES（-sc/-dc/-cc/-ac）；is_option_token 用 token.split('=', 1)[0] 识别带号别名，并识别 -cc. 前缀；argv_to_config 对点号字典别名支持 -cc.key=value、-cc.key value、追加型 -cc.key+ value（列表值可本身以 - 开头，如 -quant_fp8）；coerce 增加 Python 风格布尔值 True/False 的显式转换（json.loads 本不支持）。
4. 同步文档与示例：SWEEP_TUNING.md、RUNTIME_TUNING.md、tools/recipes/README.md 更新合规率语义与 --minimum-compliance 选项说明，并把示例 --input-tokens 2048 改为 128（与 decode_budget/2048 的计算示例保持一致）；docs/models/hardware_supported_models/cpu.md 为 gpt-oss-20b、Qwen3-1.7B/8B/30B-A3B 补充 Xeon 6 recipe 链接。
5. 测试配套缺失：本次变更没有新增或修改任何测试文件，recipe_json_to_vllm_config.py 的修复和 sweep 推荐的新逻辑均缺少自动化用例覆盖；相关 issue 中也未给出回归测试。

关键文件：

• tools/recipes/recipe_json_to_vllm_config.py（模块 配置转换；类别 source；类型 core-logic；符号 VALUE_SHORT_ALIASES, FLAG_SHORT_ALIASES, DICT_SHORT_ALIASES, coerce）: 修复 Issue #53137 的核心文件：短别名解析从单一字典拆分为值/标志/字典三类，新增 -cc.* 点号内联赋值、追加型列表值和 Python 风格布尔转换，直接影响所有使用 Recipes 生成 config.yml 的用户。
• tools/recipes/sweep_recommendation.py（模块 推荐器；类别 source；类型 core-logic；符号 _percentile_summary, _aggregate_candidates, DEFAULT_MINIMUM_COMPLIANCE）: 推荐逻辑重写的核心：新增 _percentile_summary 与 duration 加权综合合规率计算，推荐标准从 mean goodput 改为中位 P99 SLA + 合规率阈值（默认 0.99）+ 最高 mean 输出吞吐，并新增 --minimum-compliance 选项。
• tools/recipes/sweep_generation.py（模块 扫描生成；类别 source；类型 core-logic；符号 build_serve_params）: sweep 采样从 5 点扩为 8 点：新增 3/4 序列并发与更小 batch 预算，覆盖 batch 预算曲线与并发交互，是 sweep 改进的生成端。

关键符号：_percentile_summary, _aggregate_candidates, build_serve_params, coerce, is_option_token, argv_to_config

评论区精华

review 侧整体很平静：claude[bot] 因 fork PR 未执行自动审查并建议维护者用 @claude review 触发；bigPYJ1151 直接批准；ActiveSky 在合并后留言致谢，指出本 PR 是在 #53210 基础上扩展了更多短别名场景。PR 内没有针对实现细节的技术辩论，因此质量把关主要依赖 issue #53137 中描述的复现路径。值得一提的是 issue 作者对 bug 的定性非常清晰，明确说明是纯命令参数解析 bug、与运行时无关，这在后续修复边界划分上很有价值。

• 暂无高价值评论线程

风险与影响

• 风险：
  1. recipe_json_to_vllm_config.py 解析行为变化：is_option_token 与 argv_to_config 的重写改变了短别名的识别和值消费方式，尤其是点号别名“无条件消费下一个 token”的处理。若存在形如 -cc.foo 且后面紧跟另一个选项的场景，可能跨选项吞值产生新的静默错误。该文件是独立离线脚本，不影响 vLLM 运行时，但会影响所有使用 Recipes 生成配置的用户。
  2. sweep 推荐语义变化：_aggregate_candidates 的推荐策略从“最高 mean request goodput”改为“中位 P99 达标 + 合规率 ≥ 0.99 后选最高 mean output throughput”。若 summary.json 缺少 completed、duration 或 request_goodput 字段（旧版 sweep 或自定义结果），completed_requests 为 0 时 combined_compliance_ratio 为 None，会导致所有候选不满足合规条件而落到 best_effort，不产出 recommended-config.yml。这是有意的行为变化，但依赖字段的可用性。
  3. coerce 中新增的 True/False 字符串转布尔逻辑可能影响本意保留字符串字面量 'True' 的合法配置，虽然对 YAML 而言转为布尔通常更合理，但属于语义变化。
  4. 缺少测试覆盖：sweep 生成、推荐和短别名解析都无自动化测试，回归风险主要靠人工验证，而 issue 中的复现路径本身就是现成的测试用例。
     - 影响：影响范围集中在 tools/recipes 工具链和 CPU 硬件文档，不涉及 vLLM 运行时、调度器或推理内核。受益用户包括：使用 recipe_json_to_vllm_config.py 生成部署配置的 ROCm/CPU 用户（短别名修复直接解决 -cc 解析错误）、使用 --generate-sweep 做运行时调优的用户（更充分的采样与更合理的推荐）、以及通过 recipes.vllm.ai 获取 Xeon 6 配置的 CPU 用户（新增多个模型的 recipe 链接）。对团队而言，这是对离线工具的体验和正确性改进，不带来系统级风险，维护成本主要体现在后续 sweep 推荐逻辑的字段契约（completed、duration、request_goodput）上。
     - 风险标记：缺少测试覆盖, 解析行为变更, 推荐语义变更

关联脉络

• PR #53137 [Bug]: tools/recipes/recipe_json_to_vllm_config.py silently mis-parses the -cc (compilation-config) short alias: 本 PR 的直接修复对象，issue 提供了完整的复现路径和错误输出样例。
• PR #53210 [Tools][Recipes] Improve short-alias parsing in recipe_json_to_vllm_config.py: ActiveSky 在合并留言中提到本 PR 是在 #53210 基础上扩展更多短别名场景，属同一功能线的后续工作。