很多时候，模型“答得好不好”不只取决于模型本身，也取决于你怎么设置 decoding。SamplingParams 就是 vLLM 里控制输出风格、长度、停止条件、概率信息和约束生成的核心入口。

SamplingParams 不是“玄学调参”，它是在管模型下一步怎么选 token

大模型每次生成文本，本质上是在一堆候选 token 里选下一个 token。SamplingParams 负责规定“候选范围多大”“选择要不要随机”“是否惩罚重复”“什么时候停下”“要不要返回概率信息”等规则。

在 vLLM v0.6.4 中，SamplingParams 的整体设计和 OpenAI text completion API 的 sampling parameters 对齐，同时 vLLM 文档也说明它额外支持 beam search。实际工程里，你通常不会一次调完所有参数，而是先抓住几个主旋钮：temperature、top_p、max_tokens、stop、repetition_penalty。

先别背参数名，先看它们分别管哪一层

一、输出数量

n 表示返回几条结果；best_of 表示先生成多少条，再从中挑出前 n 条。best_of 必须大于或等于 n。如果只是普通服务接口，通常 n=1 就够。

二、随机性

temperature 越低，输出越确定；temperature=0 是 greedy sampling。top_p 用累计概率筛候选 token；top_k 限制只看概率最高的 k 个 token；min_p 则按照“相对于最高概率 token 的比例”过滤太弱的候选。

三、重复控制

presence_penalty 看 token 是否已经出现；frequency_penalty 看出现频率；repetition_penalty 同时参考 prompt 和已生成文本。它们都不是“质量开关”，调得过重会让文本变得生硬。

四、停止与长度

max_tokens 控制最多生成多少 token；min_tokens 控制至少生成多少 token；stop 和 stop_token_ids 负责遇到指定字符串或 token 时停止。需要注意，文档中说明 stop 触发后返回文本默认不包含 stop string，而 stop_token_ids 触发时通常会包含 stop token，除非它是 special token。

五、概率与后处理

logprobs、prompt_logprobs 用于拿到 token 级概率信息，适合分析模型置信度或做候选重排。detokenize、skip_special_tokens、spaces_between_special_tokens 则决定输出文本如何从 token 还原。

六、约束生成

bad_words 禁止部分词，allowed_token_ids 只允许指定 token，logit_bias 调整特定 token 的 logits，logits_processors 和 guided_decoding 则更偏底层或结构化控制。

实用判断：如果你只是在做普通问答服务，先调 temperature、top_p、max_tokens、stop。只有当你需要概率分析、结构化输出或安全约束时，再碰 logprobs、guided_decoding、logit_bias 这些参数。

常用参数怎么理解

可以在搜索框里输入参数名或关键词，例如 temperature、stop、概率、重复。

vLLM v0.6.4 · SamplingParams

参数	默认值	作用	使用建议	类别
n	1	返回的 output sequences 数量。	普通在线服务多用 1；多候选生成才调大。	数量
best_of	None	先生成多条，再返回其中最好的 n 条；要求 best_of ≥ n。	会增加计算量，离线生成或候选筛选时更适合。	数量
temperature	1.0	控制 sampling 随机性；越低越稳定，0 表示 greedy sampling。	事实问答 0~0.3；通用写作 0.6~0.9；创意任务可更高。	随机性
top_p	1.0	按累计概率截断候选 token。	常和 temperature 一起调；0.8~0.95 是常见区间。	随机性
top_k	-1	只考虑概率最高的 k 个 token；-1 表示不限制。	需要更硬的候选范围时再用，不必每次都开。	随机性
min_p	0.0	按“相对最高概率 token 的比例”过滤候选 token。	适合减少极低概率 token 干扰；0 表示关闭。	随机性
seed	None	设置 random seed。	复现实验结果时设置；线上服务一般不固定。	复现
presence_penalty	0.0	根据 token 是否已经出现来惩罚。	想减少“原地打转”可小幅加，比如 0.1~0.5。	重复
frequency_penalty	0.0	根据 token 出现频率来惩罚。	对长文本重复词有用，但过高会牺牲自然度。	重复
repetition_penalty	1.0	根据 prompt 和已生成文本中的重复情况惩罚。	大于 1 减少重复；略微调高即可，避免过度。	重复
stop	None	遇到指定字符串停止生成，默认返回文本不包含 stop string。	做模板输出、对话分隔、代码块截断时很有用。	停止
stop_token_ids	None	遇到指定 token id 停止生成。	更贴近 tokenizer 层，适合底层工程控制。	停止
include_stop_str_in_output	False	是否把 stop string 也放进输出文本。	需要保留分隔符时才打开。	停止
ignore_eos	False	是否忽略 EOS token，继续生成。	一般不要打开，除非明确知道模型会过早输出 EOS。	停止
max_tokens	16	每条 output sequence 最多生成多少 token。	默认 16 很短；实际问答通常要显式设置更大。	长度
min_tokens	0	生成达到该 token 数前，不允许 EOS 或 stop_token_ids 停止。	避免模型太早结束时可用。	长度
logprobs	None	返回每个输出 token 的 top log probabilities。	会增加返回信息量；分析、重排、置信度估计时使用。	概率
prompt_logprobs	None	返回 prompt token 的 log probabilities。	评估 prompt 或做打分任务时更有意义。	概率
detokenize	True	是否把输出 token 还原成文本。	普通应用保持 True；底层 token 处理可关闭。	输出
skip_special_tokens	True	输出时是否跳过 special tokens。	普通用户可见文本保持 True。	输出
spaces_between_special_tokens	True	special tokens 之间是否添加空格。	一般保持默认。	输出
bad_words	None	禁止指定词生成；更准确地说，是当下一 token 会完成对应 token 序列时禁止最后一个 token。	适合简单黑名单，不适合替代完整安全策略。	约束
allowed_token_ids	None	只保留指定 token ids 的分数。	强约束场景使用，配置错会让输出异常。	约束
logit_bias	None	对指定 token 施加 logit bias。	轻微引导可用；强行偏置容易造成怪输出。	约束
logits_processors	None	自定义函数，在生成过程中修改 logits。	高级用法，适合自定义 decoding 规则。	约束
guided_decoding	None	根据参数构造 guided decoding logits processor。	结构化输出、schema 约束时考虑。	约束
truncate_prompt_tokens	None	只保留 prompt 最后的 k 个 tokens，即 left truncation。	长上下文截断时有用，但可能丢掉前文关键信息。	工程
output_kind	CUMULATIVE	控制 request output 的形式。	流式或增量输出场景再深入配置。	输出

