llama.cpp 源码完全拆解（三十）：采样器链——logits 如何穿过惩罚、top-k、top-p、min-p 与语法，最后落成一个 token

链头的固定部分

装配顺序在源码里是分段的。common_sampler_init 先处理语法与推理预算（它们是带 prefill 的独立采样器）：

1
// 语法如果"需要预填"（输出格式、工具调用语法），先把 generation prompt 的 token 喂进去
2
if (grmr && !params.grammar_lazy && common_grammar_needs_prefill(params.grammar)) {
3
    for (const auto & token : prefill_tokens) {
4
        llama_sampler_accept(grmr, token);
5
    }
6
}
7

8
// reasoning budget
9
if (!params.reasoning_budget_start.empty() && !params.reasoning_budget_end.empty() && ...) {
10
    rbudget = common_reasoning_budget_init(vocab, {...}, ...);
11
    for (const auto & token : prefill_tokens) {
12
        llama_sampler_accept(rbudget, token);
13
    }
14
}

之后是链的第一段，固定顺序：logit bias。注意源码把用户给的 bias 和模型自带的「抑制 token」合并在一起——有些架构（如某些 Qwen/DeepSeek 版本）的 generation_config.json 里带 suppress_tokens，这些 token 必须永远不出现：

1
std::vector<llama_logit_bias> merged = params.logit_bias;
2
int32_t n_suppress = 0;
3
const llama_token * suppress = llama_vocab_get_suppress_tokens(vocab, &n_suppress);
4
for (int32_t i = 0; i < n_suppress; ++i) {
5
    merged.push_back({ suppress[i], -INFINITY });
6
}
7
if (!merged.empty()) {
8
    samplers.push_back(llama_sampler_init_logit_bias(llama_vocab_n_tokens(vocab), merged.size(), merged.data()));
9
}

把抑制 token 实现成「logit bias = $-\infty$」而不是一个单独的采样器，是因为 logit_bias 采样器本来就是「稀疏位置加减」的通用设施，复用它几乎零成本。$-\infty$ 经过后续的任何排序、softmax 都仍然是「概率为 0」，不会因为截断环节的排序而被漏掉。

链主体：for (const auto & cnstr : params.samplers)

这是本篇最关键的一段。params.samplers 是一个有序的枚举列表，由命令行 --samplers "top_k;typ_p;top_p;min_p;temp" 解析而来。common_sampler_init 用一个 switch 把它逐个翻译成采样器对象：

1
for (const auto & cnstr : params.samplers) {
2
    switch (cnstr) {
3
        case COMMON_SAMPLER_TYPE_DRY:
4
            samplers.push_back(llama_sampler_init_dry(vocab, params.dry_multiplier, params.dry_base,
5
                                                      params.dry_allowed_length, params.dry_penalty_last_n,
6
                                                      c_breakers.data(), c_breakers.size()));
7
            break;
8
        case COMMON_SAMPLER_TYPE_TOP_K:
9
            samplers.push_back(llama_sampler_init_top_k(params.top_k));
10
            break;
11
        case COMMON_SAMPLER_TYPE_TOP_P:
12
            samplers.push_back(llama_sampler_init_top_p(params.top_p, params.min_keep));
13
            break;
14
        case COMMON_SAMPLER_TYPE_TOP_N_SIGMA:
15
            samplers.push_back(llama_sampler_init_top_n_sigma(params.top_n_sigma));
16
            break;
17
        case COMMON_SAMPLER_TYPE_MIN_P:
18
            samplers.push_back(llama_sampler_init_min_p(params.min_p, params.min_keep));
19
            break;
20
        case COMMON_SAMPLER_TYPE_XTC:
21
            samplers.push_back(llama_sampler_init_xtc(params.xtc_probability, params.xtc_threshold,
22
                                                      params.min_keep, params.seed));
23
            break;
24
        case COMMON_SAMPLER_TYPE_TYPICAL_P:
25
            samplers.push_back(llama_sampler_init_typical(params.typ_p, params.min_keep));
26
            break;
27
        case COMMON_SAMPLER_TYPE_TEMPERATURE:
28
            samplers.push_back(llama_sampler_init_temp_ext(params.temp, params.dynatemp_range,
29
                                                           params.dynatemp_exponent));
30
            break;
31
        case COMMON_SAMPLER_TYPE_INFILL:
32
            samplers.push_back(llama_sampler_init_infill(vocab));
33
            break;
34
        case COMMON_SAMPLER_TYPE_PENALTIES:
35
            samplers.push_back(llama_sampler_init_penalties(llama_vocab_n_tokens(vocab),
36
                                                            params.penalty_last_n, params.penalty_repeat,
37
                                                            params.penalty_freq, params.penalty_present));
38
            break;
39
        case COMMON_SAMPLER_TYPE_ADAPTIVE_P:
40
            use_adaptive_p = true;
41
            break;
42
    }
43
}

