TensorFlow Models BERT Legacy 实现指南从预训练 Checkpoint 到 GLUE/SQuAD 微调的完整实战【免费下载链接】modelsModels and examples built with TensorFlow项目地址: https://gitcode.com/GitHub_Trending/mode/models本文基于仓库中 official/legacy/bert/README.md 的官方文档系统讲解该目录内 TensorFlow 2.x 版 BERT legacy 实现的完整使用链路预训练 checkpoint 与 tf.hub 模块的获取与恢复、tf-nightly/TPU 环境搭建、预训练与微调数据生成以及用run_classifier.py、run_squad.py在 GPU/TPU 上完成 MRPC 句对分类和 SQuAD 1.1 问答微调。全文在继承原文档全部命令与配置的基础上结合official/legacy/bert下的源码补充了关键命令行参数的默认值、取值范围与底层调用逻辑。1. Legacy 实现定位与nlp/modeling新实现的关系需要先明确本文代码的版本定位。README 开头即给出弃用警告该目录中的大部分代码正在被逐步弃用deprecating官方建议改用新教程与nlp/modeling中的新代码而该 README 本身对这份 legacy 实现依然正确。从源码结构看legacy 目录的 BERT 模型并非独立实现而是复用了新代码库的 Keras functional 风格网络bert_models.py 直接from official.nlp.modeling import models和from official.nlp.modeling import networksbert_models.py#L23-L24并引入了 official/legacy/albert/configs.py 以兼容 ALBERT 配置。这与 README 中“已切换到使用 Keras functional-style 网络”的说明一致。README 中列出的预训练 checkpoint 与 hub 模块均由 TF 1.x 官方 BERT 仓库google-research/bert的 checkpoint 转换而来以保证与 BERT 论文arXiv: 1810.04805结果一致。使用这份 legacy 代码的典型场景是需要对齐论文原始实验配置、迁移旧脚本、或复用 TF1 转换出的 checkpoint 命名结构。2. 预训练模型Checkpoint 与 tf.hub 模块2.1 预训练 Checkpoint 清单Checkpoint 托管在 Google Cloud Storage 的gs://cloud-tpu-checkpoints/bert/keras_bert目录下README 推荐在使用 Cloud GPU/TPU 时直接以 GCS 路径作为BERT_DIR。完整清单如下维度记法为L-层数_H-隐藏维度_A-注意力头数模型规格参数规模GCS 相对位置BERT-Large, Uncased (Whole Word Masking)24 层, 1024 隐藏, 16 头340Mwwm_uncased_L-24_H-1024_A-16BERT-Large, Cased (Whole Word Masking)24 层, 1024 隐藏, 16 头340Mwwm_cased_L-24_H-1024_A-16BERT-Base, Uncased12 层, 768 隐藏, 12 头110Muncased_L-12_H-768_A-12BERT-Large, Uncased24 层, 1024 隐藏, 16 头340Muncased_L-24_H-1024_A-16BERT-Base, Cased12 层, 768 隐藏, 12 头110Mcased_L-12_H-768_A-12BERT-Large, Cased24 层, 1024 隐藏, 16 头340Mcased_L-24_H-1024_A-16BERT-Base, Multilingual Cased104 种语言, 12 层, 768 隐藏, 12 头110Mmulti_cased_L-12_H-768_A-12每个 checkpoint 目录内含bert_model.ckpt、bert_config.json与vocab.txt后文微调命令中的--bert_config_file、--init_checkpoint、--vocab_file均指向这些文件。2.2 用tf.train.Checkpoint恢复权重README 给出的恢复方式是 TF2 标准的tf.train.Checkpoint机制init_checkpoint the pretrained model checkpoint path. model tf.keras.Model() # BERT 预训练模型作为特征提取器 checkpoint tf.train.Checkpoint(modelmodel) checkpoint.restore(init_checkpoint)在仓库源码中可以看到训练入口实际采用的写法。run_classifier.py 在run_keras_compile_fit中恢复 checkpoint 时注册了两个名称run_classifier.py#L219-L221if init_checkpoint: checkpoint tf.train.Checkpoint(modelsub_model, encodersub_model) checkpoint.read(init_checkpoint).assert_existing_objects_matched()这里把同一个子模型同时以model和encoder两个名字注册进tf.train.Checkpoint再用readassert_existing_objects_matched做匹配校验。从源码结构看这样命名的目的是同时兼容以model命名的 checkpoint 和以encoder命名的 tf.hub 模块导出这正是--init_checkpoint与--hub_module_url可以互换使用的底层原因。2.3 预训练 tf.hub 模块SavedModel 格式的 hub 模块覆盖与 checkpoint 相同的模型矩阵并额外提供中文模型Hub 模块规格参数规模BERT-Large, Uncased (WWL)24 层, 1024 隐藏, 16 头340MBERT-Large, Cased (WWL)24 层, 1024 隐藏, 16 头340MBERT-Base, Uncased12 层, 768 隐藏, 12 头110MBERT-Large, Uncased24 层, 1024 隐藏, 16 头340MBERT-Base, Cased12 层, 768 隐藏, 12 头110MBERT-Large, Cased24 层, 1024 隐藏, 16 头340MBERT-Base, Multilingual Cased104 种语言, 12 层, 768 隐藏, 12 头110MBERT-Base, Chinese简体中文/繁体, 12 层, 768 隐藏, 12 头110M在训练脚本中用--hub_module_urltfhub 模块路径替代--init_checkpoint即可加载 hub 模块common_flags.py 中hub_module_url的定义注明“如果指定了该 flag则不应再使用init_checkpoint”common_flags.py#L71-L75且hub_module_trainable默认为True即 hub 模块中的 Keras 层默认参与训练可微调而非冻结。3. 环境搭建README 给出的环境准备步骤如下export PYTHONPATH$PYTHONPATH:/path/to/models安装tf-nightly获取最新特性pip install tf-nightly-gpu在 TPU 上训练时无需 GPU 支持需要先用 ctpu 工具创建一台tf-nightly版 TPU 实例ctpu up -name instance name --tf-versionnightly然后在 VM 上安装 TF2 的tf-nightlypip install tf-nightly适用前提说明该目录代码面向 TF 2.x tf-nightlyREADME 中pip install tf-nightly-gpu/pip install tf-nightly与ctpu up --tf-versionnightly组合使用运行入口脚本依赖tensorflow_hubbert_models.py 顶层import tensorflow_hub as hub。4. 数据处理4.1 预训练数据create_pretraining_data.py生成预训练数据的脚本没有变化使用 official/nlp/data/create_pretraining_data.py——该脚本基本源自 BERT 研究仓库并已适配 TF2 符号与 Python 3。脚本需要输入/输出目录和词表文件且max_seq_length必须与之后运行预训练时指定的序列长度一致。README 给出的调用示例export WORKING_DIRlocal disk or cloud location export BERT_DIRlocal disk or cloud location python models/official/nlp/data/create_pretraining_data.py \ --input_file$WORKING_DIR/input/input.txt \ --output_file$WORKING_DIR/output/tf_examples.tfrecord \ --vocab_file$BERT_DIR/wwm_uncased_L-24_H-1024_A-16/vocab.txt \ --do_lower_caseTrue \ --max_seq_length512 \ --max_predictions_per_seq76 \ --masked_lm_prob0.15 \ --random_seed12345 \ --dupe_factor5各参数含义input_file为原始文本[CLS]/[SEP]分隔语料output_file输出 tfrecord 格式样本do_lower_case需与所用 checkpoint 的 cased/uncased 属性匹配max_seq_length512为 BERT 标准上下文长度max_predictions_per_seq76对应每序列最多 76 个 masked tokenmasked_lm_prob0.15即 BERT 论文中 15% 词元被遮蔽的比例其中 80% 替换为[MASK]、10% 随机词、10% 保持原样random_seed与dupe_factor5分别控制随机种子与语料重复采样轮数。4.2 微调数据create_finetuning_data.py微调数据由 official/nlp/data/create_finetuning_data.py 统一生成产出tf_record格式数据集与训练元数据文件后续训练/评估脚本通过--input_meta_data_path读取该元数据。任务类型由--fine_tuning_task_type指定源码中可选值包括classification、regression、retrieval、squad、tagging。GLUE 分类任务。先下载 GLUE 任务数据并解压到$GLUE_DIRGLUE benchmark 官网提供下载脚本再准备 checkpoint 目录$BERT_DIR可以是 GCS 路径。以 MNLI 为例export GLUE_DIR~/glue export BERT_DIRgs://cloud-tpu-checkpoints/bert/keras_bert/uncased_L-24_H-1024_A-16 export TASK_NAMEMNLI export OUTPUT_DIRgs://some_bucket/datasets python official/nlp/data/create_finetuning_data.py \ --input_data_dir${GLUE_DIR}/${TASK_NAME}/ \ --vocab_file${BERT_DIR}/vocab.txt \ --train_data_output_path${OUTPUT_DIR}/${TASK_NAME}_train.tf_record \ --eval_data_output_path${OUTPUT_DIR}/${TASK_NAME}_eval.tf_record \ --meta_data_file_path${OUTPUT_DIR}/${TASK_NAME}_meta_data \ --fine_tuning_task_typeclassification --max_seq_length128 \ --classification_task_name${TASK_NAME}其中--classification_task_name限定为 GLUE 任务名如MNLI--max_seq_length128需小于或等于 checkpoint 预训练长度 512。SQuAD 任务。所需文件为 train/dev 的 v1.1 与 v2.0 JSON 以及对应版本官方评估脚本SQuAD 官网与评估脚本均可从 SQuAD 官方站点获取export SQUAD_DIR~/squad export SQUAD_VERSIONv1.1 export BERT_DIRgs://cloud-tpu-checkpoints/bert/keras_bert/uncased_L-24_H-1024_A-16 export OUTPUT_DIRgs://some_bucket/datasets python official/nlp/data/create_finetuning_data.py \ --squad_data_file${SQUAD_DIR}/train-${SQUAD_VERSION}.json \ --vocab_file${BERT_DIR}/vocab.txt \ --train_data_output_path${OUTPUT_DIR}/squad_${SQUAD_VERSION}_train.tf_record \ --meta_data_file_path${OUTPUT_DIR}/squad_${SQUAD_VERSION}_meta_data \ --fine_tuning_task_typesquad --max_seq_length384注意生成 SQuAD 2.0 微调数据需要额外加--version_2_with_negativeTrue标志以保留“无答案”样本的 negative 标注。5. 句子/句对分类任务微调MRPC 示例本小节以在 MRPC仅约 3,600 条样本多数 GPU 上数分钟即可微调上微调BERT-Largeuncased_L-24_H-1024_A-16为例GPU 显存 16GB 或更小时建议改用BERT-Baseuncased_L-12_H-768_A-12。5.1 GPU 训练命令完整export BERT_DIRgs://cloud-tpu-checkpoints/bert/keras_bert/uncased_L-24_H-1024_A-16 export MODEL_DIRgs://some_bucket/my_output_dir export GLUE_DIRgs://some_bucket/datasets export TASKMRPC python official/legacy/bert/run_classifier.py \ --modetrain_and_eval \ --input_meta_data_path${GLUE_DIR}/${TASK}_meta_data \ --train_data_path${GLUE_DIR}/${TASK}_train.tf_record \ --eval_data_path${GLUE_DIR}/${TASK}_eval.tf_record \ --bert_config_file${BERT_DIR}/bert_config.json \ --init_checkpoint${BERT_DIR}/bert_model.ckpt \ --train_batch_size4 \ --eval_batch_size4 \ --steps_per_loop1 \ --learning_rate2e-5 \ --num_train_epochs3 \ --model_dir${MODEL_DIR} \ --distribution_strategymirrored不想用本地/GCS checkpoint 时可改用--hub_module_urltfhub 模块 URL 及版本号替代--init_checkpoint。5.2 关键参数与源码默认值结合 run_classifier.py 与 common_flags.py 的 flag 定义上例涉及参数的完整说明如下参数默认值说明--modetrain_and_eval枚举train_and_eval/export_only/predict边训边评、仅从 model_dir 最新 checkpoint 导出 SavedModel、恢复 checkpoint 对测试集出预测run_classifier.py#L37-L43--bert_config_file、--input_meta_data_path、--model_dir无三个必填 flagrun_classifier.py#L511-L513--train_batch_size/--eval_batch_size32 / 32全局 batch size内部按 replica 切分--learning_rate5e-5Adam 初始学习率common_flags.py#L57-L58--num_train_epochs3训练轮数common_flags.py#L49-L50--steps_per_loop按设备自动配置每个 graph-mode 循环内的训练步数循环内不触发回调common_flags.py#L51-L56--optimizer_typeadamw可选adamw或lambcommon_flags.py#L61-L62--distribution_strategy无可选mirrored/tpu等TPU 地址由--tpugrpc://IP:8470指定--end_lr0.0学习率衰减终点源码中还有两条值得注意的计算逻辑run_classifier.py#L373-L382steps_per_epoch train_data_size // train_batch_size且当设置--num_eval_per_epochn时实际 epoch 数放大为num_train_epochs * n每个 epoch 每处理 N/n 个样本评估一次用于获得更细粒度的评估分数与 checkpointwarmup 步数固定取总步数的 10%warmup_steps epochs * train_data_size * 0.1 / train_batch_size配合 official/nlp/optimization.py 的create_optimizer生成带线性衰减的优化器。5.3 预测与结果输出训练完成后设--modepredict并通过--eval_data_path提供测试集 tfrecord 即可获取分类概率python official/legacy/bert/run_classifier.py \ --modepredict \ --input_meta_data_path${GLUE_DIR}/${TASK}_meta_data \ --eval_data_path${GLUE_DIR}/${TASK}_eval.tf_record \ --bert_config_file${BERT_DIR}/bert_config.json \ --eval_batch_size4 \ --model_dir${MODEL_DIR} \ --distribution_strategymirrored输出写入model_dir下的test_results.tsv每行对应一个样本列为各类别的概率。这与源码中 predict 分支的行为一致恢复 checkpoint默认取tf.train.latest_checkpoint(FLAGS.model_dir)也可用--predict_checkpoint_path指定后对每条样本softmax得到概率并逐行 tab 分隔写出run_classifier.py#L456-L484。5.4 TPU 上微调从 GPU 切到 TPU 只需切换分发策略类型、提供 TPU 地址并将 checkpoint 存放在远程存储GCSexport BERT_DIRgs://cloud-tpu-checkpoints/bert/keras_bert/uncased_L-24_H-1024_A-16 export TPU_IP_ADDRESS??? export MODEL_DIRgs://some_bucket/my_output_dir export GLUE_DIRgs://some_bucket/datasets export TASKMRPC python official/legacy/bert/run_classifier.py \ --modetrain_and_eval \ --input_meta_data_path${GLUE_DIR}/${TASK}_meta_data \ --train_data_path${GLUE_DIR}/${TASK}_train.tf_record \ --eval_data_path${GLUE_DIR}/${TASK}_eval.tf_record \ --bert_config_file${BERT_DIR}/bert_config.json \ --init_checkpoint${BERT_DIR}/bert_model.ckpt \ --train_batch_size32 \ --eval_batch_size32 \ --steps_per_loop1000 \ --learning_rate2e-5 \ --num_train_epochs3 \ --model_dir${MODEL_DIR} \ --distribution_strategytpu \ --tpugrpc://${TPU_IP_ADDRESS}:8470TPU 版将--steps_per_loop1000的原因把大量训练步封装进tf.function图循环执行可显著提升 TPU 利用率代价是回调不会在循环内部触发。训练主循环采用 Kerascompile/fit 分发策略 APIsteps_per_execution即透传该值run_classifier.py#L225-L229。6. SQuAD 1.1 微调同样以BERT-Largeuncased_L-24_H-1024_A-16为例16GB 显存以内建议BERT-Base。6.1 GPU 训练命令完整export BERT_DIRgs://cloud-tpu-checkpoints/bert/keras_bert/uncased_L-24_H-1024_A-16 export SQUAD_DIRgs://some_bucket/datasets export MODEL_DIRgs://some_bucket/my_output_dir export SQUAD_VERSIONv1.1 python official/legacy/bert/run_squad.py \ --input_meta_data_path${SQUAD_DIR}/squad_${SQUAD_VERSION}_meta_data \ --train_data_path${SQUAD_DIR}/squad_${SQUAD_VERSION}_train.tf_record \ --predict_file${SQUAD_DIR}/dev-v1.1.json \ --vocab_file${BERT_DIR}/vocab.txt \ --bert_config_file${BERT_DIR}/bert_config.json \ --init_checkpoint${BERT_DIR}/bert_model.ckpt \ --train_batch_size4 \ --predict_batch_size4 \ --learning_rate8e-5 \ --num_train_epochs2 \ --model_dir${MODEL_DIR} \ --distribution_strategymirrored与分类任务一样可用--hub_module_url替代--init_checkpoint。run_squad.py默认会对--predict_file写出预测结果若将--mode设为predict并提供 SQuAD 测试数据则生成预测 JSON 文件。6.2 SQuAD 专属参数run_squad_helper.py 中的define_common_squad_flags定义了 SQuAD 相关参数run_squad_helper.py#L37-L92参数默认值说明--modetrain_and_eval六种取值train_and_eval训练、预测到 JSON 并计算指标、train_and_predict、train、eval、predict、export_only--do_lower_caseTrue输入是否小写化uncased 模型应为 Truecased 模型应为 False--predict_batch_size8预测全局 batch--n_best_size20输出到nbest_predictions.json的 n-best 候选数--max_answer_length30允许生成的最长答案因 start/end 预测相互独立而必须限制--null_score_diff_threshold0.0仅 SQuAD 2.0 使用null_score - best_non_null大于阈值时预测空答案--predict_file无支持通配符与逗号分隔的多文件模式eval模式只支持单个文件6.3 TPU 训练与评估切 TPU 同样只需换分发策略export BERT_DIRgs://cloud-tpu-checkpoints/bert/keras_bert/uncased_L-24_H-1024_A-16 export TPU_IP_ADDRESS??? export MODEL_DIRgs://some_bucket/my_output_dir export SQUAD_DIRgs://some_bucket/datasets export SQUAD_VERSIONv1.1 python official/legacy/bert/run_squad.py \ --input_meta_data_path${SQUAD_DIR}/squad_${SQUAD_VERSION}_meta_data \ --train_data_path${SQUAD_DIR}/squad_${SQUAD_VERSION}_train.tf_record \ --predict_file${SQUAD_DIR}/dev-v1.1.json \ --vocab_file${BERT_DIR}/vocab.txt \ --bert_config_file${BERT_DIR}/bert_config.json \ --init_checkpoint${BERT_DIR}/bert_model.ckpt \ --train_batch_size32 \ --learning_rate8e-5 \ --num_train_epochs2 \ --model_dir${MODEL_DIR} \ --distribution_strategytpu \ --tpugrpc://${TPU_IP_ADDRESS}:8470dev 集预测保存到model_dir下的predictions.json随后调用 SQuAD 1.1 官方评估脚本计算 Exact Match / F1python $SQUAD_DIR/evaluate-v1.1.py $SQUAD_DIR/dev-v1.1.json ./squad/predictions.json仓库内也内置了等价的评估实现run_squad_helper.py 顶部from official.nlp.tools import squad_evaluate_v1_1与squad_evaluate_v2_0run_squad_helper.py#L31-L33即--modetrain_and_eval时评估指标直接由 official/nlp/tools/squad_evaluate_v1_1.py 在进程内计算。7. 底层实现要点与延伸阅读综合上述脚本该 legacy 实现的架构可以概括为模型层bert_models.py 提供BertPretrainLossAndMetricLayermasked LM 下一句预测的加权 loss 与 accuracy 指标以及分类/问答任务模型工厂编码器本体复用 official/nlp/modeling 中 Keras functional 风格的 BERT 网络支持通过hub_module_url直接以 hub 模块为编码器。数据层统一走 official/legacy/bert/input_pipeline.py 读取create_finetuning_data.py产出的 tf_record配合元数据文件中的max_seq_length、num_labels、label_typeint/float自动切换分类/回归分支num_classes1时按回归处理使用均方误差见 run_classifier.py#L133-L135。训练层基于distribute_utils.get_distribution_strategy构建mirrored/TPU 策略Kerascompile/fit驱动训练tf.train.CheckpointManagerSimpleCheckpoint回调管理 checkpointrun_classifier.py#L233-L254混合精度fp16通过common_flags.dtype()与performance.set_mixed_precision_policy开启。测试与验证目录内附 run_classifier 与 SQuAD 相关测试official/legacy/bert/bert_models_test.py、official/legacy/bert/model_training_utils_test.py可用于验证模型构建与训练工具函数行为。如需长期维护的新项目建议迁移到 official/nlp 下基于 gin 实验配置的训练框架本文命令与参数仅对该 legacy 目录内的脚本适用。【免费下载链接】modelsModels and examples built with TensorFlow项目地址: https://gitcode.com/GitHub_Trending/mode/models创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考