todotge/canonical-basis 来源：https://github.com/todotge/canonical-basis

用于解释 Transformer 语言模型的标准基

语言模型标准基 (CBLL)：一种无损坐标变换，能打开 Transformer 大语言模型的黑箱，并使隐藏空间的每个轴均可独立度量。本仓库是 Zenodo 论文的可复现配套资源：

Gernone, G. (2026). The Hidden Geometry of Transformer Weights: A Journey > Inside the Black Box. Zenodo. DOI: 10.5281/zenodo.20520986.

paper/The Hidden Geometry of Transformer Weights: A Canonical Basis for Interpreting Transformer Language Models_EN.md 是论文的更新版本2，扩展了因果消融、多架构度量、LayerNorm 桥接以及 MoE 分析。论文中的所有数据均来自 scripts/ 中的脚本和 data/ 中的预计算数据。

本仓库演示的内容

1. 仿射重对齐是无损的——将 RMSNorm 增益吸收到相邻权重矩阵中，并使用 Householder 矩阵进行旋转，这改变了模型的坐标系，但未改变其行为。
   Qwen 2.5 0.5B：困惑度 25.38 = 25.38，MMLU 47.50% = 47.50%。
   SmolLM2 1.7B：困惑度 6.6018 → 6.6045，前5重叠率 5/5。

2. 跨层 U 对齐——在 Qwen 2.5 0.5B 上，FFN 下投影的左奇异向量在各层间强烈对齐（所有276个层对平均0.651，最大0.928；相邻层对对齐更强）。模型存在一组无人强加的共享偏好方向。

3. 富人俱乐部与双极振荡器——在标准基中，896个轴分为309个正极轴和292个负极轴；83%的正极轴拥有专用的抑制性伙伴。主轴对：轴62 ↔ 轴570，ρ = −0.97。

4. 呼吸作用——正/负轴比例在24层中呈四阶段振荡（编码 1.36 → 处理 0.42–0.88 → 解码 1.28 → 输出 0.54），与输入内容无关。相同的五层 [21, 3, 23, 2, 22] 对所有测试提示都是最强激活层。

5. 稳态——残差流的任何中间扰动会在两层内被消除（5× → 1.4× → 1.0×），由 RMSNorm、注意力 softmax 和 SiLU 操作范围的共同作用实现。这是架构性的，非学习所得。

6. 谱坍缩——奇异值大小在各层间几乎相同（秩 1/24，比值 23.2×）。层的特性存在于几何结构 (U, V) 中，而非谱中。

7. 六个谱指数——内聚性、扭转性、信息性、维度性、节律性和涡度指数量化每层结构（平均值 0.588 / 0.917 / 0.709 / 0.378 / 0.595 / 0.650），有效维度为 4.77/6，且权重谱（k90/d 0.71）与激活谱（k90/d 0.017）之间存在 41 倍的各向同性坍缩。

8. 因果证据：单轴消融——仅将轴62归零（模型参数的0.11%）会使 MMLU 从 47.50% 崩溃至 21.25%，并破坏输出连贯性（困惑度 4.24 → 23858）。将其反相关伙伴轴570归零会降低事实准确性但保持流畅度。五个控制轴无效果（≤ ±1.25 pp）。几何结构是功能性的，而非装饰性的。

9. 架构普适性——在 RMSNorm 家族（Qwen, SmolLM2）上重对齐是无损的；在 LayerNorm 家族（Pythia 1.4B：困惑度 9.2286 → 9.2359，贪婪生成3/3一致）上，通过保留直流分量的旋转实现无损。对六个家族的原生对齐度量范围为 0.02 (OLMo2) 到 0.94 (Qwen)；仅归一化类型不能决定对齐程度。

10. MoE 结构——在 OLMoE-1B-7B（64个专家）上，每个专家的跨层对齐度为0.086，跨专家对齐度为0.111：专家结构是每个专家独立的，而非跨层共享。

为什么需要标准基

Transformer 的隐藏状态是 R^d 中的一个向量，但其所在的基是任意的——取决于训练收敛的结果。在标准基中，维度 i 没有任何意义，不同层之间也无法进行比较。标准基旋转模型，使得隐藏状态的轴 k 对应于模型自身权重矩阵的特定谱方向。旋转后：

• 每个轴可独立度量（能量、相关性、熵）；
• 每个轴可独立操控（归零、放大、从第0层追踪到第23层）；
• 在标准基中分散在所有896个维度上的现象——双极振荡器、呼吸作用、关键轴——被定位到单个轴上。