由此可以读出几个设计事实：

1. 没有「默认顺序」的推断逻辑。 链顺序完全由参数列表决定。参数列表在命令行层被解析，若用户没写 --samplers，命令行层会填入一份默认顺序，common_sampler_init 本身不做任何「如果没给 top_k 就跳过」之类的推断——它只要遍历给出的列表。这意味着同一组 top_k/top_p 数值，在前端默认链与显式链下是不同的两条链。
2. 同一个采样器类型可以出现多次。列表里写两次 top_p 就会有两个独立的 top_p 对象，各自持有 min_keep 等状态。这对「先粗截断再细截断」是有意义的组合。
3. adaptive-p 被延后到链尾。switch 里只设置 use_adaptive_p = true，不立即 push，因为 adaptive-p 像 dist 和 mirostat 一样是做最终选取的采样器，必须在所有截断之后。源码注释原文：the adaptive-p sampler is like dist and mirostat in that it selects a single token, so we will add dist at the end of the chain by default, unless the user specifically included adaptive-p。
4. min_keep 被打包进每个「可能清空候选」的采样器。top_p、min_p、xtc、typical 的构造都带 params.min_keep。这是对「截断后候选集为空」的兜底：无论阈值多严，至少保留 min_keep 个 token（默认 1）。没有这个兜底，极端参数下（比如 top_p=1e-6）抽样阶段会面对空数组。

链尾：greedy 折叠的精确条件

链主体之后，mirostat == 0 的分支会追加最终选取器。这段代码是全篇最值得逐字读的部分：

1
if (use_adaptive_p) {
2
    samplers.push_back(llama_sampler_init_adaptive_p(params.adaptive_target, params.adaptive_decay, params.seed));
3
} else {
4
    // Keep distribution sampling when callers request probabilities.
5
    const bool greedy = params.n_probs == 0 && !params.samplers.empty() &&
6
        ((params.samplers.back() == COMMON_SAMPLER_TYPE_TEMPERATURE && params.temp == 0.0f && params.dynatemp_range == 0.0f) ||
7
         (params.samplers.back() == COMMON_SAMPLER_TYPE_TOP_K && params.top_k == 1));
8
    samplers.push_back(greedy ? llama_sampler_init_greedy() : llama_sampler_init_dist(params.seed));
9
}

逐条拆开：

• params.n_probs == 0：如果调用者要求返回候选概率（API 的 logprobs），就不能折叠成 greedy。为什么？greedy 采样器只找 argmax，不保证候选数组被归一化、不保证 cur_p 被整理成「按概率排序的前若干个」。而 n_probs 的输出需要完整的分布视图。所以「要给概率，就必须走 dist」——这条约束把采样器的选取语义和输出语义绑在了一起，是一个很干净的设计。
• 温度 0 必须配合 dynatemp_range == 0：动态温度（dynatemp）会让实际温度在范围内浮动，即使基准 temp == 0，动态范围会让它在某些步大于 0，于是不能折叠。
• top_k == 1 也被折叠为 greedy：只留一个候选再按分布抽，结果就是该候选本身，所以等价于 argmax。这是一个「语义等价就折叠」的优化，省掉一次 softmax 和一次随机数生成。
• samplers.back() 必须是最后一个采样器：只有当温度或 top_k=1 是链尾时，折叠才成立。如果链尾是 min-p 或典型采样，它们的 apply 可能重新归一化或再截断，折叠为 greedy 会绕过它们。

