前言¶
在 DeepSeek Harness（DSH）裏跑本地小模型，常見做法是單獨起 llama-server，再在 profile 裏手寫 OpenAI 兼容路由。啓停、上下文與路由不一致、長對話壓縮溢出、以及「線上模型能不能把翻譯/OCR 這類雜活甩給本機」往往要分好幾處改配置。維護者 verson00 的 dsh-local-llm 把本機 llama.cpp 上的 Qwen3.5-4B 收進 設置 → 本地模型 一頁：啓停、啓動參數、部署路徑、與 cordis 的路由和壓縮策略聯動，並附帶請求形狀診斷與 local_worker 混合作業。插件分類爲模型推理，當前 GitHub 星標爲 0，許可證 MIT，版本 1.0.2。
這是什麼¶
dsh-local-llm 是 DSH 的 bundle 插件：host 半爲 ESM（index.js），client 半爲手寫模塊，零依賴、零構建，裝進 profile 即可用。面向 DSH 0.2.x（README 寫明在 0.2.1-rc.5 上開發與驗證；package.json 要求 engines.dsh 爲 >=0.2.2-rc.1 <0.3.0）。運行環境文檔寫明爲 Windows + NVIDIA GPU（8 GB 顯存可跑 4B Q4），需自備 llama-server.exe（項目在 b12069 驗證）及 Qwen3.5-4B 的 GGUF 與 mmproj。
目錄與源碼：
- 插件目錄頁：https://www.skillhub.cn/plugins/verson00/dsh-local-llm
- GitHub：https://github.com/verson00/dsh-local-llm
核心功能¶
啓停與狀態¶
插件自行 spawn 本機 llama-server，參數由設置頁決定，支持一鍵啓動、停止、重啓。狀態燈含義：綠爲就緒、黃閃爲加載中、灰爲已停止、紅爲失敗；失敗時可展開 server.err.log 末尾。頁面顯示加載耗時、PID、端口、顯存佔用與當前啓動參數。可與手動腳本共存：與 start.ps1 共用 pid 文件與日誌時，頁面顯示「已就緒（外部啓動）」，也可從頁面停止。
啓動參數¶
可配上下文長度（512–262144，8 GB 卡建議 ≤ 65536）、線程數、端口、主模型與視覺投影文件（自動掃描模型目錄 .gguf）、視覺開關、思考模式與預算、歷史思考保留、採樣溫度等。
部署路徑與檢測¶
四項路徑——安裝根目錄、llama-server.exe、模型目錄、日誌目錄——留空時按根目錄推導：
exe = <root>\bin\llama-b12069\llama-server.exe
models = <root>\models
logs = <root>\logs
「檢測」會校驗存在性、列出模型目錄中的 .gguf，給出「部署可用」或「不完整」。模型裝在其它盤時改路徑即可，無需改插件代碼。
模型路由與壓縮策略聯動¶
自動將 provider local-qwen 的 contextWindow、maxTokens、baseURL 與頁面設置對齊（寫 cordis.patch.yml 並保留註釋）。對 compaction-basic 寫入本地模型專用壓縮策略（headroomTokens: 0 加顯式摘要上限），避免小窗口下觸發點爲負、每步壓縮、摘要請求自身溢出的默認行爲。
請求捕獲（診斷）¶
插件在默認 loopback 端口 8091 起透明反向代理，把 provider 路由指過去後可觀察 DSH 真實請求形狀：消息數與角色分佈、思考字段形態、工具輸出體量、schema 字節數、max_tokens、是否流式等。只記錄形狀、不存正文、不落盤。頁面可一鍵切換「經代理」或「直連」。
混合工作流（local_worker）¶
開啓後註冊 local_worker 工具與系統提示，在線模型可把自包含雜活交給本地 4B：
| action | 用途 | 輸入 |
|---|---|---|
text |
翻譯、摘要、改寫、提取要點、格式化 | path 或 input |
image |
看圖、OCR、抄寫畫面文字 | paths |
video |
等距抽幀後逐幀分析，返回帶時間戳文字 | path + frames |
每請求自動帶 chat_template_kwargs: { enable_thinking: false }，避免輸出預算耗盡在思考塊、正文爲空。
安裝與啓用¶
前置¶
- DSH
>=0.2.2-rc.1 <0.3.0（不滿足時組合階段會跳過本 bundle）。 - Windows、NVIDIA GPU、llama-server、Qwen3.5-4B GGUF 與 mmproj（見下文模型文件）。
安裝步驟¶
-
取得插件目錄（克隆或解壓），確認含
package.json、index.js、lib/、client/。 -
裝進 DSH profile：讓 agent 執行（路徑換成本機絕對路徑）：
plugin_manager install_bundle（action: install_bundle, target: <本目錄的絕對路徑>）
等價做法：在 profile 的 package.json 增加 "dsh-local-llm": "link:<本目錄>"，並在 bundle 選擇列表加入 dsh-local-llm。
-
重啓 DSH（host 半在啓動時加載）。重啓後設置頁左側出現「本地模型」。
-
若尚未配置路由，在 profile 的
cordis.patch.yml增加 OpenAI 兼容路由（示例與 README 一致）：
- id: llm-pi-ai
name: "@deepseek-ai/dsh-llm-pi-ai"
config:
providers:
local-qwen:
displayName: 本地 Qwen3.5 4B
api: openai-completions
baseURL: http://127.0.0.1:8080/v1
headers:
Authorization: Bearer local-no-auth
models:
- id: qwen3.5-4b
name: Qwen3.5 4B (本地)
contextWindow: 65536
maxTokens: 8192
input: [text, image]
reasoningEfforts: false
- 將
Qwen3.5-4B-UD-Q4_K_XL.gguf與mmproj-F16.gguf放入<安裝根目錄>\models\，確認llama-server.exe在<安裝根目錄>\bin\llama-b12069\。
收錄進插件市場前，也可在 插件 → 添加插件 填倉庫地址，或命令行：
dsh plugin --profile <profile> add github:verson00/dsh-local-llm
https://github.com/verson00/dsh-local-llm
典型用法¶
- 打開 設置 → 本地模型。
- 展開「部署路徑」，確認四項均爲 ✓，或改爲本機路徑後點「檢測」。
- 展開「啓動參數」，按顯存設置上下文（8 GB 卡建議 ≤ 65536），點「保存」。
- 在「服務狀態」點「啓動」，待狀態燈變綠（約 3–10 秒）。
- 在模型選擇器選「本地 Qwen3.5 4B」對話；或在會話中讓 agent 使用
local_worker。 - 需要混合作業時，展開「混合工作流」打開開關並保存。
停止：設置頁點「停止」，或 stop-llm.cmd。插件停止時不會結束已獨立運行的模型進程。
spawn 失敗或舊版崩潰時的外部啓動¶
1.0.1 曾因未監聽 spawn 的 error 事件導致點「啓動」後 DSH 整體退出；1.0.2 已修復爲僅標紅並提示原因。若 Windows 上仍無法由插件 spawn，可按 README 用 PowerShell 外部啓動；插件通過 /health 與 logs\server.pid 識別，頁面顯示「已就緒（外部啓動）」，路由與 local_worker 仍可用。外部啓動示例參數中強調 --parallel 1、--ctx-size 與設置頁一致、--reasoning off、看圖需 --mmproj。
模型文件¶
- 基座：Qwen/Qwen3.5-4B
- 本機常用：
Qwen3.5-4B-UD-Q4_K_XL.gguf（約 2.8 GB）、mmproj-F16.gguf（約 0.7 GB） - GGUF 可從 Hugging Face 上 Qwen3.5-4B 的 GGUF 倉庫獲取，例如 unsloth/Qwen3.5-4B-GGUF
README 給出 RTX 4060 8 GB 下的實測表（32768 ctx 約 62.9 tok/s；162144 ctx 約 17.7 tok/s 且更多分頁到系統內存）。超過約 64K 上下文速度會明顯下降，長對話應依賴壓縮策略。
適用場景與注意¶
適合誰：已在 DSH 0.2.x 上開發、想在 Windows 本機固定跑 Qwen3.5-4B，並希望路由、壓縮、診斷與「線上主模型 + 本地雜活」在同一套 profile 裏維護的開發者。
環境與權限：插件以當前 DSH 宿主進程權限運行；安裝前應閱讀倉庫源碼與 MIT 許可證，確認路徑與 spawn 行爲符合本機安全策略。請求捕獲代理僅記元數據，但仍會短暫經過 loopback，診斷結束後建議改回直連。
常見問題（摘自 README）：模型路徑錯誤導致紅燈；8080 端口占用；路由「不一致」時點「同步」；local_worker 報未運行時需先啓動服務或開啓「需要時自動拉起」。
DSH 生態強調「一切皆插件」；SkillHub 等社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-local-llm 把本機 llama.cpp Qwen3.5-4B 的運維面、與 Cordis 的路由/壓縮一致性、請求形狀診斷和 local_worker 混合作業收進一頁設置，減少「腳本、YAML、手動對齊」的分散操作。詳情與 issue 見 GitHub：https://github.com/verson00/dsh-local-llm；目錄條目見 https://www.skillhub.cn/plugins/verson00/dsh-local-llm。
