模型仓库与实验追溯：权重版本管理的工程

权重也是资产

模型权重怎么快速分发到集群各节点，「模型分发」一篇已经讲过运输问题；本篇管的是更上游的仓库问题：权重文件作为一个组织里最贵的数字资产之一，怎么命名、怎么追溯、怎么防丢防错。这件事平时不显眼，出事时却是灾难级的——「上周评测最好的那个模型到底存哪了」「这个微调版是从哪个底座训出来的」「线上跑的权重和评测时是同一份吗」，这三个问题答不上来的团队，迟早要为此买单。

权重的管理难度在于它踩在代码与数据的中间地带：它是二进制大文件，单个几 GB 到几百 GB，用 Git 直接管会爆炸；它又有严格的派生谱系——底座模型、指令微调版、偏好对齐版、各种 LoRA 适配器，一层层派生出去，谱系乱了就说不清任何一个版本「是什么、从哪来、能不能上线」。所以模型仓库的本质是两件事：给大文件一套内容寻址的存储，给版本一套可追溯的元数据。

它和代码仓库的关系也要摆正：训练代码进 Git，权重产物进模型仓库，两边用代码提交哈希互相引用——任何一个版本都能顺着引用找到「哪份代码、哪个配置、哪版数据」训出来的。所谓复现，从来不是单一仓库的事，是几套仓库咬合的结果。

这件事还有个组织层面的含义：仓库的负责人要明确——出事时谁有权删版本、谁负责宽限期通知、谁定期审权限列表，权责写进流程而不是默认压在某个人身上；资产管理没有明确的责任人，就等于没有管理。

版本语义与模型卡

什么算一个版本

模型版本的第一原则是不可变：一个版本号一旦发布，它指向的权重内容永不更改，改了就是新版本。实现上通常用内容寻址——对权重文件算哈希，版本身份由哈希决定，天然防篡改。命名上常见「架构加数据加配置」的组合约定：同一个底座架构，用不同版本的数据、不同训练配置训出的就是不同版本；日期戳可以作为后缀辅助人读，但身份标识必须落在不可变哈希上，而不是落在「final」「最终版2真的最终版」这类文件名上——文件名会骗人，哈希不会。

比命名更重要的是派生关系的记录。每个版本要回答三个问题：从哪个版本派生、用了哪版数据（数据集版本号）、用什么训练配置（超参与代码提交）。这三样齐了，任何一个线上模型都能沿着谱系回溯到最初的底座；缺了任何一样，「复现」就变成考古。LoRA 适配器是派生关系的特例：它体积小，但必须与底座版本绑定使用，仓库里要把「适配器所属的底座版本」记成硬约束——挂错底座的适配器输出就是垃圾，这类事故的排查成本远高于登记成本。

别名机制是版本语义的日常搭档：给仓库配 latest、stable、testing 这类可移动的别名，引用方用别名解耦发布节奏——实验追 latest，生产锁 stable。别名只是指针，版本身份仍在哈希上；但有一条纪律必须立：生产环境永远不用浮动别名，发布单上写死具体版本的哈希，否则「昨天还好好的今天挂了」的排查会从「谁动了别名」开始。

数据集的版本登记有个实用主义口径：不必给每次小改动都发版本，但发给训练的数据快照必须有清单——文件清单加哈希加生成配置，训练启动时记录引用的清单版本。颗粒度到「能回答用的是哪批文件」就够，不必细到每个文件的每次修改；够用的版本化才会被执行，完美的版本化只会被绕过。

模型卡：随权重走的说明书

每个正式版本应带一份模型卡：模型用途与架构、训练数据概要、许可证与使用限制、评测结果（在哪些基准上跑了多少分）、已知局限与风险。模型卡的价值在交接与审计：三个月后接手的同事、或者合规审查者，靠它理解这个模型能干什么、不能干什么、数据有没有雷。开源社区的模型卡实践已经相当成熟，企业内部照搬这套格式成本很低，收益很高。

模型卡里的评测数字要带口径：评测集是哪一版、推理参数是什么（采样温度、对话模板），否则同一个模型在不同评测配置下能差出好几个点，数字没法复验。这和实验追踪的三角是同一件事的另一面——权重、数据、参数三者对齐，数字才可信。

实验追踪的三角关系

训练实验的记录是模型仓库的另一半。一次实验的完整档案是一个三角：超参数、指标曲线、数据版本，外加代码提交哈希这个第四角。三角缺任何一角，实验就不可复现：只记指标不知道怎么跑出来的；只记超参不知道用的哪版数据；只记数据不知道这批成绩对应哪份代码。

实践上，MLflow、Weights and Biases 这类工具的通用模式是：训练脚本里埋几个记录调用，超参在启动时整体登记，指标随训练周期性上报，产物（最终权重）指向模型仓库里的某个版本。工具可以换，纪律不能换：每次实验必有记录，每个记录必能定位到权重、数据、代码三样东西。除了训练指标，GPU 利用率、显存水位这类系统指标也值得顺手记录——训练不稳定的排查经常要回看「那一刻卡上发生了什么」，只有 loss 曲线是查不出来的。

失败实验同样要记录。负结果的价值常被低估：知道「这条超参路走不通」能省掉后来者一周的卡时；只记成功实验的仓库，会诱导大家反复试同样的死路。另外提醒一句偏差：评测环境与生产环境往往不同——同一份权重在评测机与线上服务的延迟、显存表现可能有差距，重要决策前要在生产同构环境复测一遍。

还有一样东西经常漏：评测集的版本。两次实验的成绩可比，前提是同一版评测集；评测集偷偷改了，榜单上的涨跌全是噪声。评测集入仓库、给版本号，与训练数据同等对待。

