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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
sybil-solutions/inference-optimisation-skill
├── LICENSE MIT
├── README.md 结果总览 + 快速上手
├── PROMPT.md 给 Agent 用的任务模板
└── skills/inference-optimisation/
├── SKILL.md 主流程(166 行)
├── references/
│ ├── ceilings.md 理论天花板怎么算(含完整算例)
│ ├── methodology.md 测量方法论与统计陷阱
│ ├── levers.md 各类优化杠杆及实测证据
│ ├── gotchas.md 各引擎/硬件的具体坑
│ └── publishing.md 调优结果的发布验收流程
├── scripts/
│ ├── bench.py 基准测试台架(262 行,纯标准库)
│ ├── ceiling.py 天花板计算器
│ ├── queue.sh 串行 GPU 队列
│ └── mem.sh 真实内存占用探针
└── examples/ 示例配置

四个数字先摆出来(截至 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
2
3
4
5
B_target = dense_weight_bytes                    # 注意力/线性注意力、共享专家、router、norms
+ expert_bytes × (top_k / n_experts) # MoE:只读被路由到的专家
+ lm_head_bytes # 大词表下常常占总字节的 10–25%!
+ kv_bytes_per_token × context # 随上下文增长,长上下文下占主导
+ recurrent_state_bytes × 2 # SSM/GDN 混合模型的状态读+写

然后除以实测带宽,就是单用户 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
2
3
4
5
6
7
8
9
def on_ac():
try:
if sys.platform == "darwin":
return "AC Power" in subprocess.run(["pmset", "-g", "batt"], capture_output=True, text=True).stdout
import glob
vals = [open(p).read().strip() for p in glob.glob("/sys/class/power_supply/*/online")]
return not vals or "1" in vals
except Exception:
return True

而且跑完还会再检查一次,电池状态下跑的会被打上 ON_BATTERY 标记并判定 ok=False。

1
2
3
4
5
6
7
8
9
10
11
12
13
def finish(res, flags, watch):
if watch:
watch.stop.set()
res["mem_peak_gib"] = round(watch.peak / 2**30, 2)
if watch.tripped:
flags.append("MEM_CAP"); res["ok"] = False
if not on_ac():
flags.append("ON_BATTERY"); res["ok"] = False
res["flags"] = sorted(set(flags))
with open("ledger.jsonl", "a") as f:
f.write(json.dumps(res) + "\n")
print(json.dumps(res, indent=1))
return res

跑完检查环境状态,如果变了就作废这次运行 —— 这是我以前完全不会做的事。

跨引擎比较的正确姿势

同一天、同一张卡、背靠背跑。只有当 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
2
3
{"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,
"active_params_b": 2.43, "attn_layers": 10, "attn_heads": 16, "head_dim": 256, "kv_bytes_per_token": 10240, "draft_layer_gb": 0.03, "draft_head_gb": 0.05,
"spec": [{"drafts": 0, "accept": 1.0}, {"drafts": 1, "accept": 1.74}, {"drafts": 2, "accept": 2.5}], "contexts": [4096, 32768, 131072, 262144], "concurrency": [1, 4]}

输出会列出各个并发度、各个上下文长度下,不同 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
2
3
4
Measurements (all token counts come from the server's usage stats, never from streamed chunks):
startup_s, ttft_short_ms, c1_decode (median of --reps), c1_all, cN_aggregate (wall clock), cN_per_stream,
prefill_<L> (prompt_tokens / TTFT on a unique cold prompt), long-context needle retrieval (--long),
mem_peak_gib, flags (LOOP, REQ_FAIL, ON_BATTERY, MEM_CAP).

用法

1
2
python3 bench.py run configs/NAME.json [--long N] [--skip-cN] [--reps 6]
python3 bench.py show [ledger.jsonl]

关键实现细节

token 数一律取服务器 usage stats,不数流式 chunk。

这是文档反复强调的一条,因为开着投机解码时,一个 SSE chunk 里可能有多个 token:

1
2
3
body = {"model": self.cfg["model"], "messages": [{"role": "user", "content": prompt}],
"max_tokens": max_tokens, "stream": True, "stream_options": {"include_usage": True},
"temperature": self.cfg.get("temperature", 0.6) if temperature is None else temperature}

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
2
3
4
5
6
7
8
PROMPTS = [  # fixed panel: acceptance and speed depend on content, so never randomise these
"Write a Python implementation of an LRU cache with O(1) get and put, with docstrings and tests.",
"Explain, step by step, how TCP congestion control works, including slow start and fast recovery.",
"Write a short story (about 600 words) about a lighthouse keeper who finds a message in a bottle.",
"Compare B-trees and LSM-trees for a write-heavy database workload. Use a table and give a recommendation.",
"Write a bash script that backs up a directory to a timestamped tar.gz and keeps only the last 7 backups.",
"Summarise the causes and consequences of the 1929 stock market crash in five paragraphs.",
]

注释直接写明原因:接受率和速度依赖内容,随机化就没法比较。文档里提到用随机 prompt 会让接受率从 2.4 漂到 3.7。

每轮生成唯一文档,绕开 prefix cache。

1
2
3
4
5
6
7
8
9
10
11
12
def document(tokens, seed, needles=3):
"""Unique filler document of ~`tokens` tokens with `needles` retrieval codes at spread depths."""
rng = random.Random(seed)
n_words = int(tokens / 1.6)
words = [rng.choice(WORDS) for _ in range(n_words)]
codes = ["".join(rng.choices(string.ascii_uppercase + string.digits, k=8)) for _ in range(needles)]
for i, c in enumerate(codes):
pos = int(n_words * (i + 1) / (needles + 1))
words.insert(pos, f". The secret code number {i + 1} is {c}. ")
head = f"[doc {seed}-{time.time_ns()}] " # defeats prefix caching
q = "\n\nList every secret code number and its value that appears in the document above. Answer only with the codes."
return head + " ".join(words) + q, codes

注意 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
2
3
4
5
def looping(text, n=8, thresh=0.5):
"""Degenerate-output flag: share of repeated word n-grams."""
w = text.split()
grams = [tuple(w[i:i + n]) for i in range(max(0, len(w) - n))]
return len(grams) > 50 and 1 - len(set(grams)) / len(grams) > thresh

文档里解释了为什么需要它:

一个 117 tok/s 的” 纪录”,实际是模型在循环输出一个编号列表。

这正是我前面说的” 速度很快但结果没用” 的典型。

内存看门狗。 MemWatch 是个后台线程,按 interval_s 采样真实占用,超了 cap_gib 就杀掉服务器并把该次运行标记为失败。

配置长什么样

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
"name": "ctl-a",
"base_url": "http://127.0.0.1:8000",
"model": "my-model",
"launch": ["docker", "run", "-d", "--name", "llm", "--device", "/dev/dri", "--shm-size", "2g",
"-p", "127.0.0.1:8000:8000",
"-v", "/path/to/weights:/models:ro",
"-v", "/path/to/persistent-cache:/root/.cache",
"my-engine-image@sha256:...",
"python3", "-m", "sglang.launch_server", "--model-path", "/models", "--served-model-name", "my-model",
"--host", "0.0.0.0", "--port", "8000", "--context-length", "262144",
"--max-running-requests", "4", "--chunked-prefill-size", "4096",
"--speculative-algorithm", "NEXTN", "--speculative-num-steps", "1",
"--speculative-eagle-topk", "1", "--speculative-num-draft-tokens", "2"],
"stop": ["bash", "-c", "curl -s -X POST localhost:8000/abort_request -d '{\"abort_all\":true}' -H 'Content-Type: application/json'; sleep 5; docker stop -t 60 llm; docker rm -f llm"],
"health_timeout_s": 900,
"concurrency": 4,
"prefill_lengths": [4096, 32768],
"extra_body": {"chat_template_kwargs": {"enable_thinking": false}},
"temperature": 0.6,
"memory": {"cap_gib": 46, "probe": ["sudo", "-n", "bash", "scripts/mem.sh", "llm", "unified"], "interval_s": 3},
"require_ac": true
}

几个设计细节:

  • 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
2
3
4
5
6
7
8
9
10
11
12
13
#!/usr/bin/env bash
# Serialized GPU queue: runs bench.py on each config in order, one GPU job at a time across all callers.
# queue.sh ctl-a cand ctl-b # interleave controls around each candidate
# BENCH_FLAGS="--long 131072" queue.sh cand
# Detach long queues so they survive agent/terminal restarts:
# setsid nohup bash queue.sh ctl-a cand ctl-b > queue.log 2>&1 < /dev/null & disown
LOCK=${QUEUE_LOCK:-/tmp/inference-hillclimb.lock}
exec 9>"$LOCK"; flock 9
for n in "$@"; do
python3 "${BENCH:-$(dirname "$0")/bench.py}" run "configs/$n.json" ${BENCH_FLAGS:-} > "runs-$n.log" 2>&1
echo "done $n: $(tail -c 300 "runs-$n.log" | tr '\n' ' ' | cut -c1-200)"
done
echo QUEUE_DONE "$@"

核心就一行: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
2
3
4
5
6
7
8
declare -A seen
for p in $pids; do
for f in /proc/"$p"/fdinfo/*; do
id=$(awk '/drm-client-id/{print $2}' "$f" 2>/dev/null) || continue
[ -z "$id" ] && continue; [ -n "${seen[$id]:-}" ] && continue; seen[$id]=1
kb=$(awk '/drm-resident-/{s+=$2} END{print s+0}' "$f"); gpu=$((gpu + kb * 1024))
done
done

按 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
2
3
git clone https://github.com/sybil-solutions/inference-optimisation-skill
mkdir -p ~/.claude/skills
cp -r inference-optimisation-skill/skills/inference-optimisation ~/.claude/skills/

其他 Agent 直接指向 skills/inference-optimisation/SKILL.md,或者把 PROMPT.md 贴成任务提示。

不用 Agent 也能跑

1
2
3
4
5
6
S=skills/inference-optimisation
python3 $S/scripts/ceiling.py $S/examples/ceiling-ornith-b390.json # ceilings
mkdir -p configs && cp $S/examples/config-existing-server.json configs/base.json # edit base_url/model
python3 $S/scripts/bench.py run configs/base.json --long 131072 # one run
bash $S/scripts/queue.sh base cand base # interleaved A/B
python3 $S/scripts/bench.py show # ledger table

给 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