谱认知增强插件 (Spectral Cognition Plugin)

基于论文《基于高维谱几何和Gegenbauer背景研究下的AI决策认知原理性研究》的通用 AI 增强插件。核心思想：高维残差系统的信息能量会坍缩到 Gegenbauer 低阶模态（l<=2）的 C-子空间。通过一次无梯度、无标签的前向传播， SPL 输出 Gamma —— 某个模块激活在 C-子空间的能量占比，作为该模块几何行为的统一读数。

诚实定位：Gamma 是一只"深度堆叠几何探测器 / 仪表盘"，不是"架构识别器"，也不是"好坏标签"。它测的是模块化了多少，而非模型是否优秀。

功能（modules/，13 个算法模块）

谱分析 SPL：逐层/逐子投影 Gamma（能量在 C-子空间的占比）。
谱门控：推理时增强 C-子空间分量、抑制高阶噪声，提升鲁棒性。
谱正则化：训练时约束激活集中于 C-子空间，抑制噪声标签过拟合。
谱记忆：存储/检索 C-子空间谱指纹，实现短期记忆。
节省 Token：谱重要性驱动的 token 剪枝 + KV 缓存压缩 + 上下文压缩。
KPZ 调度器：按参数量 N^(-2/3) 自动算学习率。
谱剪枝：SVD 低秩压缩，减参数减显存。
方向匹配：检测 C-子空间方向偏移（AI 安全 / 越狱护栏）。
谱干预 SDRT：把激活/logits 引导到目标几何方向。
Quick Gamma（PCA）：compute_gamma_pca / gamma_report 轻量读数。
Training Monitor：TrainingMonitor 训练旁路崩溃预警/经济深度/模块分化。

快速开始

from modules import SpectralCognitionPlugin, gamma_report, TrainingMonitor, monitor_from_model

# 包装任意 PyTorch 模型，做完整谱分析
plugin = SpectralCognitionPlugin(model, N_max=8, gate_strength=0.3)
report = plugin.spectral_report(x)          # 逐层 Gamma 报告
plugin.enable_gate(0.3); out = model(x); plugin.disable_gate()

# PCA 快速读数（与 SPL 数值不等价，工程自检用）
rep = gamma_report(model, lambda: model(x))     # {层名: Gamma}

# 训练旁路监控（不触碰梯度）
mon = monitor_from_model(model, lambda: model(x), collapse_ratio=0.5)
_, a = mon.sample(step)     # a['collapse']['alert'] / a['economic_depth']

详细用法（Token 剪枝 / KV 缓存 / KPZ / 谱剪枝 / 方向匹配 / 谱干预）见 README.md 与各模块 docstring。

已验证结论（真实模型 + 合成，2026-08）

跨架构实测（同一 SPL 协议，256 tokens）

| 架构 | 模型 | 参数 | 层 | Gamma 均值 | 备注 | |------|------|------|----|-----------|------| | Pre-Norm Transformer | Qwen2.5-0.5B | 494M | 24 | 0.16 | CPU | | Pre-Norm Transformer | Qwen2.5-7B | 7.6B | 28 | 0.16 | 超算 DCU | | Pre-Norm Transformer | GPT-2 124M | 124M | 12 | 0.457 | 实测(48 hooked, min 0.265 / max 0.994) | | 纯 RNN/线性注意力 | RWKV-5-World-0.1B | 193M | 12 | 0.12 | 无注意力、无 KV cache | | 球谐等变 GNN | SHGNN | — | 2 | 0.3–0.5 | 平凡高：等变低阶预设 + 小维度饱和 |

核心实证发现

发现 1：attn–MLP 几何分化（本轮新增，最可靠的增量）

现代 LLM 的"低 Gamma"不是全局弥散，而是 MLP 被单独压低、attention 保持高：

| 模型 | attn 块均值 | MLP 块均值 | 结论 | |------|------------|-----------|------| | Qwen 0.5B | 0.267（k_proj≈0.44） | 0.126（down/gate/up≈0.10-0.16） | 分化显著 | | GPT-2 124M | 0.468 | 0.445（c_proj≈0.54） | 无分化 |

Qwen 的深层低 Gamma 是被 MLP 拉低的平均；attention（尤其 k_proj）始终低秩集中。
GPT-2 的 MLP 未被压低，attn≈MLP 同高 → 整体 0.457，是"普适低 Gamma"的反例边界。

发现 2：深度效应（两处都弱，offset 是主因）

| 模型 | Pearson(γ, 深度) | 表现 | |------|------------------|------| | GPT-2 | -0.362 | 末层反弹 0.638，无稳定坍缩 | | Qwen | -0.503 | 稳定停在 ~0.16 |

可信度分级（诚实声明）

