vLLM - SamplingParams 参数

vLLM - SamplingParams 参数

flyfish

一、生成数量控制

控制生成的输出序列数量及候选筛选策略。

参数名	说明	默认值	注意事项
n	返回的输出序列数量（每个序列独立生成）。	1	需与 best_of 配合使用，要求 best_of ≥ n。
best_of	先生成 best_of 个候选序列，再从中选择前 n 个最优序列（按分数排序）。	等于 n	仅 V0 版本支持，默认与 n 相同；生成成本随 best_of 增大而上升。

二、生成长度控制

限制生成的 token 数量范围（最小/最大长度）。

参数名	说明	默认值	注意事项
max_tokens	每个输出序列的最大生成 token 数（超过则强制终止）。	16	若生成中途遇到 stop/EOS 或 min_tokens 未满足，会提前终止。
min_tokens	生成 EOS 或停止 token 前的最小 token 数（未达时不允许终止）。	0	确保生成内容至少达到指定长度，常用于强制生成基础内容（如摘要开头）。

三、采样策略与随机性

控制 token 选择的随机性、筛选范围及概率分布（核心影响生成多样性）。

参数名	说明	默认值	注意事项
temperature	控制随机性： - 0：贪心采样（完全确定，选概率最高的 token） - >0：随机采样（概率加权）	1.0	值越高，输出越随机；0 时 忽略 top_p/top_k/min_p，直接选全局最优。
top_p	核采样：选择累积概率 ≥ top_p 的最小 token 集合（范围 (0, 1]）。	1.0	需与 temperature>0 配合，top_p=1 表示考虑所有 token（等价于不筛选）。
top_k	顶部 k 采样：选择概率最高的前 k 个 token（0 或 -1 表示不限制）。	0	top_k=0 表示不限制（考虑所有 token）；temperature=0 时 无效（直接选全局最优）。
min_p	最小相对概率：token 概率需 ≥ 最可能 token 概率 × min_p（范围 [0, 1]）。	0	进一步过滤低概率 token，较少使用，通常与 top_p/top_k 组合使用。
seed	随机种子，确保生成结果可复现（None 时使用随机种子）。	None	temperature>0 时有效，0 时无需设置（结果完全确定，种子不影响）。

四、内容约束与停止条件

控制生成内容的合法性、终止规则及禁止/允许的词汇。

参数名	说明	默认值	注意事项
stop	停止生成的字符串列表（生成遇到时终止，输出不包含这些字符串）。	None	支持单个字符串（如 "\n"）或列表（如 ["###", "END"]），优先级低于 stop_token_ids。
stop_token_ids	停止生成的 token ID 列表（生成遇到时终止，输出包含这些 token，除非是特殊 token）。	None	直接基于 token ID 终止，适用于自定义分词器场景，可与 stop 同时使用。
bad_words	禁止生成的词汇列表（阻止补全禁用词汇的最后一个 token，如 ["badword"]）。	None	按 token 序列匹配（需分词器支持），例如 “bad” 可能被拆分为多个 token，需确保完整匹配。
allowed_token_ids	仅允许生成的 token ID 列表（严格过滤，仅保留指定 token 的概率）。	None	与其他筛选参数（如 top_p）叠加生效，优先级最高（不在列表中的 token 概率置为 -∞）。
ignore_eos	是否忽略模型的 EOS（结束符）并继续生成（True 时强制突破默认结束符）。	False	用于生成超长文本或忽略模型内置结束信号（如续写时不被 EOS 打断）。

五、惩罚机制

调整 token 概率以避免重复、鼓励新内容或控制频率（提升生成质量）。

参数名	说明	默认值	注意事项
presence_penalty	存在惩罚： - >0：惩罚已在生成文本中出现过的 token（鼓励新内容） - <0：鼓励重复	0	作用于生成文本中所有已出现的 token（包括提示和历史生成内容）。
frequency_penalty	频率惩罚： - >0：惩罚高频出现的 token（抑制重复，鼓励低频内容）	0	基于 token 在生成文本中的出现次数（次数越多，惩罚越强）。
repetition_penalty	重复惩罚： - >1：惩罚在提示或生成文本中出现过的 token（抑制重复） - <1：鼓励重复	1.0	最常用的重复控制参数，推荐值 [1.0, 1.2]（值越高，重复抑制越强）。

六、输出格式与处理

控制输出的文本格式、特殊 token 处理及去标记化逻辑。

参数名	说明	默认值	注意事项
detokenize	是否对生成的 token 列表进行去标记化（转换为自然文本，如合并子词）。	True	设为 False 时返回原始 token ID 列表（适用于需要 token 级输出的场景）。
skip_special_tokens	是否在输出中跳过特殊 token（如 <s>, </s>, <unk> 等）。	True	保留特殊 token 可能影响文本可读性，通常建议保持默认值。
spaces_between_special_tokens	是否在特殊 token 之间添加空格（提升可读性）。	True	仅在 skip_special_tokens=False 时生效，影响输出文本的格式。
include_stop_str_in_output	是否在输出中包含 stop 字符串（默认不包含）。	False	若需保留停止字符串（如用于解析边界），设为 True。

七、日志与调试参数

用于获取生成过程中的概率信息（调试或分析用途）。

