ik_llama.cpp 采样顺序定制导致 llama-server 崩溃的完整修复记录与配置指南
ik_llama.cpp 采样顺序定制导致 llama-server 崩溃的完整修复记录与配置指南
导读
本文以 ik_llama.cpp 仓库中 GitHub Issue #575「llama-server crash with sampling order」为核心线索,完整还原了该缺陷从复现、定位到最终修复的全过程,并结合 common/sampling.cpp 与 examples/server/server-context.cpp 源码,深入讲解 --samplers / --sampling-seq 采样器顺序配置的底层原理。读者读完本文后,将掌握 llama-server 采样链的自定义方法、DRY 采样器与采样队列的生命周期关系,以及如何正确配置采样顺序以避免服务崩溃。
一、缺陷背景:自定义采样顺序触发服务崩溃
1.1 问题现象
在提交 Commit 3f111ad(引入 DRY 采样器,对应 PR #513)之后,用户 mcm007 报告:只要在 OpenAI 兼容端点(/v1/chat/completions)请求中显式指定采样器顺序,llama-server 就会崩溃。
触发条件是请求体中携带如下采样配置:
{
"samplers": ["min_p", "temperature"]
}
或使用命令行启动参数:
llama-server --samplers "min_p;temperature"
# 或等价的简化写法
llama-server --sampling-seq "mt"
该缺陷具备以下特征:
- WebUI 工作正常,只有 HTTP API(
/completion与/v1/chat/completions两个端点)崩溃; - 与模型无关:不同模型(FA、MLA、MoE 架构)均能复现;
- 与后端无关:Vulkan 等其他后端同样崩溃;
- 崩溃前服务日志正常完成上下文初始化与槽位(slot)调度,问题发生在请求处理阶段。
1.2 环境与复现信息
报告者给出的构建与运行环境:
version: 3760 (3f111ad7)
built with cc (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0 for x86_64-linux-gnu
构建方式:
cmake -B build -DGGML_NATIVE=ON
cmake --build build --config Release -j$(nproc)
启动服务:
llama-server --host 0.0.0.0 --port 8080 --ctx-size 4096 --verbose \
--model /models1/Qwen_Qwen3-0.6B-Q6_K.gguf
最小复现请求(curl):
curl -k ik_llamacpp:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer no-key" \
-d '{
"model": "Qwen_Qwen3-0.6B-Q6_K.gguf",
"messages": [
{
"role": "user",
"content": "Hello!"
}
]
}'
请求日志中可以看到槽位携带的采样参数被正确解析("samplers":["min_p","temperature"]),随后服务在处理该任务时崩溃。
二、崩溃根因:DRY 采样器状态指针未初始化
2.1 复现边界:只在「不包含 DRY」时崩溃
经过用户 mcm007 的大量组合测试,崩溃边界被精确划定出来:
崩溃的组合(采样链中不含 DRY):
--samplers "top_k"
--samplers "top_k;tfs_z"
--samplers "top_k;tfs_z;typical_p;top_p;min_p;temperature"
--samplers "top_n_sigma;top_k;typ_p;top_p;min_p;xtc;temperature"
--sampling-seq "mt"
正常工作的组合(采样链中包含 DRY):
--samplers "penalties;dry;top_n_sigma;top_k;typ_p;top_p;min_p;xtc;temperature"
--samplers "dry;top_n_sigma;top_k;typ_p;top_p;min_p;xtc;temperature"
--samplers "dry"
--samplers "dry;min_p;temperature"
--samplers "min_p;temperature;dry"
--sampling-seq "mtd"
--sampling-seq "dt"
结论非常清晰:只要自定义采样序列中缺少 DRY 采样器,llama-server 就会崩溃;包含 DRY 则一切正常。
2.2 源码级定位:smpl 指针的空悬调用
在 common/sampling.cpp 的 common_sampler_init 中,DRY 采样器的初始化被绑定在采样序列的遍历逻辑里:
llama_sampling_set_rng_seed(result, params.seed);
for (const auto& cnstr : params.samplers_sequence)
{
switch (cnstr)
{
case llama_sampler_type::DRY:
{
std::vector<const char*> c_breakers;
c_breakers.reserve(params.dry_sequence_breakers.size());
for (const auto& str : params.dry_sequence_breakers)
{
c_breakers.push_back(str.c_str());
}
result->smpl = llama_sampler_init_dry(vocab,
params.dry_multiplier, params.dry_base, params.dry_allowed_length,
params.dry_penalty_last_n, c_breakers.data(), c_breakers.size());
break;
}
case llama_sampler_type::ADAPTIVE_P:
{
if (params.adaptive_target >= 0.0f) {
result->adapt_p_ctx = llama_init_adaptive_p(
params.adaptive_target, params.adaptive_decay,
params.adaptive_updt_w_cur, result->rng());
}
break;
}
default:
break;
}
}
关键问题在于:DRY 采样器实例(result->smpl)只有在采样序列中出现 llama_sampler_type::DRY 时才会被创建。而 common_sampler 结构体中该字段被声明为裸指针(common/sampling.h):
llama_sampler_dry* smpl;
当用户指定的序列(如 "mt"、"top_k;tfs_z")不含 d(DRY)时,result->smpl 保持未初始化状态。
2.3 崩溃路径:状态重置与逐 token 采样
在 common_sampler_reset(common/sampling.cpp)中,每次处理新任务时都会无条件调用 DRY 状态重置:
void common_sampler_reset(common_sampler * ctx) {
ctx->prev.clear();
llama_sampler_dry_reset(ctx->smpl); // <-- 空指针解引用
llama_free_adaptive_p(ctx->adapt_p_ctx);
ctx->adapt_p_ctx = llama_init_adaptive_p(...);
ctx->speculative_rng.seed(ctx->speculative_seed);
}
同样,在逐 token 采样的核心函数 sampler_queue(common/sampling.cpp)中:
for (auto sampler_type : samplers_sequence) {
switch (sampler_type) {
case llama_sampler_type::DRY:
llama_sample_dry(ctx_main, ctx_sampling->smpl, &cur_p); // <-- 未初始化指针
break;
...
}
}
虽然此处对 DRY 的调用发生在序列包含 DRY 时(此时 smpl 已初始化),但 common_sampler_reset 中的调用则是无条件执行的。因此,只要采样序列不含 DRY,ctx->smpl 就是一个未初始化(悬空)指针,llama_sampler_dry_reset(ctx->smpl) 在服务端每次槽位重置时必然触发非法内存访问——这正是 llama-server 崩溃的直接原因。
从源码结构看,
llama-cli之所以不受影响,是因为它的采样器生命周期与服务器端不同:CLI 进程内common_sampler_init与后续调用之间不存在跨任务的重置路径,或其在无 DRY 时不会走到该重置逻辑;而服务器端每个请求都会经过common_sampler_reset,从而稳定复现崩溃。
三、修复过程:从 PR #578 到 PR #588
3.1 第一轮修复(PR #578):未覆盖服务器路径
2025-07-03,项目作者 ikawrakow 在 Issue 下回复「#578 应该修复了这个问题」,并提交了 PR 578 - Do not crash when there is no DRY sampler。该 PR 在 llama-cli 路径上解决了无 DRY 时的崩溃问题。
然而用户测试版本 3785 (3e024de1) 后反馈:llama-server 依然崩溃。作者随后验证 llama-cli --sampling-seq mt 工作正常,确认了 CLI 与服务器两条代码路径的差异。用户进一步确认:llama-cli 已正常,但服务器的 /completion 与 /v1/chat/completions 两个端点仍崩溃。
3.2 最终修复(PR #588):服务器端补丁
2025-07-06,社区贡献者 firecoperana 提交 PR 588 - Fix server crash when there is no DRY sampler,专门针对 llama-server 的崩溃路径打补丁。作者 ikawrakow 在评审中回复:
"I missed that one. Thanks!"
("我漏掉了那一处,谢谢!")并予以 ✅ APPROVED。
用户 mcm007 最终确认:
"It works OK, thank you both!"
至此,Issue #575 关闭,缺陷完整解决。
3.3 修复要点总结
| 环节 | 问题 | 修复位置 |
|---|---|---|
| CLI 路径 | 无 DRY 时崩溃 | PR #578 |
| Server 路径 | 无 DRY 时每次槽位重置崩溃 | PR #588 |
| 根因 | smpl 指针仅在序列含 DRY 时初始化,而 common_sampler_reset 无条件调用 |
common/sampling.cpp |
从实现角度看,正确的修复应保证 smpl 在使用前先判空(或统一初始化),使「采样序列是否包含 DRY」与「DRY 状态对象是否存活」解耦——即:即使序列中不含 DRY,重置与采样阶段也不应对悬空指针发起调用。
四、采样器顺序配置的完整实战指南
理解了这个 Bug 的来龙去脉后,下面系统梳理 llama-server 中采样顺序的两种配置方式及全部可用采样器。
4.1 两种配置语法
方式一:完整名称列表(--samplers,分号分隔)
llama-server \
--samplers "penalties;dry;top_n_sigma;top_k;typical_p;top_p;min_p;xtc;temperature" \
--model /path/to/model.gguf
方式二:单字符缩写序列(--sampling-seq,默认 kfypmt)
llama-server --sampling-seq "mtd" --model /path/to/model.gguf
两者均可通过 HTTP API 请求体覆盖(见 4.3 节)。
4.2 采样器名称与缩写映射表
根据 common/sampling.cpp 与 llama_sampling_types_from_chars 的映射表,当前版本支持以下采样器:
| 缩写字符 | 完整名称 | 对应采样器 |
|---|---|---|
d |
dry |
DRY 重复惩罚(无参,状态化采样器) |
k |
top_k |
Top-K 截断 |
p |
top_p |
Top-P(核采样) |
y |
typical_p |
Typical-P |
m |
min_p |
Min-P |
f |
tfs_z |
Tail Free Sampling |
x |
xtc |
XTC |
n |
top_n_sigma |
Top-N-Sigma |
t |
temperature |
温度采样(支持动态温度) |
w |
adaptive_p |
Adaptive-P(自动置于链尾) |
注意:
--sampling-seq中kfypmt的默认顺序为top_k → tfs_z → typical_p → top_p → min_p → temperature。另外,llama_sampling_types_from_names还接受别名(如nucleus、temp、tfs等,common/sampling.cpp),便于用户按习惯书写。
4.3 API 请求中的采样器覆盖
examples/server/server-context.cpp 展示了服务器端如何解析请求体中的 samplers 字段:
{
const auto samplers = data.find("samplers");
if (samplers != data.end()) {
if (samplers->is_array()) {
slot.sparams.samplers_sequence = llama_sampling_types_from_names(*samplers, false);
}
else if (samplers->is_string()) {
slot.sparams.samplers_sequence = llama_sampling_types_from_chars(samplers->get<std::string>());
}
else {
slot.sparams.samplers_sequence = default_sparams.samplers_sequence;
}
}
}
即请求体支持两种形态:
{ "samplers": ["min_p", "temperature"] } // 数组:完整名称列表
{ "samplers": "mt" } // 字符串:单字符缩写序列
解析完成后,服务器会释放旧的采样上下文并用新参数重新初始化(server-context.cpp):
if (slot.ctx_sampling != nullptr) {
common_sampler_free(slot.ctx_sampling);
}
slot.ctx_sampling = common_sampler_init(model, slot.sparams);
这解释了为何 Issue 中 "samplers":["min_p","temperature"] 会触发崩溃:该请求在每次任务处理时都会经过上述重建路径,而重建后的 ctx_sampling 内部 smpl 为未初始化状态,随后的 common_sampler_reset 便发生非法访问。
4.4 采样链的实际执行顺序
在 sampler_queue(common/sampling.cpp)中,采样器严格按照 samplers_sequence 顺序对概率分布 cur_p 依次处理:
for (auto sampler_type : samplers_sequence) {
switch (sampler_type) {
case llama_sampler_type::DRY: llama_sample_dry(ctx_main, ctx_sampling->smpl, &cur_p); break;
case llama_sampler_type::TOP_K: llama_sample_top_k(ctx_main, &cur_p, top_k, min_keep); break;
case llama_sampler_type::TFS_Z: llama_sample_tail_free(ctx_main, &cur_p, tfs_z, min_keep); break;
case llama_sampler_type::TYPICAL_P: llama_sample_typical(ctx_main, &cur_p, typical_p, min_keep); break;
case llama_sampler_type::TOP_P: llama_sample_top_p(ctx_main, &cur_p, top_p, min_keep); break;
case llama_sampler_type::MIN_P: llama_sample_min_p(ctx_main, &cur_p, min_p, min_keep); break;
case llama_sampler_type::XTC: llama_sample_xtc(ctx_main, &cur_p, xtc_probability, xtc_threshold, min_keep); break;
case llama_sampler_type::TOP_N_SIGMA: llama_sample_top_n_sigma(ctx_main, &cur_p, top_n_sigma); break;
case llama_sampler_type::TEMPERATURE:
if (dynatemp_range > 0) {
// 动态温度:在 [temp - dynatemp_range, temp + dynatemp_range] 区间按熵调整
llama_sample_entropy(ctx_main, &cur_p, dynatemp_min, dynatemp_max, dynatemp_exponent);
} else {
llama_sample_temp(ctx_main, &cur_p, temp);
}
break;
case llama_sampler_type::ADAPTIVE_P: use_adaptive_p = ctx_sampling->adapt_p_ctx != nullptr; break;
default: break;
}
}
// adaptive_p 固定放到链尾执行,忽略其在序列中的位置
if (use_adaptive_p) {
llama_sample_adaptive_p(ctx_main, &cur_p, ctx_sampling->adapt_p_ctx);
}
几点实战要点:
- 顺序敏感:
top_k → top_p → min_p → temperature与temperature → top_k → top_p → min_p的结果不同。通常建议先做硬性截断类(top_k、top_p、min_p),最后再做温度缩放,避免先缩放后被截断导致概率分布失真; - DRY 是有状态采样器:它在链内维护重复序列检测状态(
prev历史、序列分隔符dry_sequence_breakers),因此要求在使用它的每个环节(初始化、重置、逐 token 采样、释放)状态一致,这也是本 Bug 的核心教训; - Adaptive-P 特殊:无论写在序列哪个位置,最终都被固定放到链尾执行(见 common/sampling.cpp 的注释 "adaptive p should be put to the last")。
4.5 DRY 采样器的相关参数
DRY 采样器由 common/sampling.h 中的参数控制:
| 参数 | 默认值 | 说明 |
|---|---|---|
dry_multiplier |
0.0 |
0 表示禁用;对延伸重复的 token 施加的惩罚系数 |
dry_base |
1.75 |
指数底数:multiplier * base ^ (重复长度 - allowed_length) |
dry_allowed_length |
2 |
重复长度超过该值才施加惩罚 |
dry_penalty_last_n |
-1 |
向后扫描重复的 token 数(0 禁用惩罚,-1 表示整个上下文) |
dry_sequence_breakers |
["\n", ":", "\"", "*"] |
序列分隔符,用于打断重复匹配 |
在 Issue 的服务端日志中可以看到这些参数的默认值被完整序列化进槽位状态("dry_multiplier":0.0,"dry_base":1.75,"dry_allowed_length":2,"dry_penalty_last_n":4096,...),证明服务器默认会为 DRY 配置好状态对象,但只有当序列含 DRY 时才真正实例化——这正是 Bug 的触发条件。
五、故障排查方法论:遇到 llama-server 崩溃怎么定位
5.1 快速二分法
如果自定义采样配置导致服务崩溃,可参考 Issue 中的复现矩阵进行二分:
- 先用
--sampling-seq "kfypmt"(默认序列)确认服务本身正常; - 再逐步向序列中添加/删除单个采样器,缩小崩溃边界;
- 重点检查有状态采样器(DRY、Adaptive-P)是否出现在序列中——它们在初始化、重置、释放阶段都有额外状态管理,最容易出现生命周期问题。
5.2 从日志与代码双线定位
- 日志侧:开启
--verbose,观察槽位(slot)状态 JSON 中"samplers":[...]字段,确认请求体的采样序列确实被解析生效(如 Issue 日志中"samplers":["min_p","temperature"]); - 代码侧:检查
common_sampler_init(初始化)、common_sampler_reset(重置)、sampler_queue(逐 token 执行)、common_sampler_free(释放)四处对同一采样器实例的引用是否在所有路径上都安全(判空或一致初始化); - 对比验证:同一采样配置分别用
llama-cli与llama-server验证,可快速判断是核心采样库问题还是服务器封装层问题——正如 Issue 中作者与用户确认的那样,llama-cli正常而服务器崩溃,说明缺陷位于服务器与采样上下文的重置交互路径上。
六、相关资源与后续参考
- 完整 Issue 记录:github-data/issues/575 - Bug_ llama-server crash with sampling order.md
- 第一轮修复 PR:github-data/pull_requests/578 - Do not crash when there is no DRY sampler.md
- 最终修复 PR:github-data/pull_requests/588 - Fix server crash when there is no DRY sampler.md
- 采样器核心实现:common/sampling.cpp、common/sampling.h
- 服务器采样参数解析:examples/server/server-context.cpp
- 服务器命令行选项说明:examples/server/README.md
结语
Issue #575 是一个典型的「有状态采样器生命周期」缺陷案例:DRY 采样器作为有状态组件被引入后,其初始化被耦合在采样序列遍历逻辑中,而服务器端的无条件重置路径绕过了这一条件,导致空指针崩溃。该案例的价值不仅在于修复本身,更在于揭示了一条通用经验——任何有状态组件(采样器、KV 缓存、语法解析器等)在引入时必须保证初始化、重置、执行、释放四条路径的状态一致性,否则任何一条路径的遗漏都会在特定配置组合下暴露为难以排查的崩溃。对于使用 llama-server 自定义采样顺序的开发者,本文的配置指南与排查方法论可直接落地到日常部署与调优中。