旋转是无损的：重对齐后的模型产生与原始模型相同的输出。它是一台显微镜，而非修改。

为何这不是一个自由操作

RMSNorm 使用逐通道学习的增益，且 (g ⊙ h)R^T ≠ g ⊙ (hR^T) ——增益破坏了旋转对称性。必须先将增益吸收到相邻权重矩阵中（W' = W @ diag(g)），使归一化均匀化。LayerNorm 还减去均值，这只在固定全1向量（保留直流分量的旋转）下旋转等变；其 γ 和 β 参数被吸收到权重列和投影偏置中。这两个过程都是无损的，在 scripts/ 中实现。

如何使用

快速验证（预计算数据，无需GPU）

所有论文数据均以JSON格式位于 data/ 中：

# 单轴消融（论文第4节）
python3 -c "import json; d=json.load(open('data/single_axis_ablation.json')); \
print('baseline', d['baseline']['mmlu']['accuracy']); \
[print(k, v['mmlu']['accuracy'], v['delta_mmlu']) for k,v in d.items() if k.startswith('axis_')]"

# 多架构对齐（论文第5.3节）
python3 -c "import json; d=json.load(open('data/gguf_cbll_multiarch.json')); \
[print(k, v['u_alignment_mean']) for k,v in d.items()]"

# Pythia 直流桥接（论文第5.2节）
python3 -c "import json; d=json.load(open('data/pythia_dc_bridge_results.json')); \
print(d['ppl_original'], '->', d['ppl_canonical'], 'lossless:', d['lossless'])"

完整复现（需GPU，测试于6GB显存）

pip install -r requirements.txt
bash reproduce.sh  # 7个步骤，约30分钟：重对齐 → 收集 → 诊断 → 消融

单独步骤

python scripts/save_model.py --model Qwen/Qwen2.5-0.5B-Instruct \
  --output compressed_models/realigned_qwen05b  # 重对齐（无损）

python scripts/diagnose_shared_sigma.py        # U对齐、稳态、sigma
python scripts/investigate_rich_club.py         # 正/负极
python scripts/analyze_correlations.py          # 896×896 相关矩阵
python scripts/benchmark_mmlu.py                # MMLU 12×20 基线
python scripts/ablate_single_axis.py \
  --test-axes 62 570 0 400 50 100 200 500 800  # 因果消融（9个轴）

其他模型

• SmolLM2 1.7B（RMSNorm，Llama风格）：scripts/realign_smollm_cbll.py，然后 scripts/smollm_cbll_continue.py 以访问标准基。
• Pythia 1.4B（LayerNorm，GPT-NeoX）：scripts/pythia_dc_bridge.py —— 保留直流分量的旋转，保留LayerNorm，无损。
• OLMoE-1B-7B（MoE，RMSNorm）：scripts/analyze_olmoe_cbll.py —— 读取旋转后的fp16权重并计算稠密/专家/跨专家对齐度和谱指数。
• GGUF模型（Falcon3, StarCoder, Nemotron, DeepSeek-Coder, OLMo2）：scripts/analyze_gguf_cbll.py —— 从Ollama blob解量化GGUF张量并测量原生U对齐度和k90/d。

配置：路径在哪里

发布的脚本中没有硬编码的机器路径。所有内容通过环境变量配置，或回退到标准位置：

示例：

export HF_HOME=/data/models
export OLLAMA_BLOBS=/data/ollama/blobs
export OLMOE_ROTATED_DIR=/data/olmoe/rotated_fp16
export OLMOE_R_PATH=/data/olmoe/olmoe_R.npy
bash reproduce.sh

脚本将其输出写入 runs/（已gitignore），并从 compressed_models/（已gitignore，由 scripts/save_model.py 生成）读取重对齐模型。预计算结果位于 data/ 中，永远不会被运行覆盖——请重新生成，然后与 data/ 进行比较。

调试与故障排除

预期值（健全性检查）

常见故障模式

1. “重对齐模型输出垃圾”——几乎总是遗漏吸收或钩子方向错误。按顺序检查： (a) 吸收后所有 RMSNorm 增益是否为 1.0？ (b) embed钩子使用 R^T 旋转，最后一层钩子使用 R（行向量约定）？ (c) 输出侧偏置是否旋转（b @ R^T）？Qwen类模型无偏置；GPT-NeoX每个投影都有偏置。

