# Polarbear递归自我进化 Transforms 架构 **Repository Path**: Mint-Space/polarbear ## Basic Information - **Project Name**: Polarbear递归自我进化 Transforms 架构 - **Description**: 基于 [Mint]谱系的 **递归自我进化 Transforms 架构**。 Mint 把 Decoder-only Transformer 从零写在 Rust 里(RMSNorm / RoPE / SwiGLU / 手写 CUDA)。 Polarbear 再往前走一步:**把架构本身变成可递归组合、可突变、可进化的数据**。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-21 - **Last Updated**: 2026-09-21 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Polarbear 基于 [Mint](../../Mint) 谱系的 **递归自我进化 Transforms 架构**。 Mint 把 Decoder-only Transformer 从零写在 Rust 里(RMSNorm / RoPE / SwiGLU / 手写 CUDA)。 Polarbear 再往前走一步:**把架构本身变成可递归组合、可突变、可进化的数据**。 ``` Mint: 代码里写死 Embedding → L × Block → Head Polarbear: Genome 树(可嵌套 Recursive) → 突变 → 适应度选择 → 改写树 ``` > 五份文档各管一段:[USAGE](USAGE.md) 怎么用、[DESIGN](DESIGN.md) 为什么这样设计、 > [TRAINING](TRAINING.md) 怎么调、[CHANGELOG](CHANGELOG.md) 曾经错在哪。本文只讲是什么。 ## 核心思想 ### 1. TransformSpec — 架构即数据 ```text Identity 恒等(中性漂变位点) Attention { heads } 因果 MHA + RoPE SwiGLU { d_ff } 门控前馈 Residual { inner } x + inner(x) Seq { steps } 顺序组合 Recursive { depth, tied, body } 递归自应用 DecoderBlock { heads, d_ff } 标准 Pre-Norm 解码块 ``` `Recursive` 是递归的关键: | `tied` | 含义 | |---|---| | `true` | body 权重共享,真正递归(Universal Transformer / ALBERT 风格) | | `false` | 每次展开独立参数(堆叠层) | body 本身还可以是 `Recursive` / `Seq`,形成任意深度的自相似结构。例如: ```text Rec[untied×2]( Seq[ Block(h=4, ff=96) → Rec[tied×2](Block(h=2, ff=64)) ] ) ``` 展开深度 = 2 × (1 + 2) = **6** 个块应用。 ### 2. 突变算子(改写树) - `depth±` — 增减 Recursive 深度 - `heads` / `ffn` — 改头数或 FFN 倍率 - `nest_recursive` — 在 Block 外再包一层 Recursive - `insert_identity` — 插入恒等(中性突变) - `toggle_tied` — 切换权重共享 - `wrap_residual` — 额外残差包装 非法配置(头数不整除 d_model、展开过深)会在突变后自动修复。 ### 3. 进化循环 ```text 初始化种群(Mint 式堆叠 + 真递归 tied 种子) for each generation: 每个个体:物化模型 → 短训 N 步 → 验证损失 fitness = val_loss + λ · relative_complexity 保留 elite 突变产生子代 归档历史最优(hall of fame,满了淘汰最差的) 最终落盘: 冠军架构 → models/polarbear-genome-<数据集>-<架构>-<时间戳>.json 冠军权重 → models/polarbear-champion-<数据集>-<架构>-<时间戳>.json (每代只要冠军被刷新就更新一次,见「进化中的冠军会边跑边落盘」) ``` 复杂度惩罚防止无意义加深。 ## 与 Mint 的关系 | 维度 | Mint | Polarbear | |---|---|---| | 架构位置 | 代码硬编码 | Genome 树(数据) | | 层数 | 配置字段 | `Recursive.depth` 可突变 | | 嵌套 | 无 | body 可再含 Recursive | | 权重共享 | 无 | tied recursion | | 优化目标 | 固定架构训权重 | **架构 + 权重双层进化** | | 数学组件 | RMSNorm/RoPE/SwiGLU/MHA | 同源,全部保留并手写反向 | | 设备 | GPU CUDA | GPU CUDA(Mint 核函数)+ CPU 回退 | ## 目录 ```text src/ lib.rs 库入口:data / evolve / genome / gpu / gpu_train / runtime / tensor main.rs CLI(bin):全部子命令、参数校验、交互菜单;另外以 mod 引入下面两个 tensor.rs 张量与核心算子(含 RMSNorm 有限差分测试) genome.rs TransformSpec 树 + 突变算子 + 校验(check_heads / canonical / unrolled_slots) runtime.rs 物化模型 + CPU 前向/反向 + SGD + 全局范数裁剪 + 检查点读写与校验 gpu/ 手写 CUDA:kernels.cu / FFI / ops / 设备初始化与自检 gpu_train.rs GPU 常驻训练器:展开后的块序列、分块批、块对角掩码 data.rs 语料加载:格式嗅探、蓄水池抽样、窗口化打包、内存预算 evolve.rs 种群 / 适应度 / 进化引擎 / 冠军权重保留 naming.rs (bin)文件命名与列表、按验证损失清理、评分缓存 ui.rs (bin)终端界面:颜色、实时进度条、赞赏二维码、训练热键 icon/ gratuity.jpg 赞赏二维码原图 gratuity.ans/.ascii 由 tools/gratuity_art.py 生成并嵌入二进制的终端图案 tools/ gratuity_art.py 二维码 → 终端图案(含网格对齐校验) hotkey_check.ps1 训练热键的端到端检查(注入真实按键事件) data/ 语料(gitignore):data/<名字>/ 自动发现 models/ 全部产物(gitignore):类别 / 数据集 / 架构 / 时间戳 dist/ 打包产物(gitignore) ``` `naming` 与 `ui` 只在 bin 里编译,其余在库里——这决定了 `cargo test` 的分半:它们的测试 算在 CLI 那一半里。 ## 构建与运行 默认启用 `cuda`(需 CUDA Toolkit + MSVC,与 Mint 相同)。 ```powershell cargo test -- --test-threads=1 cargo run --release -- gpu cargo run --release -- datasets # data/ 下有哪些语料 cargo run --release -- train --steps 300 # 省略 --data 时用第一个数据集 cargo run --release -- chat # 交互对话 cargo run --release -- evolve --pop 12 --gens 8 --steps 30 ``` 无 GPU 或 `--no-gpu` 时自动走 CPU。不带参数启动进入交互菜单。 ### CLI | 命令 | 说明 | |---|---| | `train` | 训练 / **继续训练** / 用进化架构训练 | | `chat` | 交互式生成:多轮上下文 + 流式输出 | | `sample` | 一次性采样 | | `evolve` | 架构进化,写冠军 genome 与冠军模型 | | `models` | 列出 `models/` 下的模型(最新的在最上面);`--score` 附带验证损失 | | `thanks` | 显示赞赏二维码(`--open` 打开原图) | | `datasets` / `inspect` / `demo` | 数据目录 / 查看模型 / 快速演示 | | `gpu` | 设备诊断:显存用量 + 跑一次真实内核的自检(`--selftest`) | 不指定 `--model` 时,`chat` / `sample` / `inspect` 自动载入 `models/` 里**最新**的一个 (按文件名里的时间戳判断,见「模型保存」)。 ### 训练 一个命令覆盖三种任务: ```powershell # 1) 从头训练种子模型(省略 --data 时用 data/ 下第一个数据集) polarbear train --steps 300 # 2) 加载已保存模型继续训练(微调)——沿用它的架构与词表 polarbear train --model models/polarbear-trained-LCCC-base-split-d32-l2-h4-<时间戳>.json --steps 200 # 3) 用进化出的架构从头训练 polarbear train --genome models/polarbear-genome-LCCC-base-split-d32-x4-g3-<时间戳>.json --steps 300 # 4) 指定语料与规模 polarbear train --data LCCC-base-split --steps 2000 --batch 8 --gpu-only ``` | 选项 | 说明 | |---|---| | `--model FILE` | 继续训练该检查点(保留架构 + 词表;词表必须与数据集一致) | | `--genome FILE` | 用该 genome 的架构从头训练 | | `--steps` `--batch` `--lr` `--seq` | 步数 / 批大小 / 学习率 / 序列长度 | | `--d-model` `--layers` `--heads` | 新建种子架构的形状 | | `--eval-every N` | 每 N 步验证一次(默认 10) | | `--save-every N` | 周期性存档间隔(默认 0 = 不写周期存档) | | `--patience N` | 连续 N 次验证无改进就早停(0=关闭) | | `--min-delta F` | 算作改进的最小验证损失下降(默认 1e-4) | | `--samples N` | 训练样本数上限;0(默认)= 用整个语料,超出内存预算时整文件均匀抽样 | | `--keep N` | 每个"数据集+架构"保留的检查点数(默认 1,0=全留)。架构取自检查点**内的基因组**,不是名字——名字里的架构段是有损摘要,两个不同架构可能同名 | | `--seed N` | 初始化种子;默认是固定常数,**与 `--steps`/`--batch`/`--lr`/`--epochs` 无关**,只改训练长度的对照实验共用同一个初始化 | | `--out FILE` | 最优检查点路径(默认按命名规范写入 `models/`;给了它就不做清理) | | `--no-gpu` `--gpu-only` | 强制 CPU / 禁止回退 | 训练特性:**warmup + 余弦学习率调度**、每步报告**困惑度**、验证改进只更新内存里的最优、 **跑完只写一次**最优检查点、可选周期存档、可选早停。微调默认学习率自动降到 0.02 (训练 0.06)。 训练中还可以随时按键干预(有真实控制台时才启用,见下): | 键 | 行为 | |---|---| | `S` | 立即把**当前**权重存成一个 `manual` 检查点,训练继续 | | `Q` | 停止训练,并同样存下当前权重(不覆盖最优检查点) | `Q` 不会丢结果:最优权重与「停止那一刻」的权重分别落在两个文件里。 ### 交互对话 ```powershell polarbear chat --model models/model_trained.json ``` ``` 你 › abcabc 模型 › abcabcabcabcabcabcabcabc... 60 tok · 8200.0 tok/s · 上下文 66 位置 ``` - **多轮记忆**:整个会话共用一个 KV cache,模型看得到之前的全部内容 - **增量解码**:第 n 个 token 只花 O(历史长度),不是 O(历史²) - **流式输出**:逐字打印 - **上下文预算**:`--ctx N`(默认 256 位置),超出自动裁剪最旧部分并提示 - 命令:`/help` `/clear` `/info` `/temp F` `/topk N` `/tokens N` `/ctx N` `/quit` > 这是**字符级续写**模型:它接着你的文字往下写。想让它真正按问答回复, > 需要用带对话轮次标记的数据训练(见下方"数据与损失掩码")。 ## 命令行界面 界面是手写的(不引入 UI 依赖,与项目从零手写的风格一致): - **彩色输出**:状态标签着色,改进项绿色、警告黄色、错误红色;标签按**显示宽度** 对齐,中英文混排不会错列 - **一个设计列宽**:横幅方框与所有分隔线同宽(取终端宽度,限制在 44–78 列), 窄窗口自动收窄、宽窗口不会拉成一条 200 列的长线;宽度可用 `POLARBEAR_WIDTH` 或 `COLUMNS` 指定 - **对齐表格**:`models` 用带表头和对齐标尺的表格;列宽按**可见宽度**(忽略 ANSI 颜色码、CJK 记 2 列)计算,所以给单元格上色也不会把列挤歪 - **紧凑统计行**:`kv_row` 把「词表 / 训练 / 验证 / 序列」排成一行对齐的键值对, 取代原来一串 `|` 拼成的长句 - **实时进度条**:训练时逐步刷新,显示百分比、步数、当前 loss、学习率、 已用时间与 ETA;验证结果打印在进度条上方 (`[ 20/300] val 1.5218 ppl 4.58 train 1.4089 lr 0.04223 ← 最优`) - **自动降级**:输出重定向到文件时不再画进度条,改为每若干步一行,日志干净可读 - **训练热键**:`S` 立即存档、`Q` 停止并保存(仅真实控制台可用,见「模型保存」) - **赞赏二维码**:`polarbear thanks` 直接在终端里画出二维码(编译期烘入,无需图片文件) - **环境变量**:`NO_COLOR=1` 关闭颜色、`POLARBEAR_ASCII=1` 用 `#`/`-` 进度条、 `POLARBEAR_FORCE_TTY=1` 强制实时进度条(适用于无法自动识别的终端) - Windows 下自动开启 ANSI 虚拟终端处理(`SetConsoleMode`,无额外依赖) **表格收缩曾经只调一列。** 终端的宽度不够时,旧代码只调整**最宽的那一列**,并把它夹在 `8` 以上,之后**从不复查总和**——于是多列都宽时行宽可以是终端宽度的两倍。实测 `POLARBEAR_WIDTH=30` 下数据行 **55** 字符、分隔线 62。现在按总和**逐列迭代收缩**(先把 最宽的削到下限,不够再削下一列),同一个例子降到 37 字符。 `MIN_COL = 8` 是一个**下限**:终端若窄到连"列数 × 8"都装不下,行仍然会溢出——把文件名 截到更短就完全读不出内容了,而读者可以调宽终端或用 `POLARBEAR_WIDTH`,这也是唯一能装下 超过下限的办法。 ``` ╔════════════════════════════════════════════════════════════════════════════╗ ║ Polarbear v1.0.0 · 训练 ║ ║ 从检查点继续训练 ║ ╚════════════════════════════════════════════════════════════════════════════╝ 数据集 LCCC-base-split 词表 2580 训练 4000 条 验证 400 条 序列 32 模型参数 29633 个 设备 GPU · NVIDIA GeForce RTX 3050 Laptop GPU 计划 300 步 | 批大小 16 | 学习率 0.02 → 0.00200(warmup 30) | 每 10 步验证 ████████████░░░░░░░░░░░░░░░░ 41% 122/300 loss 0.3412 lr 0.01704 1.2s eta 1.7s ``` ## 完全用 GPU 训练 训练的计算(前向、反向、SGD/Adam、梯度裁剪)全部在显存里完成, 权重自始至终不离开显卡。 - 权重在每个基因组评估开始时 `sync_from_model` 上传一次 - **只有冠军的权重会被保留**:其余个体评估完立即释放显存(`TrainedState::Discarded`) - 冠军权重一直留在 GPU,直到进化结束才一次性取回并落盘 - `--gpu-only` 关闭 CPU 回退:设备不可用、trainer 创建失败或 loss 非法时**直接报错**, 而不是静默降级到 CPU ```powershell polarbear evolve --data LCCC-base-split --gpu-only polarbear train --data LCCC-base-split --steps 200 --gpu-only ``` ### 怎么确认程序真的在用显卡 任务管理器的默认那栏「利用率」是 **3D** 引擎,而消费级驱动把 CUDA 计算就记在它上面—— 「Compute」那栏通常一直是 0%。所以只看默认视图容易得出「显卡没用上」的结论。三个办法: 1. `polarbear gpu` —— 现在会打印设备、**实时可用/总显存**,并**跑一次真实内核**报告实测吞吐: ``` 设备 NVIDIA GeForce RTX 3050 Laptop GPU 显存 3312 MB 可用 / 4095 MB 总计 自检 10 次 1024×1024 矩阵乘 15.2 ms(1417 GFLOPS)· 内核确实跑了 ``` 2. 训练/进化时看「专用 GPU 内存」:d32 的小模型常驻约 **70 MB**(实测峰值 72.7 MB), d256 会到几百 MB。这个数字比利用率更能说明问题。 3. Windows 自带的 GPU 计数器(和任务管理器同源): ```powershell Get-Counter "\GPU Engine(pid_*)\Utilization Percentage" ``` 训练时本进程在 `engtype_3d` 上有约 20% 的占用(同一时刻 `compute` 为 0)。 **推理(`chat` / `sample`)确实跑在 CPU 上**,这是刻意的,而且程序现在会明说: ``` 生成设备 CPU(生成在主机上:这个规模的模型,一次 GPU 内核启动比一次乘加还贵) ``` 理由是可以量化的:d32 模型一次前向的算术约 0.2 ms(CPU 带 KV 缓存实测 **5988 tok/s**), 而 GPU 路径每 token 要发起约 60 次内核启动(每次 5–10 µs),仅启动开销就是 0.3–0.6 ms。 小模型上 GPU 会**更慢**,所以默认不用;GPU 训练与进化仍然全程在设备上。 ### GEMM 内核已做寄存器分块(3–4 倍,但训练只快 7%) 这个自检曾经暴露:1024³ 矩阵乘只有 **269 GFLOPS**,而这张卡的 f32 峰值约 6 TFLOPS——即约 4%。原因是 `k_matmul_dev` 是朴素 16×16 分块、**每个线程只算一个输出**,内层每 2 次浮点运算 就要 2 次共享内存加载。 当时**先没有动它**,理由是:那一版 d32 的训练步是**内核启动主导**的,改 GEMM 对实际跑分 几乎没有影响。这个理由后来**被测量推翻**——批量前向把启动次数压下去之后,算力重新成为 主项,而且随宽度急剧上升(同 `--batch 16`:d64 21.2 ms/步、d128 21.9 ms、**d256 36.1 ms**, 第一次翻倍只 +3%,第二次 +70%)。 所以给它加了寄存器分块:16×16 的线程块算 64×64 的输出瓦片、每线程 4×4 存在寄存器里, 一个加载值复用 4 次,并有 4 条独立累加链。实测: | 指标 | 改前 | 改后 | |---|---|---| | 自检 1024³ | 47–80 ms(269–463 GFLOPS) | **15.2 ms(1417 GFLOPS)** | | 训练步 d128 | 21.9 ms | 20.6 ms(**−6%**) | | 训练步 d256 | 36.1 ms | 33.6 ms(**−7%**) | **为什么自检 3–4 倍而训练只快 7%**:训练里真正发出的 GEMM 是**高瘦型**——头部是 `[512×256]×[256×6755]`,B 操作数 6.9 MB、每个行块都要重读一遍,所以瓶颈是 **B 的带宽**; 寄存器复用减少的是共享内存加载,对带宽无能为力。正方形自检是**有利情形**,不是典型情形。 三个内核现在都做了寄存器分块:`k_matmul_t1`(`C = Aᵀ·B`)与 `k_matmul_t2`(`C = A·Bᵀ`)是**反向**用的转置变体,只差在加载寻址(t1 的 A 瓦片转置、t2 的 B 瓦片转置)。补齐它们比改前向收益更大——反向发出的矩阵乘更多:实测 **d256 从 33.6 降到 26.0 ms/步(−23%)**,d128 持平(在噪声内)。 ## GPU 实现要点 - `kernels.cu`:分块 matmul、RoPE、RMSNorm、SwiGLU、融合交叉熵、Adam、 两个"累加式"归约(`k_sum_acc` / `k_sum_sq_acc`),让一批/一轮的 loss 与梯度范数 各只回传一个标量 - tied Recursive 的多个 slot 把梯度累加到同一套共享参数 - **梯度按 token 归一化**,与 CPU 路径语义一致;全局范数裁剪(10.0)兜底 - `gpu_matmul*` / `gpu_add` 封装带形状断言:传错立即 panic,而不是静默越界写坏显存 - **显存缓冲按大小池化复用**:`cudaFree` 会同步设备,逐样本分配释放等于把 GPU 挂在 主机分配器上(见上表) - GPU 与 CPU 的前向等价性由 `gpu_forward_matches_cpu` 直接对拍保证 ## 模型保存 所有产物统一写在 **`models/`** 下(目录不存在时自动创建),文件名自带全部关键信息: ``` polarbear-<类别>-<数据集>-<架构>[-stepN]-.json │ │ │ │ └── 本地时间戳,永远是最后一段 │ │ │ └─────────── 可选标签:存档时的步数 │ │ └──────────────────── d32-l2-h4(层堆栈)或 d32-x4-g3(基因组的展开深度/参数组数) │ └──────────────────────────── 数据集名(中文也能保留,非法字符换成 -) └─────────────────────────────────── 类别 ``` | 类别 | 来源 | 内容 | |---|---|---| | `trained` | `train` 从头训练 | 最优(val 最小)权重 + 架构 + 词表 | | `finetuned` | `train --model` 继续训练 | 同上 | | `manual` | 训练中按 `S` / `Q` | 按键那一刻的权重 | | `snapshot` | `train --save-every` | 周期安全副本 | | `champion` | `evolve` | 冠军权重 + 架构 + 词表 | | `genome` | `evolve` | 冠军架构(纯 genome,体积很小) | 时间戳在**最末位**且定长,所以按文件名排序就是按时间排序——`models` 命令、以及 `chat` / `sample` / `inspect` 的「默认用最新那个」都只靠这一个规则,不需要额外的 "当前模型"指针文件。名字精确到秒,因此一次保存不会悄悄覆盖上一次的结果。 这里的"最新"指的是**最新的可加载产物**:`genome` 类别只有架构、没有权重,`chat` / `sample` 拿它当检查点会直接失败,所以它被跳过(目录里只剩 genome 时会退回最新项,`inspect` 照常)。 `evolve` 结束时写的 genome 用的是新时间戳、必然比运行中写的冠军更新,所以这条跳过不是 可选项。 **但同名比较不会无限堆积**:`trained` / `finetuned` 两个类别下,**每个数据集+架构 只保留验证损失最优的那一个文件**。训练结束时会把同组里更差的旧检查点删掉并逐条打印, 如果本次结果不如已有检查点,那么被删的就是本次结果,并明确提示。手动存档(S/Q)、 周期存档(`--save-every`)、进化冠军与 genome **一律不动**——它们不是别人的副本; 无法解析的文件也不删(看不懂的东西不该删)。用 `--keep N` 改变保留数量,`--keep 0` 彻底关闭清理;显式给了 `--out` 时不清理,因为路径是你自己指定的。 "同一个架构"按检查点**内部的基因组**判断,不是按文件名:名字里的架构段是给人看的摘要 (`d32-l2-h4` 只有宽度、展开深度和第一个 block 的头数),而"这是不是同一个模型"只有基因组 说得算。曾经按名字分组,于是 tied 与 untied 这种同名不同结构的两个架构会互相删除。 ``` ── 训练完成 ────────────────────────────────────────────────────────────────── 最优 val 8.4154(第 25 步) 输出 models\polarbear-trained-BelleGroup--train_0-5M_CN-d32-l2-h4-20260914-010228.json 清理 本次结果 polarbear-trained-...-010228.json(val 8.4154) 提示 该数据集+架构只保留最优,本次结果不如已有的检查点 保留 models\polarbear-trained-...-004512.json(该数据集+架构现存最优) 下一步: polarbear chat --model models\polarbear-trained-...-004512.json ``` (`latest()` 仍然取"最新的文件",清理之后它自然就落在存活下来的那些文件上。) ```powershell polarbear models # 列表:类别 / 名字 / 大小,最新在最上面 polarbear chat # 不带 --model:自动用最新那个 polarbear thanks # 赞赏二维码 # 显式指定输出路径(父目录会自动创建);此时按键存档会放在同一个目录下 polarbear train --data LCCC-base-split --out runs/exp1/model.json ``` ``` ── 模型列表 ───────────────────────────────────────── 目录 models 数量 9 个(最新的在最上面) › manual polarbear-manual-toy-d32-l2-h4-step74-20260913-234318.json 343 KB ← 最新,chat/sample 默认用它 trained polarbear-trained-toy-d32-l2-h4-20260913-234316.json 343 KB snapshot polarbear-snapshot-toy-d32-l2-h4-step15-20260913-234146.json 343 KB 命名: polarbear-<类别>-<数据集>-<架构>[-stepN]-<时间戳>.json ``` 检查点是**自包含**的:架构 + 全部参数张量 + **词表**,因此加载后无需再指定数据集。 - 格式 `polarbear-checkpoint-v1`,**原子且持久**地写入:先写 `<路径>.tmp`、`fsync` 刷到盘、再 rename 就位(Unix 下还会 flush 目录项)。原子性保证崩溃不会留下半截文件; fsync 保证**断电**也不会出现「rename 已可见、内容却还在页缓存」——长训练里最怕丢的 正是最优检查点。写失败时临时文件会被清掉,不留垃圾 - 序列化**直接从模型流式写出**(`CheckpointRef` 借用张量 + `to_writer` 直写文件), 不再先 clone 一份权重、再拼出整串 JSON;d256 规模下保存的峰值内存明显下降 - 加载时校验:格式串、参数组数、张量形状、词表长度 - **基因组必须与权重配对**:拿别人的张量配自己的基因组会被拒绝加载 (`checkpoint_rejects_genome_weight_pairing_mismatch`) - 词表随存档,修掉了此前"不带 `--data` 就套用内置词表 → 采样乱码"的问题 ### 最优检查点只在跑完时写一次 以前**每一次验证只要 val 变好就立刻把整份 checkpoint 重写一遍**(写到同一个 `out_path`)。 在 `--eval-every 10` 这种常规配置下,一个持续收敛的模型就是每 10 步重写一次;对 d256 那种 几百 MB 的检查点,这基本等于持续写盘,而每次的内容只比上一份好一点点。 现在最优权重**留在内存里,跑到最后才写一次**: - 验证改进只做 `best_weights = Some(当前权重)`,不再落盘;运行中不会出现任何「已保存」行 - 跑完、早停、发散中断、或按 `Q` 停止时,写到 `out_path` 的是**最优那一刻**的权重, 记的 `val_loss` 也是那个最优值——不是最后的损失 - 这一点实测过:用一个会发散的学习率跑,曲线在第 12 步最优(val 19.9545)、此后一路变差 到 20.4254,文件里记的是 **19.9545** - `Q` 另外还会把**停止那一刻**的权重写到旁边一个 `manual` 文件;两者含义不同,摘要分别列出 - 代价是**多占一份模型的内存**(d32 约 1 MB,d256 会到几百 MB) ### 验证损失的缓存(`models/.polarbear-index.json`) `val_loss` 存在检查点**文件内部**,所以 `models --score` 和每次训练结束时的清理都要把 文件逐个打开解析。现在同目录下多了一个 `models/.polarbear-index.json`,记着每个检查点的分数, 以及**读到它时的文件大小与 mtime**: - 命中要求 name、size、mtime 三者一致;任一对不上就当未命中、重新读文件。所以 **过期条目永远不会给出错误分数**,最坏只是多读一次 - 它只是缓存:删掉会自动重建;文件不可解析或被截断只会被当成"空缓存",从不报错 - 写回时会丢掉文件已不存在的条目,不会随时间无限增长 - 它**不是一个产物**:`list` 跳过它,`models` 不把它列成模型,`latest()` 也不会选中它 - 缓存里区分"**读不了**"和"**没记分数**"——这两者对清理的含义相反:前者**永不删除**, 后者可被排序淘汰。合并两者就会把一个"不敢动"的文件变成"会删"的文件 ### 进化中的冠军会边跑边落盘 以前 `evolve` 只在**全部代跑完**时才写冠军,于是一次崩溃或被 kill 掉的长进化什么都留 不下——热键 `Q` 也只覆盖了"有人守着"的情况。现在**每一代只要冠军被刷新就立刻写盘**: - 文件名的时间戳在整轮开始时固定(`naming::filename_stamped`),所以连续改进落在 **同一个文件**上,而不是每代留一个近似副本 - 冠军架构变化会让文件名随之改变;此时上一份会被删掉,一轮进化只留**一个**活着的冠军 - 结束时若没给 `--out`,冠军权重就写回这个已经在跑的同一路径,不再另起一个时间戳 - 引擎只报告"这一代刷新了冠军"(`Generation.improved`),写到哪仍由 CLI 决定—— 和热键走的是同一条 `Control::Save` 通路 ### 训练 / 进化中的一键存档 训练与架构进化都支持热键,语义一致:**先保存,再决定要不要停**。 | 场景 | `S` | `Q` | |---|---|---| | `train` | 立刻把**当前权重**存成 `manual` 检查点,训练继续 | 停止训练,并把当前权重另存一份 | | `evolve` | 立刻把**当前冠军**(架构 + 权重 + 词表)存成 `manual`,进化继续 | 保存并停止 | `evolve` 的热键**每代结束时响应**(一次评估是一整代;逐代响应才能保证存下来的冠军权重 是稳定的)。这一点以前是进化的硬伤:产物只在**全部代跑完**时才写盘,所以一次跑到一半被 Ctrl-C、崩溃或手动停掉的进化**什么都留不下**。现在 `Q` 停止后照常写出冠军模型与最优 genome,`S` 则让你在任意一代留一个带代数标签的快照 (`polarbear-manual-<数据集>-d32-x3-g3-gen7-<时间戳>.json`)。 引擎不自己读键盘:`Engine::run_controlled` 每代把决策交给调用方(`Control::Save(路径)` / `Stop`),CLI 负责按键与文件名。这样同一条代码路径可以在**没有控制台**的测试里驱动—— `a_mid_run_save_writes_the_champion_and_the_run_continues` 断言中途存档能重新加载、且运行 继续;`stopping_early_still_yields_the_champion` 断言提前停止仍拿得到冠军权重。 热键读法: `S` / `Q` 走 Win32 **控制台输入队列**(`ReadConsoleInputW`,不是 CRT 的 `_kbhit()`, 后者依赖工具链链接了哪个 CRT)。是否启用**只看 stdin 是不是真实控制台**: stdin 被管道或重定向时热键自动失效,训练照常进行,也不会吞掉任何不属于它的输入。 stdout 是否重定向则无关——`polarbear train ... > log.txt` 里照样能按键(这条最初写错过, 判据里混进了「stdout 是终端」,导致重定向日志时热键静默失灵)。 热键无法用单元测试覆盖——它需要真实控制台输入队列,所以 `tools/hotkey_check.ps1` 自己开一个控制台跑训练,再用 `AttachConsole` + `WriteConsoleInputW` 把一次 `KEY_EVENT` 真的投递进那个队列,最后用**文件系统**(是否出现 `manual` 存档、 进程是否自行正常退出)判断结果: ``` $ powershell -NoProfile -File tools/hotkey_check.ps1 -Key s -Steps 3000 PASS: key 's' wrote polarbear-manual-toy-d32-l2-h4-step73-20260913-235117.json (351479 bytes) PASS: after 's' the trainer kept running $ powershell -NoProfile -File tools/hotkey_check.ps1 -Key q -Steps 3000 PASS: key 'q' wrote polarbear-manual-toy-d32-l2-h4-step99-20260913-235108.json (351247 bytes) PASS: after 'q' the trainer exited on its own (exit 0) --- trainer output (tail) --- 中断 已停止并保存当前权重 models\polarbear-manual-...-step99-...json ── 训练中断 ───────────────────────────────────────── 最优 val 无 —— 中断发生在第一次验证之前 当前权重 models\polarbear-manual-...-step99-...json ``` 脚本把训练进程的输出转发到临时文件后回显(否则那个摘要只出现在一闪而过的窗口里)。 它必须保持**纯 ASCII**:Windows PowerShell 5.1 会把无 BOM 的 `.ps1` 当 ANSI 读, 一个多字节字符就会破坏引号解析变成语法错误(这个坑踩了两次)。 ## 数值正确性 反向传播由**有限差分对拍**把关(`fd_gradient_check_block_backward`):它把解析梯度 (按 `train_batch` 的反向顺序复算)与模型自身损失的中央差分逐元素比较,覆盖 `Block`、尾随残差区间、非尾随区间、**嵌套/重叠残差区间**、untied 递归、tied 递归、 `AttnOnly`/`FfnOnly`,以及**嵌套递归**(`nest_recursive_at` 会把一层递归放进另一层的 body,于是 tied 展开里"按偏移重放 pool 索引与残差区间"那段代码成了可达路径)共 **11 种拓扑**,并逐个探针**全部 16 个参数张量** (`wq`/`wk`/`wv`/`wo`、四个偏置、`w_gate`/`w_up`/`w_down`/三个 FFN 偏置、两个范数增益), 而不是只看 `wq`——只看 `wq` 的话,`wv`、`w_up` 或范数增益反向写错可以一直通过。 其它测试只断言「loss 会下降」,而**错误的梯度同样能让 loss 下降**——只有这个测试能发现梯度错误。 一个真实教训:注意力子层曾误用上游 `dy` 而非累加后的 `d_x`,丢掉 `x → x_mid → FFN → x_out` 的交叉项,有限差分显示相对误差 **155%**(部分元素符号相反)。 修复后 6 种拓扑的误差都回到 5% 以内。另一处是尾随残差区间时 head 反向用错了输入点 (误差约 2×),现由 `forward_inner` 返回 head 真实消费的张量解决。 ### 有限差分本身的分辨率(判据为什么要写成两条) 把探针从 `wq` 扩到全部 16 个张量后,有几处近噪声底的元素报出 10%–60% 的相对误差, 看起来像又一个梯度错误。用**改 ε** 把它们和噪声区分开:ε 从 1e-2 提到 4e-2,同一个 元素的解析值纹丝不动(+6.4e-5,它按定义与 ε 无关),而数值解从 +7.2e-5 → +6.0e-5 **向它收敛**(噪声 ∝ 1/ε)。 但 ε 扫描只在**截断误差可忽略**时才是有效判据——中央差分的截断 ∝ ε²,ε=4e-2 时约 1.6e-4,于是又有另一批元素因为**误差随 ε 变大**而失败。两者方向相反,所以工作点只能是 1e-2 附近(此时两项都在 ~1e-5 量级),而 ε 扫描的用途是**标定噪声底**,不是重跑测试。 标定结果:扰动量 ε=1e-2 时损失的变化本身只有 ~1e-6,而每个 loss 是量级 2.5 的 f32 (1 ulp ≈ 3e-7),所以差值带几个 ulp 的误差是必然的。判据因此写成两条: - 相对误差 < 5%(对量级正常的梯度元素有效),**或** - 绝对差 ≤ `1e-6 / 2ε`(在 1e-2 下是 5e-5),即落在方法的分辨率之内 **两条都立刻反向验证过**:把当年级的 P0(`d_sa = dy`,注意力丢掉交叉项)改回去,差异 `0.033`——噪声底的 **650 倍**,测试依旧失败;把 `w_up` 的梯度乘 1.7,差异 `0.0033`—— **65 倍**,而且报错直接点名 `w_up[0]`。也就是说这次扩容让"某个非 `wq` 张量的反向写错" 从"完全测不出"变成"立刻抓住"。 ### 参数校验 `--heads` 不整除 `d_model` 时 `BlockParams` 会 assert,进程直接 abort: ``` $ polarbear train --data LCCC-base-split --d-model 30 --heads 4 train: --heads 4 不能整除 d_model 30(每头维度必须是整数);d_model 30 可用的 --heads:1、2、3、5、6、10、15 ``` `evolve --d-model 30`(默认 `--seed-heads 4`)与 `evolve --pop 0` 也曾分别以 assert 和索引越界崩溃,现在前者给出同样的可操作错误、后者取 `max(1)`。 `--seq 1`(或 0)会让每个样本只剩一个 token、根本没有「下一个 token」可预测, 于是交叉熵在模型深处断言、进程以 101 退出。`train` 与 `evolve` 现在都在解析参数 时拒绝(`--seq 至少为 2`),数据加载器也做同样的边界检查,所以程序化调用同样安全。 ## 数据与损失掩码 `data/` 下五个真实语料全部可训练(`train --data <名字>`): | 语料 | 文件 | 格式 | 加载 | |---|---|---|---| | `BelleGroup--train_0.5M_CN` | 286 MB | JSONL `instruction/input/output` | 流式逐行 | | `BelleGroup--train_1M_CN` | 458 MB | 同上 | 流式逐行 | | `LCCC-base-split` | 933 MB + 2.9 MB 验证 | JSON 数组的数组(分词语料) | 流式扫描 + 自带验证集 | | `LCCC-large` | 1.5 GB | 同上 | 流式扫描 | | `zhwiki` | 8.8 GB JSONL(另有 15 GB 原始 xml,按扩展名忽略) | JSONL `sentence` | 流式逐行 | **内置的合成语料(toy)不再作为一个数据集**:`datasets` 只列出 `data/` 下真实存在的 目录,`--data` 省略时取第一个,帮助里也不再有它。它只作为库函数 `toy_dataset()` 保留, 供测试套件与 `polarbear demo` 直接调用——两者因此仍不需要磁盘上有任何语料。 (`--data toy` 这个名字仍然解析得到,但没有任何地方会推荐它;`data/` 为空时 `train`/`evolve` 会明确报错并告诉你语料该放哪里,而不是悄悄跑合成任务。) **LCCC 的 JSON 数组以前是整个读进内存再解析的**:为了取 4400 个样本,932 MB 的 训练集要付 3.2 GB 常驻内存和 10.2 秒,1.5 GB 的 LCCD 更甚。现在 `read_json_dialogue` 按字节流扫描,只保留当前所在的元素,内存有界,不再有那个 3.2 GB 的峰值。 当时的改造还顺带"凑够 `limit` 个样本就立刻返回",于是五个语料都在 **1.8–3.3 秒、 约 110 MB 峰值**内读完头部。但**后来默认改成在整份语料上均匀抽样**,而均匀性正来自 "看见了全部"——所以现在**必须扫完整个文件**,那 1.8–3.3 秒早已不成立,真实代价见下节 (LCCC-base 31 秒、LCCC-large 45 秒、zhwiki 约一分钟)。两次改造方向相反,这里曾长期 只留下前一个数字。 ### 默认使用整个语料 以前每次训练只取**开头 4000 条**:933 MB 的 LCCC 训练集,模型其实只见过它前 1 MB。 现在默认用整份语料: - 装得下就**全部载入**,装不下就在整个文件上**均匀抽样**——一条记录按 `--seq` 切成 几个窗口就算几行,所以"装得下"是按**行**算的:Belle 0.5M 的 519,255 条按窗口计费后 已经放不下(实测抽样 412,901 条 → 2,579,450 行),而小的语料仍然全部载入 - 装不下(LCCC / zhwiki)就**在整个文件上均匀抽样**,而不是只吃开头。抽样用 蓄水池算法(Algorithm R):一遍顺序扫描、内存有界,每条记录被选中的概率相同; 样本量不超过容量时它就等于"全部保留" - 池子大小由内存预算(默认 2 GiB)反推,`--samples N` 可直接指定条数,0(默认)即自动。 `--samples N` 说的是**训练样本数/行数**:验证集先从池子里切出来(十分之一,上限 400 条 记录),再把训练行截到 N、验证行截到 N 的十分之一,所以 `--samples 1` 就是 1 行 (此前池子层面的上限会让它变成 361 行) - 验证集也从池子里**随机切分**(先打乱),不再固定取文件尾部——按主题排序的语料 否则会得到系统性偏斜的验证集;语料自带验证文件时仍优先用它 - 训练前会打印来源:`样本 全部 240 条`(记录)与 `240 train / 60 val from data\…`(行) **例外是 `evolve`**:它对每个个体都要各训一次,所以默认每个个体只读 **400 行训练 / 40 条验证** 记录(`--pool-train` / `--pool-val` 可改;注意两者单位不同,训练池按行截、验证池按记录)。 这意味着进化报出的 `val_loss` 默认是 40 条验证样本 上的数——噪声不小,冠军的排名可能被采样波动左右。要回答"进化到底有没有用",先把 `--pool-val` 提上去(例如 `--pool-val 400 --pool-train 2000`)做一次对照,比调 λ 或代数更值得。 代价是**要读完整个文件**:zhwiki 8.4 GB 约需一分钟(LCCC-base 31 秒、LCCC-large 45 秒), 所以开始扫之前会打印一行「在整个语料上取样,大文件需要几十秒…」,免得看着像卡住。 `--samples` 指一个很小的数时也仍然扫全文,因为均匀性正来自"看见了全部"。 关于"流式"的两个事实,各有测试兜着:**内存有界**(按字节扫描,只保留当前所在的元素, `streaming_dialogue_reader_survives_escapes_and_unicode`),以及**会读到文件末尾**—— 它**不再**在凑够 `limit` 时提前返回(均匀性正需要看全),所以末尾若有一条被截断的记录, 它会被丢弃而不影响前面已解析出的样本 (`a_truncated_last_record_is_dropped_and_the_rest_still_parses`)。 ## 修复史 每一批真实发生过的缺陷、当时的证据与处置都收在 **[CHANGELOG.md](CHANGELOG.md)**,条目按时间 排列、保留原始措辞与实测数字。这里只留它们的共同模式: > **让检测得到的发散,变成看起来合理的结果。** 被静默截断到 `seq_len` 的语料、被吞掉的 > JSON 数组元素、被忽略的参数、在唯一会烧断的输入上失效的梯度裁剪、分不清「被屏蔽」与 > 「已发散」的掩码哨兵、按有损的名字而不是基因组分组的清理、报出「成功」的退出码。 配套的是方法:**先测量再下结论**,并且测量本身也要被核对——有两处是我自己的度量先错 (一个漏了 `residual_spans`,一个把中间结果当成了结论),纠正之后结论才成立。 ## 测试(134) - 张量:非方阵矩阵乘、RoPE 往返、RMSNorm 反向有限差分、非有限行 softmax 置零 - Genome:种子展开、嵌套递归展开、40 次突变后仍合法、**零宽度(`d_ff`/`d_model`) 被拒绝而不是走进 rayon 断言**、**`repair_heads` 把 0 头修成 1 并保持整除**、 depth 0 的递归仍可物化 - Runtime:**有限差分梯度对拍(11 种拓扑 × 块内全部 16 个参数张量,含嵌套/重叠残差区间 与嵌套递归,外加输出头的 3 个张量)**、**判据同时看绝对差与相对误差(噪声底由 ε 扫描标定)**、 **KV cache 逐 token 对拍全序列(10 种架构,含嵌套残差与 two-spans)**、 **上下文累积/裁剪/停止符**、**贪心采样跳过被屏蔽的 argmax**、 **被屏蔽的 argmax 不会让采样停摆(τ 0.01–0.8)**、 **首块非注意力时缓存长度仍然增长、预算仍能裁剪**、前向形状、tied 参数共享、 训练降损、嵌套递归可训、`Residual` 包装确实改变输出、**每一层 Residual 包裹都被实现**、 `AttnOnly`/`FfnOnly` 只跑对应子层、 填充位置不计损失、NaN 行零梯度+NaN 损失、 采样边界(空 prompt / 极小温度 / 不输出 pad)、 检查点往返(权重与 logits 逐元素一致)、词表随存档、 拒绝外来格式、拒绝基因组/权重错配 - 数据:**蓄水池抽样(装得下全留、装不下按整文件均匀抽样、每条记录都被读到)**、 **自带验证集与上限的规则**、**流式分词语料解析**、截断的末条记录被丢弃而不报错、 JSON 转义与字符串内的括号、`sentence` 行、未知格式快速失败、 **长记录被切成多个窗口且不丢字符(尾窗口只有一个 token 时丢弃)**、 **裸字符串数组保留每一个元素**、**对象数组与同样内容的 JSONL 读法一致**、 **名字没命中时不会认领无关文件当自带验证集**、 **未闭合字符串被 8 MB 上限拦住**、**长度全部不足 4 的语料被如实归因而不是甩锅给格式**、 合成语料的验证集与训练集不重合、**`--samples N` 就是 N 条训练样本(对行数封顶)**、 **长度小于 2 的序列被拒绝而不是崩溃** - GPU:matmul 对拍、前向与 CPU 一致、训练稳定降损、 **含 `+inf` 的 logit 行在 GPU 与 CPU 上都报 NaN,而不是一个有限(可能恰好为 0)的损失**、 **梯度范数非有限时整组梯度被归零(不留给 sgd)、超界范数缩放到恰好等于界、界内不动**、 **Adam 路径能降损、动量缓冲即使拿到回收缓冲区也读到 0**、 **超过字节上限的缓冲区不被池保留**、 **带填充批次的 GPU/CPU 损失逐值相等**、 **dk ∈ {8,3,4,1}(含奇数与退化)下前向都与 CPU 一致**、 **RoPE 上限常量与 `kernels.cu` 一致**、 **显存缓冲按大小回收复用**、 **16 种拓扑(Full / AttnOnly / FfnOnly / 残差包裹与嵌套 / tied 与 untied 递归 / 嵌套递归 / 递归裹残差 / 残差裹递归 / 相邻残差) 单步前后的损失都与 CPU 一致** - Evolve:两代进化产生有限适应度、冠军权重可保留并重载、 **中途保存冠军可重新加载且运行继续**、**提前停止仍拿到冠军权重**、 **非有限适应度排到最后且不会被当成最优**、**适应度池/验证池的大小由调用方决定**、 **0 代被拒绝而不是给一个从未评估的基因组加冕**、`--gpu-only` 拒绝 CPU 训练 - CLI:`--seq 0/1` 被拒绝、**`--flag=value` 能到达旗标、值不合法或根本没给值都报错**、 **需要取值的参数缺值(末尾无值 / 后面紧跟另一个参数)会报错** - 命名:非法字符净化(含中文名不得塌成 `unknown`)、文件名自描述、标签不破坏时间戳排序、 只有真正的尾部时间戳才算数(旧的 `model_trained.json` 不得盖过新文件)、 `models` 列表按时间倒序且类别从名字读出、 **进化存档按适应度淘汰最差的而不是最旧的**、 **只保留最优:同组更差的被删、跨架构/跨数据集互不影响、manual/snapshot/champion 不动、无法解析的文件不删、`--keep 0` 关闭**、 **同名的两个不同架构不互相删除(按基因组指纹分组,且删除时说明被谁取代)** - UI:CJK 显示宽度、**忽略 ANSI 的可见宽度**、横幅各行等宽、 **横幅与分隔线同宽**、`kv` 值列对齐、`kv_row` 标签列对齐、 **表格列在彩色与中文单元格下仍对齐**、时长时间格式化、 进度条对 total=0 不崩、嵌入的赞赏图案是完整二维码(定位角 + 白底静默区、 两份图案行列数一致)、待打开的图片确实是 JPEG 且与嵌入副本逐字节相同 - 热键:无控制台时 `KeyReader` 不读取也不阻塞(真实控制台由 `tools/hotkey_check.ps1` 注入按键事件验证) ## 赞赏支持 ``` polarbear thanks # 终端里显示二维码 polarbear thanks --open # 用系统看图器打开原图 ``` 二维码在**编译期**就被烘进二进制(`include_bytes!` / `include_str!`),发布出去的 单个 exe 不需要任何图片文件;`--open` 在找不到 `icon/gratuity.jpg` 时会自动从内嵌 副本恢复一份到临时目录再打开。 终端图案由 `tools/gratuity_art.py` 从原图生成,它先按「黑/白交替密度」找出二维码的 包围盒,再把每个模块采样到合法尺寸(21/25/…/45)的网格上。二维码的采样极易假阳性: 重采样一次就会得到一张**看起来很正常但扫不出来**的图。所以生成器不信任何单一启发式, 而是逐条校验二维码的不变量: - 三个**定位角**(7×7 固定图案,含分隔符) - 行 6 / 列 6 的**时序图案**(严格交替) - 右下**校正图案**(中心深、外圈浅) - **格式信息**:15 位 BCH(15,5) 码字,存了两份且位置互不相交。32768 个可能值里 只有 32 个合法,网格错一个模块两份就同时崩掉——所以它能解出来,等于证明了 整个采样映射(进而包括数据区)都是精确的。本例解出 `纠错级别 Q · 掩码 6`, 两份副本一致 - 固定深色模块 `(4V+9, 8)` 校验不通过就**拒绝写入**。当前资产(45×45,QR version 7): ``` $ python tools/gratuity_art.py detected: 45x45 modules (QR version 7) 格式信息: 纠错级别 Q · 掩码 6 —— 两份副本一致,解码为合法码字 ✓ validation: 定位角 / 时序图案 / 校正图案 / 格式信息 / 固定模块 全部匹配 ✓ wrote icon/gratuity.ans (46873 bytes) wrote icon/gratuity.ascii (4850 bytes) ``` 彩色图案用 `▀` 半块字符一格画两个像素,**每格都显式画出黑/白背景**——否则空格会 露出终端的底色,深色终端上二维码会被反相、静默区也会消失。无颜色输出时退化到 纯字符版(`██` 两列一格,补偿终端字符约 1:2 的宽高比),此时它依赖浅色终端背景, 程序会提示这一点。 换一张原图要重新生成并重新编译,因为图案是编译期烘进去的: ```powershell python tools/gratuity_art.py # 校验通过才写文件 cargo build --release ``` ## 文档 | 文件 | 管什么 | |---|---| | **README.md**(本文) | 一页纸:这是什么、怎么跑、核心思想、目录 | | [USAGE.md](USAGE.md) | 手册:每个命令与旗标、默认值、样例输出、退出码、已知限制 | | [DESIGN.md](DESIGN.md) | 设计参考:当前的结构、训练配方、跨后端不变式、数据管线、GPU 实现、检查点 | | [TRAINING.md](TRAINING.md) | 调参:批大小 / 学习率 / 序列长度 / 语料的实测数据与建议 | | [CHANGELOG.md](CHANGELOG.md) | 修复史:每一批发生过的问题、当时的证据、现在的处置 | 一句话分工:**README 讲它是什么,USAGE 讲怎么用,DESIGN 讲为什么是这样,TRAINING 讲怎么调, CHANGELOG 讲它曾经错在哪。**