dsh-llm-sampling：DeepSeek Harness 模型採樣策略插件

DeepSeek Harness (DSH) 的核心理念是“一切皆插件”。在構建智能體或編排模型調用時，開發者往往需要對特定模型或提供商路由的採樣參數進行精細控制。dsh-llm-sampling 插件提供了這種能力，它通過 agent/request waterfall 強制執行採樣策略。

插件定位¶

這是一個 DeepSeek Harness 插件包，由 kuma-loong 維護。它負責管理部署層面的採樣策略。DSH 核心負責提供者中立（provider-neutral）的字段和持久請求頭，而適配器負責線路翻譯，此插件僅管理採樣策略的注入。

安裝¶

從 GitHub 安裝時，需要固定已審查的 commit，以確保環境一致。

dsh plugin --profile web add github:kuma-loong/dsh-llm-sampling#<commit>

Git 安裝會運行包內的 prepare 腳本。如果使用 pnpm 10 及以上版本，必須在 profile 的 pnpm-workspace.yaml 中顯式允許構建：

allowBuilds:
  dsh-llm-sampling@https://codeload.github.com/kuma-loong/dsh-llm-sampling/tar.gz/<commit>: true

複製 pnpm 打印的 exact key 後，重新運行安裝命令。

配置¶

在 $DSH_HOME/settings.yaml 中添加 llm-sampling 配置節。支持的採樣字段包括 temperature、topP、topK、minP、presencePenalty 和 repetitionPenalty。

llm-sampling:
  providers:
    sparse-vllm:
      models:
        Qwen3.8-27B:
          default:
            temperature: 1
            topP: 0.95
            topK: 20
            minP: 0
            presencePenalty: 0
            repetitionPenalty: 1
          off:
            temperature: 0.7
            topP: 0.8
            presencePenalty: 1.5

這裏的 Profile 是策略而非調用者默認值：配置的值會覆蓋 agent/request waterfall 中的早期提案。後續的請求策略也可以通過正常的水流順序有意覆蓋它們。

工作原理¶

插件通過 llm-sampling.providers 命名一個路由後激活。對於命名的路由，配置模型默認 Profile 的採樣值會替換所有采樣值。當 reasoningEffort 被顯式設爲 off 時，off Profile 會完全覆蓋默認 Profile。

插件不會向模型 prompt 添加額外文本或工具 schema。它僅在模型提供的請求中注入採樣值，並在會話的 request/header 中記錄這些有效值。這會影響生成分佈，可能改變輸出長度。由於沒有改變 prompt 前綴，KV 緩存不會因採樣策略變化而失效，但提供者可能會將採樣控件包含在請求緩存身份中，導致策略變化影響提供者側的緩存重用。

限制與要求¶

• 依賴要求：插件需要 DeepSeek Harness 的構建版本，其 LlmCallConfig 和 GenerateOptions 必須包含 topP、topK、minP、presencePenalty 和 repetitionPenalty。在對應的 npm 發佈版本達到這些要求之前，僅能使用包含這些修改的源碼構建版。
• 適配器映射：適配器必須能夠映射配置的字段。例如，@deepseek-ai/dsh-llm-pi-ai 適配器支持 OpenAI Chat Completions 的擴展字段，但對其他協議可能會拒絕這些字段。
• 休眠狀態：在 llm-sampling.providers 未命名任何路由之前，插件處於休眠狀態，不會對請求產生任何影響。
• 未配置路由：未配置路由的請求將保持原樣，不受插件影響。

此插件爲模型推理提供了細粒度的參數控制能力。更多細節可查看插件目錄或源碼倉庫。