2. “困惑度有微小差异”——预期的。fp16前向传播引入约10⁻²的逻辑差异；行为上不可见（前5重叠率 5/5，贪婪生成一致）。需要fp32才能完全一致。

3. “k90/d值看起来错误”——使用完整SVD（np.linalg.svd(W, compute_uv=False)），而非使用少量组件的随机化SVD。随机化SVD会严重低估k90。OLMoE脚本包含两者；请信任 d_k90_fullsvd.json。

4. “轴归零无效果”——检查轴是否在标准基中归零（在embed旋转之后，取消旋转之前），且干预在权重层面（归零 W_down 行），而非激活层面：激活层面的扰动会被稳态在两层内消除——这正是第3.3节的重点。

5. “CUDA内存不足”——GPU一次持有模型（6GB显存）。通过保存参考逻辑、释放模型，然后加载标准基模型来比较逻辑（realign_smollm_cbll.py 中使用的模式）。

6. “LayerNorm重对齐性能下降”——确保使用保留直流分量的旋转，而非RMSNorm替换。条件是 R^T 1 = 1；用 np.abs(R @ np.ones(d) - np.ones(d)).max() < 1e-8 验证。

验证标准基可访问性

在任何重对齐模型上最快检查：

# 在最后一层输出、取消旋转前归零标准轴 k
# 困惑度：轴 0（Qwen）→ 灾难性；轴 500 → 无变化
python scripts/ablate_single_axis.py --test-axes 62 500 --skip-chat

或使用 demo/chat.py 进行交互：/ablate 62，然后 /restore。

模型与架构

我们可根据要求将流程扩展到更多架构：保留直流分量的旋转覆盖所有LayerNorm家族，吸收过程覆盖所有参数化归一化。

我们发布的重对齐模型： OLMo MoE家族 (OLMoE-1B-7B) 的标准基——旋转后的fp16权重加上旋转矩阵——以便任何人都可以进行测量而无需重新运行重对齐。

交互式演示：每轴控制聊天

demo/chat.py 是一个独立的交互式聊天，具有精细的每轴控制——感受第4节因果结果的最快方式。

pip install torch transformers
python demo/chat.py                     # 正常聊天
python demo/chat.py --ablate 62         # 移除轴62的聊天
python demo/chat.py --ablate 62 --compare # 并排比较基线与消融结果
python demo/chat.py --prompt "Capital of Italy?" # 非交互单提示

首次运行会下载 Qwen 2.5 0.5B（约1GB），运行仿射重对齐（GPU约30秒，CPU约60秒），并缓存重对齐模型。后续运行会立即加载缓存。可在CPU上运行（可选GPU，约3倍速）。

聊天中的交互命令：

/ablate 62        # 在每层的FFN输出归零轴62
/ablate 62 570    # 归零多个轴
/restore          # 恢复所有轴
/quit             # 退出

您将看到（摘自 demo/README.md）：

═══ 基线（所有轴激活）═══
用一句话解释量子计算。
量子计算使用可以同时存在于多个状态的量子比特，从而能够更快地解决某些问题。

═══ 轴 [62] 已归零 ═══
用一句话解释量子计算。
the the the the the the the the...

═══ 已恢复 ═══
用一句话解释量子计算。
量子计算使用可以同时存在于多个状态的量子比特，从而能够更快地解决某些问题。

轴62的静态激活接近于零（能量排名895/896），但在轴相关网络中具有最大中介中心性（3702）——一个动态控制器，而非静态特征。在每层归零它会从残差流中移除其贡献，模型失去跨层协调。/restore 将其恢复——干预是可逆的，效果是即时的，并且交互式再现了第4节的因果消融。

仓库布局

canonical-basis/
├── README.md                     # 本文件
├── reproduce.sh                  # 完整流程，7个步骤
├── requirements.txt              # torch, transformers, datasets, numpy, scipy
├── CITATION.cff                  # 引用元数据
├── LICENSE
├── paper/
│   ├── The Hidden Geometry of Transformer Weights:A Canonical Basis for Interpreting Transformer Language Models_EN.md  # 论文v2（英文）
│   └── The Hidden Geometry of Transformer Weights:A Canonical Basis for Interpreting Transformer Language Models_IT.md  # 论文v2（意大利文）
├── demo/
│   ├── chat.py                   # 交互式每轴控制聊天
│   └── README.md                 # 演示用法
├── assets/                       # 图表和演示生成器
├── validation/                   # 验证说明
├── scripts/                      # 每个论文主张一个脚本
└── data/                         # 预计算结果（所有论文数据）

已发布的内容