Preface

DeepSeek Harness (DSH) adopts the philosophy of “everything is a plugin” and aims to enable flexible customization of tool chains through modular extensions. When deploying vLLM inference on Ascend NPUs, performance bottlenecks often appear in host-side scheduling, NPU computation, cross-device communication, or data copying (H2D/D2H). However, the profiling artifacts exported by CANN and torch_npu have several pitfalls: trace_view.json is usually a bare JSON array rather than a standard structure, table headers drift across different versions, and the artifacts lack labels for the Prefill and Decode stages. These artifacts are difficult to use directly for performance analysis.

Plugin Introduction

This is a DeepSeek Harness plugin (DSH plugin) for uploading vLLM-Ascend / Ascend NPU profiling artifacts. It automatically performs file validation, streaming parsing, dedicated visualization page display, structured performance optimization suggestions, and Markdown/PDF report export. The plugin itself has zero runtime dependencies and uses only Node.js built-in modules and native browser APIs, without bundling any third-party frontend libraries.

Core Features

The plugin provides the following verified capabilities:

  • Artifact Parsing: Parses vLLM-Ascend / Ascend NPU profiling artifacts and handles format issues such as bare JSON arrays and header drift.
  • Visual Analysis: Provides Host/Device operator execution swim-lane charts and time-share attribution, and supports drag-and-drop upload, package upload, or path-based streaming analysis of large files.
  • Stage Distinction: Automatically distinguishes Prefill and Decode stages, with switching between automatic inference, Prefill-only, and Decode-only.
  • Optimization Suggestions: Outputs structured performance optimization suggestions and supports Markdown and PDF report export.

Installation and Enablement

The plugin is a zero-dependency pure ESM package; you only need to make sure the DSH profile can resolve it.

Method A: Install from GitHub (requires pnpm)

Run the following command in the profile directory:

dsh plugin --profile web add github:nutsDad/dsh-plugin-vllm-ascend-profiler

The command runs pnpm installation in the profile directory and automatically appends the plugin to dsh.profile.bundles. Because this package declares dsh.bundle.patch and has no build scripts, no allowBuilds approval is needed. The profile must be restarted after installation for the plugin to take effect.

Method B: Install from a Local Directory

  1. Create a link in the profile directory (junction for Windows, symlink for Unix):
    $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"
  1. Edit $env:DSH_HOME\profiles\web\package.json (do not use UTF-8 with BOM; otherwise DSH will fail when reading the manifest):
    {
      "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"
        }
      }
    }
  1. Restart dsh --profile web.

Uninstallation

Remove the package name from dsh.profile.bundles (and delete the dependency and link) to completely uninstall the plugin. The plugin does not write any persistent files and does not register any background tasks.

Typical Usage

  1. Open the page: A Profiler Analysis entry appears at the bottom of the sidebar, or visit http://127.0.0.1:<port>/vllm-ascend-profiler/ directly.
  2. Import artifacts: Three methods are supported—drag-and-drop or multi-select upload (regular CSV files plus small-to-medium traces), package upload (supports .zip / .tar.gz), and path-based analysis (GB-scale trace_view.json).
  3. View results: The page contains three major visualization modules and supports drag-and-drop upload, package upload, or path-based streaming analysis of large files.
  4. Export report: Markdown and PDF export formats are supported.

Applicable Scenarios and Notes

  • Installation Requirements: Method A requires pnpm. The profile must be restarted after installation for the plugin to take effect.
  • File Formats: Artifact format issues (such as bare JSON arrays and header drift) need to be handled; the plugin includes built-in parsing logic.
  • Runtime Behavior: The plugin does not write persistent files and does not register background tasks; analysis is completed entirely on the host side.
  • Notes: Check the source code and license (MIT) before use.

Conclusion

This plugin provides a structured tool chain for vLLM-Ascend performance analysis, allowing key metrics to be extracted from massive profiling artifacts and enabling traceable optimization suggestions and reports. For more details and source code, visit the GitHub repository.