zhaochuang001 vLLM Ascend 精度诊断与修复
目标是以可复现证据找到最小致因，实施可回滚修复，并按用户确认的标准完成精度、稳定性和性能回归。不要仅凭输出表象归因，也不要用 repetition_penalty 或提示词改写掩盖系统性错误。
路由与默认边界
- 远程容器场景必须先读取 references/remote-container-workflow.md，并按其中的“推荐首轮提问”收集服务器/认证/容器、可选联网代理、每个容器内模型服务的启动脚本、异常复现信息和用户验收标准；不要另写更长的表格。
- 默认目标是专门用于精度排障的非生产测试容器，允许直接修改、安装依赖和重启。用户声明为生产环境或限制操作时，以其约束为准。
- 出现乱码、复读、空输出或分数退化时，按 references/diagnostic-playbook.md 选择症状路由和消融维度。
- 致因缩小后，读取 references/remediation-playbook.md 选择最小修复层级。
- 查询版本行为时只使用与目标版本对应的官方文档、release note、GitHub issue/PR 和源码；
latest文档不能代表旧版本。
解决闭环
- 锁定输入和验收：确认用户验收标准；用户没有标准时，根据正常基线提出量化方案并请其确认。
- 冻结环境：记录镜像、版本、权重/tokenizer、模型服务启动脚本与实际进程、并行拓扑和健康状态，且不泄露凭据。优先用
scripts/env_snapshot.py --host <IP> [--container <容器>]一键采集版本矩阵、卡状态、CANN 环境与运行中 vllm 进程的实际加载库（JSON 存档，诊断前后各拍一次可 diff 出环境漂移）；脚本自包含无外部依赖，只需本机能密钥 SSH 到目标机器。 - 复现并建立基线：固定请求/token、chat template、采样参数、seed 和评测器；在原始配置复现，并与已知正常版本或参考后端对照。
- 单变量定位：依次检查输入/解析、权重/量化、执行模式、并行通信、调度/KV、MTP、sampler 等层级；概率问题使用有界的目标负载重复测试。
- 迭代修复：每轮备份原文件，只改一个假设对应的变量，记录 diff、启动配置、结果和回滚点；无效则恢复，有效则做回切验证。
- 验证恢复：运行原 bad case、代表性精度集和目标 PD/TP/DP/EP 拓扑，报告失败数/总数、任务分数、吞吐、TTFT、TPOT 和显存变化。
- 保存成果：将最终 diff/patch、修改文件、启动配置、回归结果和报告复制到容器外。仅在用户要求生产化交付时构建镜像或修改部署配置。
状态推进
本节是状态定义与推进规则的唯一来源，其他文件只引用、不重复定义。发现有效修改后必须按以下状态推进，不能跳过验证或过早结束：
有效修改 → 候选修复 → 扩大回归
├─ 根因已修复且满足验收 → 已解决
├─ 仅通过回退/关闭功能规避 → 已规避，询问用户是否接受
└─ 未满足验收 → 继续迭代
- 候选修复永远是中间状态：只要尚未覆盖用户要求的模型、数据集、负载和拓扑，就必须继续回归，不得生成最终报告或结束任务。
- 已规避默认也是中间结果：继续定位根因。只有用户明确接受规避方案，或根因修复因硬件、源码、权限等外部条件受阻且用户同意收尾时，才可作为终态。
- 已解决要求证据定位到错误实现、修复该实现并通过回切验证，且满足用户验收标准；现象消失但根因未确认时不得使用此状态。
- 没有可接受规避方案且无法继续推进时，标记为受阻并说明所需外部条件。
可选生态协同（本 skill 单独可用；装了同仓库其他 skill 时按需调用）
- 复现找机：需要一台有空闲卡的服务器复现问题时，用 server-management 查询集群空闲状态（
fleet_cli.py capacity --min-idle <卡数>），替代逐台 SSH 探测；机器清单与密钥也由其管理。 - 环境复刻：在另一台机器复刻问题环境（容器 + 代码 + 权重）时，用 npu-migrate 迁移，替代手工 commit/传输/rsync。
- 空间不足：安装依赖或迁移环境时磁盘满，用 disk-cleanup 分析清理（只读分析 → 安全级 → 确认级），不要盲目
rm。 - 环境快照脚本（env_snapshot.py）已自包含，无需上述依赖。
测量要求
- 将输出异常率与任务得分分开；乱码/复读检测不等同于业务精度。
- 参考与目标两侧的输入 token IDs、采样与评分配置逐项对齐；对齐清单以诊断手册为准。
- 同时报告绝对分数、基线差值、样本数和逐样本结果；随机采样使用多个 seed。
- 可用
scripts/analyze_generations.py初筛 JSONL 中的空输出、异常字符和 n-gram 复读，但不能用它替代任务指标或人工判定。
完成条件与交付
只有同时满足以下条件才报告为“已解决”：
- 达到用户确认的 bad case/数据集和分数标准；
- 在目标上下文、并发和并行拓扑下完成回归，概率问题报告测试规模；
- 通过 A/B/A、版本回切或等价证据建立因果关系；
- 已保存可执行变更、回归用例和回滚方法。
候选修复不是终态。关闭功能、回退版本或启用确定性计算只算“已规避”，终态条件按「状态推进」执行，不得报告为已解决。
任务达到已解决、用户已接受的已规避或受阻等终态时，读取 references/final-report-template.md 生成独立 Markdown 报告。用户未指定目录时写入当前工作目录，文件名使用 vllm-ascend-accuracy-report-YYYYMMDD-HHMM.md 且不得覆盖已有文件。报告按模板要求脱敏；最终回复提供报告的可点击绝对路径。
需要提交公开 issue 或研发缺陷单时，再读 references/issue-report.md。