对齐Hugging Face五条契约，跑通自定义LLM训练

1. 先把思路理清为什么自定义训练程序总要“迁就” Hugging Face把自定义的 LLM 训练程序接进 Hugging Face 生态本质上不是调 API而是签合同。我在这个系列的 Lab 里反复打磨这个问题后最深的体会是很多人明明样本、模型、GPU 都有了训练却一直跑不起来十有八九是没搞懂接口契约这回事。这篇文章是 LLM Training Lab 系列的第六篇我准备把五条核心契约拆开讲清楚。适合谁看如果你正在微调一个改了结构的小模型或者想用 Trainer / Accelerate / 分布式训练来管理自己的训练程序再或者你只是想让实验能被别人从 Hub 上直接复现这篇都能帮上忙。换句话说只要你的训练程序不满足这些默认约定每走一步都会出错。我之所以把这类要求叫契约而不是接口是因为它们管的不是“函数长什么样”而是“你和我必须共同遵守什么行为”。接口对不上最多报一个 TypeError契约没遵守程序照样跑但结果全错或者换一台机器就彻底起不来。1.1 是接口更是行为约定Hugging Face 生态看着是一堆库transformers 管模型结构datasets 管数据tokenizers 管文本编码accelerate 管分布式训练hub 管模型分发。但真正把这些库串起来的是一套隐式约定。你写一个 PyTorch 模型理论上只要 forward 能算输出就能自己写循环训练。可一旦你想用Trainer管理日志、断点续训、分布式包装Trainer 就会用一套预设逻辑来“读取”你的模型它要检查model.config有没有pad_token_id要调用model.forward(input_ids, labels...)要把模型放进accelerator.prepare()并重新分发到各卡。这些行为不是 PyTorch 定义的是 transformers 生态定义的。所以接入 HF 不是把代码塞进某个目录而是让你的代码从“一个独立的模型文件”变成“一个能对齐生态默认行为的插件”。五条契约就是我提炼出来的、最容易出问题也最基础的五处对齐点。1.2 一个典型接入失败的现场我见过很多次类似情况有人用原生 PyTorch 写了一个基于 LLaMA 结构的小模型自己写数据加载自己写 loss在小数据集上也能过拟合。等到想放到多卡上跑或者想用现成框架管理实验问题就冒出来了。最常见的报错长这样Model should be a instance of PreTrainedModel。有人看到这个提示第一反应是“那我不用 Trainer 不就行了”但后面又会遇到模型权重报错、tokenizer 编码的 attention_mask 和 input_ids 对不上、保存的 checkpoint 在另一台机器上加载不了。这些问题表面看是不同 bug根子上是同一条没有按生态的契约来设计模型、数据和训练流程。所以我在下面的内容里不再讲“怎么把一个已有的 PyTorch 模型改成 HF 风格”而是反过来讲在你写第一行模型代码之前就要按这五条契约去约束自己。你省下的时间绝对值回票价。2. 五条接口契约总览一张表看懂所有对接关系为了让你先有一个全貌我把五条契约列成一张表。这五条不是我从文档里抄来的而是基于“一个模型从定义到训练再到分发”这条完整生命周期倒推出来的。契约编号契约名称约束对象违反时最典型的症状契约一PreTrainedModel 合法子类模型类Trainer 初始化直接报 “instance of PreTrainedModel”generate 等工具方法不可用契约二PretrainedConfig 合法子类配置类from_pretrained时找不到model_type或配置字段丢失契约三Dataset / DatasetDict 数据结构训练数据DataLoader 能做不能用collate 后字段对不上labels 缺失契约四Tokenizer 行为约定文本处理推理变长报错attention_mask 错位pad 方向不对导致精度异常契约五save_pretrained / from_pretrained 落盘协议训练产物权重保存了但重载缺 key或者根本推不上 Hub 复现2.1 契约之间如何串联这五条契约其实是一条链配置拉起模型结构tokenizer 编码文本datasets 供给训练数据训练循环把前四者串起来最终 save_pretrained 把产物沉淀下来供下一次 from_pretrained 启动。任何一个环节脱链后面的操作都会跟着崩。比如你花大力气改了模型结构但 config 类没有继承PretrainedConfig那么在from_pretrained加载时transformers 只会按照默认的PretrainedConfig去解析 config.json那些自定义超参会被当成未知字段丢进kwargs等于你的 hidden_size、num_layers 全白设了。再比如 data 处理时没把 labels 对齐训练跑起来 loss 不会报错但数值完全是错的这种隐性 bug 比报错更可怕。2.2 判定契约是否达标的三个信号实践里怎么快速判断自己的程序是否满足契约我通常用三个自检信号。第一模型能不能用AutoModel.from_pretrained(path)原样加载回来。注意是 AutoModel不是你直接用MinimalLLMModel.from_pretrained。前者走完整的自动路由后者只是普通类方法。第二Trainer能不能直接接收你的模型和数据集不做任何自定义子类就能开始训练。如果为了适配 Trainer 而专门重写半个 Trainer说明你的模型或数据接口契约有缺口。第三整个流程能不能只凭一个model_card加上几个文件在另一台干净机器上复现。只要还需要“手动改某行代码”、“手动放某个文件到某个目录”就说明产物契约没闭环。这三个信号比逐个对 API 更稳。接下来我按契约一、二契约三、四契约五的顺序拆开讲每一条都给出可以直接照抄的写法。3. 先拆模型与配置让 from_pretrained 认得你的架构契约一和契约二关系太紧密了必须放在一起讲。一个模型要接入 HF 生态第一步不是写nn.TransformerEncoder而是先定义配置类再定义模型类两者还要在model_type上保持一致。3.1 第一步继承 PretrainedConfig别在 config 上偷懒很多自己写训练代码的人习惯用 Python 字典存超参训练的时候从 dict 里读 hidden_size、num_layers。这种写法单独跑没问题但一旦进入 HF 生态模型文件和 config.json 应该是绑定的。加载者看到 config.json 就应该知道这个模型长什么样。正确的做法是继承PretrainedConfig把自定义字段固化到类属性里。下面是我常用的模板from transformers import PretrainedConfig class MinimalLLMConfig(PretrainedConfig): model_type minimal_llm def __init__( self, vocab_size32000, hidden_size768, num_hidden_layers12, num_attention_heads12, intermediate_size3072, max_position_embeddings4096, pad_token_id0, **kwargs ): super().__init__(pad_token_idpad_token_id, **kwargs) self.vocab_size vocab_size self.hidden_size hidden_size self.num_hidden_layers num_hidden_layers self.num_attention_heads num_attention_heads self.intermediate_size intermediate_size self.max_position_embeddings max_position_embeddings这里有几个点值得注意。model_type是 HF 识别模型类型的核心标识它必须全局唯一。定义了一个叫minimal_llm的 type之后AutoConfig.from_pretrained就能根据 config.json 里的model_type: minimal_llm找到对应的类。**kwargs也不要省因为 transformers 会往PretrainedConfig里塞一些通用字段比如torch_dtype、revision、return_dict如果不透传config 加载时会被莫名截断。另外还有一个容易坑到人的点pad_token_id这类特殊字段最好通过super().__init__传进去而不是只放在自定义属性里。很多下游模块比如 generate、数据 collator会直接从config.pad_token_id读值你只存成self.pad_token_id属于自己定义了一个属性HF 的PretrainedConfig里没有这个属性名等于没设。3.2 第二步把模型做成 PreTrainedModel 的合法子类配置定义好了接着是模型类。这里最核心的一件事必须继承PreTrainedModel并且通过config_class和base_model_prefix把模型类和配置类绑定起来。from transformers import PreTrainedModel from transformers.modeling_outputs import CausalLMOutputWithPast import torch.nn as nn class MinimalLLMModel(PreTrainedModel): config_class MinimalLLMConfig base_model_prefix minimal_llm def __init__(self, config): super().__init__(config) self.embed_tokens nn.Embedding( config.vocab_size, config.hidden_size, config.pad_token_id ) # 这里按你自己的需求堆 Transformer 层 # self.layers nn.ModuleList([...]) self.lm_head nn.Linear(config.hidden_size, config.vocab_size, biasFalse) self.post_init() def forward(self, input_ids, attention_maskNone, labelsNone, **kwargs): # 省略中间层计算拿到 hidden_states 后算 logits logits self.lm_head(hidden_states) loss None if labels is not None: shift_logits logits[..., :-1, :].contiguous() shift_labels labels[..., 1:].contiguous() loss_fct nn.CrossEntropyLoss() loss loss_fct( shift_logits.view(-1, shift_logits.size(-1)), shift_labels.view(-1), ) return CausalLMOutputWithPast( lossloss, logitslogits, ) def prepare_inputs_for_generation(self, input_ids, past_key_valuesNone, **kwargs): return {input_ids: input_ids, past_key_values: past_key_values}这里我解释几个容易被忽略的设计。base_model_prefix是权重 key 的前缀。PreTrainedModel.from_pretrained在加载权重时会把 checkpoint 里的 key 和模型 state_dict 做匹配。如果你的模型没有定义这个前缀那么当你把模型作为某个更大模型的一部分时权重的命名空间就会撞车。定义成minimal_llm之后所有参数都会带着minimal_llm.前缀保存进 checkpoint 后也能被正确检索。post_init()是 PreTrainedModel 自带的初始化钩子它会在所有模块初始化后执行通常会做参数初始化。我不建议在__init__最后自己写一堆初始化逻辑因为 HF 的某些功能比如tie_weights绑定 embedding 和 lm_head 权重会在post_init里处理你没有调用它后续很容易出现”embedding 权重明明绑定了但保存时对不上“的问题。forward尽可能返回 transformers 的 dataclass。比如因果语言模型返回CausalLMOutputWithPast就不会在 Trainer 的 loss 计算、generate 的 past_key_values 传递等环节被强制解构。有些教程让你 return 一个 tuple说能跑就行但到了 Trainer 的某些回调里它期望的可能是属性的方式访问outputs.loss、outputs.logits。3.3 第三步用 AutoConfig 注册 model_type完成自动路由很多人在这一步卡住明明 config 和 model 都继承对了为什么AutoModel.from_pretrained还是报错“Unrecognized model type”因为你没有把自定义类型注册进 AutoClass 的表格。AutoModel并不是一个类而是一个路由工厂它内部维护了一个“model_type 到类”的映射表。你自定义的 type 不在表里自然没被识别。注册有两种方式。第一种是手动注册from transformers import AutoConfig, AutoModelForCausalLM AutoConfig.register(minimal_llm, MinimalLLMConfig) AutoModelForCausalLM.register(minimal_llm, MinimalLLMModel)第二种是用装饰器风格的register_for_auto_class把它写进你的类定义后面MinimalLLMConfig.register_for_auto_class() MinimalLLMModel.register_for_auto_class(AutoModelForCausalLM)两种方式都行。我更推荐第二种因为它把注册逻辑跟着模型定义走团队换人之后也不会漏掉。这里还有一个坑如果模型代码本身放在 Hugging Face Hub 仓库里加载的时候需要trust_remote_codeTrue因为 transformers 要执行仓库里的自定义代码。如果你走的是本地目录加载则不需要这个开关。很多同学在本地看起来正常推到 Hub 后别人加载就失败就是漏了 trust_remote_code 或者没在仓库里放 modeling 文件。4. 再拆数据与 Tokenizer训练循环的隐形地基模型和配置对齐了只是把骨架立起来了。真正训练能不能跑顺数据侧和文本编码侧占了另外半壁江山。严格说这部分不属于 transformers 库的职责但 Trainer 在这方面的默认行为多到让你无法忽视。4.1 数据契约把训练语料装进 DatasetDictHF 生态里datasets.Dataset不只是数据容器它自带缓存、分片、内存映射还能和 DataLoader、Trainer 直接协作。最关键的约定是数据应该是 Dataset 或 DatasetDict并且字段里要有模型 forward 可接受的键。很多人直接给 Trainer 传一个List[Dict]虽然某些版本勉强能跑但一旦涉及num_proc多进程 map、断点续训时数据集 cache 重建就会出各种莫名其妙的资源问题。我给你的建议是一开始就按标准格式组织。from datasets import DatasetDict, load_dataset from transformers import AutoTokenizer raw_dataset load_dataset(json, data_filestrain.jsonl)[train] tokenizer AutoTokenizer.from_pretrained(meta-llama/Llama-2-7b-hf) if tokenizer.pad_token is None: tokenizer.pad_token tokenizer.eos_token def tokenize(batch): encoded tokenizer( batch[raw_text], max_length2048, truncationTrue, paddingFalse, return_attention_maskTrue, ) encoded[labels] [ids.copy() for ids in encoded[input_ids]] return encoded processed raw_dataset.map( tokenize, batchedTrue, remove_columns[raw_text], num_proc8, ) dataset processed.train_test_split(test_size0.05)上面这段代码里有几个要点。labels必须显式复制一份。labels在因果语言模型里通常是 input_ids 的右移版本但如果你偷懒直接encoded[labels] encoded[input_ids]那么 map 之后所有样本的 labels 和 input_ids 是同一个 list 对象引用。用的时候你不小心做了 in-place 修改会连带污染输入。这个 bug 不报错但训练曲线会变得很奇怪。remove_columns一定要把原始文本字段删掉。如果不删Trainer 的默认 collator 会把 dict 里所有字段都做 batch 化字符串字段有时会被 collate 成不一致的 list然后 DataLoader 报错。删掉之后整个数据集只剩input_ids、attention_mask、labelscollator 处理起来非常干净。num_proc8能加快 map但如果你的 tokenizer 是非线程安全的多进程会随机报错。实践里我一般先num_proc1跑通再开多进程不要一上来就八路并发。4.2 Tokenizer 契约padding 方向和 labels 对齐是重灾区Tokenizer 这块的契约比很多人以为的要严格。核心是三个点pad_token 必须存在、padding 方向要一致、labels 长度要跟 input_ids 一致。先看 pad_token。很多开源模型的 tokenizer 默认没有设置 pad_token典型的就是 GPT2 系和部分 LLaMA 系。这时候你用tokenizer.pad_token tokenizer.eos_token顶一下没问题但要注意这个兼容设置相当于把 EOS 也当 PAD 用如果训练时恰好样本末尾是 pad 位模型会把 EOS 位置也当成普通 token 来学有轻微污染。要求高的话可以单独添加一个 pad_token重新训练 embedding但这个操作成本和收益要看具体场景。再看 padding 方向。HF 训练时一般用右侧 padding就是短样本往右侧补 pad。但自回归模型的 generate 阶段为了避免 pad 位参与 attention 计算往往用左侧 padding 凑齐 batch。用 Trainer 的paddingFalse配合DataCollatorForLanguageModeling或者DataCollatorWithPadding它会自动处理所以我强烈建议不要手动pad_to_max_length。手动 pad 不仅浪费显存还可能在分布式训练时让各 rank 的输入长度不一致。最后看 labels。你在 map 阶段里把labels复制成input_ids的副本但 Trainer 内部并不会为因果模型自动做 shift。所以即便 forward 内部做了 shift也必须保证传入的 labels 在长度、padding 位置上和 input_ids 完全一致。如果你用了DataCollatorForLanguageModeling(mlmFalse)它会自动把标签里的 pad 位置改成-100从而让 CrossEntropyLoss 忽略它们。这个细节非常关键很多人的 loss 肉眼可见地在乱跳就是因为 pad 位置的-100没设置模型把大量无意义的 pad token 也算进 loss。4.3 训练循环对接Trainer 与 Accelerate 的选型数据契约和 tokenizer 契约搞定后训练循环本身往往不再需要“重写”而是选择接入方式。我通常会根据训练代码的复杂度在 Trainer 和 Accelerate 之间二选一。如果 loss 就是标准的交叉熵有 eval、有保存 checkpoint 的需求直接用Trainer是最省事的from transformers import Trainer, TrainingArguments training_args TrainingArguments( output_dir./checkpoints/exp_06, per_device_train_batch_size2, per_device_eval_batch_size2, gradient_accumulation_steps8, learning_rate1e-5, num_train_epochs3, logging_steps10, eval_strategysteps, eval_steps100, save_strategysteps, save_steps500, deepspeedds_config.json, # 需要时再开 report_towandb, ) trainer Trainer( modelmodel, argstraining_args, train_datasetdataset[train], eval_datasetdataset[eval], tokenizertokenizer, data_collatorDataCollatorForLanguageModeling( tokenizertokenizer, mlmFalse, ), ) trainer.train()这里最值得聊的是gradient_accumulation_steps的计算。假设你只有 8 张卡每卡 batch size 设 2梯度累积 8 步那么全局有效 batch size 是 2 * 8 * 8 128。如果你想让全局 batch 接近 256而显存只允许每卡 2 条样本那梯度累积就要设成 256 / (2 * 8) 16。这个计算看起来简单但很多人调了半天学习率发现收敛形态不对就是没意识到有效 batch size 变了learning rate 也应该跟着调。如果你的 loss 比较复杂比如加了对比学习、RLHF 里的 policy loss 和 value loss 混合那 Trainer 的默认逻辑就不够用了。这时我建议直接换 Accelerate把手动循环写清楚from accelerate import Accelerator from torch.utils.data import DataLoader accelerator Accelerator(gradient_accumulation_steps8) dataloader DataLoader(dataset[train], batch_size2, shuffleTrue, collate_fndata_collator) model, optimizer, dataloader, scheduler accelerator.prepare( model, optimizer, dataloader, scheduler ) for step, batch in enumerate(dataloader): with accelerator.accumulate(model): outputs model(**batch) loss custom_loss(outputs, batch) accelerator.backward(loss) optimizer.step() scheduler.step() optimizer.zero_grad()不管是 Trainer 还是 Accelerate有一点是共通的分布式训练时子进程必须能 import 到你的模型类。所以模型定义不要放在if __name__ __main__里也不要放在 Jupyter Notebook 的某个 cell 里应该单独建一个models/minimal_llm.py在训练脚本开头显式导入。否则多卡会报ModuleNotFoundError但这个错误经常被误认为是环境问题实际是模块导入路径问题。5. 最后拆训练产物save_pretrained 到 push_to_hub 的闭环训练结束只是开始产物能不能被别人/未来的你复用取决于契约五。这可能是五条里最容易被低估的一条但它直接决定了“在 Lab 06 里跑出的模型”是资产还是垃圾。5.1 save_pretrained 到底保存了什么model.save_pretrained(./my_model)并不只是存权重。默认情况下它会生成三个关键文件config.json、model.safetensors或者pytorch_model.bin、generation_config.json如果有生成相关配置。其中config.json是灵魂。它记录了 model_type、自定义超参、pytorch 版本、transformers 版本等信息。加载模型时从config.json反推出模型结构再加载权重。所以如果你只保存了权重没保存 config或者 config.json 里没有 model_type那么即使权重文件完好AutoModel.from_pretrained也无法正确路由到你的自定义类。我不知道你有没有遇到过这种情况训练完保存了 checkpoint过了两周自己回来加载发现报错说 missing key。大概率是因为你改了模型结构但旧 config 还在用旧的 hyperparameter。因此保存 checkpoint 一定要连同tokenizer.save_pretrained一起执行并且最好每次实验都打一个 tagmodel.save_pretrained(./my_model_final) tokenizer.save_pretrained(./my_model_final)tokenizer.save_pretrained容易被忽略。没有 tokenizer 文件别人拿到你的模型权重也编不了码还得自己去找 base tokenizer根本谈不上复现。另外一个细节safe_serialization默认是True所以现在 HF 保存的是 safetensors 而不是以前的 PyTorch bin。safetensors 的好处是格式自带校验不会出现“权重加载一半内存崩了但文件还在变大”的损坏问题。我建议不要随便关掉这个默认值。5.2 from_pretrained 能原样读回来才算闭环保存完之后必须做一次完整的加载演练。我会单独写一个check_loading.pyfrom transformers import AutoConfig, AutoModelForCausalLM, AutoTokenizer path ./my_model_final config AutoConfig.from_pretrained(path) model AutoModelForCausalLM.from_pretrained(path) tokenizer AutoTokenizer.from_pretrained(path) text The meaning of life is inputs tokenizer(text, return_tensorspt) outputs model.generate(**inputs, max_new_tokens16) print(tokenizer.decode(outputs[0]))这个脚本如果跑通才说明契约五合格。跑不通的典型情况有三种。第一种是权重 key 对不上。如果你改过base_model_prefix或者对某些层做了重命名加载时会出现Some weights of the model checkpoint at ... were not used或者Some newly initialized parameters ... were not used的告警。这类告警不是简单警告它意味着权重根本没有正确加载。第二种是模型类和 config 类没有被 import。因为你直接用AutoConfig.from_pretrained它需要把model_type: minimal_llm映射到MinimalLLMConfig类。如果加载脚本里没有from my_models import MinimalLLMConfig, MinimalLLMModel即使在minimal_llm.py里做了自动注册也白搭因为 Python 进程里压根没有这个类。第三种是 dtype 问题。safetensors 保存时会记录每个张量的 dtype加载时如果用 CPU 且显存不足容易自动转成 float32。这本身不是 bug但如果你习惯用torch_dtypeauto加载要留意模型半精度和全精度下的数值行为差异尤其在打印生成结果时可能看出一丢丢浮点误差层面的不一样。5.3 push_to_hub 和 model card把模型变成可复现资产最后一步是把产物推到 Hub。这里不只是传文件更要把 model card 写清楚。我的习惯是 markdown 里至少包含基座模型和 tokenizer 版本、训练数据概况、超参表、评估结果、以及复现命令。训练直接自动化 push 其实不用额外写脚本TrainingArguments里支持直接配hub_model_id your_org/minimal-llm-exp-06 push_to_hubTrue这样每个 save checkpoint 的步骤都会自动往 hub 传。前提是先跑过一次huggingface-cli login或者设置好 token 环境变量。我更喜欢用HfApi.upload_folder做总控把最终产物一次性推上去from huggingface_hub import HfApi api HfApi() api.upload_folder( folder_path./my_model_final, repo_idyour_org/minimal-llm-exp-06, repo_typemodel, commit_messageLab 06 final result, )这个做法的好处是本地训练产物和 hub 仓库之间没有自动同步的隐性状态推的就是最终你验证过的那份。自动 push 虽然省事但很容易把坏中间步也推上去。model card 这一层看似不影响程序运行但它决定了后来的人能不能看懂你的实验。我见过太多模型仓库只有一个 README 标题没有超参没有数据描述权重文件倒是都在但要复现基本靠猜。其实写 model card 花不了十分钟收益却很大——三个月后的你也是“后来的人”。6. 常见问题速查与排查技巧记录每次做这种改造我基本都会踩几个固定的坑。整理一份排查记录可以帮你少走很多弯路。6.1 报错实录一模型的 type 检查不过报错信息Model should be a instance of PreTrainedModel。原因基本可以分成两类。第一类是模型类确实没有继承 PreTrainedModel只是结构类似。第二类是继承了但因为循环 import 或者直接 import 了别的同名模块导致类对象地址不一致isinstance 判断失败。排查方法在报错位置前直接打一行print(isinstance(model, PreTrainedModel))。如果结果是 False先检查 class 声明如果代码没问题检查 import 路径。尤其是 notebook 环境下重新加载了模块但旧类还在内存里模型类本身没问题但 notebook 里的类地址变了也会出现这种诡异现象。解决办法是重启 kernel或者确保from importlib import reload; reload(my_model_module)。6.2 报错实录二权重 key 对不上与 tokenizer 不匹配权重对不上的典型告警是Some weights of the model checkpoint ... were not used。我会第一时间打开state_dict对比 keyimport torch statedict torch.load(path_to_safetensors/model.safetensors, map_locationcpu) print(len(statedict.keys())) print(list(statedict.keys())[:20])对比模型自己的model.state_dict().keys()加上 base_model_prefix 前后差异基本一眼就能看出是前缀问题还是层结构变化问题。tokenizer 不匹配的报错则更隐蔽。比如你训练时用的是 LLaMA 的 tokenizer但推理时换成 Qwen 的 tokenizer词表 index 错位会让生成结果变成乱码甚至越界报错。排查方法是在 save_pretrained 后立刻用同一 tokenizer 做一次 decode 测试不要只测 encode。6.3 离线与受限网络下怎么拉通整个流程很多公司内部机器访问 Hugging Face Hub 并不顺畅这本身不妨碍你遵守契约只是下载环节要额外处理。我的做法分两种场景。第一种能下载到外网的机器直接用HF_ENDPOINThttps://hf-mirror.com这样的环境变量把默认端点切到镜像站然后正常跑from_pretrained。第二种彻底离线的机器在外网机器上把当前from_pretrained需要的整个缓存目录打包传到离线机器的~/.cache/huggingface/hub或者更直接一点把模型文件下载后解压到一个本地目录后面统一用本地路径加载。本地加载其实是非常符合契约五的因为 HF 的from_pretrained本身就支持目录路径。你可以干脆不把模型传到 hub而是把所有内容存在共享盘上每人直接from_pretrained(/share/models/minimal-llm-exp-06)。这样权重、config、tokenizer 都在一起跟 hub 上的行为一致只是少了 git 版本管理。如果团队人多、有版本回滚需求还是建议推 hub 私有仓库用 git 本身做版本追溯。6.4 我的避坑清单最后给一份可以直接贴到团队文档里的避坑清单。自定义模型一律继承 PreTrainedModel并且实现config_class、base_model_prefix、prepare_inputs_for_generation。配置类一定继承 PretrainedConfig并且把model_type定义成全局唯一字符串。模型类放在独立模块训练脚本顶部显式 import别放在 main 函数里。数据预处理后用remove_columns清掉非数值字段labels 独立复制一份。训练阶段用右侧 padding、动态 padding不要手动 pad 到最大长度。保存产物时同时保存 model 和 tokenizer加载验证脚本必须在产物目录上跑通一遍。推 Hub 时写清楚 model card包含超参、数据来源和复现命令。这几条看着简单但每一条都对应着我实际踩过的某个坑。我记得 Lab 03 的时候为了在DataCollatorForLanguageModeling里手动设置mask_token_type折腾了大半天最后发现根因不过是 pad_token 没设置collator 在 label 里打不上-100。那种查错过程很难受但经验也就这么沉淀下来了。如果你现在的项目正卡在某个“HF 接口”上先别急着搜教程对照这五条契约一条条过一遍大概率能直接定位到问题。尤其是“能跑但结果不对”这一类几乎都是契约三或契约四的隐性违约。