前言¶
DeepSeek Harness（DSH）采用“一切皆插件”的理念，旨在通过模块化扩展实现工具链的灵活定制。在昇腾 NPU 上部署 vLLM 推理时，性能瓶颈常出现在 Host 调度、NPU 计算、跨卡通信或数据拷贝（H2D/D2H）上。然而，CANN 与 torch_npu 导出的 profiling 产物存在若干“坑”：trace_view.json 通常是裸 JSON 数组而非标准结构、表头在不同版本间漂移、产物中缺少 Prefill 与 Decode 阶段的标签等。这些产物难以直接用于性能分析。
插件介绍¶
这是一个 DeepSeek Harness 插件（DSH plugin），用于上传 vLLM-Ascend / 昇腾 NPU 的 profiling 产物，自动完成文件校验、流式解析、独立可视化页面展示、结构化性能优化建议以及 Markdown/PDF 报告导出。插件本身零运行时依赖，仅使用 Node 内置模块与浏览器原生 API，不打包任何第三方前端库。
核心功能¶
插件提供以下已核实的能力：
- 解析产物：解析 vLLM-Ascend / Ascend NPU profiling 产物，处理裸 JSON 数组、表头漂移等格式问题。
- 可视化分析：提供 Host/Device 算子执行泳道图与耗时占比归因，支持拖拽、打包或按路径流式分析大文件。
- 阶段区分：自动区分 Prefill 与 Decode 阶段，支持在自动推断、仅 Prefill、仅 Decode 之间切换。
- 优化建议：输出结构化性能优化建议，支持 Markdown 和 PDF 报告导出。
安装与启用¶
插件是零依赖的纯 ESM 包，只需要让 DSH profile 能解析到它。
方式 A：从 GitHub 安装（需要 pnpm）¶
在 profile 目录执行以下命令：
dsh plugin --profile web add github:nutsDad/dsh-plugin-vllm-ascend-profiler
该命令会在 profile 目录执行 pnpm 安装，并自动将插件追加进 dsh.profile.bundles。由于本包声明了 dsh.bundle.patch 且没有任何构建脚本，无需 allowBuilds 放行。安装后需要重启 profile 才能生效。
方式 B：从本地目录安装¶
- 在 profile 目录建立链接（Windows 用 junction，Unix 用 symlink）：
$profile = "$env:DSH_HOME\profiles\web"
New-Item -ItemType Junction `
-Path "$profile\node_modules\dsh-plugin-vllm-ascend-profiler" `
-Target "D:\path\to\dsh-plugin-vllm-ascend-profiler"
- 编辑
$env:DSH_HOME\profiles\web\package.json（注意不要写成带 BOM 的 UTF-8，否则 DSH 读取清单会报错）：
{
"dependencies": {
"dsh-plugin-vllm-ascend-profiler": "file:D:/path/to/dsh-plugin-vllm-ascend-profiler"
},
"dsh": {
"profile": {
"bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-plugin-vllm-ascend-profiler"],
"patchReload": "live"
}
}
}
- 重启
dsh --profile web。
卸载¶
从 dsh.profile.bundles 中删除本包名（并删掉依赖与链接）即可完全卸载。插件不写任何持久化文件、不注册任何后台任务。
典型用法¶
- 打开页面：侧边栏底部会出现「Profiler 分析」入口，或直接访问
http://127.0.0.1:<port>/vllm-ascend-profiler/。 - 导入产物：支持三种方式——拖拽/多选上传（常规 CSV + 中小 trace）、打包上传（支持
.zip/.tar.gz）、按路径分析（GB 级trace_view.json）。 - 查看结果：页面包含三大可视化模块，支持拖拽上传、打包上传或按路径流式分析大文件。
- 导出报告：支持 Markdown 和 PDF 格式导出。
适用场景与注意¶
- 安装要求：方式 A 安装需要 pnpm。安装后必须重启 profile 才能生效。
- 文件格式：需要处理产物格式的坑（如裸 JSON 数组、表头漂移等），插件已内置解析逻辑。
- 运行机制：插件不写持久化文件、不注册后台任务，完全在宿主侧完成分析。
- 注意事项：使用前应检查源码与许可证（MIT）。
结尾¶
该插件为 vLLM-Ascend 的性能分析提供了结构化工具链，能够从海量 profiling 产物中提取关键指标，生成可追溯的优化建议与报告。更多细节与源码可访问 GitHub 仓库。