参数名	说明	默认值	注意事项
logprobs	每个输出 token 返回的对数概率数量（包含选中 token 的概率及 top-k 概率）。	None	设为 N 时，返回前 N 个最可能 token 的概率，至少包含 1 个（选中 token）。
prompt_logprobs	每个提示 token 返回的对数概率数量（分析提示阶段的 token 概率）。	None	资源消耗随值增大而上升，仅调试时使用。

八、高级选项与扩展

用于自定义解码逻辑或特殊场景（如格式约束、性能优化）。

参数名	说明	默认值	注意事项
logits_processors	自定义对数几率处理器列表（修改 token 概率分布，高级扩展功能）。	None	需实现 LogitsProcessor 接口，用于复杂约束（如语法检查、动态筛选）。
guided_decoding	引导解码参数（生成符合 JSON/正则/语法规则的文本，如指定结构约束）。	None	支持 JSON 模式、正则表达式、枚举选项等，需配合 GuidedDecodingParams 使用。
logit_bias	对特定 token 的概率偏差（直接调整 logits，如 {token_id: bias}）。	None	偏差范围 [-100, 100]（OpenAI 规范），正数增加概率，负数降低概率。
truncate_prompt_tokens	截断提示 token： - -1：使用模型默认截断长度 - k：保留最后 k 个 token（左截断）	None	用于处理超长提示（如历史对话上下文），避免内存溢出。
extra_args	自定义附加参数（传递给自定义采样器，框架内部不使用）。	None	用于扩展功能，如特定硬件优化参数。

最佳实践

1. 确定性生成（如代码、结构化输出）：
   • 设置 temperature=0（贪心采样），忽略 top_p/top_k，可配合 repetition_penalty>1 避免重复。
2. 多样性生成（如创意写作）：
   • 调整 temperature=0.7~1.2，结合 top_p=0.9 或 top_k=50，平衡随机性和质量。
3. 格式约束（如 JSON、Markdown）：
   • 使用 guided_decoding 或 allowed_token_ids，确保生成内容符合结构要求。
     优先看具体的模型文档给出的推荐使用方法

temperature=0（贪心采样）

一、核心原理：确定性贪心解码

当 temperature=0 时，模型采用 贪心策略（Greedy Decoding），即每一步生成token时：

1. 直接选择当前状态下概率最高的token（无任何随机性）；
2. 忽略所有概率分布的“平滑”操作（temperature的本质是对概率分布进行缩放，temperature=0时相当于概率分布被无限“陡峭化”，唯一保留概率最高的token）。

数学层面：

• 原始概率分布为 $P(token) $，经temperature缩放后为 $P’(token) = \frac{\exp(\log P(token) / temperature)}{\sum \exp(\log P(token) / temperature)} $。
• 当 $temperature \to 0 $ 时，$P’(token) $ 退化为仅保留概率最高的token（其他token概率趋近于0），即 硬选择最高概率token。

二、与其他参数的交互

1. 完全忽略 top_p 和 top_k

   • 贪心策略是“全局最优”选择，无需限制候选范围（top_p筛选候选分布、top_k限制候选数量的逻辑均不生效）。
   • 即使设置 top_p=0.9 或 top_k=50，模型仍会直接选择全局概率最高的token。

2. repetition_penalty 仍可能生效

   • 若模型支持“重复惩罚”机制（如避免重复生成相同token），该参数会在计算概率时调整重复token的分数，间接影响贪心选择（但本质仍是选调整后的最高概率token）。

三、行为表现

1. 输出完全确定

   • 相同输入、相同参数下，生成结果绝对一致（无任何随机性）。
   • 示例：输入“今天天气”，每次生成的后续内容完全相同（如“很好，适合出门散步”）。

2. 可能陷入局部最优

   • 贪心策略只考虑当前步最优，不展望未来（类似“贪心算法”缺陷），可能导致生成序列非全局最优。
   • 例如：生成句子时，当前最优token可能导致后续逻辑矛盾（如“我买了苹果，因为它很红” vs. 更合理的“我买了苹果，因为它很甜”）。

四、适用场景

1. 需要精确、无变化的输出

   • 代码生成（要求语法严格正确）、数学推理（答案唯一）、固定格式文本（如邮件模板）。
   • 参数示例：

     {"temperature": 0,       # 贪心策略，无随机性"top_p": 0.0,           # 无效（被忽略）"top_k": 0,             # 无效（被忽略）"repetition_penalty": 1.2  # 可选，防止重复
     }
     

2. 快速生成（计算效率高）

   • 无需采样或概率分布计算，每一步仅需找最高概率token，速度比采样策略更快。

3. 不适用场景

   • 创意内容（如诗歌、故事）：需要多样性，贪心策略会导致输出单调；
   • 多模态生成（如图文结合）：可能因局部最优导致整体逻辑不连贯。

五、与其他temperature值的对比

temperature	策略	随机性	输出特点	典型场景
0	贪心解码	无（确定）	完全重复，局部最优优先	精确任务（代码、公式）
0.1-0.5	低温采样	低随机性	保守，接近常见表达	正式文本、翻译
0.6-1.0	中温采样	中等随机性	平衡常见与创新	对话、故事生成
1.0+	高温采样	高随机性	创新、多样化（可能不合逻辑）	创意写作、头脑风暴