# Vllm Ascend Accuracy

> 仅在 vLLM Ascend（昇腾）推理出现精度或输出质量问题时使用：模型输出乱码、复读、答案错误、与参考实现/其他后端结果不一致、基准评测分数不达标，需要"复现→隔离→根因→修复→回归"的系统性精度排查闭环。用户的请求是普通开发调试时不要使用——如"看下代码报错"、"调试一下"、"服务起不来"、"环境配置问题"、"改个功能"，这些是常规开发任务不是精度问题；也不用于纯性能调优（吞吐/时延优化）。

- Skill: `zhaochuang001/vllm-ascend-accuracy` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add zhaochuang001/vllm-ascend-accuracy`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhaochuang001/vllm-ascend-accuracy/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zhaochuang001 (https://skillmd.com/u/zhaochuang001)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zhaochuang001/vllm-ascend-accuracy

---


# vLLM Ascend 精度诊断与修复

目标是以可复现证据找到最小致因，实施可回滚修复，并按用户确认的标准完成精度、稳定性和性能回归。不要仅凭输出表象归因，也不要用 `repetition_penalty` 或提示词改写掩盖系统性错误。

## 路由与默认边界

- 远程容器场景必须先读取 [references/remote-container-workflow.md](references/remote-container-workflow.md)，并按其中的“推荐首轮提问”收集服务器/认证/容器、可选联网代理、每个容器内模型服务的启动脚本、异常复现信息和用户验收标准；不要另写更长的表格。
- 默认目标是专门用于精度排障的非生产测试容器，允许直接修改、安装依赖和重启。用户声明为生产环境或限制操作时，以其约束为准。
- 出现乱码、复读、空输出或分数退化时，按 [references/diagnostic-playbook.md](references/diagnostic-playbook.md) 选择症状路由和消融维度。
- 致因缩小后，读取 [references/remediation-playbook.md](references/remediation-playbook.md) 选择最小修复层级。
- 查询版本行为时只使用与目标版本对应的官方文档、release note、GitHub issue/PR 和源码；`latest` 文档不能代表旧版本。

## 解决闭环

1. **锁定输入和验收**：确认用户验收标准；用户没有标准时，根据正常基线提出量化方案并请其确认。
2. **冻结环境**：记录镜像、版本、权重/tokenizer、模型服务启动脚本与实际进程、并行拓扑和健康状态，且不泄露凭据。优先用 `scripts/env_snapshot.py --host <IP> [--container <容器>]` 一键采集版本矩阵、卡状态、CANN 环境与运行中 vllm 进程的实际加载库（JSON 存档，诊断前后各拍一次可 diff 出环境漂移）；脚本自包含无外部依赖，只需本机能密钥 SSH 到目标机器。
3. **复现并建立基线**：固定请求/token、chat template、采样参数、seed 和评测器；在原始配置复现，并与已知正常版本或参考后端对照。
4. **单变量定位**：依次检查输入/解析、权重/量化、执行模式、并行通信、调度/KV、MTP、sampler 等层级；概率问题使用有界的目标负载重复测试。
5. **迭代修复**：每轮备份原文件，只改一个假设对应的变量，记录 diff、启动配置、结果和回滚点；无效则恢复，有效则做回切验证。
6. **验证恢复**：运行原 bad case、代表性精度集和目标 PD/TP/DP/EP 拓扑，报告失败数/总数、任务分数、吞吐、TTFT、TPOT 和显存变化。
7. **保存成果**：将最终 diff/patch、修改文件、启动配置、回归结果和报告复制到容器外。仅在用户要求生产化交付时构建镜像或修改部署配置。

## 状态推进

本节是状态定义与推进规则的唯一来源，其他文件只引用、不重复定义。发现有效修改后必须按以下状态推进，不能跳过验证或过早结束：

```text
有效修改 → 候选修复 → 扩大回归
                    ├─ 根因已修复且满足验收 → 已解决
                    ├─ 仅通过回退/关闭功能规避 → 已规避，询问用户是否接受
                    └─ 未满足验收 → 继续迭代
```

- **候选修复**永远是中间状态：只要尚未覆盖用户要求的模型、数据集、负载和拓扑，就必须继续回归，不得生成最终报告或结束任务。
- **已规避**默认也是中间结果：继续定位根因。只有用户明确接受规避方案，或根因修复因硬件、源码、权限等外部条件受阻且用户同意收尾时，才可作为终态。
- **已解决**要求证据定位到错误实现、修复该实现并通过回切验证，且满足用户验收标准；现象消失但根因未确认时不得使用此状态。
- 没有可接受规避方案且无法继续推进时，标记为**受阻**并说明所需外部条件。

## 可选生态协同（本 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](references/final-report-template.md) 生成独立 Markdown 报告。用户未指定目录时写入当前工作目录，文件名使用 `vllm-ascend-accuracy-report-YYYYMMDD-HHMM.md` 且不得覆盖已有文件。报告按模板要求脱敏；最终回复提供报告的可点击绝对路径。

需要提交公开 issue 或研发缺陷单时，再读 [references/issue-report.md](references/issue-report.md)。