折叠的实际效果：链尾的 dist 被替换成 greedy，而 greedy 的 apply 只做一次 argmax 扫描并设置 cur_p.selected，不生成随机数、不做 softmax。这是 llama.cpp 采样链里最大的单项优化——贪心场景下整条链的成本只剩前面各截断采样器的 logits 变换。

mirostat 分支

mirostat == 1/2 时，链尾是 temp + mirostat/mirostat_v2，且不经过上面那段 params.samplers 的截断循环（mirostat 自己控制截断）。mirostat 是一种自适应截断算法：用运行时估计的目标困惑度 $\tau$ 动态调整截断阈值，无需 top-k/top-p 参数。llama.cpp 实现里 mirostat 的第三个参数 100 是 n_vocab 上限相关的初始候选规模，mirostat_v2 省掉了显式的 $s$ 偏移量维护。这部分在默认部署里很少用到，但读源码时要注意它和 params.samplers 是互斥路径。

backend sampling 的禁用条件

链装配完之后还有一段：

1
if (grmr && params.backend_sampling) {
2
    LOG_WRN("%s: backend sampling is not compatible with grammar, disabling\n", __func__);
3
    params.backend_sampling = false;
4
}
5
if (rbudget && params.backend_sampling) {
6
    LOG_WRN("%s: backend sampling is not compatible with reasoning budget, disabling\n", __func__);
7
    params.backend_sampling = false;
8
}

backend sampling 是较新版本引入的路径：随机数、采样本身都在 GPU 后端完成，CPU 只负责取回 token。它与 grammar 不兼容的原因很直接：语法后校验需要「在 CPU 上拿到候选数组、失败后重新施加掩码再抽」；与 reasoning budget 不兼容是因为 budget 也是链外状态机。源码选择的是自动降级——打印警告、关掉 backend sampling，而不是报错。这体现了 llama.cpp 前端一贯的「参数能救就救」的风格。

第一步：同步、计时、取 logits

1
llama_synchronize(ctx);
2
const auto tm = gsmpl->tm();
3
gsmpl->set_logits(ctx, idx);

llama_synchronize 在计时开始之前——注释说明这是为了不把异步计算的时间算进采样耗时。set_logits 把第 idx 行的 logits 拷进 cur 候选数组，并初始化 cur_p。从这一刻起，cur_p 是整条链共享的工作区：每个 apply 都在原地修改它。

第二步：backend sampling 短路

1
id = llama_get_sampled_token_ith(ctx, idx);
2
if (id != LLAMA_TOKEN_NULL) {
3
    for (size_t i = 0; i < cur_p.size; ++i) {
4
        if (cur_p.data[i].id == id) { cur_p.selected = i; break; }
5
    }
6
    return id;
7
}

如果后端已经采出 token，CPU 只需要在候选数组里找到它的下标（供 n_probs / 概率输出对齐），然后直接返回。这里有两个 GGML_ASSERT 保证语法与预算不会被越过——与前面装配阶段的「自动降级」配合，正常情况下走到这里时它们已被置空。

第三步：链前施加预算，然后做语法后校验

1
llama_sampler_apply(rbudget, &cur_p);
2

3
if (grammar_first && grammar_should_apply(gsmpl)) {
4
    llama_sampler_apply(grmr, &cur_p);
5
}
6

7
llama_sampler_apply(chain, &cur_p);
8

9
id = cur_p.data[cur_p.selected].id;
10

11
if (grammar_first || !grammar_should_apply(gsmpl)) {
12
    return id;
13
}

grammar_first 为真时，语法作为普通掩码在链前施加，链的抽样自然只从合法集合里选，直接返回。这是「全程约束」路径。

grammar_first 为假（默认）时，先不管语法跑完整条链，得到候选 id，再进入后校验：

1
llama_token_data single_token_data = { id, 1.0f, 0.0f };
2
llama_token_data_array single_token_data_array = { &single_token_data, 1, -1, false };
3
llama_sampler_apply(grmr, &single_token_data_array);
4

5
const bool is_valid = single_token_data_array.data[0].logit != -INFINITY;
6
if (is_valid) {
7
    return id;
8
}

