Spaces:
Running
Running
| title: Math Under Llm | |
| emoji: 🌖 | |
| colorFrom: gray | |
| colorTo: green | |
| sdk: gradio | |
| sdk_version: 6.14.0 | |
| python_version: '3.13' | |
| app_file: app.py | |
| pinned: false | |
| license: apache-2.0 | |
| short_description: 'Compute SVD of LLM Q/K/V weights directly from Hugging Face' | |
| Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference | |
| --- | |
| # Wang's Five Laws — LLM Spectral Analyzer | |
| ## 完整项目文档 README.md（6-Tab Gradio App） | |
| --- | |
| # 🔬 Wang's Five Laws — LLM Spectral Analyzer | |
| **静态分析 LLM 注意力权重，无需推理，无需 benchmark，直接评估推理能力。** | |
| 通过对 Q/K/V 权重矩阵做 SVD 分解，验证王氏五定律， | |
| 计算 Wang Score（= 1 − median SSR_QK），实现跨模型推理能力排行。 | |
| [](https://doi.org/10.5281/zenodo.19707844) | |
| [](https://hal.science/hal-05609398) | |
| [](https://github.com/emis-framework/math-under-llm) | |
| --- | |
| ## 目录 | |
| 1. [项目背景](#1-项目背景) | |
| 2. [王氏五定律速查](#2-王氏五定律速查) | |
| 3. [整体架构](#3-整体架构) | |
| 4. [目录结构](#4-目录结构) | |
| 5. [各层详细说明](#5-各层详细说明) | |
| - 5.1 [core 层](#51-core-层——计算引擎) | |
| - 5.2 [db 层](#52-db-层——数据持久化) | |
| - 5.3 [ui 层](#53-ui-层——用户界面) | |
| - 5.4 [app.py 入口](#54-apppy——主入口) | |
| 6. [数据库表结构](#6-数据库表结构) | |
| 7. [数据流全链路](#7-数据流全链路) | |
| 8. [函数调用关系图](#8-函数调用关系图) | |
| 9. [关键设计决策](#9-关键设计决策) | |
| 10. [部署说明](#10-部署说明) | |
| 11. [依赖清单](#11-依赖清单) | |
| 12. [改动历史](#12-改动历史) | |
| --- | |
| ## 1. 项目背景 | |
| 传统评估 LLM 推理能力需要跑 benchmark（耗时、昂贵、可刷榜）。 | |
| 本项目发现：**只看权重矩阵的奇异值分解（SVD）结构， | |
| 就能静态评估模型推理质量**，无需任何推理。 | |
| 核心原理： | |
| - 对每一层注意力的 Q、K、V 权重矩阵做 SVD | |
| - 计算奇异值谱之间的相关性、形状残差、子空间对齐度 | |
| - 这些指标与模型推理能力高度相关（经多个模型验证） | |
| **运行方式**：HTTP Range Request 直接读取 HuggingFace 远程权重， | |
| 无需下载整个模型（一个 14B 模型只需读取约 200MB 数据而非 28GB）。 | |
| --- | |
| ## 2. 王氏五定律速查 | |
| | 定律 | 名称 | 公式 | 理论极值 | 实测范围 | | |
| | -------- | ------------------ | ----------------------------------- | ---------- | ------------ | | |
| | 第一定律 | 谱线性对齐 | Pearson r(s_Q, s_K) | → 1 | 0.94~0.99 | | |
| | 第二定律 | 谱形状残差 | SSR = mean\|ŝ_Q − ŝ_K\| | → 0 | 0.006~0.016 | | |
| | 第三定律 | 精度-深度约束 | L_max = min(L_info, L_quant, L_dyn) | 由精度决定 | FP16→16层 | | |
| | 第四定律 | 输出子空间解耦 | cosU(U_Q,U_V) < 1/√d_head | 超正交 | ~20%低于随机 | | |
| | 第五定律 | 输入子空间随机正交 | cosV ≈ 1/√d_model | ≈随机基线 | 符合理论 | | |
| **Wang Score = 1 − median(SSR_QK)**（越高越好，理论极值=1） | |
| --- | |
| ## 3. 整体架构 | |
| ``` | |
| ┌─────────────────────────────────────────────────────┐ | |
| │ app.py │ | |
| │ 主入口，组装所有 6 个 Tab │ | |
| │ 启动时调用 init_db() │ | |
| └──────┬──────────────────────────────────────────────┘ | |
| │ 调用 | |
| ▼ | |
| ┌──────────────────────────────────────────────────────┐ | |
| │ ui/ 层 │ | |
| │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ | |
| │ │tab_inspect │ │tab_analyze │ │tab_leaderbd │ │ | |
| │ │结构探测 │ │分析+写库 │ │排行榜 │ │ | |
| │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ | |
| │ │ │ │ │ | |
| │ └────────────────┼────────────────┘ │ | |
| │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ | |
| │ │tab_database │ │ tab_plot │ │ tab_tables │ │ | |
| │ │数据库浏览 │ │ 作图导出 │ │ 论文表格 │ │ | |
| │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ | |
| │ └────────────────┼────────────────┘ │ | |
| └──────┬──────────────────────────┬───────────────────┘ | |
| │ 调用 │ 调用 | |
| ▼ ▼ | |
| ┌─────────────────┐ ┌─────────────────────────────┐ | |
| │ core/ 层 │ │ db/ 层 │ | |
| │ │ │ │ | |
| │ fetcher.py │ │ schema.py writer.py │ | |
| │ 远程读取权重 │ │ 建表 写入数据 │ | |
| │ │ │ │ | |
| │ layer_profile.py│ │ reader.py │ | |
| │ 推断层结构 │ │ 查询数据 │ | |
| │ │ │ │ | |
| │ metrics.py │ │ SQLite 文件 │ | |
| │ 计算五定律 │ │ /data/wang_laws.db │ | |
| │ │ │ │ | |
| │ plotter.py │ │ │ | |
| │ matplotlib静态图 │ │ │ | |
| │ │ │ │ | |
| │ plotter_plotly │ │ │ | |
| │ Plotly交互图 │ │ │ | |
| │ │ │ │ | |
| │ table_gen.py │ │ │ | |
| │ 论文表格生成 │ │ │ | |
| └─────────────────┘ └─────────────────────────────┘ | |
| ``` | |
| **三层职责：** | |
| | 层 | 职责 | 不做什么 | | |
| | ------- | --------------------------- | ---------------------- | | |
| | `core/` | 纯计算，无 UI，无 DB | 不写数据库，不渲染界面 | | |
| | `db/` | 纯数据库操作 | 不做计算，不渲染界面 | | |
| | `ui/` | 纯界面逻辑，调用 core 和 db | 不做底层计算 | | |
| --- | |
| ## 4. 目录结构 | |
| ``` | |
| 项目根目录/ | |
| │ | |
| ├── app.py # 主入口：初始化DB，组装6个Tab | |
| ├── requirements.txt # 依赖清单 | |
| │ | |
| ├── core/ # 计算引擎（纯Python，无副作用） | |
| │ ├── __init__.py # 空文件 | |
| │ ├── config.py # 全局开关（DEBUG=True/False） | |
| │ ├── debug.py # 调试输出工具（受config.DEBUG控制） | |
| │ ├── fetcher.py # HTTP Range Request 读取远程权重 | |
| │ ├── layer_profile.py # 自动推断模型层结构 | |
| │ ├── metrics.py # 计算王氏五定律全部指标 | |
| │ ├── plotter.py # matplotlib 静态图（4×3，18×20in，300dpi） | |
| │ ├── plotter_plotly.py # Plotly 原生交互图（12×1，全宽） | |
| │ └── table_gen.py # 论文表格生成（6张表，LaTeX/Markdown/CSV） | |
| │ | |
| ├── db/ # 数据持久化层 | |
| │ ├── __init__.py # 空文件 | |
| │ ├── schema.py # 建表SQL + 数据库连接 | |
| │ ├── writer.py # 写入分析结果 + 断点续传 + 级联删除 | |
| │ └── reader.py # 查询排行榜、模型详情、原始数据 | |
| │ | |
| └── ui/ # Gradio 界面层 | |
| ├── __init__.py # 空文件 | |
| ├── tab_inspect.py # Tab1：模型结构探测 | |
| ├── tab_analyze.py # Tab2：分析模型 + 写库 | |
| ├── tab_leaderboard.py # Tab3：王氏评分排行榜 | |
| ├── tab_database.py # Tab4：数据库浏览 + 模型删除 | |
| ├── tab_plot.py # Tab5：作图（Plotly交互 + matplotlib导出） | |
| └── tab_tables.py # Tab6：论文表格生成 | |
| ``` | |
| --- | |
| ## 5. 各层详细说明 | |
| ### 5.1 `core/` 层——计算引擎 | |
| #### `core/config.py` | |
| ```python | |
| DEBUG = False # True → 打印详细调试信息；False → 静默运行 | |
| ``` | |
| 全局唯一开关。所有调试输出都受这个控制。 | |
| --- | |
| #### `core/debug.py` | |
| | 函数 | 签名 | 用途 | | |
| | -------- | ------------------------------ | -------------------------------------- | | |
| | `dlog` | `(lines: list[str], msg: str)` | 向日志列表追加调试信息（仅DEBUG=True） | | |
| | `dprint` | `(msg: str)` | 打印到stdout（仅DEBUG=True） | | |
| `dlog` 用于 `metrics.py` 和 `tab_analyze.py`（有 lines 列表的地方）。 | |
| `dprint` 用于 `fetcher.py`（没有 lines 列表的地方）。 | |
| --- | |
| #### `core/fetcher.py` | |
| **核心思想**：safetensors 文件头记录了每个 tensor 的字节偏移， | |
| 用 HTTP Range Request 只下载需要的字节，无需下载整个文件。 | |
| | 函数 | 签名 | 返回 | 用途 | | |
| | ------------------------- | ------------------------------------------------ | -------------------------------- | -------------------------- | | |
| | `get_file_url` | `(model_id, filename)` | `str` | 拼接 HF 下载 URL | | |
| | `read_safetensors_header` | `(url, token)` | `(header_dict, header_size)` | 读取文件头（两次HTTP请求） | | |
| | `load_tensor_remote` | `(url, tensor_name, header, header_size, token)` | `torch.Tensor` | 按名读取单个tensor | | |
| | `get_safetensor_files` | `(model_id, token)` | `list[str]` | 列出所有.safetensors文件 | | |
| | `find_index_file` | `(model_id, token)` | `dict\|None` | 读取分片索引文件 | | |
| | `get_all_shard_files` | `(model_id, token)` | `list[str]` | 获取全部分片文件名 | | |
| | `load_all_shard_headers` | `(model_id, token)` | `dict[filename, (header, size)]` | 读取所有分片的header | | |
| | `check_quantization` | `(model_id, token)` | `(is_blocked, message)` | 三重量化检测 | | |
| | `http_error_msg` | `(e, model_id)` | `str` | HTTP错误码转中文提示 | | |
| **`load_all_shard_headers` 返回结构：** | |
| ```python | |
| { | |
| "model-00001-of-00006.safetensors": (header_dict, header_size), | |
| "model-00002-of-00006.safetensors": (header_dict, header_size), | |
| ... | |
| } | |
| # header_dict 结构： | |
| { | |
| "model.layers.0.self_attn.q_proj.weight": { | |
| "dtype": "BF16", | |
| "shape": [4096, 4096], | |
| "data_offsets": [0, 33554432] | |
| }, | |
| ... | |
| } | |
| ``` | |
| **量化检测四重逻辑（按顺序）：** | |
| 1. 检测 `config.json` 中的 `quantization_config` 字段 | |
| 2. 检测模型名是否含 `gptq/awq/gguf` 关键词 | |
| 3. 检测文件列表是否有 `.gguf` 文件 | |
| 4. 检测 header 中是否有量化专用 key（如 `qweight`, `qzeros`） | |
| --- | |
| #### `core/layer_profile.py` | |
| **核心思想**：从权重文件的 key 名自动推断模型结构，零 hard coding， | |
| 不依赖模型名称或配置文件（配置文件只是辅助参考）。 | |
| **关键数据结构：** | |
| ```python | |
| @dataclass | |
| class QKVKey: | |
| shard: str # 所在分片文件名，如 "model-00001-of-00006.safetensors" | |
| key: str # 完整tensor名，如 "model.layers.0.self_attn.q_proj.weight" | |
| shape: list # tensor形状，如 [4096, 4096] | |
| @dataclass | |
| class LayerProfile: | |
| prefix: str # 组件前缀，如 "model.language_model." | |
| layer_idx: int # 层号（原始safetensors key中的N） | |
| q: QKVKey # Q权重位置 | |
| k: QKVKey # K权重位置 | |
| v: QKVKey|None # V权重位置（None表示K=V共享） | |
| head_dim: int # 每个head的维度 | |
| n_q_heads: int # Q head数量 | |
| n_kv_heads: int # KV head数量（GQA时 < n_q_heads） | |
| d_model: int # 模型隐层维度（= q_shape[1]） | |
| kv_shared: bool # True = K和V共享（如Gemma全局层） | |
| complete: bool # True = Q/K都存在且head_dim推断成功 | |
| infer_ok: bool # head_dim推断是否成功 | |
| head_dim_source: str # 推断来源："k_norm"/"q_norm"/"config"/"enum" | |
| ``` | |
| | 函数 | 签名 | 返回 | 用途 | | |
| | ----------------------- | ------------------------------------ | ------------------------------------ | --------------------------------------------------- | | |
| | `classify_qkv_suffix` | `(suffix: str)` | `'q'/'k'/'v'/None` | 从key后缀判断是Q/K/V | | |
| | `is_norm_key` | `(suffix: str)` | `bool` | 判断是否为norm key（辅助推断head_dim） | | |
| | `scan_model_structure` | `(all_shard_headers, config_params)` | `dict[(prefix,layer), LayerProfile]` | **核心函数**：扫描全部headers，构建LayerProfile字典 | | |
| | `summarize_structure` | `(profiles)` | `str` | 生成人类可读的结构报告（Tab1使用） | | |
| | `extract_config_params` | `(config: dict)` | `dict` | 从config.json提取关键参数（兼容Gemma4嵌套结构） | | |
| **`scan_model_structure` 工作流程：** | |
| ``` | |
| 第一遍扫描：遍历所有shard的所有key | |
| → 用正则 r'layers\.(\d+)\.' 提取层号 | |
| → prefix = key的layers.N.之前部分 | |
| → suffix = key的layers.N.之后部分 | |
| → classify_qkv_suffix(suffix) → 归类为Q/K/V | |
| → is_norm_key(suffix) → 收集k_norm/q_norm形状（辅助推断head_dim） | |
| 第二遍构建：对每个(prefix, layer_idx)槽 | |
| → 检查Q/K是否都存在（必要条件） | |
| → V不存在 → kv_shared=True | |
| → _infer_head_dim() → 推断head_dim（5个优先级） | |
| → 计算n_q_heads, n_kv_heads, d_model | |
| → 构建LayerProfile | |
| ``` | |
| **head_dim 推断优先级：** | |
| ``` | |
| 1. k_norm.shape[0] ← 最可靠（Gemma系列有这个） | |
| 2. q_norm.shape[0] ← 备用 | |
| 3. config["head_dim"] ← config.json直接给出 | |
| 4. config["hidden_size"] / config["num_attention_heads"] ← 计算得出 | |
| 5. 枚举候选值 [512,256,128,96,80,64,48,40,32,16] ← 最后手段 | |
| ``` | |
| **KV共享检测（Gemma全局层）：** | |
| ``` | |
| V的key不存在于任何shard header → kv_shared=True → layer_type="global" | |
| ``` | |
| --- | |
| #### `core/metrics.py` | |
| 对一层的Q/K/V权重矩阵计算所有指标。 | |
| **底层计算函数：** | |
| | 函数 | 签名 | 返回 | 对应定律 | | |
| | ------------- | ---------------------- | ------------------- | ---------------------- | | |
| | `pearson` | `(a, b: Tensor)` | `float` | 第一定律 | | |
| | `spearman_r` | `(a, b: Tensor)` | `float` | 第一定律（补充） | | |
| | `ssr` | `(a, b: Tensor)` | `float` | 第二定律 | | |
| | `svr` | `(a, b: Tensor)` | `(alpha, residual)` | 尺度因子 | | |
| | `cos_U` | `(U_a, U_b: Tensor)` | `float` | 第四定律（左奇异向量） | | |
| | `cos_V` | `(Vt_a, Vt_b: Tensor)` | `float` | 第五定律（右奇异向量） | | |
| | `sigma_stats` | `(s: Tensor)` | `(max, min, cond)` | 第三定律 | | |
| **`ssr` 计算细节：** | |
| ```python | |
| # 归一化后逐元素绝对差的均值 | |
| n = min(len(a), len(b)) | |
| an = a[:n] / ||a[:n]|| # L2归一化 | |
| bn = b[:n] / ||b[:n]|| | |
| SSR = mean(|an - bn|) | |
| ``` | |
| **主分析函数：** | |
| ```python | |
| def analyze_layer( | |
| W_q: torch.Tensor, # shape: [n_q_heads * head_dim, d_model] | |
| W_k: torch.Tensor, # shape: [n_kv_heads * head_dim, d_model] | |
| W_v: torch.Tensor, # shape: [n_kv_heads * head_dim, d_model] | |
| profile: LayerProfile, | |
| ) -> tuple[list[dict], str]: | |
| # 返回：(records列表, 格式化日志字符串) | |
| ``` | |
| **`analyze_layer` 工作流程：** | |
| ``` | |
| 对每个 kv_head（0 ~ n_kv_heads-1）： | |
| 切片：k_t = W_k[kv_h*d_head : (kv_h+1)*d_head, :] | |
| SVD：U_k, s_k, Vt_k = svd(k_t) | |
| 计算 sigma_stats(s_k) | |
| 对每个 q_head（属于这个kv_head的group，GQA时 group = n_q/n_kv）： | |
| 切片：q_t = W_q[h*d_head : (h+1)*d_head, :] | |
| SVD：U_q, s_q, Vt_q = svd(q_t) | |
| 计算所有指标： | |
| pearson_QK, spearman_QK, ssr_QK, alpha_QK ← Q vs K奇异值 | |
| pearson_QV, ssr_QV, alpha_QV ← Q vs V奇异值 | |
| ssr_KV, alpha_KV ← K vs V奇异值 | |
| cosU_QK, cosU_QV, cosU_KV ← 左奇异向量 | |
| cosV_QK, cosV_QV, cosV_KV ← 右奇异向量 | |
| sigma_max/min/cond for Q, K, V | |
| append到records | |
| 特殊处理：kv_shared=True时，KV指标设为理论值（ssr=0, pearson=1, cosU=1等） | |
| ``` | |
| **`records` 每条记录的字段（共37个字段）：** | |
| ```python | |
| { | |
| "prefix": str, "layer": int, | |
| "kv_head": int, "q_head": int, | |
| "kv_shared": bool, "head_dim": int, | |
| "d_model": int, "n_q_heads": int, "n_kv_heads": int, | |
| # 第一定律 | |
| "pearson_QK": float, "spearman_QK": float, | |
| "pearson_QV": float, "pearson_KV": float, | |
| # 第二定律 | |
| "ssr_QK": float, "ssr_QV": float, "ssr_KV": float, | |
| # 第三定律 | |
| "sigma_max_Q": float, "sigma_min_Q": float, "cond_Q": float, | |
| "sigma_max_K": float, "sigma_min_K": float, "cond_K": float, | |
| "sigma_max_V": float, "sigma_min_V": float, "cond_V": float, | |
| # 第四定律 | |
| "cosU_QK": float, "cosU_QV": float, "cosU_KV": float, | |
| # 第五定律 | |
| "cosV_QK": float, "cosV_QV": float, "cosV_KV": float, | |
| # 尺度因子 | |
| "alpha_QK": float, "alpha_QV": float, "alpha_KV": float, | |
| "alpha_res_QK": float, "alpha_res_QV": float, "alpha_res_KV": float, | |
| } | |
| ``` | |
| ```python | |
| def summarize_records(records: list[dict], model_id: str) -> str: | |
| # 对records做统计汇总，返回格式化文本 | |
| # 按prefix分组，对每个指标计算 Median/Mean/Min/Max | |
| # KV指标自动排除kv_shared=True的行（避免理论值污染统计） | |
| ``` | |
| --- | |
| ### 5.2 `db/` 层——数据持久化 | |
| #### `db/schema.py` | |
| 数据库路径逻辑： | |
| ```python | |
| def get_db_path() -> str: | |
| if os.path.exists("/data"): # HF Space bucket挂载点 | |
| return "/data/wang_laws.db" | |
| return "wang_laws.db" # 本地开发回退 | |
| ``` | |
| | 函数 | 签名 | 用途 | | |
| | ---------------- | -------- | ---------------------------------- | | |
| | `get_db_path` | `()` | 返回数据库文件路径 | | |
| | `get_connection` | `()` | 返回SQLite连接（WAL模式，Row工厂） | | |
| | `init_db` | `()` | 建表+建索引，幂等，返回连接 | | |
| | `get_db_stats` | `(conn)` | 返回各表行数+文件大小 | | |
| --- | |
| #### `db/writer.py` | |
| | 函数 | 签名 | 用途 | | |
| | ------------------------ | --------------------------------------------------- | ------------------------------------------------------------------------- | | |
| | `infer_layer_type` | `(kv_shared: bool)` | `True→"global"`, `False→"standard"` | | |
| | `infer_modality` | `(prefix: str)` | 从 prefix 推断模态：language/vision/audio | | |
| | `check_write_permission` | `(admin_token: str)` | 验证 WRITE_TOKEN，返回 bool | | |
| | `get_analyzed_layers` | `(conn, model_id, prefix)` | 返回已完成的层号集合（断点续传用） | | |
| | `is_layer_complete` | `(conn, model_id, prefix, layer, expected_records)` | 检查某层记录数是否达到预期 | | |
| | `upsert_model` | `(conn, model_id, model_type, notes)` | 写入/更新模型元数据 | | |
| | `upsert_component` | `(conn, model_id, prefix, n_layers, ...)` | 写入/更新组件信息 | | |
| | `write_layer_records` | `(conn, model_id, records: list[dict])` | 批量写入一层的逐头数据（INSERT OR REPLACE） | | |
| | `_pseudobulk_col` | `(rows, col_name: str)` | Pseudo-bulk 两步聚合：消除 GQA 伪重复计数 | | |
| | `_calc_summary_row` | `(rows, model_id, prefix, layer_type)` | 用 pseudo-bulk 计算单行汇总统计 | | |
| | `update_model_summary` | `(conn, model_id, prefix)` | 重算并写入 model_summary 的 all/standard/global 三行 | | |
| | `refresh_all_summaries` | `(conn)` | 遍历所有(model_id, prefix)重跑 update_model_summary，供 Tab3 Refresh 调用 | | |
| | `delete_model` | `(conn, model_id, admin_token)` | 级联删除模型所有数据，需 WRITE_TOKEN 验证 | | |
| **`update_model_summary` 逻辑：** | |
| ``` | |
| 对 layer_type in ["all", "standard", "global"]： | |
| 从 layer_head_metrics 查对应行 | |
| 用 _pseudobulk_col() 两步聚合（先按 kv_head 组内 median，再跨组 median） | |
| → 消除 GQA 模型（如 LLaMA-3 32Q/8KV）的伪重复计数偏差 | |
| wang_score 统一用 standard 层的 pseudo-bulk median(ssr_QK) 计算 | |
| （即使写 all/global 行，wang_score 也来自 standard 层） | |
| INSERT OR REPLACE 写入 model_summary | |
| ``` | |
| **`delete_model` 逻辑：** | |
| ``` | |
| 1. check_write_permission(admin_token) → 失败直接返回错误 | |
| 2. 查 models 表确认模型存在 | |
| 3. 统计各子表行数（用于返回日志） | |
| 4. 按顺序级联删除： | |
| layer_head_metrics → model_summary → components → models | |
| 5. 返回 (True, 详细删除日志) | |
| ``` | |
| --- | |
| #### `db/reader.py` | |
| | 函数 | 签名 | 返回 | 用途 | | |
| | --------------------- | -------------------------------------------------------------- | -------------- | ---------------------------- | | |
| | `get_leaderboard` | `(conn, prefix_filter, layer_type, limit)` | `pd.DataFrame` | 排行榜查询，按wang_score降序 | | |
| | `get_model_summary` | `(conn, model_id)` | `pd.DataFrame` | 某模型所有组件的汇总统计 | | |
| | `get_layer_metrics` | `(conn, model_id, prefix, layer_type, start_layer, end_layer)` | `pd.DataFrame` | 逐头原始数据查询 | | |
| | `get_analyzed_models` | `(conn)` | `pd.DataFrame` | 所有已分析模型列表 | | |
| | `get_resume_status` | `(conn, model_id, prefix)` | `dict` | 断点续传状态：已完成层号集合 | | |
| --- | |
| ### 5.3 `ui/` 层——用户界面 | |
| #### `ui/tab_inspect.py` — Tab1：结构探测 | |
| **函数：** | |
| ```python | |
| def inspect_model(model_id, hf_token, progress) -> (str, pd.DataFrame): | |
| """ | |
| 工作流程： | |
| 1. check_quantization() ← 量化检测，失败则返回 | |
| 2. 读取 config.json ← extract_config_params() | |
| 3. load_all_shard_headers() ← 读取所有分片header | |
| 4. scan_model_structure() ← 构建LayerProfile字典 | |
| 5. summarize_structure() ← 生成文本报告 | |
| 6. 构建概览DataFrame ← 每层一行 | |
| 返回：(日志文本, 层结构DataFrame) | |
| """ | |
| def build_tab_inspect() -> (inspect_model_id, inspect_token): | |
| """ | |
| 构建Tab1的Gradio组件 | |
| 返回：(model_id文本框, token文本框) | |
| ← 返回值供app.py做Tab1→Tab2的联动同步 | |
| """ | |
| ``` | |
| **UI组件：** | |
| ``` | |
| 模型ID输入框 + Token输入框 + 探测按钮 | |
| → 日志文本框（结构报告） | |
| → 层结构表格（prefix/layer/d_model/head_dim/n_q/n_kv/kv_shared等） | |
| ``` | |
| --- | |
| #### `ui/tab_analyze.py` — Tab2：分析（核心Tab） | |
| **函数：** | |
| ```python | |
| def run_analysis(model_id, hf_token, start_layer, end_layer, admin_token, progress) | |
| -> (str, pd.DataFrame): | |
| """ | |
| 完整工作流程： | |
| [准备阶段] | |
| 1. init_db() ← 获取DB连接 | |
| 2. check_quantization() ← 量化检测 | |
| 3. 读取 config.json | |
| 4. load_all_shard_headers() ← 读所有分片header | |
| （404/网络错误 → 提前返回，DB零污染） | |
| 5. scan_model_structure() ← 构建LayerProfile字典 | |
| 6. upsert_model() ← 写模型元数据到DB | |
| （注意：故意在 shard headers 加载成功后才写， | |
| 防止模型名拼写错误产生脏数据） | |
| 7. upsert_component() for each prefix ← 写组件信息到DB | |
| [断点续传检查] | |
| 8. get_analyzed_layers() for each prefix | |
| → done_layers: dict[prefix, set[int]] | |
| → 打印待分析层和已跳过层 | |
| [逐层分析循环] | |
| for each (prefix, layer_idx) in filtered（按prefix+layer排序）: | |
| 9. 检查：layer_idx in done_layers[prefix] → continue（跳过） | |
| 10. load_tensor_remote(Q) ← HTTP Range Request | |
| 11. load_tensor_remote(K) | |
| 12. kv_shared ? W_v=W_k.clone() : load_tensor_remote(V) | |
| 13. analyze_layer(W_q, W_k, W_v, prof) ← 计算五定律 | |
| 14. write_layer_records(conn, model_id, records) ← 写DB | |
| 15. update_model_summary(conn, model_id, prefix) ← 更新排行榜 | |
| 16. del W_q, W_k, W_v ← 释放内存 | |
| [收尾] | |
| 17. 更新 models.analyze_sec（总耗时） | |
| 18. summarize_records() ← 生成汇总文本 | |
| 返回：(日志文本, 逐头结果DataFrame) | |
| """ | |
| def build_tab_analyze() -> (model_id_input, token_input): | |
| """构建Tab2的Gradio组件，返回值供app.py联动""" | |
| ``` | |
| **UI组件：** | |
| ``` | |
| 模型ID + Token + 起始层号 + 结束层号 + Admin Write Token + 分析按钮 | |
| 侧边栏：推荐模型列表 + 层号说明 + Reviewer Note（留空token可只读分析） | |
| → 分析日志文本框（逐头详情） | |
| → 逐头结果表格（37列全指标） | |
| ``` | |
| --- | |
| #### `ui/tab_leaderboard.py` — Tab3：排行榜 | |
| **函数：** | |
| ```python | |
| def _format_leaderboard(df: pd.DataFrame) -> pd.DataFrame: | |
| """ | |
| 格式化显示： | |
| - model_id → model_name（取最后一段） | |
| - wang_score → wang_score_pct（百分制字符串） | |
| - 数值列 → 6位小数字符串 | |
| - 选择展示列（隐藏冗余列） | |
| """ | |
| def load_leaderboard(modality, layer_type) -> (pd.DataFrame, str): | |
| """ | |
| 调用 refresh_all_summaries(conn) 静默重算所有模型汇总 | |
| → 自动将历史数据迁移到 pseudo-bulk 聚合 | |
| 调用 reader.get_leaderboard() | |
| modality 控制按模态过滤（language/vision/audio/all） | |
| layer_type="all" → 实际查 "standard"（排行榜默认用standard） | |
| """ | |
| def build_tab_leaderboard(): | |
| """ | |
| UI：组件过滤输入框 + 层类型下拉 + 刷新按钮 | |
| → 状态文本 + 排行榜表格 + 指标说明 | |
| 用户手动点刷新（不自动加载） | |
| """ | |
| ``` | |
| --- | |
| #### `ui/tab_database.py` — Tab4：数据库浏览 | |
| **函数：** | |
| ```python | |
| def load_db_stats() -> str: | |
| """调用 get_db_stats()，返回各表行数+文件大小""" | |
| def load_model_list() -> pd.DataFrame: | |
| """调用 get_analyzed_models()，返回模型列表""" | |
| def load_model_detail(model_id) -> (pd.DataFrame, str): | |
| """ | |
| 调用 get_model_summary() → summary_df | |
| 调用 get_resume_status() for each prefix → 断点续传状态文本 | |
| """ | |
| def run_delete_model(model_id, admin_token) -> (str, pd.DataFrame): | |
| """ | |
| 调用 db/writer.delete_model() 执行级联删除 | |
| 需要 Admin Write Token 验证 | |
| 删除成功后自动刷新 models_table | |
| 返回 (状态文本, 刷新后的模型列表DataFrame) | |
| """ | |
| def load_layer_data(model_id, prefix, layer_type, start_layer, end_layer) | |
| -> (pd.DataFrame, str): | |
| """调用 get_layer_metrics()，返回逐头原始数据""" | |
| def build_tab_database(): | |
| """ | |
| UI分为5个区块： | |
| 1. 数据库统计（行数+文件大小） | |
| 2. 已分析模型列表 | |
| 3. 🗑️ 删除模型（Model ID + Admin Token + Delete按钮，variant="stop"红色警示） | |
| → 删除成功后自动刷新模型列表 | |
| 4. 模型详情+断点续传状态 | |
| 5. 逐头原始数据查询（支持按modality/layer_type/层号范围过滤） | |
| """ | |
| ``` | |
| --- | |
| #### `ui/tab_plot.py` — Tab5：作图 | |
| **两条独立渲染路径（无嵌套 gr.Tabs()，用两个并排按钮区分）：** | |
| | 按钮 | 引擎 | 速度 | 输出 | | |
| | ------------- | ------------------------ | ---- | ---------------------------- | | |
| | ⚡ Interactive | `core/plotter_plotly.py` | ~2s | 浏览器内交互，hover/zoom | | |
| | 🖨️ Export | `core/plotter.py` | ~30s | PNG(300dpi) + PDF + SVG 下载 | | |
| **函数：** | |
| ```python | |
| def gen_single_plotly(model_id, modality, start_l, end_l, show_band) -> (go.Figure, str): | |
| """从DB加载数据，调用 plotly_single()，返回 Plotly Figure""" | |
| def gen_single_export(model_id, modality, start_l, end_l, show_band) -> (str, img, png, pdf, svg, zip): | |
| """从DB加载数据，调用 plot_single_model()，保存 PNG/PDF/SVG，返回下载链接""" | |
| def gen_compare_plotly(model_a, model_b, modality, start_l, end_l, show_band, show_delta) -> (go.Figure, str): | |
| """双模型对比，调用 plotly_compare()""" | |
| def gen_compare_export(model_a, model_b, modality, start_l, end_l, show_band, show_delta) -> (str, img, png, pdf, svg, zip): | |
| """双模型对比导出，调用 plot_compare_models()""" | |
| def build_tab_plot(): | |
| """ | |
| UI分为两个 Accordion： | |
| 1. 📊 Single Model：选模型 → ⚡Interactive / 🖨️Export | |
| 2. 📊 Two-Model Comparison：选A+B → ⚡Interactive / 🖨️Export + Δ填充开关 | |
| 共享控件：Modality / Start Layer / End Layer / IQR band 开关 | |
| """ | |
| ``` | |
| **12子图布局（Plotly 12×1 全宽）：** | |
| ``` | |
| 行 0：pearson_QK 定律1 谱线性对齐 | |
| 行 1：ssr_QK 定律2 谱形状保真度 | |
| 行 2：alpha_QK 定律1+2 尺度因子α | |
| 行 3：sigma_max_Q 定律3 最大奇异值(Q) | |
| 行 4：sigma_max_K 定律3 最大奇异值(K) | |
| 行 5：cond_Q + cond_K 定律3 条件数κ（双线，对数坐标） | |
| 行 6：cosU_QK 定律4 输出子空间 Q-K | |
| 行 7：cosU_QV 定律4 输出子空间 Q-V（超正交） | |
| 行 8：cosU_KV 定律4 输出子空间 K-V（超正交） | |
| 行 9：cosV_QK 定律5 输入子空间 Q-K | |
| 行10：cosV_QV 定律5 输入子空间 Q-V | |
| 行11：cosV_KV 定律5 输入子空间 K-V | |
| ``` | |
| --- | |
| #### `ui/tab_tables.py` — Tab6：论文表格 | |
| **一键生成6张论文表格，数据来源：language modality + standard layers only。** | |
| **函数：** | |
| ```python | |
| def generate_tables(selected_models, table2_model_a, table2_model_b, group_text) | |
| -> (status, t1~t6 DataFrames, latex_str, md_str, csv×6, latex_file, md_file, zip): | |
| """ | |
| 工作流程： | |
| 1. _load_all_models(selected_models) ← 从DB读取所有选中模型数据 | |
| 2. _parse_groups(group_text) ← 解析用户定义的层组（如"0-11,12-23"） | |
| 3. generate_all_tables() ← core/table_gen.py 生成6张表 | |
| 4. format_all_latex() / format_all_markdown() ← 格式化输出 | |
| 5. 保存 CSV × 6 + .tex + .md → 打包 ZIP | |
| 返回：所有输出供 Gradio 组件展示和下载 | |
| """ | |
| def build_tab_tables(): | |
| """ | |
| UI分为： | |
| - 模型多选框（CheckboxGroup）+ Refresh按钮 | |
| - Table2专用：Model A / Model B 下拉 + 层组输入框 | |
| - 🚀 Generate All Tables 按钮 | |
| - 6个 Accordion，每个内含 DataFrame + CSV下载 | |
| - LaTeX / Markdown 代码框（可直接复制粘贴） | |
| - 批量下载：.tex / .md / ZIP | |
| """ | |
| ``` | |
| **6张表说明：** | |
| | 表格 | 内容 | 对应定律 | | |
| | ------- | ------------------------------------------ | --------- | | |
| | Table 1 | 跨模型汇总：Pearson r, SSR | 定律1 & 2 | | |
| | Table 2 | SSR 层组趋势（RL改善效果，用户自定义层组） | 定律2 | | |
| | Table 3 | 输出子空间 cosU：Q-K, Q-V, K-V + 随机基线 | 定律4 | | |
| | Table 4 | 输入子空间 cosV：Q-K, Q-V, K-V + 随机基线 | 定律5 | | |
| | Table 5 | 条件数κ：全层/第0层/深层 分别统计 | 定律3 | | |
| | Table 6 | Wang Score 排行榜（按分降序） | 定律1 & 2 | | |
| --- | |
| ### 5.4 `app.py`——主入口 | |
| ```python | |
| # 启动时执行（模块级） | |
| init_db() # 建表，幂等 | |
| # Gradio Blocks | |
| with gr.Blocks(...) as demo: | |
| # 标题 + 五定律表格（英中双语并排）+ DOI徽章 | |
| with gr.Tabs(): | |
| inspect_model_id, inspect_token = build_tab_inspect() | |
| analyze_model_id, analyze_token = build_tab_analyze() | |
| build_tab_leaderboard() | |
| build_tab_database() | |
| build_tab_plot() | |
| build_tab_tables() | |
| # Tab1 → Tab2 联动（避免重复输入） | |
| inspect_model_id.change(fn=lambda x:x, | |
| inputs=inspect_model_id, outputs=analyze_model_id) | |
| inspect_token.change(fn=lambda x:x, | |
| inputs=inspect_token, outputs=analyze_token) | |
| ``` | |
| --- | |
| ## 6. 数据库表结构 | |
| 共4张表，SQLite 存储于 `/data/wang_laws.db`。 | |
| ### `models` — 模型基本信息 | |
| ```sql | |
| CREATE TABLE models ( | |
| model_id TEXT PRIMARY KEY, -- "google/gemma-4-e2b" | |
| model_type TEXT, -- "gemma4" / "qwen2" 等 | |
| analyzed_at TIMESTAMP, -- 最后分析时间 | |
| analyze_sec REAL, -- 本次分析总耗时（秒） | |
| notes TEXT -- 备注 | |
| ); | |
| ``` | |
| ### `components` — 组件信息 | |
| ```sql | |
| CREATE TABLE components ( | |
| id INTEGER PRIMARY KEY AUTOINCREMENT, | |
| model_id TEXT NOT NULL, | |
| prefix TEXT NOT NULL, -- "model.language_model." | |
| n_layers INTEGER, -- 该组件完整层数 | |
| head_dim_min INTEGER, -- 最小head_dim（异构层存在时有意义） | |
| head_dim_max INTEGER, -- 最大head_dim | |
| has_kv_shared INTEGER DEFAULT 0, -- 是否有K=V共享层 | |
| has_global INTEGER DEFAULT 0, -- 是否有global层 | |
| d_model INTEGER, -- 输入维度 | |
| UNIQUE(model_id, prefix) | |
| ); | |
| ``` | |
| ### `layer_head_metrics` — 逐头原始数据（主数据表） | |
| ```sql | |
| CREATE TABLE layer_head_metrics ( | |
| id INTEGER PRIMARY KEY AUTOINCREMENT, | |
| model_id TEXT NOT NULL, | |
| prefix TEXT NOT NULL, | |
| layer INTEGER NOT NULL, | |
| layer_type TEXT DEFAULT 'standard', -- "standard" / "global" | |
| kv_head INTEGER NOT NULL, | |
| q_head INTEGER NOT NULL, | |
| kv_shared INTEGER DEFAULT 0, -- 1=K=V共享（理论值），0=正常 | |
| head_dim INTEGER, | |
| d_model INTEGER, | |
| n_q_heads INTEGER, | |
| n_kv_heads INTEGER, | |
| -- 第一定律 | |
| pearson_QK REAL, spearman_QK REAL, pearson_QV REAL, pearson_KV REAL, | |
| -- 第二定律 | |
| ssr_QK REAL, ssr_QV REAL, ssr_KV REAL, | |
| -- 第三定律 | |
| sigma_max_Q REAL, sigma_min_Q REAL, cond_Q REAL, | |
| sigma_max_K REAL, sigma_min_K REAL, cond_K REAL, | |
| sigma_max_V REAL, sigma_min_V REAL, cond_V REAL, | |
| -- 第四定律 | |
| cosU_QK REAL, cosU_QV REAL, cosU_KV REAL, | |
| -- 第五定律 | |
| cosV_QK REAL, cosV_QV REAL, cosV_KV REAL, | |
| -- 尺度因子 | |
| alpha_QK REAL, alpha_res_QK REAL, | |
| alpha_QV REAL, alpha_res_QV REAL, | |
| alpha_KV REAL, alpha_res_KV REAL, | |
| UNIQUE(model_id, prefix, layer, kv_head, q_head) | |
| ); | |
| ``` | |
| ### `model_summary` — 汇总统计（排行榜用） | |
| ```sql | |
| CREATE TABLE model_summary ( | |
| model_id TEXT NOT NULL, | |
| prefix TEXT NOT NULL, | |
| layer_type TEXT NOT NULL DEFAULT 'all', -- all/standard/global | |
| -- 第一定律 | |
| median_pearson_QK REAL, mean_pearson_QK REAL, | |
| -- 第二定律 | |
| median_ssr_QK REAL, mean_ssr_QK REAL, | |
| median_ssr_QV REAL, mean_ssr_QV REAL, | |
| -- 第三定律 | |
| median_cond_Q REAL, mean_cond_Q REAL, | |
| -- 第四定律 | |
| median_cosU_QK REAL, median_cosU_QV REAL, | |
| -- 第五定律 | |
| median_cosV_QK REAL, median_cosV_QV REAL, | |
| -- 王氏评分（始终用standard层计算，即使layer_type=all/global） | |
| wang_score REAL, | |
| n_layers INTEGER, | |
| n_records INTEGER, | |
| updated_at TIMESTAMP, | |
| PRIMARY KEY(model_id, prefix, layer_type) | |
| ); | |
| ``` | |
| **每个(model_id, prefix)在model_summary中有3行：** | |
| ``` | |
| (model_id, prefix, "all") ← 全部层混合统计 | |
| (model_id, prefix, "standard") ← 只含standard层 | |
| (model_id, prefix, "global") ← 只含global层（如Gemma全局层） | |
| ``` | |
| **layer_type 推断规则（零hard coding）：** | |
| ``` | |
| kv_shared=True → layer_type="global" | |
| kv_shared=False → layer_type="standard" | |
| ``` | |
| --- | |
| ## 7. 数据流全链路 | |
| ``` | |
| 用户输入模型ID（如 "google/gemma-4-e2b"） | |
| │ | |
| ▼ | |
| [Tab1 或 Tab2] | |
| check_quantization() | |
| → 检测config.json / 模型名 / 文件列表 / header内容 | |
| → 量化模型直接拒绝 | |
| │ | |
| ▼ | |
| load_all_shard_headers() | |
| → 对每个.safetensors文件： | |
| HTTP GET bytes=0-7 → header_size（8字节小端整数） | |
| HTTP GET bytes=8-{8+size} → JSON header | |
| → 返回 {filename: (header_dict, header_size)} | |
| │ | |
| ▼ | |
| scan_model_structure() | |
| → 两遍扫描所有key → 构建 {(prefix,layer): LayerProfile} | |
| → 自动推断：head_dim / n_q_heads / n_kv_heads / kv_shared | |
| │ | |
| ▼（Tab2专有） | |
| 断点续传检查 | |
| → get_analyzed_layers() → done_layers: dict[prefix, set[int]] | |
| │ | |
| ▼（逐层循环） | |
| load_tensor_remote(W_q) → HTTP GET bytes={abs_start}-{abs_end} | |
| load_tensor_remote(W_k) → 同上 | |
| load_tensor_remote(W_v) → 同上（kv_shared时直接clone W_k） | |
| │ | |
| ▼ | |
| analyze_layer(W_q, W_k, W_v, profile) | |
| → 按head切片 | |
| → SVD分解每个head | |
| → 计算37个指标 | |
| → 返回 records: list[dict] | |
| │ | |
| ▼ | |
| write_layer_records(conn, model_id, records) | |
| → INSERT OR REPLACE 批量写入 layer_head_metrics | |
| │ | |
| ▼ | |
| update_model_summary(conn, model_id, prefix) | |
| → 查询 layer_head_metrics | |
| → 计算 median/mean | |
| → wang_score = 1 - median(ssr_QK) [用standard层] | |
| → INSERT OR REPLACE 写入 model_summary（all/standard/global 3行） | |
| │ | |
| ▼ | |
| [Tab3 排行榜] | |
| get_leaderboard() | |
| → SELECT from model_summary WHERE layer_type='standard' | |
| → ORDER BY wang_score DESC | |
| → 格式化展示 | |
| ``` | |
| --- | |
| ## 8. 函数调用关系图 | |
| ``` | |
| app.py | |
| ├── init_db() [db/schema.py] | |
| ├── build_tab_inspect() [ui/tab_inspect.py] | |
| │ └── inspect_model() | |
| │ ├── check_quantization() [core/fetcher.py] | |
| │ ├── extract_config_params() [core/layer_profile.py] | |
| │ ├── load_all_shard_headers() [core/fetcher.py] | |
| │ │ ├── get_all_shard_files() | |
| │ │ │ └── find_index_file() | |
| │ │ └── read_safetensors_header() | |
| │ ├── scan_model_structure() [core/layer_profile.py] | |
| │ │ ├── classify_qkv_suffix() | |
| │ │ ├── is_norm_key() | |
| │ │ └── _infer_head_dim() | |
| │ └── summarize_structure() | |
| │ | |
| ├── build_tab_analyze() [ui/tab_analyze.py] | |
| │ └── run_analysis() | |
| │ ├── init_db() [db/schema.py] | |
| │ ├── check_quantization() [core/fetcher.py] | |
| │ ├── extract_config_params() [core/layer_profile.py] | |
| │ ├── load_all_shard_headers() [core/fetcher.py] ← 成功后才写DB | |
| │ ├── scan_model_structure() [core/layer_profile.py] | |
| │ ├── upsert_model() [db/writer.py] ← 在此之后写入 | |
| │ ├── upsert_component() [db/writer.py] | |
| │ ├── get_analyzed_layers() [db/writer.py] | |
| │ ├── load_tensor_remote() ×3 [core/fetcher.py] | |
| │ ├── analyze_layer() [core/metrics.py] | |
| │ │ ├── pearson() | |
| │ │ ├── spearman_r() | |
| │ │ ├── ssr() | |
| │ │ ├── svr() | |
| │ │ ├── cos_U() | |
| │ │ ├── cos_V() | |
| │ │ └── sigma_stats() | |
| │ ├── write_layer_records() [db/writer.py] | |
| │ │ └── infer_layer_type() | |
| │ ├── update_model_summary() [db/writer.py] | |
| │ │ ├── _pseudobulk_col() | |
| │ │ └── _calc_summary_row() | |
| │ └── summarize_records() [core/metrics.py] | |
| │ | |
| ├── build_tab_leaderboard() [ui/tab_leaderboard.py] | |
| │ └── load_leaderboard() | |
| │ ├── init_db() [db/schema.py] | |
| │ ├── refresh_all_summaries() [db/writer.py] | |
| │ │ └── update_model_summary() ×N | |
| │ ├── get_leaderboard() [db/reader.py] | |
| │ └── _format_leaderboard() | |
| │ | |
| ├── build_tab_database() [ui/tab_database.py] | |
| │ ├── load_db_stats() | |
| │ │ └── get_db_stats() [db/schema.py] | |
| │ ├── load_model_list() | |
| │ │ └── get_analyzed_models() [db/reader.py] | |
| │ ├── run_delete_model() | |
| │ │ ├── delete_model() [db/writer.py] | |
| │ │ │ └── check_write_permission() | |
| │ │ └── load_model_list() ← 删除后自动刷新 | |
| │ ├── load_model_detail() | |
| │ │ ├── get_model_summary() [db/reader.py] | |
| │ │ └── get_resume_status() [db/reader.py] | |
| │ └── load_layer_data() | |
| │ └── get_layer_metrics() [db/reader.py] | |
| │ | |
| ├── build_tab_plot() [ui/tab_plot.py] | |
| │ ├── gen_single_plotly() | |
| │ │ ├── get_layer_metrics() [db/reader.py] | |
| │ │ └── plotly_single() [core/plotter_plotly.py] | |
| │ ├── gen_single_export() | |
| │ │ ├── get_layer_metrics() [db/reader.py] | |
| │ │ ├── plot_single_model() [core/plotter.py] | |
| │ │ └── save_figure() | |
| │ ├── gen_compare_plotly() | |
| │ │ ├── get_layer_metrics() ×2 [db/reader.py] | |
| │ │ └── plotly_compare() [core/plotter_plotly.py] | |
| │ └── gen_compare_export() | |
| │ ├── get_layer_metrics() ×2 [db/reader.py] | |
| │ ├── plot_compare_models() [core/plotter.py] | |
| │ └── save_figure() | |
| │ | |
| └── build_tab_tables() [ui/tab_tables.py] | |
| └── generate_tables() | |
| ├── get_layer_metrics() ×N [db/reader.py] | |
| ├── generate_all_tables() [core/table_gen.py] | |
| │ ├── make_table1() | |
| │ ├── make_table2() | |
| │ ├── make_table3() | |
| │ ├── make_table4() | |
| │ ├── make_table5() | |
| │ └── make_table6() | |
| ├── format_all_latex() | |
| └── format_all_markdown() | |
| ``` | |
| --- | |
| ## 9. 关键设计决策 | |
| ### 零 hard coding 原则 | |
| 任何模型相关的参数（head_dim、层数、组件结构） | |
| 都从权重文件的 key 名自动推断，不写死任何模型名或层号。 | |
| ### GQA 支持 | |
| 当 `n_q_heads > n_kv_heads` 时（如 Llama-3-8B 的 32Q/8KV）， | |
| `group = n_q / n_kv`，每个KV head对应group个Q head， | |
| 全部独立计算，每个Q head一条记录。 | |
| ### K=V 共享（Gemma全局层） | |
| Gemma-4-31B 每6层有一个全局层，V权重不存在（K和V共享）。 | |
| 检测方式：V的key不在任何shard的header中。 | |
| 处理方式：`W_v = W_k.clone()`，KV相关指标设为理论值。 | |
| 存储方式：`kv_shared=1`，`layer_type="global"`。 | |
| ### 断点续传粒度 | |
| 以 `(model_id, prefix, layer)` 为粒度。 | |
| 某层的所有head全部写入才算完成。 | |
| 允许随时中断，下次从未完成的层继续。 | |
| ### 排行榜的 wang_score | |
| 无论 `model_summary` 的 `layer_type` 是 all/standard/global， | |
| `wang_score` 统一从 standard 层的 `ssr_QK` 计算， | |
| 避免全局层（K=V共享，SSR=0）人为拉高评分。 | |
| ### 每个(model_id, prefix)在排行榜中是一行 | |
| 排行榜以 `(model_id, prefix)` 为单位， | |
| 多模态模型（如Gemma-4）的language_model和vision_tower分别占一行。 | |
| ### 防脏数据写入（Lazy Write） | |
| `upsert_model()` 和 `upsert_component()` 故意推迟到 `load_all_shard_headers()` 成功之后才调用。 | |
| 模型名拼写错误（如 "Meta-Llama-3-70B-intruct" 少一个s）会在 HF 返回 404 时提前 return， | |
| DB 中零污染。旧版本在量化检测通过后立即写入，会留下只有名字没有数据的孤立行，污染 Tab4/5/6。 | |
| ### Pseudo-bulk 两步聚合（GQA 伪重复问题） | |
| GQA 模型（如 LLaMA-3-8B 32Q/8KV）中，同一 KV head 下的多个 Q head 共享同一 K， | |
| 彼此强相关。若直接对所有头做 median，等价于对 KV head 的指标重复计数 group 次（伪重复）。 | |
| 标准做法（Nature Comms 2021）： | |
| ``` | |
| Step 1: groupby(layer, kv_head).median() → 每KV head一个值，消除组内相关 | |
| Step 2: 对Step1结果做 median/mean → 每层一个无偏代表值 | |
| ``` | |
| 实现在 `db/writer._pseudobulk_col()` 和 `core/plotter._aggregate_by_layer()`。 | |
| Tab3 Refresh 按钮触发 `refresh_all_summaries()` 自动将历史数据重算为 pseudo-bulk。 | |
| ### 级联删除与写入权限统一验证 | |
| `delete_model()` 和所有写库操作均通过同一个 `check_write_permission(admin_token)` 验证， | |
| 后者对比环境变量 `WRITE_TOKEN`（HF Space Secrets 注入）。 | |
| 删除顺序严格遵循外键依赖：`layer_head_metrics → model_summary → components → models`。 | |
| 删除后返回各表实际删除行数，便于审计确认。 | |
| --- | |
| ## 10. 部署说明 | |
| ### HuggingFace Space 部署 | |
| 1. 创建 Space，选择 Gradio SDK | |
| 2. 在 Space Settings 中添加 **Persistent Storage**（挂载到 `/data`） | |
| - `wang_laws.db` 重启后不丢失 | |
| 3. 上传所有文件（保持目录结构） | |
| 4. 如需访问私有模型，在 Space Secrets 中设置 `HF_TOKEN` | |
| #### 配置管理员写入权限（重要） | |
| 在 **Space Settings → Secrets** 中添加： | |
| | Secret 名称 | 值 | 说明 | | |
| | ------------- | ---------------- | ------------------------------- | | |
| | `WRITE_TOKEN` | 你自己设置的密码 | 管理员写库密钥，不进入 git repo | | |
| **工作原理：** | |
| ``` | |
| HF Space Secrets（加密存储，不在 git 中） | |
| ↓ HF 运行时自动注入 | |
| Docker 容器环境变量 WRITE_TOKEN | |
| ↓ 服务端读取 | |
| os.environ.get("WRITE_TOKEN") | |
| ↓ 与用户输入的 Admin Token 比对（纯服务端，前端不可见） | |
| True → 写入数据库 | |
| False → 只读模式，分析正常运行 | |
| ``` | |
| **三类用户的体验：** | |
| | 用户 | Admin Write Token | 行为 | | |
| | --------------- | ----------------- | ---------------------------------- | | |
| | 你（管理员） | 填写正确密钥 | 分析结果写入数据库，排行榜更新 | | |
| | 审稿人 / 复现者 | 留空 | 分析正常运行，指标完整显示，不写库 | | |
| | 恶意用户 | 随意填写 | 分析可以跑，写库被拒绝 | | |
| **未配置 `WRITE_TOKEN` 时：** | |
| ```python | |
| # check_write_permission() 的行为： | |
| server_token = os.environ.get("WRITE_TOKEN", "") | |
| if not server_token: | |
| return False # 服务端未配置 → 拒绝所有写入 | |
| ``` | |
| 即使有人猜到任意字符串也无法写入。 | |
| ### 本地运行 | |
| ```bash | |
| pip install -r requirements.txt | |
| # 可选：设置写入权限 | |
| export WRITE_TOKEN="your_secret_password" | |
| python app.py | |
| # 浏览器打开 http://127.0.0.1:7860 | |
| ``` | |
| 本地运行时数据库存于当前目录的 `wang_laws.db`。 | |
| 不设置 `WRITE_TOKEN` 则所有人都是只读模式。 | |
| ``` | |
| --- | |
| ## 改动汇总 | |
| | 文件 | 改动 | | |
| | ----------------------- | ---------------------------------------------------------------------------- | | |
| | `db/writer.py` | 末尾追加 `check_write_permission()`，其余不变 | | |
| | `ui/tab_analyze.py` | 完整重写：加 `admin_token` 参数，所有写库操作加 `can_write` 判断，日志改英文 | | |
| | `README.md` | 第10节部署说明扩充写权限配置说明 | | |
| | `db/schema.py` | 不变 | | |
| | `db/reader.py` | 不变 | | |
| | `ui/tab_inspect.py` | 不变 | | |
| | `ui/tab_leaderboard.py` | 不变 | | |
| | `ui/tab_database.py` | 不变 | | |
| | `app.py` | 不变 | | |
| ### 注意事项 | |
| - 分析大模型（如 70B）时每层需要约 30 秒（受 HF CDN 网速限制） | |
| - HF Space 免费版有 48 小时超时限制，建议开启断点续传分批分析 | |
| - 量化模型（GPTQ/AWQ/GGUF）自动拒绝，需使用原始 BF16 版本 | |
| --- | |
| ## 11. 依赖清单 | |
| ``` | |
| gradio>=4.0.0 # Web UI 框架 | |
| requests # HTTP Range Request 读取远程权重 | |
| numpy # 数值计算（统计汇总） | |
| scipy # spearman相关系数 | |
| torch # SVD分解（torch.linalg.svd） | |
| huggingface_hub # list_repo_files（文件列表） | |
| matplotlib # 静态图导出（PNG/PDF/SVG，300dpi，论文级） | |
| plotly # 交互图（12×1全宽，浏览器内hover/zoom） | |
| ``` | |
| Python 内置（无需安装）： | |
| ``` | |
| sqlite3 # 数据库 | |
| struct # 解析safetensors header的8字节整数 | |
| json # 解析safetensors header JSON | |
| re # 正则提取层号 | |
| datetime # 时间戳 | |
| dataclasses # LayerProfile数据结构 | |
| ``` | |
| --- | |
| ## 12. 改动历史 | |
| ### v0.1 — 初始版本（Tab1~4） | |
| - Tab1 Inspect：模型结构探测，零下载，仅读 safetensors header | |
| - Tab2 Analyze：HTTP Range Request 逐层分析，写库，断点续传 | |
| - Tab3 Leaderboard：Wang Score 排行榜 | |
| - Tab4 Database：数据库浏览，逐头原始数据查询 | |
| ### v0.2 — 作图与论文表格（Tab5~6） | |
| - 新增 `core/plotter.py`：matplotlib 4×3 静态图，18×20in @ 300dpi | |
| - 新增 `core/plotter_plotly.py`：原生 Plotly 12×1 交互图，全宽自适应 | |
| - 新增 `ui/tab_plot.py`（Tab5）：两条渲染路径（⚡Interactive / 🖨️Export） | |
| - 新增 `core/table_gen.py`：6张论文表格生成（LaTeX/Markdown/CSV） | |
| - 新增 `ui/tab_tables.py`（Tab6）：一键生成，批量下载 | |
| - `app.py` 双语改造：英文在左，中文在右，两列并排表格 | |
| ### v0.3 — Pseudo-bulk 聚合 + 防脏数据 + 级联删除 | |
| **问题修复：** | |
| - `ui/tab_analyze.py`：`upsert_model` / `upsert_component` 推迟到 `load_all_shard_headers()` 成功后执行，防止模型名拼错产生脏数据 | |
| **新功能：** | |
| - `db/writer.py`：新增 `_pseudobulk_col()`，`update_model_summary()` 改用 pseudo-bulk 两步聚合，消除 GQA 伪重复计数偏差 | |
| - `db/writer.py`：新增 `refresh_all_summaries()`，Tab3 Refresh 按钮触发，自动将历史数据重算为 pseudo-bulk | |
| - `db/writer.py`：新增 `delete_model(conn, model_id, admin_token)`，级联删除模型所有数据，需 WRITE_TOKEN 验证 | |
| - `ui/tab_database.py`：新增 🗑️ Delete Model 区块，删除成功后自动刷新模型列表 | |
| - `ui/tab_inspect.py`：全文翻译为英文，逻辑不变 | |
| **改动文件汇总：** | |
| | 文件 | 类型 | 说明 | | |
| | -------------------- | ---- | ------------------------------------------------------- | | |
| | `db/writer.py` | 更新 | 新增 pseudo-bulk / refresh_all_summaries / delete_model | | |
| | `ui/tab_analyze.py` | 修复 | upsert_model 推迟到 shard headers 加载成功后 | | |
| | `ui/tab_database.py` | 更新 | 新增删除模型 UI | | |
| | `ui/tab_inspect.py` | 重构 | 全文英文化 | |