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 未命名任何路由之前，插件处于休眠状态，不会对请求产生任何影响。
• 未配置路由：未配置路由的请求将保持原样，不受插件影响。

此插件为模型推理提供了细粒度的参数控制能力。更多细节可查看插件目录或源码仓库。