导读：temperature=0.7、top_k=50、top_p=0.9——这串参数几乎出现在每个大模型 API 里，但多数人只会抄配置。本文从 softmax 的数学出发，讲清三个参数各自『动』的是分布的哪一部分、为什么顺序不能乱、以及如何组合使用，附 70 行可运行的 NumPy 采样器、transformers 实战代码和 7 个高频 Bug。

一、起点：模型输出的不是文字，而是一张概率表

自回归语言模型每一步只做一件事：给定前文，对词表中每个 token 输出一个分数 logit z_i，然后 softmax 归一化成概率：

▍Softmax

 

              exp(z_i)

P(token_i) = ----------        # softmax：把任意实数分数变成概率分布

             Σ_j exp(z_j)

『生成文本』的本质，就是在这张几万到十几万项的概率表里反复做抽样。如果永远抽概率最大的那个（贪心/argmax），输出确定但呆板，还容易陷入重复循环；如果完全按原始分布抽，又可能抽到概率 0.001 的胡话。三个参数，就是三种『改造这张概率表』的旋钮。

二、Temperature：对整个分布做『缩放』

Temperature 在 softmax 之前对 logits 做除法：

▍带温度的 softmax

 

                exp(z_i / T)

P_T(token_i) = --------------

               Σ_j exp(z_j / T)

它的几何意义非常干净：

T → 0：z/T 的差距被无限放大，最大 logit 的概率趋于 1，退化为贪心 argmax；

T = 1：原始分布，什么都不改；

T > 1：差距被压缩，分布变『平』，小概率词的机会上升，输出更随机、更有『创意』。

用信息论的语言：T 控制的是分布的熵。可以证明对固定 logits，分布熵 H(T) 关于 T 单调不减——这就是『调高温度=更发散』的严格说法。还有一个工程细节：softmax 对 logits 整体加常数不敏感（分子分母同乘 e^c 抵消），但除法则会改变相对差距，所以『除温度』是一个真正有信息量的操作，而不是简单的数值缩放。

三、Top-K：固定名额的『硬截断』

Top-K 的规则一句话：只保留概率最高的 K 个 token，其余概率置 0，然后重新归一化。K=1 即贪心；K=50 即『只在前 50 名里抽』。它的好处是简单、可预期；缺点同样明显——名额是死的，而分布是活的：

当模型非常确定时（如『中国的首都是__』），前 1 名就占了 99%，K=50 等于把 49 个噪声词请进了候选池，平白引入胡话风险；

当模型很犹豫时（开放式开头），合理候选可能有 200 个，K=50 又强行砍掉了长尾里的多样性。

这就是 Top-K 的『固定窗口』问题：截断阈值不随分布形状自适应。

四、Top-P（核采样）：按概率质量动态截断

Top-P 换了个思路：不数人头，数概率。把 token 按概率从大到小排序，依次累加，直到累计概率刚刚超过 p，这个最小集合称为『核（nucleus）』，只在核内重新归一化抽样。（Holtzman et al., 2020,《The Curious Case of Neural Text Degeneration》）

p=0.9 意味着『在覆盖 90% 概率质量的最小集合里抽』。模型确定时核可能只有 1~2 个词，模型犹豫时核自动扩大到几十个——截断宽度随分布自适应，这正是 Top-P 相对 Top-K 的核心优势。实践中还常见两个近亲：min_p（按最高概率的比例设下限，如 0.1×p_max）与 typical sampling（按『信息量接近熵』筛选），思路同源。

五、一张图看懂三者区别与组合顺序

图 1  (a) 温度对分布形状的缩放；(b) Top-K 固定截断；(c) Top-P 动态核；(d) 一次解码的完整参数流水线

组合使用的标准顺序（也是 HuggingFace transformers 内部 logits warper 的顺序）：重复惩罚 → 温度 → Top-K → Top-P → softmax → 抽样。先温度后截断很重要：温度改变了相对差距，也就改变了 Top-P 核的大小；反过来先截断再除温度，核的边界就不受温度控制了。

六、实操一：70 行 NumPy 写一个完整采样器

▍完整采样器：温度 → Top-K → Top-P → 抽样

跑一遍你会看到：T=0.3 时几乎总抽 0 号；T=1.5 时 3~6 号频繁出现；top_k=3 把候选锁死在前 3 名；top_p=0.9 的候选集则随分布自动伸缩。同一个函数，三种旋钮，改造的是同一张概率表的不同部位。

七、实操二：transformers 中的正确姿势

▍HuggingFace generate 参数示例

7.1 场景化参数建议

八、常用 Bug 与排查

Bug 1：调了半天 temperature，输出纹丝不动

原因：do_sample=False（transformers 默认）时走贪心，temperature/top_k/top_p 全部被忽略，旧版本甚至不告警。自检：打印 model.generation_config.do_sample；服务侧（vLLM/TGI）确认 sampling 参数真的透传到了 sampling_params 而非被覆盖。

Bug 2：temperature=0 直接报错 / 出 NaN

一些手写实现直接 z/T，T=0 触发 ZeropisionError 或 inf/NaN。正确处理：T<=0 时走 argmax 分支（见上文采样器第 ② 步）。注意『T=0』和『do_sample=False』语义等价，选一种表达即可。

Bug 3：高温 + top_p=1.0 → 胡话与复读机齐飞

高温把长尾噪声抬进候选池，top_p=1.0 又完全不截断，模型开始认真抽样概率 1e-4 的词，表现为乱码、跨语言跳变、无限重复。修复：高温必须配截断（top_p≤0.95 或 top_k≤100）；重复问题再叠加 repetition_penalty 或 frequency_penalty。

Bug 4：Top-K 与 Top-P 的『顺序错觉』

有人以为 top_k 和 top_p 谁写前面效果一样。标准实现是先 K 后 P：K 先砍绝对长尾，P 在剩余集合里按概率质量再截。若实现成先 P 后 K，高温下核很大，K 的兜底作用就被削弱。自研推理代码时务必写单测验证截断顺序。

Bug 5：『我设了 seed 为什么两次结果不一样』

复现需要三处种子（torch/numpy/random）一致，且硬件与精度不变。GPU 上某些归约算子非确定性、fp16 与 fp32 的 softmax 舍入差异，都会让『同 seed 不同结果』。严格复现：CPU 或固定 GPU + fp32 + torch.use_deterministic_algorithms(True)。反过来，线上服务想要多样性，记得每个请求换 seed。

Bug 6：fp16 logits 上做 softmax，高温下概率全 0 / 溢出

fp16 最大值 65504，logits 稍大 exp 即 inf；高温下 z/T 的细微差异在 fp16 里被舍入抹平，分布失真。规则：采样阶段一律上转到 fp32 计算（上文采样器第 ① 步），这是推理框架的通行做法。

Bug 7：把 repetition_penalty 当成温度的替代品

两者作用阶段不同：repetition_penalty 在温度之前修改 logits（对已出现 token 的 logit 做除/乘惩罚），温度在其后缩放整体分布。『输出太重复』优先调惩罚项与 top_p，『输出太跳』优先降温度——对症下药，而不是把三个旋钮一起拧。

九、总结

三个参数都在改造同一张概率表：Temperature 缩放整体形状（控熵），Top-K 固定名额截断，Top-P 按概率质量动态截断；

标准流水线：重复惩罚 → 温度 → Top-K → Top-P → softmax → 抽样，顺序即语义；

T→0 即贪心；要复现就贪心+固定 seed，要创意就适度高温+top_p 兜底；

工程上：fp32 采样、显式配置、分场景预设、单测验证截断顺序。