直接可抄的几组 SamplingParams

稳定问答 / RAG

目标是少编、少跑题、尽量贴近检索内容。

temperature=0.2top_p=0.8max_tokens=512

from vllm import SamplingParams

params = SamplingParams(
    temperature=0.2,
    top_p=0.8,
    max_tokens=512,
)

通用聊天 / 解释型回答

目标是稳定但不死板，适合写解释、课程笔记、普通问答。

temperature=0.7top_p=0.9max_tokens=800

from vllm import SamplingParams

params = SamplingParams(
    temperature=0.7,
    top_p=0.9,
    max_tokens=800,
)

创意写作 / 多样化生成

目标是让表达更有变化，但仍保留基本可控性。

temperature=0.95top_p=0.95presence_penalty=0.3

from vllm import SamplingParams

params = SamplingParams(
    temperature=0.95,
    top_p=0.95,
    presence_penalty=0.3,
    max_tokens=1000,
)

严格格式 / 批处理输出

目标是让模型更听格式要求，减少自由发挥。

temperature=0stop=[...]max_tokens=256

from vllm import SamplingParams

params = SamplingParams(
    temperature=0,
    max_tokens=256,
    stop=["\n\nEND", "</answer>"],
)

实际调 SamplingParams，可以按这条顺序来

先定任务类型。

事实问答、RAG、代码解释这类任务，先降低 temperature；创意写作、改写、头脑风暴，则允许更高的 temperature 和 top_p。

再定输出边界。

先设置 max_tokens，否则默认值可能让输出过短。需要明确截断位置时，再加 stop 或 stop_token_ids。

处理重复问题。

如果模型反复绕圈，先小幅增加 repetition_penalty 或 presence_penalty。不要一上来把多个 penalty 都调得很高。

需要分析时再打开概率。

logprobs 和 prompt_logprobs 很适合调试、打分、候选重排，但普通业务接口不一定需要返回这些信息。

结构化输出才上强约束。

当你需要固定 JSON、枚举答案或 schema 输出时，再考虑 guided_decoding、allowed_token_ids、logit_bias 等更强的约束手段。

一个完整调用示例

复制代码

from vllm import LLM, SamplingParams

llm = LLM(model="your-model-path-or-name")

prompts = [
    "用三句话解释什么是 KV Cache。"
]

sampling_params = SamplingParams(
    temperature=0.4,
    top_p=0.9,
    max_tokens=300,
    stop=["\n\n"],
    repetition_penalty=1.05,
)

outputs = llm.generate(prompts, sampling_params)

for output in outputs:
    print(output.outputs[0].text)

一句话记忆：temperature 管“敢不敢乱想”，top_p/top_k/min_p 管“候选池有多大”，max_tokens/stop 管“什么时候收手”，penalty 管“别老重复自己”。

两个方法：clone 与 update_from_generation_config

文档里还列出了两个方法。clone() 会做 deep copy，但排除 LogitsProcessor 对象，因为这类对象可能携带任意且较大的数据。update_from_generation_config() 则用于从 generation_config 里更新非默认值。

复制代码

base_params = SamplingParams(
    temperature=0.7,
    top_p=0.9,
    max_tokens=512,
)

new_params = base_params.clone()
new_params.max_tokens = 1024

实际项目里，可以把一组稳定的 SamplingParams 当作 base config，再针对不同接口做轻量修改。这样比到处散落参数更容易维护。

参考来源：vLLM v0.6.4 官方文档 · Sampling Parameters

说明：本文不是逐句翻译，而是按工程使用逻辑对 SamplingParams 做中文化整理。参数名称、API 名称和关键技术词保留英文。