前言¶

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：從本地目錄安裝¶

1. 在 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"

2. 編輯 $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"
        }
      }
    }

3. 重啓 dsh --profile web。

卸載¶

從 dsh.profile.bundles 中刪除本包名（並刪掉依賴與鏈接）即可完全卸載。插件不寫任何持久化文件、不註冊任何後臺任務。

典型用法¶

1. 打開頁面：側邊欄底部會出現「Profiler 分析」入口，或直接訪問 http://127.0.0.1:<port>/vllm-ascend-profiler/。
2. 導入產物：支持三種方式——拖拽/多選上傳（常規 CSV + 中小 trace）、打包上傳（支持 .zip / .tar.gz）、按路徑分析（GB 級 trace_view.json）。
3. 查看結果：頁面包含三大可視化模塊，支持拖拽上傳、打包上傳或按路徑流式分析大文件。
4. 導出報告：支持 Markdown 和 PDF 格式導出。

適用場景與注意¶

• 安裝要求：方式 A 安裝需要 pnpm。安裝後必須重啓 profile 才能生效。
• 文件格式：需要處理產物格式的坑（如裸 JSON 數組、表頭漂移等），插件已內置解析邏輯。
• 運行機制：插件不寫持久化文件、不註冊後臺任務，完全在宿主側完成分析。
• 注意事項：使用前應檢查源碼與許可證（MIT）。

結尾¶

該插件爲 vLLM-Ascend 的性能分析提供了結構化工具鏈，能夠從海量 profiling 產物中提取關鍵指標，生成可追溯的優化建議與報告。更多細節與源碼可訪問 GitHub 倉庫。