这段是 llama.cpp 语法采样的核心技巧，也是 common/sampling.h 文件头注释写的「grammar-based rejection sampling」。它构造了一个只有一个元素的候选数组，把这个 token 喂给语法采样器。语法采样器看到单元素数组，成本从 $O(V)$ 降到 $O(1)$，只检查这一个 token 在当前状态是否可以接受；可以，logit 原样保留；不可以，apply 把它置为 $-\infty$。于是后校验退化成「一次单点查询」。

grammar_should_apply 还有一层逻辑：语法被设为 lazy、并且 reasoning budget 处于活动状态时，语法暂不生效（思考阶段允许输出任意 token），等 budget 结束（DONE）再启用。这就是「思维链阶段不约束，正式回复阶段约束」的实现位置。

第四步：失败后的全量重抽样

1
gsmpl->set_logits(ctx, idx);             // 重新拷一份原始 logits
2

3
llama_sampler_apply(rbudget, &cur_p);
4
if (grammar_should_apply(gsmpl)) {
5
    llama_sampler_apply(grmr, &cur_p);   // 这次是整张词表
6
}
7
llama_sampler_apply(chain, &cur_p);
8
id = cur_p.data[cur_p.selected].id;

注意这里重新 set_logits。因为第三步已经把 cur_p 原地改得面目全非（截断把大量位置设成了 $-\infty$ 或剔除），不能在此基础上再叠加语法掩码；必须回到原始分布重新跑整条链，这次语法在前，链只会在合法集合里抽样。

这条路径的成本：一次全词表语法掩码 + 一次完整链。它只在「随机抽到了非法 token」时发生。有多频繁？取决于模型在合法集合外的概率质量——对强约束语法（如 JSON 字段名枚举），越界率不高；对宽松语法（如自由文本 + 某几个触发器）几乎为 0。这正是「常见路径快、少见路径正确」的取舍：绝大多数步只付 $O(1)$，少数步付两次链。

整体时间线小结

1
                   ┌─ backend 已采出 token？──是──> 回填 selected，返回
2
set_logits ────────┤
3
                   └─ 否
4
                        │
5
                        ├─ grammar_first ──> [rbudget] → [grammar 整表] → [chain] → 返回
6
                        │
7
                        └─ 默认
8
                             ├─ [rbudget] → [chain] → 候选 id
9
                             ├─ 单元素语法检查：合法？──是──> 返回
10
                             └─ 否
11
                                  set_logits（重拷原始分布）
12
                                  [rbudget] → [grammar 整表] → [chain] → 返回

penalties：重复、频率、存在惩罚

三者合并在一个 llama_sampler_init_penalties 对象里，参数是 penalty_last_n、penalty_repeat、penalty_freq、penalty_present。设最近 penalty_last_n 个 token 中 token $i$ 出现 $c_i$ 次：

• 重复惩罚 $r$：若 $z_i>0$ 则 $z_i \leftarrow z_i/r$，否则 $z_i \leftarrow z_i\cdot r$。只对出现过的 token 做乘除，符号敏感的处理保证「总是向 0 方向收缩」，而不是把负数乘成更负（那反而抬高了相对排名）。
• 频率惩罚 $f$：$z_i \leftarrow z_i - f\cdot c_i$，线性扣分，出现越多扣越多。
• 存在惩罚 $p$：$z_i \leftarrow z_i - p\cdot[c_i>0]$，只扣一次。

源码里 params.penalty_freq 与 params.penalty_present 默认都是 0，penalty_repeat 默认 1.0（即不惩罚）。历史窗口由 prev 环形缓冲提供，但 penalty_last_n 可以小于缓冲长度——窗口只取最近的若干个。窗口的存在解释了为什么惩罚没有「无限累积」问题。

顺序为什么重要：惩罚排在任何截断之前时，先压低再截断，被压低的 token 可能直接被 top-k 挤出候选；若排在温度之后，缩放又会改变惩罚的相对强度（惩罚是加法/乘法，与温度缩放不可交换）。llama.cpp 把顺序交给用户，但默认顺序（若命令行给出）是惩罚在前。

DRY：按字符 n-gram 的重复约束

DRY（Don’t Repeat Yourself）是社区提出的防复读采样器，参数包括 dry_multiplier、dry_base、dry_allowed_length、dry_penalty_last_n 和一组 dry_sequence_breakers。它的原理与「token 级重复惩罚」不同：它按字符序列找最长的已出现后缀，然后对「可能延续该 n-gram 的 token」施加以 dry_base 为底的指数惩罚：