顺带一个联动提醒：评测集的管理要特别提防「泄漏回路」——评测集必须与训练语料隔离存放，任何进入训练管道的数据要先过一次与评测集的相似度检查，这个检查本身就是一次去重作业，上一片的 MinHash 在这里直接复用。

存储布局：本地缓存与对象仓库

本地缓存目录约定

训练与推理节点上的权重缓存有一个事实上约定俗成的布局（以 HuggingFace 生态为代表）：缓存根目录下按「组织名加模型名」建目录，内部再分 blobs 与 snapshots 两层——blobs 存实际文件（以哈希命名），snapshots 里按版本提交组织符号链接指向 blobs。这个设计有三个实际好处：同一模型的多个版本共享未变的文件，磁盘不翻倍；版本切换只是换符号链接指向，瞬时完成；下载中断后重下可以按文件哈希校验续传。理解这个布局，排查「显存没超但磁盘满了」「为什么下了两份模型」这类问题会快很多。

大文件下载还有两件配套工程：断点续传（分块下载，中断后从块边界继续）与完整性校验（下载完对整文件验哈希）。校验这一步经常被省，省的代价是「训练到第三天才发现权重文件损坏」——加载时多数工具只查结构不查内容，坏字节会安静地进显存。下载必校验，写进工具链而不是写进口头叮嘱。

多版本并存时的磁盘账要定期盘：缓存目录的体积报表（每个模型、每个版本占多少）纳入例行巡检，过期版本及时清理。这里有个容易踩的坑：blobs 共享设计意味着「删掉一个旧版本」通常只省下很小一部分磁盘——真正占空间的是没有版本引用它的孤儿文件，清理工具要按「无引用的 blob」来删才有效，按版本目录删常常白忙一场。

对象仓库与 LFS 的痛点

仓库侧的常见方案有两类。Git LFS 是最低门槛的起点，但痛点明显：大文件走指针引用，拉取慢、服务端存储与带宽压力大、并发下载受限，仓库一大每次克隆都很痛。更工程化的做法是对象存储加元数据数据库：权重文件按内容哈希直接进对象存储，元数据（版本、派生关系、模型卡、指标链接）进数据库或 Git 仓库，两者用哈希关联。这个布局还有个经济红利：同一底座派生的十个微调版共享底座文件，存储只算一份；上传时先查哈希，已存在就跳过。企业内网自建仓库基本都落在这个形态。

企业内网仓库的搭建要点

自建内网模型仓库，权限、安全、分发、生命周期四件事要一次想全。

权限至少分三级：可下载（多数研发）、可上传（训练平台与负责人）、可管理（删版本、改元数据）。上传与删除要留审计日志——权重的误删与误替换是真实发生过的事故形态，事后却常常查不到是谁、什么时候动的。账号形态上，服务账号与个人账号要分开：训练平台用服务账号上传，人用个人账号下载与管理，出问题能定位到主体；个人离职回收权限，服务账号的凭据轮换进密码库管理。安全这一条最容易被忽视：权重文件本质是序列化数据，加载即执行代码，恶意构造的序列化内容是现实威胁；所以入库前要过扫描（社区已有现成的权重安全扫描工具，专门检查序列化内容里的危险调用），外部下载的模型一律先扫描再入库，来源不明的权重禁用 pickle 类加载通道。分发上，仓库要和镜像分发、P2P 分发链路联动：新版本入库即触发预拉取到常用节点，避免上线时刻全部节点同时回源——这正是「模型分发」篇的领地，两边接口对齐即可。生命周期上，定好保留策略：活跃版本全量保留，过期版本归档到廉价存储，废弃版本下线前留一段宽限期并通知使用方，别让下游业务在某个早晨突然发现模型链接失效。

研发节点的本地缓存是另一处事故高发地：每个人机器上的权重缓存目录悄悄膨胀，挤爆系统盘拖垮整个节点的故事在各团队反复上演。解法是组合拳：缓存目录统一挪到大容量分区、设配额与告警、提供缓存清理工具并纳入例行巡检，把「人肉找谁占了大头」变成一条自动报表。

常见事故形态自查

把内网仓库的真实事故形态列一遍，可以直接当自查清单：本地缓存挤爆磁盘拖垮节点；别名被误移，生产环境悄悄换了权重；适配器挂错底座版本，输出劣化却查不出原因；外部下载的模型没过扫描就加载，踩中恶意序列化；评测集混进训练语料，榜单虚高被外部戳穿；删除版本没走宽限期，下游线上引用突然失效。每一项的预防手段前文都覆盖了，这里的用途是对照演练——半年自查一次，项项全绿才算仓库真的在管。

小结

模型仓库解决的是「权重资产化」的最后一公里：版本不可变、身份走内容哈希、派生关系三问（从哪来、用什么数据、什么配置）必有答案；模型卡让每个版本自带说明书；实验追踪守住超参、指标、数据版本、代码提交的三角，让每次成绩可复现；存储布局上本地缓存与对象仓库各司其职，blobs 加 snapshots 的结构让版本切换瞬时、多版本共享存储；企业自建时把权限、扫描、分发联动、生命周期一次配齐。

这套工程的价值是慢变量：平时只是「查东西快了」，出事时是「三分钟定位到线上模型是哪一版、从哪来、能不能回滚」。大模型团队的规模越大、实验越密，仓库的复利越明显。判断一个团队的模型工程是否成熟，有个简单的试金石：随机挑一个线上模型版本，问三个问题——它是从哪个底座派生的、训练数据是哪一版、出问题能不能十分钟内回滚。三个问题都有秒答，仓库就立住了；有一个支支吾吾，就该把本篇的清单拿去补课。