无HuggingFace transformers库环境下基于本地文件离线使用BERT分词器与模型的实现

一、基于本地vocab.txt实现离线BERTTokenizer #

因环境无法安装transformers库，bert-base-uncased的WordPiece分词逻辑可完全基于本地文件手写实现，无额外第三方依赖：

• 第一步：构建token与索引的映射表
  逐行读取本地vocab.txt，生成两个核心字典：token到id的正向映射、id到token的反向映射。自动识别特殊token的对应索引：[PAD]、[UNK]、[CLS]、[SEP]、[MASK]，无需硬编码特殊值。
• 第二步：实现核心分词流程，完全对齐bert-base-uncased的预处理规则
  • 基础文本预处理：统一转小写，过滤不可见控制字符，按空格拆分基础词单元
  • 子词匹配逻辑：对每个拆分出的基础词，优先匹配完整词；如果不在词汇表内，从长到短拆分片段，为每个片段添加##前缀匹配词汇表中的子词，若最终仍有无法匹配的片段则替换为[UNK]
  • 输入格式拼接：在token序列开头添加[CLS]，句末添加[SEP]；双句输入场景下，在两个句子中间插入一个[SEP]分隔
  • 生成模型输入所需的三个张量：input_ids（token对应的索引序列）、attention_mask（真实token位置标记为1，padding位置标记为0）、token_type_ids（第一句对应位置标记为0，第二句对应位置标记为1，padding位置标记为0）
• 第三步：补充序列长度处理逻辑
  从本地config.json中读取max_position_embeddings参数，对超出最大长度的序列做截断；对长度不足的序列补[PAD]对应的索引完成填充。

二、基于PyTorch原生能力离线加载BertForTokenClassification模型 #

按照PyTorch模型加载的通用逻辑，结合本地config与权重文件完成模型构建，无需依赖transformers库的模型类：

• 第一步：解析本地config.json
  用Python内置json库读取本地配置文件，提取全部模型结构参数：vocab_size、hidden_size、num_hidden_layers、num_attention_heads、intermediate_size、max_position_embeddings、type_vocab_size，所有参数直接用于后续模型结构搭建。

  注意：本地权重文件若误命名为python_model.bin，需修正为bert-base-uncased标准的pytorch_model.bin命名，否则会出现文件读取失败。

• 第二步：搭建与HuggingFace BERT结构完全对齐的PyTorch模型
  按读取到的参数依次实现组件：
  • 嵌入层：融合token嵌入、位置嵌入、token类型嵌入，搭配LayerNorm与Dropout层
  • 多层Transformer Encoder结构：包含多头自注意力层、逐位置前馈网络
  • Token分类输出头：将Encoder每个位置的输出接入全连接层，映射为与自有数据集标签数匹配的输出维度
    关键要求：所有层的命名必须与本地权重文件内的键名完全对齐，否则加载时会出现键不匹配的问题，比如嵌入层权重需对应bert.embeddings.word_embeddings.weight这类原权重的存储命名规则。
• 第三步：加载本地预训练权重
  用PyTorch原生的torch.load()读取本地权重文件，拿到state_dict后，过滤掉自定义Token分类头对应的权重条目（这部分为随机初始化，无需加载预训练值），将匹配上的预训练权重一一赋值到搭建好的模型层上。
  加载时设置map_location='cpu'适配无GPU环境，设置strict=False允许部分键值缺失，避免加载报错。

三、实操避坑要点 #

• 分词逻辑必须严格对齐bert-base-uncased的WordPiece规则，特别是大小写转换、##前缀的子词拼接逻辑，否则会导致分词结果与预训练模型的训练分布偏差，精度大幅下降
• 全程不要触发任何远程网络请求，所有文件均通过本地绝对路径读取，避免违反环境的网络安全限制
• 自定义Token分类头的输出维度需与自有数据集的标签总数完全匹配，可使用PyTorch默认的正态分布初始化

内容的提问来源于stack exchange，提问作者cclams4444