前言¶

在 DeepSeek Harness（DSH）中讓智能體執行 GPU 任務時，常見的問題是：狀態查詢、選卡、命令執行、後臺任務管理都要靠 shell 手工拼接。直接調用 nvidia-smi 或手動設置 CUDA_VISIBLE_DEVICES 也能工作，但多卡選擇、後臺作業和併發選卡邏輯會變得零散。

下面介紹 dsh-gpu。它是面向 DeepSeek Harness 的 GPU-aware execution layer：提供 gpu_status、gpu_exec、gpu_run_bg 三個工具，支持可選的 per-step GPU context injection，並自動處理 CUDA_VISIBLE_DEVICES 選卡。

這是什麼¶

dsh-gpu 是 DeepSeek Harness 插件，定位爲 GPU-aware execution layer for DeepSeek Harness。它把 GPU 狀態查詢、GPU 命令執行、GPU 後臺作業封裝到 DSH 工具層，許可證爲 MIT。

倉庫地址：

https://github.com/zytsyj/dsh-gpu

核心功能¶

gpu_status：一次查詢所有 GPU 狀態¶

gpu_status 用於一次查詢所有設備，返回：

• memory used/total
• SM utilization
• temperature
• free/busy verdict

一個設備在以下任一條件滿足時被視爲 busy：

• memory used 達到或超過 80%
• utilization 達到或超過 50%

兩個閾值均可配置。

gpu_exec：執行一次性 GPU 命令¶

gpu_exec 用於一次性命令。它會按當前選卡結果設置 CUDA_VISIBLE_DEVICES，並通過 DSH 掛載的 ctx.shell executor 執行命令。

它支持：

• 自動選擇較空閒的卡
• 顯式指定卡
• 爲多 GPU 命令選擇 count 張卡

gpu_run_bg：後臺運行長時間 GPU 任務¶

gpu_run_bg 用於訓練、推理服務、benchmark 等長時間任務。任務會作爲 gpu job 註冊到 ctx.jobs，並立即返回 job id。

之後可以：

• 用 job_output 讀取輸出
• 用 job_kill 停止任務

它需要 composition 中已經啓用 jobs service：

@deepseek-ai/dsh-jobs
@deepseek-ai/dsh-tool-jobs

Per-step context：給 eligible steps 注入一行 GPU 快照¶

Per-step context 是可選能力，默認開啓。它會爲 eligible steps 注入一行 GPU snapshot，並且限速爲每分鐘一次 sample。

安裝與啓用¶

先確定要啓用該插件的 DSH profile，再執行插件安裝命令：

dsh plugin --profile <name> add dsh-gpu

這裏的 <name> 是 profile 佔位符，按當前 profile 名稱替換。

加載順序上，建議把 dsh-gpu 放在 execution-world 插件之後。例如，如果 DSH 通過 SSH provider 插件提供 shell seam，dsh-gpu 應放在該插件之後，確保它查詢的是預期的 shell seam。

典型用法¶

下面是基於已覈實能力整理的調用路徑：

1. 先調用 gpu_status，查看當前 GPU 的 memory used/total、SM utilization、temperature 和 free/busy verdict。
2. 對一次性 GPU 命令調用 gpu_exec。插件會設置 CUDA_VISIBLE_DEVICES，並通過 ctx.shell executor 執行命令。
3. 對訓練、推理服務、benchmark 等長任務調用 gpu_run_bg，拿到 job id 後，用 job_output 讀取輸出，用 job_kill 停止任務。
4. 如果需要每步看到 GPU 狀態，保留默認的 per-step context，讓它按每分鐘一次 sample 的限速注入一行 GPU snapshot。

如果需要更強的確定性，可以在同一 step 內先讀取 gpu_status，再顯式 pin gpuIndex。

適用場景與注意¶

dsh-gpu 適合需要在 DSH 智能體中接入 GPU 執行邏輯的場景，例如：

• 查詢 GPU 狀態
• 執行一次性 GPU 命令
• 運行訓練、推理服務、benchmark 等後臺任務
• 在多卡環境中自動選擇較空閒的卡

需要注意以下幾點：

• nvidia-smi 會忽略 CUDA_VISIBLE_DEVICES，始終報告物理索引。gpu_exec 對 CUDA 程序的選卡仍按設計工作，但不要用 nvidia-smi 輸出來驗證 pinning。
• 選卡是 advisory，不是 reservation。兩個併發 agent 仍可能選中同一張卡。需要獨佔判斷時，應在同一 step 內從 gpu_status 讀取並 pin gpuIndex。
• gpu_run_bg 依賴 jobs service。composition 中需要 @deepseek-ai/dsh-jobs 和 @deepseek-ai/dsh-tool-jobs。
• 在沒有 NVIDIA GPU 的 host 上，gpu_status 會報告 clean no-gpu result，而不是失敗。
• 插件會接入當前 DSH profile 的執行鏈路，並以當前 dsh 進程權限使用已掛載的 shell executor。安裝前應檢查源碼和 MIT 許可證。

結尾¶

dsh-gpu 的價值在於把 GPU 狀態查詢、命令執行和後臺作業收斂到 DSH 工具層，減少智能體手動查卡、拼環境變量、輪詢後臺任務的重複邏輯。

倉庫地址：

https://github.com/zytsyj/dsh-gpu