其中 $L$ 是匹配长度，$m$ 是 dry_multiplier，$b$ 是 dry_base（如 1.75）。匹配越长，惩罚越大；短于 dry_allowed_length 的匹配不罚。dry_sequence_breakers（如 \n、:、"）用来切断匹配——跨过换行或冒号的重复视为「不同结构的重复」，不应惩罚。

DRY 需要维护「上下文中所有字符 n-gram 的最长后缀匹配」，实现上用后缀树/哈希表按长度分桶，每步只更新末尾新增的部分，不是每步全量重建。这是链里状态最重的采样器之一，也是它为什么必须支持 accept/reset/clone——投机解码的草稿链要复制它的状态。

top-k、top-p、min-p、top-n-sigma

• top-k：保留分数最高的 $k$ 个。当 $k=1$ 且位于链尾时会被折叠为 greedy（前文）。实现需要一个「前 $k$ 大」的选择，llama.cpp 实际做法是先对整个候选数组做降序排序（std::partial_sort 类思路），然后截断到前 $k$。因为后续的 top-p 等常常共用同一份排序，避免重复排序是 common_sampler 里的一类优化（不同版本实现有差异，读源码时留意「候选数组在链中是否被复用」）。

• top-p（核采样）：在降序排列上累加 $p$，直到累计值达到阈值，保留前缀。这里的概率阈值是累计阈值而不是单个 token 的概率阈值——分布尖锐时可能只留几个 token，平缓时可能留几百个。min_keep 保证至少保留几个。

• min-p：保留 $p_i \ge p_{\min}\cdot p_{\max}$ 的 token，即以最大概率为参照的相对阈值：

  $$S=\{i\mid p_i\ge p_{\min}\,p_{\max}\}$$

  分布尖锐时自动收窄、平缓时自动放宽，不需要像 top-p 那样处理累加语义。

• top-n-sigma：以 logits 的均值和标准差为参照，保留在 $\mu + n\sigma$ 之内的 token，是另一种「相对阈值」形式，对 logits 尺度敏感。

• typical（typ_p）：先用 $-\sum p_i\log p_i$ 得到条件熵 $H$，再按 $- (-\log p_i) - H$ 的偏差保留「典型」token。

• XTC：以 xtc_probability 的概率触发，触发时把概率高于 xtc_threshold 的头部 token 排除（保留一个兜底），目的是打破「总是输出最常见短语」的惯性。

这些采样器的共同点是：读 cur_p、原地修改 logits、维护少量状态。它们的相对顺序决定了「截断作用于原始分布还是已缩放分布」「候选集是哪个阶段的结果」。

temp / temp_ext：动态温度

llama_sampler_init_temp_ext 同时携带 temp、dynatemp_range、dynatemp_exponent。动态温度在每一步根据当前熵在 $[T-T_{\text{range}}, T+T_{\text{range}}]$ 内选取实际温度——熵低时选低温度（更自信），熵高时选高温度（更探索）。这也是前面 greedy 折叠要求 dynatemp_range == 0 的原因：动态温度意味着「实际温度每步都可能不为 0」。

温度在链中的位置决定它缩放的是「已经惩罚过的 logits」还是「原始 logits」。把温度放在链尾是最常见的写法，这样所有截断都在原始尺度上进行，温度只做最后一步缩放。

dist 与 greedy：最终选取

dist 在前缀和上做逆 CDF 采样：对归一化的候选计算累计概率 $\text{cdf}$，生成 $u\sim U(0,1)$，二分找到第一个 $\text{cdf}(i)>u$。随机数来自 gsmpl->rng。greedy 只做 argmax。二者都不修改截断结果，只设置 cur_p.selected。

infill：FIM 中间填充

infill 采样器服务于「中间填充」（fill-in-the-middle）场景：用户给了前缀和后缀，要求模型在中间补全。它的作用是根据当前已生成内容推导 FIM 的哨兵 token（如 <|fim_prefix|>、<|fim_suffix|>、<|fim_middle|>，不同模型不同），在合适时机强制输出 <|fim_middle|>，使模型进入补全模式。它在链中的位置通常在截断之前，因为它是「结构性的强制约束」而不是概率调整。