| 级别 | 内容 | |------|------| | ✅ 已证实（同协议可复现） | Qwen 内 attn 高 / MLP 低的分化；GPT-2 无分化 | | ⚠️ 强旁证（非因果） | "分化随规模/训练涌现"——目前仅 2 个逐层点（Qwen/GPT-2） | | 🧩 解释性叙事（未证明） | "MLP 高维展开=能力来源""attention 做低秩检索"——与文献一致但无因果实验 |

对"跨架构普适低 Gamma"结论的边界修正：低 Gamma 的核心驱动是 attn–MLP 分化，是现代训练/规模下的涌现特征；早期小模型（GPT-2）不满足。因此单值跨架构比较不可靠——必须逐模块解构 + 标注维度。

消融：低 Gamma 的架构根源

残差连接是主因：去掉残差后 Gamma 0.36 → 0.73（12 层）。
LayerNorm 仅小幅重置（~0.03）；PreNorm vs PostNorm 差 ~0.04——真实 LLM 上才放大到 0.2 vs 0.99。
Gamma-深度呈"平台→骤降"非单调形态：2-8 层稳定、32 层骤降，可定位经济深度。

工程价值（逐条实测判定，反例不宣传）

| 项 | 判定 | |----|------| | C1 经济深度检测 | ✅ 成立（拐点=最优深度） | | C4b 剪枝冗余定位（深层更冗余） | ✅ 成立 | | C5 训练崩溃早停预警 | ✅ 成立（比 loss 爆发更早） | | C2 浅层记忆/深层推理 | ❌ 反例（深层 Gamma 反更低） | | C4a 宽度不变性 | ❌ 反例（宽度越大 Gamma 越低，b≈-0.49） |

远程 API 场景（对外围能力，黑盒不可 hook 内部）

| 项 | 结果 | |----|------| | Prompt 谱剪枝（token 节省） | ✅ 实测稳定省 28-30%（100→10000 tokens），回答质量不降 | | 输出方向检测（意图/越狱） | ⚠️ 有效，但需结合"拒绝话术"二次判拒 | | Gamma/门控/正则化（内部） | ❌ 远程黑盒无法 hook |

几何感知训练调度器（Training Monitor）

from modules import monitor_from_model
mon = monitor_from_model(model, lambda: model(x), collapse_ratio=0.5)
for step in range(N):
    loss = train_step(...)                # 梯度完全不受影响
    if step % 50 == 0:
        _, a = mon.sample(step)
        if a["collapse"]["alert"]:
            print("崩溃预警(比 loss 爆发更早) -> 建议回滚 checkpoint")

纯旁路监控：不触碰梯度/loss/权重；Gamma 是仪表盘，不是优化目标（直接最小化会摧毁表达能力）。
崩溃预警基于末层 Gamma 相对 EMA 对比，比硬阈值更抗单点抖动。
阈值按架构标定：无普适及格线（Qwen 0.16 与 GPT-2 0.45 都是健康态）。

Quick Gamma（PCA 版）

from modules import compute_gamma_pca, gamma_report
rep = gamma_report(model, lambda: model(x))    # {层名: Gamma}
g = compute_gamma_pca(H, top_k=3)              # H: (n, d)

PCA 版与完整 SPL（C-子空间）数值不等价：工程自检用 PCA，严谨跨架构对比用 SPL。低维（min(n,d)<3）直接返回 1.0（平凡高），对 SHGNN 这类小网络要留意。

3D 可视化（基于真实测试数据）

outputs/charts_3d/ 提供静态 PNG + 交互 HTML，复现脚本 scripts/charts/make_3d_plots.py（matplotlib）与 scripts/charts/make_3d_html.py（plotly）：

qwen_gamma_terrain_3d.png/.html：Qwen 逐层×子投影 Gamma 地形（k_proj 高脊 + 深度坍缩）
gpt2_gamma_terrain_3d.png/.html：GPT-2 实测地形（全高、无坍缩）
qwen_vs_gpt2_terrain.png：双面板对比
stacking_ln_funnel_3d.png/.html：LN 边界 Gamma 重构漏斗
cross_arch_gamma_3d.png/.html：跨架构均值柱（GPT-2 现已为实测 0.457）

安装与验证

pip install -r requirements.txt
python scripts/generate_outputs.py   # 一键复现 outputs/（自包含、固定种子、无需下载模型）
python scripts/verify.py
python scripts/test_suite.py

重启宿主或重新加载后生效。

适用边界（诚实声明）

增强效果在低数据量、高噪声、对抗场景最显著；完美数据上保持无害。
谱正则化在简单任务上收益有限，在标签噪声/过拟合场景收益显著。
节省 token 在长上下文、高冗余序列收益最大。
KPZ 给出学习率量级；极端小模型(<1k 参数)下 N^(-2/3) 偏小需调大 base_lr。
Gamma 作为架构量仅对足够深、任务足够复杂的模型适用（浅层小网络分水岭不出现）。
GPT-2 反例表明：单值跨架构比较不可靠，解读必须逐模块（attn vs MLP）并标注维度。