sybil-solutions/inference-optimisation-skill:把本地大模型推理调优变成可复现的工程流程
我调了三个月本地大模型,才发现最缺的不是算力,是方法
先说个真实的经历。
去年年底我在一台 4090 上跑 Qwen2.5-32B-AWQ,之前一直没找到好的参数组合。显存够,模型能跑起来,就是慢。32B 量化后大概 18GB,单卡 decode 二十几个 token/s,能用,但做批量任务的时候就是干等。
我试过很多” 优化” 手法。改 --gpu-memory-utilization,改 chunked prefill size,换 quant 格式,抄别人的启动命令。每改一次,跑一次,看一眼 tok/s,觉得快了就留下。
然后我发现了两个残酷的事实:
第一,我抄来的” 最优配置”,在我这台机器上跑出来比我的慢。别人说是 60 tok/s,我这儿 38 tok/s。
第二,也是更糟的 —— 我某次把一个参数从 0.9 改成 0.85,跑出 52 tok/s,特别开心,记下来。过了两天再跑同一个配置,还是 52 tok/s。但我把这次” 进步” 的基准点往前翻,发现我之前记的那个” 基线” 41 tok/s,其实是在机器刚开机、温度还低的时候测的。不是我的优化有效,是我的基线被 thermal throttling 污染了。
那一瞬间挺崩溃的。不是优化没效果,是我所有的优化可能都是幻觉。
后来我系统看了下本地推理调优的资料,发现真正做严肃调优的人,几乎都在做同一件事:先把理论天花板算出来,然后按” 天花板缺口 × 成功概率” 排优先级,一次只改一个变量,用交叉对照压住噪声,改完必须过稳定性门禁。 这套东西听起来像常识,但真按它做一遍,和我之前那套” 改参数看运气” 的差距是数量级的。
sybil-solutions/inference-optimisation-skill 就是把这套流程固化下来的一个开源项目。
它只有 32KB,一半是 Markdown,但把它和我之前的方式对照一下,差别挺说明问题的。
一、它到底是什么:不是调参手册,是一套” 爬坡” 协议
仓库的自我定位很精确 ——hill-climbing a model server。
“爬坡” 这个词选得准。它不是给你一份” 最佳参数表”,因为最佳参数是绑定在特定硬件 + 特定模型 + 特定量化 + 特定引擎版本上的,一张表到了你机器上大概率失效。
它给的是怎么在你自己这台机器上,系统性地逼近那个上限的过程。
1 | sybil-solutions/inference-optimisation-skill |
四个数字先摆出来(截至 2026-11-20 通过 GitHub API 查证):
| 指标 | 数值 |
|---|---|
| Stars | 1259 |
| Forks | 114 |
| License | MIT |
| 主要语言 | Python |
| 创建时间 | 2026-11-16 |
| 仓库体积 | 32 KB |
创建才四天,1259 star,fork/star 比例接近 1/11—— 这个比例在工具类项目里算相当高的,说明大部分人是真拿去用了,而不是随手点了个星。
它和” 最优参数表” 的本质区别
关键在于它把结论和结论的获得方式分开了。
一个参数表告诉你” 在 4090 上,chunked_prefill_size 设 4096 最好”。它不告诉你:
- 你的基线是在什么温度下测的?
- 你这个” 最好” 是跑一次的结果还是 6 次的中位数?
- 这个改动在 256K 上下文下还成立吗?
- 有没有可能它其实让你的另一个指标退化了 10%?
这个 Skill 里所有性能数字都带测量条件 —— 中位数还是单次、冷启动还是热缓存、thinking 开还是关、用哪个 harness 测的。这是我读它时印象最深的一点。
作者在 publishing.md 里明确要求:“State in the README which numbers come from the gates and which from the hill-climb harness, and how each was measured.” 不同来源的数字不能混用,必须说清楚。
这在我见过的开源调优材料里是很少见的自觉。
二、核心思想一:先算天花板,再决定值不值得动手
这是整个方法论里我最服的一条,也是我以前完全没做的。
两种截然不同的瓶颈
Decode(生成 token) 是内存带宽瓶颈。每生成一个 token,模型要把所有权重读一遍。所以决定速度的是你的显存 / 内存带宽,不是你的算力。
Prefill(预填充,处理输入) 是算力瓶颈。它要做大量矩阵乘法。
搞混这两个,你会做出完全相反的优化决策。比如有人为了让 decode 更快去减少算力 —— 没用,decode 根本不缺算力,缺带宽。
Decode 的字节账怎么算
ceilings.md 给出的公式:
1 | B_target = dense_weight_bytes # 注意力/线性注意力、共享专家、router、norms |
然后除以实测带宽,就是单用户 decode 的天花板。
几个细节值得注意:
用的是 checkpoint 里张量的实际大小,不是参数量 × 位宽。 因为量化之后不同张量的实际位宽不一样,均匀假设会算错。
MoE 只读被路由到的专家。 top-8 / 256 专家,意味着每步只读 1/32 的专家权重。这是 MoE 模型 decode 能跑得动的原因。
LM head 在大词表下是个大头。 文档里说它常常占总字节的 10–25%。这个后面会讲为什么它重要。
KV 会随上下文线性增长。 1K 上下文时它可以忽略,256K 上下文时它就是主导项。
作者的完整算例
ceilings.md 里有一个非常完整的例子,我把它完整复现一遍,因为这是理解这套方法的最好入口。
硬件(实测,非规格表):
- 115 GB/s 拷贝带宽,跑在 64GB LPDDR5X 上(规格是 153.6 GB/s)
- 35.8 TFLOPS FP16 @ 4096³,到 8192³ 掉到 20 TFLOPS
模型: Ornith-1.5-35B-A3B(Qwen3.5-MoE 混合架构),EXL3 4 bpw
40 层 = 30 层 GDN 线性注意力 + 10 层全注意力,256 个专家,top-8。
| 组件 | GB / 每个目标 token |
|---|---|
| 路由专家:16.26 GB × 8/256 | 0.508 |
| 稠密部分:GDN 0.515 + 全注意力 0.137 + 共享专家 0.064 + router 0.042 | 0.758 |
| LM head(6-bit,248K 词表) | 0.382 |
| 合计 | 1.648 |
单用户 decode 天花板(按 115 GB/s):
| 模式 | 每个产出 token 的 GB | 天花板 |
|---|---|---|
| 不做投机 | 1.68 | 68 tok/s |
| 1 个 MTP draft,完整 draft head,a = 1.85 | 1.38 | 83 tok/s |
| 1 个 draft,剪枝到 32K 词表的 draft head | 1.19 | 97 tok/s |
| 2 个 draft,a ≈ 2.5 | 1.11 | ~103 tok/s |
看清楚这张表的最后两行:
剪枝 draft head 带来的提升,比多加一个 draft 更大。
原因很直白:draft head 是要被每个 draft step 完整读一遍的,一个 248K 词表的 LM head 非常大。作者的说法是剪枝后的 draft head “about 8× fewer head bytes”。而多一个 draft 的收益,取决于接受率。
三、核心思想二:投机解码的关键不在接受率,在每步成本
几乎所有关于投机解码的文章都在讲” 接受率”。这个 Skill 直接指出了一个更重要的点。
tok/s = a ÷ step_time
接受率 a 只是分母的一半。如果 step_time 同时变大,高接受率完全可能被抵消。
levers.md 里有个非常典型的例子:
一个 7-token 的 draft 被接受了 3.26,MTP 的接受率是 2.85—— 看起来 MTP 更差。但那个 7-token draft 实际运行慢 11–14%。
剪枝 draft LM head 的实测效果
这是我认为整个仓库最有价值的单条技巧。
原理:draft 模型每步要生成候选 token,要过它自己的 LM head。词表大到几十万时,这个 head 的读取量非常可观。但实际上 draft 的候选绝大多数落在词表的高频区域。
做法:把 draft head 的词表裁剪成只保留最常用的块。目标模型仍然对完整词表做 verify,所以输出完全不变。
实测收益:
- Intel Arc Pro B70 / vLLM:c1 decode 37.9 → 48.2 tok/s(+27%),用的是 1,940 个块中的 512 个,覆盖率 98.6%
- Intel Arc B390 / SGLang:+14%,用 256 个块
+27% 这个数字,对应的开销是” 准备一个裁剪词表”。这性价比高得有点离谱。
最优 draft 长度随并发和上下文变化
这条也很反直觉:
- B70:k=4 在 c1 最优,k=3 在 c4 最优,k=2 在 c16 最优(+11%,因为能塞下更多流)
- B390 在 128K 上下文:1 个 draft 跑 29.6 tok/s,3 个 draft 只有 15.5 tok/s—— 但 3 个 draft 在短上下文下反而赢
所以必须按 workload 扫 draft 长度,不能用别人的最优值。
投机解码有时候是负优化
文档里也明确说了这种情况:
- Apple M4:3 个 MTP draft 让速度从 6.35 掉到 3.25 tok/s
- llama.cpp MTP 在难 prompt 上:36.7 vs 45.4(不开反而更快)
原因:带宽紧张的设备上,draft 的额外字节读取代价超过了接受率带来的收益。
verify 必须走 decode 路径
还有一条实现层面的坑,很有代表性:
把 k-query 的 verify 发给 prefill kernel,会让 step time 每 1K 上下文增长 3.5 ms(16K 上下文时从 47 ms 涨到 104 ms)。改成每行当 decode query 跑之后:SGLang B70 的 c1 从 75.7(vLLM)变成 82.6 tok/s。
还有” 把 sampler 留在 GPU 上”:CPU sampler 每 step 大约多 3 ms,移到 GPU 后 B390 的 c1 涨了 10%。
四、核心思想三:噪声控制 —— 为什么你的” 优化” 经常是假的
这是我觉得整个仓库价值最高的部分,因为它解决的是方法论问题,不是工具问题。
单次运行的噪声是 ±5–10%
methodology.md 开头就是这句。然后它列出了所有噪声来源:
- 温度和时钟:跑久了降频
- 供电:笔记本用电池、或平衡模式跑,慢 8–10%
- 后台 CPU 负载:一台带 RTX 4080 的笔记本在轻微 CPU 负载下从 107 → 75 tok/s
- prompt 内容:接受率本来就跟文本类型强相关
我前文说的那个” 基线被污染” 的经历,本质就是最后这条的变体。
三条硬规则
规则一:≥6 次采样取中位数,不是最大值也不是单次。
规则二:交叉对照,控制 — 候选 — 控制。
这个设计的精髓在于 —— 候选只跟它的邻居比。文档里给出的理由非常硬:
一个小时的漂移都可能超过你正在测的效应。同一个配置相隔一小时测出 53.8 和 49.5。
所以流程是 control → candidate → control,候选必须同时打败左右两个 control。如果只有中间那次特别好,说明是漂移不是效果。
这在统计上叫 randomized block design 的简化版,我做数值优化的时候见过同样的思路,但推理调优领域很少有人这么干。
规则三:固定环境,并且让工具拒绝在环境不对时运行。
bench.py 里有个 require_ac 配置项:
1 | def on_ac(): |
而且跑完还会再检查一次,电池状态下跑的会被打上 ON_BATTERY 标记并判定 ok=False。
1 | def finish(res, flags, watch): |
跑完检查环境状态,如果变了就作废这次运行 —— 这是我以前完全不会做的事。
跨引擎比较的正确姿势
同一天、同一张卡、背靠背跑。只有当 median (B)/median (A) 的 bootstrap 95% CI 下界大于 1.0,才接受”B 更快”。
一个反常识的结论
接受率更高也可能更慢。
前面提过 7-token draft 那个例子。而贪心等价性检查也可能因为数值差异而分叉:
开 / 关投机解码的贪心结果可能因为数值而分叉:M=1 和 M=k 行用了不同的 kernel。在分叉点比较 logits 再下结论。top-2 平局 0.016 nats 不是 bug。
这种细节,只有真踩过坑的人才会写下来。
五、核心思想四:先算天花板,能让你 early 止损
这是我个人最认同的一个设计。
如果你想要 100 tok/s,而理论天花板只有 68 tok/s,那这个目标从一开始就不可能。知道了这一点,你可以直接告诉用户” 你的目标超过了物理极限”,省下几小时的无效调优。
反过来,如果天花板是 103,你跑到了 53,那你就知道还有一半空间,而且 ——
SKILL.md 里说要用百分比来报告进度:
Report progress as a percentage of the practical ceiling.
作者自己的算例就是这么做的。B390 那次:
- Decode:算出来 100 tok/s 只有在两个有效 draft 的情况下才够得着。但这个模型的 draft head 在 depth 2 接受率只有~14%,所以现实目标是~88–97 tok/s。实际跑到~55%。剩下的差距是量化 GEMV kernel 效率(verify graph 里有效带宽~76 GB/s)。
- Prefill 256K:实用天花板~670–684 tok/s,实际 628 tok/s。基本贴着天花板了。
注意这里的表述方式:不吹” 我们优化到了 628 tok/s”,而是” 我们在天花板的 94%,长上下文 prefill 已经接近极限,不值得再花时间”。
能说出” 这里不值得再优化了”,比多榨 3% 更有价值。
天花板计算器
对应 scripts/ceiling.py,纯标准库:
1 | python3 scripts/ceiling.py skills/inference-optimisation/examples/ceiling-ornith-b390.json |
它读的 JSON 长这样:
1 | {"bandwidth_gbs": 115, "peak_tflops": 36, "mfu": 0.5, "dense_gb": 0.758, "experts_gb": 16.26, "top_k": 8, "n_experts": 256, "lm_head_gb": 0.382, |
输出会列出各个并发度、各个上下文长度下,不同 draft 数量对应的聚合 decode 天花板,以及 prefill 天花板和 KV 占用。
几个参数解释一下:mfu 是 model FLOPs utilization,脚本默认按 0.5 算(文档说”practical ceilings assume about 100% of measured bandwidth and about 50% of measured peak FLOPs”);experts_gb 对稠密模型设 0;draft_head_gb 记得填裁剪后的量,不然天花板会算低。
六、bench.py:一个不依赖任何第三方库的基准台架
262 行,纯标准库(json, os, random, statistics, string, subprocess, sys, threading, time, urllib.request + concurrent.futures)。不装 openai SDK、不装 torch,往目标机器上 scp 过去就能跑。
这点我觉得很重要 —— 要在一个已经跑满 90% 显存的服务器上做基准,你不一定还能装得下一个 torch 依赖树。
它测什么
1 | Measurements (all token counts come from the server's usage stats, never from streamed chunks): |
用法
1 | python3 bench.py run configs/NAME.json [--long N] [--skip-cN] [--reps 6] |
关键实现细节
token 数一律取服务器 usage stats,不数流式 chunk。
这是文档反复强调的一条,因为开着投机解码时,一个 SSE chunk 里可能有多个 token:
1 | body = {"model": self.cfg["model"], "messages": [{"role": "user", "content": prompt}], |
decode 速度的计算方式:
1 | decode = (ct - 1) / (t_end - t_first) if ct and ct > 1 and t_end > t_first else None |
即” 第一个 token 之后的 completion token 数 ÷ 首个 token 到结束的时间”。这排掉了 TTFT 的干扰。
prompt 用固定面板,不随机。
1 | PROMPTS = [ # fixed panel: acceptance and speed depend on content, so never randomise these |
注释直接写明原因:接受率和速度依赖内容,随机化就没法比较。文档里提到用随机 prompt 会让接受率从 2.4 漂到 3.7。
每轮生成唯一文档,绕开 prefix cache。
1 | def document(tokens, seed, needles=3): |
注意 time.time_ns() 那个随机前缀 —— 明确为了击穿 prefix caching。这对应 methodology 里那条:”Build prompts before the clock starts. Make them unique per run, with a random prefix, so prefix caching cannot hit, unless you are measuring cache hits deliberately.”
同时插入的 needle 是长上下文检索正确性的验证手段。
输出退化检测。
1 | def looping(text, n=8, thresh=0.5): |
文档里解释了为什么需要它:
一个 117 tok/s 的” 纪录”,实际是模型在循环输出一个编号列表。
这正是我前面说的” 速度很快但结果没用” 的典型。
内存看门狗。 MemWatch 是个后台线程,按 interval_s 采样真实占用,超了 cap_gib 就杀掉服务器并把该次运行标记为失败。
配置长什么样
1 | { |
几个设计细节:
launch和stop都可选。省略launch就是直接测一个已经在跑的服务器(config-existing-server.json就是这种)。stop里带abort_request然后 sleep 5 再停容器。 这对应SKILL.md里那条硬规则:”Never force-kill a server mid-batch. A forced stop mid-prefill has caused GPU driver faults.”(gotchas.md里也有:强制停止容器导致 Intel xe GPU page fault)"my-engine-image@sha256:..."—— 镜像按 digest 固定,不是 tag。这跟 publishing.md 的要求一致。- 没有
launch就不测 startup,因为服务器不是这次启动的。
七、queue.sh:防止两个任务抢同一块卡
1 |
|
核心就一行:flock 9 对 /tmp/inference-hillclimb.lock 加文件锁。全局的,不只是进程内的。所以哪怕你同时开两个终端、两个 Agent 在同一台机器上调优,也不会互相踩。
这条对应 gotchas.md 里的警告:
同一块 GPU 上跑第二个引擎,或者有个野 benchmark 还在跑,会悄悄把结果砍一半,或者两边都崩。
另外它还用 setsid nohup ... & disown 的方式支持 detach,让长队列在 Agent 重启后还能活着。这个细节对 Agent 场景特别重要 ——gotchas.md 里专门写了”Agent 重启会杀掉子进程”。
八、mem.sh:统一内存机器上的真实占用
这是我觉得被严重低估的一个问题。
在 Apple Silicon、Intel/AMD 核显、GB10/Spark 这类统一内存设备上,GPU 分配绕过 cgroup 记账。
methodology.md 里的例子:
MemAvailable 的差值显示 14 GiB,真实占用是 29.4 GiB。
差了整整一倍。这种情况下你的内存看门狗就是个摆设。
解法是直接读驱动的 residency 计数:
1 | declare -A seen |
按 drm-client-id 去重(同一个 client 可能多 fd),累加 drm-resident-*,再加上 cgroup 的 anon。
NVIDIA 离散卡走另一条路,用 nvidia-smi --query-compute-apps 查容器内进程占用的显存。
脚本注释里还提醒:读别的用户的 fdinfo 需要 root,要么给免密 sudo,要么以 root 跑,并且不要把密码写进脚本。
九、官方给出的实测结果
README 里有一张表,把作者跑过的所有 hill-climb 汇总了。我挑重点列几个(数据来自 README,未做任何改动):
| 硬件 | 模型 / 量化 / 引擎 | 优化前 → 优化后 |
|---|---|---|
| Intel Arc B390 iGPU(笔记本,64GB LPDDR5X,~115 GB/s) | Ornith-1.5-35B-A3B,EXL3 4 bpw,SGLang XPU + MTP | Decode 1 用户:43.6 → 53 tok/s(中位数) Decode 4 用户:84.7 → 103 tok/s Prefill 32K:1,037 → 1,660 tok/s Prefill 256K:297 → 628 tok/s(2.1×) KV cache:264K tokens → 4 × 256K 启动:113 → 43 s |
| Intel Arc Pro B70 | Qwen3.8-27B,EXL3 4 bpw,vLLM + 自研 XPU kernel | Decode:91.2 tok/s(1 用户),365(16 用户) 同卡 llama.cpp Q4_K_M:25.0 Prefill 4K/32K/128K/254K:1,654/1,434/928/650 → 2,421/2,259/1,415/911 Agent session 回放:193 → 147 s |
| Intel Arc Pro B70 | 同模型,SGLang + 相同 kernel | Decode 1 用户:82.6 tok/s,同日同卡 vLLM 为 75.7 |
| RTX 3090 | Qwen3.8-27B EXL3 3 bpw + MTP | 96.2 tok/s(文本)/ 141.1(代码),1 用户 |
| RTX 3090 | Qwen3.6-35B-A3B EXL3 3 bpw + MTP | 251.7 / 357.9 tok/s,1 用户 |
| 4× H200 NVL | DeepSeek-V4.1-Flash,vLLM + 投机解码 | 负载下崩溃 → 229.1 tok/s decode,17,546 tok/s prefill;全部六项门禁通过 |
几个我特别想指出的:
B390 那一行里,KV cache 从 264K tokens 变成 4 × 256K。 这个提升不是靠加显存,是靠调整引擎的池大小。而且 levers.md 里写明这个结果是用” 并发满长度 soak” 验证过的 ——4 条流、36.8 GiB 峰值、4/4 needle 全部命中。
B70 上 vLLM 91.2 tok/s,同一张卡上 llama.cpp 只有 25.0。 差 3.6 倍。这说明引擎选型的影响可能远大于调参。
RTX 3090 上代码比散文快(141.1 vs 96.2)。文档解释了原因:接受率跟内容强相关,代码和贪心解码的 draft 接受率高得多。
H200 那行从” 负载下崩溃” 到 229.1 tok/s。 起点是崩的,说明这套流程的价值不只是提速,还有救活一个跑不起来的服务。
所有原始数据都放在作者的 local-ai-registry 仓库里,B390 那次有完整 hill-climb 日志(PR #453)。
十、调优杠杆清单:按性价比排序
SKILL.md 给了一个明确的顺序,原则是便宜的先来:
1. 持久化 JIT / 编译 /graph 缓存(启动时间 −50–70%)
这个收益很夸张但很容易理解:编译缓存不跨重启保留的话,每次启动都要重新编译 kernel。
- Arc B390 / SGLang:113 s → 43 s
- 4× RTX PRO 6000 /vLLM:后续启动从约 22 分钟降到 7 分钟
配套的还有 TORCHINDUCTOR_COMPILE_THREADS=1—— 编译 worker 会占约 6 GiB 瞬时内存,内存紧张的机器上要限制。
还有个 vLLM 专属的坑:
mmap 权重加载在某些文件系统上只有约 60 MB/s:27 GB 跑了 26 分钟。
--safetensors-load-strategy eager把它降到几秒。
2. Decode graph 捕获(CUDA/XPU graph)
- Arc Pro B70:14.4 → 28.4 tok/s
- SGLang XPU:16 → 32 tok/s
- vLLM INT4:11 → 27 tok/s
基本是翻倍。
3. 投机解码(前面详细讲过了)
4. 并发与 KV 容量
这条有几个反直觉的点:
混合 SSM/GDN/Mamba 模型,限制并发的是 state slot 和 page size,不是 KV token 数。
SGLang 拒绝调度超过 1 个请求,直到--max-mamba-cache-size被调大。
以及:
保持 vLLM 精确的 1,600-token block,而不是向上取整到 2,048,c16 的并发流从 10 提到 14,聚合吞吐 +17%。
prefix caching 必须显式打开,有些引擎对混合模型会静默关闭它:
66K-token 的第二轮 TTFT:36 s → 0.45 s。
5. Prefill
- chunk size 是吞吐和 decode 卡顿的权衡:B70 上 8,192 → 2,048,把最坏卡顿从 7.1 s 降到 1.95 s,代价是 decode −4%
- 先换更快的 attention 库,别急着自己写:oneDNN 融合 SDPA 比 FA2 快 7–18%;手写的 flash attention 只跑到 48 vs 61 TFLOPS
- int8/fp8 prefill GEMM(标注为有损权衡):Hadamard 旋转域下每行一个 scale 就够,所有 linear 快 1.89×,NLL +0.17%,top-1 一致率 97.2%,decode 保持 bit-exact
6. kernel 线程数和 tile size
为一张卡调的默认值,搬到另一张卡就是错的。
B70:4096 → 1024 线程,代码 c1 从 48.5 到 56.9。
7. 改 kernel(最后才做)
只有配置杠杆都到平台期了才动。
而且有一条经验值得单独拎出来:
在 graph 之下,融合小 kernel 很少有用。 B390 上三次融合尝试(融合 GEMV、共享专家融合、折叠注意力)都是正确的,收益是 0%。时间在主 kernel 里面。
十一、诚实说说它的局限
这个仓库质量很高,但我不打算把它吹成银弹。下面几点是我读完源码和文档后认为的真实限制。
1. 它不产生新的性能,它产生可信的性能
整个仓库没有一行 kernel 优化代码,也没有一个” 一键最优启动脚本”。它提供的是流程和工具。
如果你期待的是”clone 下来就有 2 倍加速”,那会失望。真实的收益是:你调出来的数字你敢信了,以及你不会把噪声当成收益。
作者自己在 README 里也说,这是”we actually got these speedups” 的方法记录,不是 flag 清单。
2. 仓库很新,实践样本还少
创建于 2026-11-16,到我写这篇为止只有四天,6 个 open issue。所有引用的性能数字都来自作者自己的机器和几个合作仓库(local-ai-registry、trellis-serve、qwen-serve)。
跨硬件、跨模型的可重复性还没有被第三方独立验证过。 这是个必须诚实说明的点。
3. 高度依赖具体的引擎版本
gotchas.md 开头就写了:”Versions matter; re-check on newer releases.”(版本很重要,升级后要重新检查)
文档里大量条目是特定版本的行为,比如 SGLang XPU 后端 0.5.x 的五个具体 bug。这些 bug 被修掉之后,相关的 workaround 就没必要了,甚至可能有害。
4. 门槛比想象中高
这套流程要求你有:
- 一台能折腾的机器(要 root 权限读 DRM residency,要能改电源策略)
- 至少几小时的连续时间(交叉对照 + 6 次采样 + 稳定性门禁,单轮就不快)
- 一个能管理长任务的 Agent 或脚本环境
这不是” 五分钟搞定的调参技巧”,是几天起步的工程项目。
对个人用户来说,收益上限可能撑不起这个成本。
5. 硬规则有真实的副作用
其中几条会实际影响你的系统:
- 要求独占 GPU(会打断你其他任务)
- 要求固定电源策略(笔记本用户会注意到)
bench.py会停止并重启你的服务器(stop+launch)- 要求” 不要中途强杀服务器”
跑之前要先确认你的服务器上没有正在服务的请求。
6. 内存看门狗在部分环境不可用
mem.sh 要读 /proc/<pid>/fdinfo,读别的用户的进程需要 root。gotchas.md 里也提到 Intel XPU 上 torch.topk 在宽输入下会 segfault(约 2–8K 以上)—— 虽然那不是本项目的问题,但说明这类底层环境的水很深。
十二、跟同类东西比一下
对比 llm-performance /genai-bench 这类通用 benchmark 工具
那些工具测的是” 给定配置下模型跑多快”,是测量工具。
这个项目测完之后还会告诉你 **” 这个结果可不可信”**—— 样本数、中位数还是单次、交叉对照有没有过、内存是不是真实的、有没有在跑偏。
差别不在功能,在可信度保证。
对比各家引擎的官方调优文档
vLLM、SGLang、llama.cpp 的官方文档都会告诉你有哪些参数、什么时候用哪个。问题是:
- 它们不告诉你在你这台机器上哪个参数最优
- 它们不告诉你你的基线测对了吗
- 它们不会告诉你” 这个参数在 256K 上下文下失效”
这个项目补的正是这一层:在具体硬件上的具体结论 + 得出结论的可靠方法。
对比别人的” 优化配置” 仓库
这类仓库通常给一张参数表。问题是那张表没有测量条件 —— 多少样本、冷的还是热的、中位数还是最好的一次、thinking 开还是开。
这个项目最核心的贡献之一就是强制标注测量条件,还专门要求在 README 里说明哪组数字来自哪个 harness。
对比 local-ai-registry(作者的另一个项目)
两者是配套的:
local-ai-registry(324 star):每台机器一份验证过的 recipe,附上证据。是结果库。inference-optimisation-skill(1259 star):怎么在你自己机器上得到 recipe。是方法论。
作者的分工很清楚:Skill 负责爬坡,Registry 负责沉淀和复用。
十三、适合谁 / 不适合谁
适合
你要在一台固定机器上长期跑本地大模型,需要压榨出可用性能。
这个场景收益最大 —— 硬件固定、模型固定、可以跑几小时的对照实验。
你在做推理引擎、量化格式或 kernel 相关的工作。levers.md 里那些” 在 graph 下融合小 kernel 收益 0%”、”AMD B70 上 stride-3 寄存器区域变成逐元素搬移” 级别的经验,是论文里不会写的东西。
你需要发布可复现的调优配方。publishing.md 的六道验收门禁 + pin + 干净构建 + A/B 证明,对应的是” 我的配方别人能复现” 这个诉求。
你在做 Agentic 编码,Claude Code 之类。
它本来就是设计成 SKILL.md 格式的 Agent Skill。
不适合
你只是想跑通一个模型,不需要优化。
直接装 ollama、LM Studio,用默认参数就行。
你没有一块能连续占用几小时的机器。
交叉对照、6 次采样、稳定性门禁,全都需要连续时间。
你需要开箱即用的” 一键最优配置”。
这个仓库给不了,也给不了任何人。
你在做的是云上多租户推理服务。
这个 Skill 是面向单机单租户优化的,强调独占 GPU、固定环境。分布式推理的调度、容错、弹性伸缩,基本不在覆盖范围内。
十四、怎么用起来
安装
1 | git clone https://github.com/sybil-solutions/inference-optimisation-skill |
其他 Agent 直接指向 skills/inference-optimisation/SKILL.md,或者把 PROMPT.md 贴成任务提示。
不用 Agent 也能跑
1 | S=skills/inference-optimisation |
给 Agent 的任务模板
PROMPT.md 是个填空模板,字段包括:模型 + 量化、引擎、当前启动命令、硬件、要最大化的指标(按优先级排)、硬约束(内存上限、必须稳定的上下文长度、并发数、质量要求是” 只允许无损” 还是” 允许标注的有损权衡”)。
关键的一句是 “Stretch goal from the user”:
Check it against the ceiling and report honestly.
把用户的期望目标和天花板做对比,诚实汇报。这就是整套东西的落点 —— 不是帮你吹出更高的数字,是帮你知道真实的天花板在哪。
十五、我的实际建议
如果你是第一次认真做本地推理调优,我建议按这个顺序:
第一步,先装 bench.py,测一遍你现在的配置。
不调任何参数,就先测。用你真实的 prompt(不是玩具 prompt),让 require_ac 开着,让它跑 6 次取中位数。
这一步大概率会让你发现” 我以为的基线” 和” 实际的基线” 有出入。很多人卡在这一步就明白了。
第二步,算天花板。
把 ceiling.py 的 JSON 按你机器和模型填了(注意 experts_gb 稠密模型填 0,draft_head_gb 填裁剪后的量)。看看你的目标到底在不在物理可行范围内。
第三步,只做两件事:持久化缓存 + decode graph。
这两个在 levers.md 里排最前面,因为收益最确定、副作用最小、跟硬件几乎无关。启动时间 −50–70%、decode 接近翻倍,基本是白捡的。
第四步,如果模型支持,剪枝 draft head。
+14% 到 +27%,而且输出不变。性价比极高。
第五步,才进入投机解码、并发 KV、prefill 这些需要按 workload 调的。
而且记住文档里那句:按你的并发数和上下文扫 draft 长度,别抄别人的。
最后,建立你自己的 PLAN.md。
哪怕只是一行”2026-11-20,chunked_prefill 4096→2048,c1 从 38.2→37.6(−1.6%,在噪声内),prefill 32K 从 1200→1380(+15%,采纳)”。
记下失败比记下成功更有价值。 文档里明确说了:”Most of the value in PLAN.md is the list of things that did not work and why.”
这样半年后你不用重复踩坑,也不用再像我一样,重新发现自己的基线是脏的。
最后
这个仓库 32KB,四个脚本,纯标准库,MIT 协议,创建四天 1259 star。
它没有魔法。它做的是把一件大家都凭直觉在做、但直觉经常靠不住的事 —— 性能调优 —— 变成可测量、可对照、可复现、可发布的工程流程。
里面的每一条建议背后都有真实硬件上的实测数据和原始日志链接。文档里明确标注了哪些是通用的 [G],哪些只在某个技术栈上见过 [S: stack]。哪些数字来自验收门禁、哪些来自爬坡 harness,必须分开标注。哪些结论没验证过,作者自己在 PROMPT.md 里就写了一条 “What you did not verify.”
在一个到处都是” 我调了调快了 30%” 的领域里,愿意把方法、边界和失败都写下来的东西,是稀缺的。
如果你也在折腾本地模型,别再抄参数表了。先测,再算,再改。
仓库地址: https://github.com/sybil-solutions/inference-optimisation-skill
许可证: MIT
Star 数: 1259(截至 2026-11-20,GitHub API 查证)
作者其他项目: local-ai-registry(324 star,调优配方与证据库)、trellis-serve、qwen-serve