所谓「让模型直接读写权重」，实际分工是这样的：调度模型（文中暂称 Astra，它的接口、上下文长度、可用工具以官方文档当前版本为准；没有它，任何能写代码、能执行脚本的模型都能顶上）负责读懂模型结构、生成脚本、解读评测结果；真正动权重的是 torch 和 safetensors。把这件事故意拆成一条可回滚的流水线：结构快照、定位候选参数、生成补丁、写回并校验、能力回归、副作用排查。
需要先说清楚：0.016% 是这条流水线里的「参数预算」约束，不是保证涨点的魔法比例。预算换成 0.005% 或 0.05%，流程一模一样，结果会不一样。下面按报错排查的方式来写，把整条流水线跑通过程中会撞上的坑逐条拆开。
报错现象
场景：本地有一份 Qwen 系列开源权重（规模、目录结构、分片数量以你下载的官方发布为准），目标是用极小的参数改动提升数学题表现。流程跑到一半，会撞上下面几类问题。
读结构阶段：
```
KeyError: 'model.layers.12.mlp.down_proj.weight'
```
或者：
```
safetensors_rust.SafetensorError: Error while deserializing header
```
写回后重新加载：
```
RuntimeError: Error(s) in loading state_dict for Qwen2ForCausalLM:
Missing key(s) in state_dict: "model.layers.0.self_attn.q_proj.weight", ...
Unexpected key(s) in state_dict: "layers.0.attn.wq.weight", ...
```
计算补丁时：
```
torch.OutOfMemoryError: CUDA out of memory.
RuntimeError: expected scalar type BFloat16 but found Float
```
评测阶段的表现则是另一类：
- 数学集正确率没变化，甚至下降；
- 输出开始复读，「因此因此因此因此……」停不下来；
- 通用对话明显变差，回答变短、拒答变多；
- 同一个 prompt 跑两次结果不同，根本没法判断改动是否有效。
影响范围：这些问题只发生在离线权重编辑流程里，不碰线上服务；但一旦把改后的权重推上线，所有走这个模型的业务都会受牵连，所以写回之前必须留好回滚路径。
可能原因
1. 层名与结构假设错。照着别的模型架构写死路径，或者手写正则没匹配上分片文件里的真实 key。Qwen 系列不同代的结构有差异（比如注意力的 q/k/v 是否带 bias），一切以 config.json 和权重文件里的真实 key 为准。
2. dtype 与设备不一致。在 float32 上算出来的增量直接赋给 bf16 权重，或者反过来；也可能一部分张量在 CPU、一部分在 GPU，赋值时被静默转换。
3. 参数预算算错。按「张量个数」而不是「元素个数」算比例，或者定位脚本一次选中整个 down_proj，实际改动量远超预期。
4. 写回不完整。分片 safetensors 只覆盖了一个 shard、index 文件没同步、进程 OOM 被杀导致文件写了一半。
5. 评测协议不一致。prompt 模板、few-shot 数量、答案抽取正则、max_new_tokens、采样参数在改动前后不同。
6. 定位用的数据与评测集重叠。拿评测题算梯度再去评测，涨点是假的。
7. 显存或内存不足，模型没完整加载就开始统计，结果本身不可信。
逐条排查与解决
原因 1：结构假设错
先打印真实结构，不要凭记忆写路径。
```bash
python - <<'PY'
import json, glob
cfg = json.load(open("Qwen/config.json"))
print("layers:", cfg.get("num_hidden_layers"))
print("hidden:", cfg.get("hidden_size"))
print("dtype:", cfg.get("torch_dtype"))
print("tie_word_embeddings:", cfg.get("tie_word_embeddings"))
for f in sorted(glob.glob("Qwen/*.safetensors.index.json")):
idx = json.load(open(f))["weight_map"]
keys = sorted(idx)
print(len(keys), "keys")
for k in keys[:15]:
print(" ", k, "->", idx[k])
PY
```
判断标准：打印出来的 key 是否都能被 ^model\.layers\.\d+\.(self_attn|mlp)\. 匹配上，层号范围是否等于 num_hidden_layers。对不上就说明路径写错了，改成「先枚举再匹配」的写法：
```python
import re
pat = re.compile(r"^model\.layers\.(\d+)\.(.+)\.weight$")
cands = [(int(m.group(1)), m.group(2), k) for k in state if (m := pat.match(k))]
```
原因 2：dtype 与 device
```python
w = model.model.layers[i].mlp.down_proj.weight
print(w.dtype, w.device, w.shape, w.requires_grad)
```
判断：如果 dtype 是 torch.bfloat16 而你算的 delta 是 torch.float32，赋值时会被静默截断精度。做法是增量统一在 float32 里算，写回前显式转换并断言：
```python
delta = delta_fp32.to(w.dtype)
assert delta.dtype == w.dtype and delta.shape == w.shape
with torch.no_grad():
w.add_(delta)
assert torch.isfinite(w).all(), "权重出现 NaN/Inf，立即回滚"
```
原因 3：参数预算算错
把「改了多少元素 / 总参数」打印出来，别靠估。
```python
total = sum(p.numel() for p in model.parameters())
edited = sum(d.numel() for d in deltas.values())
print(f"edited={edited} total={total} ratio={edited/total:.6%}")
```
0.016% 就是 1.6e-4。以 7B 量级的模型为例，大约是一百多万个参数，量级上相当于若干个小秩低秩矩阵，或者几百条通道。如果打印出来是 5%、20%，说明选层逻辑把整层都框进去了，回头收紧候选集。
原因 4：写回不完整
写回后别直接进评测，先做一致性校验：非目标张量必须逐一相等，目标张量的差异应该在预期量级。
```python
from safetensors.torch import load_file
before = load_file("Qwen/orig.safetensors") # 分片模型按 shard 逐个加载
after = load_file("Qwen/patched.safetensors")
for k in before:
if k in deltas_keys:
continue
assert torch.equal(before[k], after[k]), f"{k} 被意外修改"
for k in deltas_keys:
diff = (after[k].float() - before[k].float()).norm().item()
print(k, diff)
```
分片模型还要确认 index 里 weight_map 指向的文件全部更新到位。比较稳妥的做法是整份目录复制一份再改，不原地覆盖。
原因 5：评测协议不一致
固定这几项：greedy 解码、统一的 max_new_tokens、统一 prompt 模板、统一答案抽取规则、固定随机种子。把评测配置单独存成文件一起归档。
```python
gen = dict(do_sample=False, max_new_tokens=512, temperature=None, top_p=None)
```
判断：同一份权重跑两次评测，结果必须完全一致；不一致就说明协议里还有随机源没控制住。
原因 6：定位数据与评测集重叠
用 n-gram 重叠做粗筛即可。
```python
def ngrams(s, n=13):
t = s.split()
return {tuple(t[i:i+n]) for i in range(max(0, len(t)-n+1))}
train_ng = set().union(*(ngrams(x) for x in calib_texts))
leak = [q for q in eval_questions if ngrams(q) & train_ng]
print("疑似重叠:", len(leak))
```
判断：只要有一条重叠就换数据。定位用的题目和评测题目必须来自不同来源。
定位本身怎么做
这是整条流水线里比较关键的一步。常用做法是梯度显著性：拿一小批数学题算 loss、反向传播、统计每个模块的梯度范数，取排名靠前的模块当候选。
```python
scores = {}
for batch in calib_loader:
loss = model(**batch).loss
model.zero_grad()
loss.backward()
for name, p in model.named_parameters():
if p.grad is not None and p.dim() >= 2:
scores[name] = scores.get(name, 0.0) + p.grad.detach().float().norm().item() ** 2
for k in sorted(scores, key=scores.get, reverse=True)[:20]:
print(f"{scores[k] ** 0.5:10.4f} {k}")
```
拿到候选后按预算截断：从高到低累加 numel()，到了预算上限就停。补丁可以用「负梯度方向的一小步」，也可以先做低秩分解再乘一个小系数：
```python
dW = -lr * grad.float()
U, S, Vh = torch.linalg.svd(dW, full_matrices=False)
r = 8
dW_lowrank = (U[:, :r] * S[:r]) @ Vh[:r]
```
判断这一步有没有意义：在定位集之外的一小批题上做改动前后对比，如果连这批题都没有任何翻转，先别急着大规模评测，回头看补丁幅度是不是太小、选层是不是偏了。
回归评测怎么做
分三层来做。
1. 能力回归：数学集改动前后各跑一遍，记录逐题结果。不只看总分，看「变好题数 / 变坏题数 / 不变题数」。总分持平但翻转很多，说明这次改动不稳定。
2. 副作用集：通用对话、指令跟随、长文本、代码、多语言、拒答行为各抽一小批。重点看三个指标：输出长度分布、复读率、拒答率。
3. 困惑度：在留出集上算 ppl，改动前后对比。明显上升说明语言建模能力被破坏。
复读率可以这样粗算：
```python
def repeat_ratio(text, n=4):
t = text.split()
grams = [tuple(t[i:i+n]) for i in range(max(0, len(t)-n+1))]
if not grams:
return 0.0
return 1 - len(set(grams)) / len(grams)
```
都不管用时的兜底方案
- 回滚优先。改之前整目录复制、记录文件哈希；出问题直接丢掉改后的目录，不要在坏权重上继续调参。
- 放弃改权重，换外挂方案：LoRA 等增量微调、检索增强、让模型调用计算器或符号求解工具、在 prompt 里加解题步骤模板。这些方案上手成本通常低于权重编辑，可回滚性也更好。
- 缩小改动面：只改一层、只改一个模块，做单变量 A/B。改动面越小，定位问题越容易。
- 把「暴涨」当假阳性处理。换一套完全没参与过定位的评测集重跑，换随机种子重跑，必要时换人来写评测脚本。
- 请另一个模型或同事独立复核评测脚本，尤其检查答案抽取正则和判分逻辑——相当一部分「涨点」其实是抽取规则变了。
如何预防再次发生
1. 建一份权重编辑清单，每次照单执行：结构快照（config 加 key 列表）、dtype 记录、预算计算、写回校验、评测协议、回滚路径。少一项就不算跑完。
2. 全流程脚本化并且幂等，加 --dry-run 只打印将要改的张量和参数量，不落盘。
3. 版本化四样东西：原权重哈希、tokenizer 哈希、评测集哈希、脚本 commit。任何一份变了，前后结论就不能直接对比。
4. 先用一个小模型跑冒烟测试，把整条流水线走通再上大模型，省时间也省显存。
5. 报告里强制写清三件事：改了多少参数 / 总参数、定位数据与评测集是否重叠、副作用集结果。缺一项的结论不采信。
6. 上线走三段：离线评测、影子流量对比、小流量灰度，每一段都留回滚开关。
最后提醒一句：参数比例小不等于风险小。0.016% 只是一个预算数字，它可能带来明显提升，也可能什么都没改变，还可能悄悄破坏通用能力。真正决定这件事能不能做成的，是定位数据干不干净、评测协议稳不稳定、回滚路径通不通。