前言¶
在 DeepSeek Harness（DSH）裏做模型推理相關開發時，往往需要對接 GPU 集羣：看節點與顯卡餘量、提交部署、跟實例狀態、拉日誌、做一次真實推理驗收、再查用量。若只靠 curl 或手寫腳本，上下文要在人和模型之間來回搬，密鑰也容易混進對話記錄。
dsh-plugin-gpustack 把 GPUStack v2 的 /docs 運維接口封裝成 DSH 的 Agent 工具。安裝並配置集羣地址與 API Key 後，模型可以盤點集羣、部署模型、查看實例日誌、等待就緒、跑推理驗收、查用量；其餘 200+ 端點可通過通用請求工具覆蓋。
這是什麼¶
- 名稱：
dsh-plugin-gpustack（npm 包名相同） - 維護者：zh-Littlebird（Hu Zhang）
- 分類：模型推理（社區目錄歸類）
- 版本：1.0.0（MIT 許可證）
- 定位：GPUStack v2 集羣工具——模型部署與生命週期、Worker/GPU 盤點、實例日誌、推理驗收、用量統計與通用 API 調用；API Key 設計爲留在模型會話之外。
插件以 dsh.bundle.patch 聲明的組合包形式安裝，依賴 DSH >=0.2.2-rc.1 <0.3.0、Node >=22.19.0。
核心功能¶
工具面¶
README 中列出的工具與用途如下（節選）：
| 工具 | 用途 |
|---|---|
gpustack_config |
查看/設置集羣地址（不接收 Key） |
gpustack_test |
連通性與憑據自檢（healthz、version、用戶身份、推理模型數等） |
gpustack_inventory |
集羣、Worker、GPU 設備盤點 |
gpustack_models |
模型列表或單個模型及實例詳情 |
gpustack_deploy_model |
部署模型（POST /v2/models） |
gpustack_update_model |
修改副本、參數、env 等規格 |
gpustack_model_action |
重啓、回滾、刪除（刪除需 confirm=true） |
gpustack_logs |
模型實例日誌 |
gpustack_wait_model |
輪詢直到 running/error 或超時 |
gpustack_chat |
OpenAI 兼容推理驗收（真實 /v1/chat/completions） |
gpustack_usage |
用量彙總與明細 |
gpustack_request |
任意端點的通用通道 |
注意：gpustack_models 的 state 參數對應列表接口的就緒過濾（ready/not_ready/stopped）；若按 pending|partial|running|error 篩選，應使用 modelState。
安全與權限¶
- API Key 僅存在本機加密文件（AES-256-GCM），不進入工具參數、工具結果或會話記錄。
- 寫操作受
allowWrites總開關控制；delete需顯式confirm=true。 - 每次調用寫一行審計日誌（不含請求體與查詢串）。
- 設置頁可按類別單獨關閉部署、修改規格、重啓回滾、刪除、通用寫、推理等權限。
安裝與啓用¶
插件裝進當前 profile 即可。官方 README 給出的命令如下。
# 從 npm 安裝
dsh plugin --profile desktop add dsh-plugin-gpustack
# 或先從源碼克隆，再按目錄安裝
git clone https://github.com/zh-Littlebird/dsh-plugin-gpustack
dsh plugin --profile desktop add ./dsh-plugin-gpustack
Agent 場景可調用 plugin_manager 的 install_bundle，target 傳包名 dsh-plugin-gpustack 或本地目錄絕對路徑。
安裝後 gpustack_* 工具在下一個會話（或工具表刷新後）可用；設置頁與插件行配置頁重新加載頁面後生效，重啓 Harness 一定生效。
配置集羣與憑據¶
圖形界面（推薦）¶
打開「設置 → GPUStack」，或在「插件」頁打開 dsh-plugin-gpustack 的配置頁：
- 填寫集羣地址（可粘貼
/docs鏈接，會自動去掉後綴）與 API Key，點「保存」後立即生效。 - 使用「測試連接」分項查看 healthz/version、管理接口身份、推理接口模型數。
- 在「操作權限」中按類別開關寫操作；可調整超時與組織 ID。
命令行等價操作¶
模型不參與、也看不到密鑰輸入：
cd 'dsh-plugin-gpustack'
node scripts/dsh-gpustack.mjs setup --base-url http://192.0.2.10:31901
node scripts/dsh-gpustack.mjs set --api-key # 隱藏輸入，形如 gpustack_xxx
node scripts/dsh-gpustack.mjs status
node scripts/dsh-gpustack.mjs test # 探活 /healthz、/version、/v2/users/me
配置優先級：環境變量 > site.json（設置頁/CLI 寫入）> 插件配置（cordis.patch.yml 的部署默認值）。常用環境變量包括 GPUSTACK_BASE_URL、GPUSTACK_API_KEY、DSH_GPUSTACK_DATA_DIR（默認 $DSH_HOME/gpustack）。
非機密與審計數據落在 site.json、credentials.json + master.key、audit.log 等本地文件中，細節見 README 表格。
典型用法¶
部署並驗收¶
gpustack_inventory— 確認 worker ready、卡型與餘量。gpustack_deploy_model— 提交name/source/backend/replicas/...。gpustack_wait_model— 等到state=running（不要僅憑 200 認爲成功）。gpustack_chat— 用模型名跑一次真實推理。gpustack_models modelId=<id>— 覈對實例落在預期 worker/GPU。
排障¶
gpustack_models modelId=<id>— 查看state、state_message、實例狀態。gpustack_logs modelId=<id>— 鏡像/模型路徑/OOM 等；重啓過可加previous=true。- 修復後
gpustack_model_action action=restart，再gpustack_wait_model。
改配置¶
gpustack_update_model 只更新規格；改 backendParameters/env/鏡像等時必須 restart=true（或隨後單獨 restart），否則進程仍跑舊參數。restart 整組重建且非冪等，restarting_since 未清空前再次調用可能返回 409。
適用場景與注意¶
適合誰：已在 GPUStack v2 上跑模型、又在 DSH 裏用 Agent 做部署與運維對話的開發者；希望 Key 與寫操作有明確邊界和審計的團隊。
運行邊界：插件以當前 DSH 進程的權限訪問本機配置與集羣 API；安裝前應自行審閱 源碼 與 MIT 許可證。一個插件實例綁定一個集羣（baseUrl）；多集羣需切換地址或多份配置。
已知限制（摘自 README）：模型 zip 導入導出、部分看板端點等未做 typed 工具，可用 gpustack_request；壓測類接口使用前需確認對線上流量的影響。
DSH 生態理念是「一切皆插件」；SkillHub 目錄頁 爲社區站點，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-plugin-gpustack 把 GPUStack v2 的日常運維收成一組可編排的 Agent 工具，並在密鑰、寫權限與審計上做了分層約束。需要安裝說明、配置字段與完整工具表時，以倉庫 README 爲準。
- 目錄頁：https://www.skillhub.cn/plugins/zh-Littlebird/dsh-plugin-gpustack
- GitHub：https://github.com/zh-Littlebird/dsh-plugin-gpustack
