dsh-llm-gate: DeepSeek Harness 單模型提供商併發門控插件

前言¶

在使用 DeepSeek Harness（DSH）進行模型推理時，如果底層模型服務（例如開啓 --parallel 1 的 llama.cpp）無法同時處理多個請求，多餘的請求會被服務端直接丟棄。客戶端無法區分是“正在等待槽位”還是“服務已死”，導致 Node HTTP 層在 300 秒後報錯 terminated。這種問題常在子代理與主代理或壓縮與代理請求重疊時發生。

dsh-llm-gate 旨在解決上述問題。它通過在 DSH 進程內部維護一個 FIFO 隊列，將多餘的請求暫存起來，直到模型服務騰出槽位後再發出 HTTP 請求。這避免了請求在等待期間因超時而被丟棄，確保請求有序處理。

核心功能¶

按提供商併發控制：針對特定的模型提供商設置併發上限。
請求隊列管理：通過 FIFO 隊列暫存超出併發上限的請求。
全鏈路覆蓋：掛鉤 llm/stream waterfall，覆蓋代理、子代理、壓縮和標題生成等所有模型請求場景。
錯誤處理：處理隊列滿（QUEUE_FULL）和超時（QUEUE_TIMEOUT）等錯誤狀態。

安裝與啓用¶

使用官方安裝命令將插件添加到指定配置文件（例如 web）：

dsh plugin --profile web add dsh-llm-gate

安裝完成後，需要重啓 dsh web 並打開新會話以使配置生效。可以通過以下命令驗證配置是否正確加載：

dsh --profile web --dump-config

配置示例¶

在 ~/.dsh/profiles/web/cordis.patch.yml 文件中添加配置。這裏的 providers 鍵對應的名稱應與你的 llm-pi-ai.providers（或其他適配器）設置中的路由名稱一致。未列出的提供商不受此插件控制。

- id: llm-gate
  config:
    providers:
      llamacpp:
        maxConcurrent: 1
        maxQueued: 16
        queueTimeoutMs: 3600000

配置項說明¶

配置項	必填	說明
`maxConcurrent`	是	允許同時向該提供商發出的請求數。對於 `llama.cpp`，請將其值與 `--parallel` 參數保持一致。
`maxQueued`	否	允許在隊列中等待的請求數。超過此數量，新請求會立即失敗，報錯 `QUEUE_FULL`。默認爲無限制。
`queueTimeoutMs`	否	請求等待槽位的最大時長。超過此時間將失敗，報錯 `QUEUE_TIMEOUT`。默認爲無限等待。

日誌輸出¶

該插件會在 DSH 終端輸出以下日誌，用於監控請求的排隊和調度情況：

排隊時：顯示當前請求進入隊列以及隊列深度。

    llm-gate: llamacpp session=a61e6e40 queued (depth 1)

調度時：顯示請求在等待一段時間後被分發。

    llm-gate: llamacpp session=a61e6e40 dispatched after 5730ms

輔助請求：帶有 purpose=compaction 或 purpose=session-title 的請求也會被記錄。

注意事項¶

串行化限制：該插件會對請求進行串行化處理，因此它不會讓單槽服務器處理速度變快。若需提升性能，需給 llama.cpp 增加槽位（如 --parallel 2 --kv-unified），並相應提高 maxConcurrent。
超時機制：等待時間不計入適配器的 streamIdleTimeoutMs，因爲適配器在獲取槽位前不會被調用。仍需根據提示處理時間設置足夠的 streamIdleTimeoutMs。
請求取消：隊列中的請求通過 abort signal 取消。如果在未取消流的情況下丟棄流，該請求會一直停留在隊列中，直到槽位釋放後立即分發並關閉。
依賴要求：插件需要 llm 服務，並掛鉤 llm/stream waterfall。

生態與許可¶

許可證：MIT
倉庫：https://github.com/d3vmeh/dsh-llm-gate
目錄頁：https://www.skillhub.cn/plugins/d3vmeh/dsh-llm-gate

DSH 的插件生態強調模塊化與可擴展性，dsh-llm-gate 作爲其中的一員，爲處理高併發下的單槽模型服務提供了可控的隊列管理機制。