bilm-tf

用于从论文《深度上下文词表示》（arXiv:1802.05365）中计算 ELMo 表示的预训练双向语言模型的 TensorFlow 实现。

该仓库既支持训练双向语言模型，也支持使用预训练模型进行预测。

我们还在 AllenNLP 中提供了 PyTorch 版本的实现。

如果您只是想进行预测，使用 TensorFlow Hub 提供的版本可能会更加方便。

引用：

@inproceedings{Peters:2018,
  author={Peters, Matthew E. and  Neumann, Mark and Iyyer, Mohit and Gardner, Matt and Clark, Christopher and Lee, Kenton and Zettlemoyer, Luke},
  title={Deep contextualized word representations},
  booktitle={Proc. of NAACL},
  year={2018}
}

安装

请安装 Python 3.5 或更高版本、TensorFlow 1.2 和 h5py：

pip install tensorflow-gpu==1.2 h5py
python setup.py install

确保在您的环境中运行测试通过：

python -m unittest discover tests/

使用 Docker 安装

要运行镜像，您必须使用 nvidia-docker，因为此仓库需要 GPU。

sudo nvidia-docker run -t allennlp/bilm-tf:training-gpu

使用预训练模型

我们提供了多种不同的英语预训练双向语言模型供使用。每个模型由两个文件组成：一个 JSON 格式的超参数“选项”文件，以及一个 HDF5 格式的模型权重文件。预训练模型的下载链接可在 这里 找到。

根据您的应用场景，有三种方式可以将 ELMo 表示集成到下游任务中：

1. 使用字符输入，从原始文本实时计算表示。这是最通用的方法，能够处理任何输入文本，但计算开销也最大。
2. 预先计算并缓存与上下文无关的词元表示，然后使用双向 LSTM 对输入数据计算上下文相关的表示。这种方法比方法 1 计算开销小，但仅适用于固定且已知的词汇表。
3. 预先计算整个数据集的表示，并将其保存到文件中。

我们过去曾针对不同场景使用过这三种方法。方法 1 是在测试时评估未见过的数据（例如公开的 SQuAD 排行榜）所必需的；方法 2 是处理大型数据集时的一个折中方案，当方法 3 的文件过大而不可行时适用（如 SNLI、SQuAD）；方法 3 则适合较小的数据集，或者当您希望在其他框架中使用 ELMo 时。

无论采用哪种方法，流程大致相同。首先，创建一个 Batcher（或对于方法 2 使用 TokenBatcher），将分词后的字符串转换为字符（或词元）ID 的 NumPy 数组。然后，加载预训练的 ELMo 模型（BidirectionalLanguageModel 类）。最后，对于方法 1 和方法 2，使用 weight_layers 计算最终的 ELMo 表示；而对于方法 3，则使用 BidirectionalLanguageModel 将所有中间层写入文件。

形状约定

每个分词后的句子是一个 str 列表，一批句子则是分词后句子的列表（List[List[str]]）。

Batcher 会将这些打包成形状为 (n_sentences, max_sentence_length + 2, 50) 的字符 ID NumPy 数组，长度不足最大值的句子会在右侧用 0 填充。每句的第一个和最后一个 token 是由 Batcher 添加的特殊句首和句尾标记。

输入字符 ID 占位符的维度可以设置为 (None, None, 50)，其中批次维度（轴 0）和时间维度（轴 1）会根据每次批处理动态确定，上限由 BidirectionalLanguageModel 构造函数中指定的最大批次大小决定。

对批次运行推理后，返回的 biLM 嵌入是一个形状为 (n_sentences, 3, max_sentence_length, 1024) 的 NumPy 数组，移除了特殊的句首/句尾标记。

词汇表文件

为了提高效率，Batcher 需要一个词汇表文件作为输入。这是一个文本文件，每行一个 token，以换行符 (\n) 分隔。词汇表中的每个 token 只会被缓存一次，对应的 50 维字符 ID 序列也会被存储。由于模型完全基于字符，不在词汇表中的 token 在运行时仍能被正确处理，只是会略微降低运行速度。建议始终在词汇表中包含区分大小写的特殊标记 <S> 和 </S>。

使用字符输入的 ELMo

详细用法示例请参见 usage_character.py。

使用预先计算并缓存的与上下文无关的词元表示

为了加快具有固定词汇表的模型推理速度，可以预先计算与上下文无关的词元表示，将其保存到文件中，并在推理时重复使用。请注意，我们不支持对未登录词汇回退到字符输入，因此此方法仅适用于双向语言模型用于计算具有固定且明确词汇表的输入嵌入的情况。

使用此方法的步骤如下：

1. 首先，创建一个包含数据集中所有唯一 token 的词汇表，并添加特殊的 <S> 和 </S> 标记。
2. 使用完整模型运行 dump_token_embeddings，将词元嵌入写入 HDF5 文件。
3. 使用 TokenBatcher（而非 Batcher）配合您的词汇表文件，在 BidirectionalLanguageModel 构造函数中设置 use_token_inputs=False，并传入步骤 2 中生成的输出文件名。

详细用法示例请参见 usage_token.py。

将整个数据集的 biLM 嵌入转储到单个文件中

要采用此方法，请创建一个包含分词后数据集的文本文件，每行是一个分词后的句子（以空格分隔）。然后使用 dump_bilm_embeddings。

输出文件为 HDF5 格式。输入数据中的每句话都会以数据集的形式存储，键为 str(sentence_id)，其中 sentence_id 是数据集文件中的行号（从 0 开始计数）。每句话的嵌入是一个形状为 (3, n_tokens, 1024) 的数组。

详细示例请参见 usage_cached.py。

在新语料上训练双向语言模型

广义上讲，训练和使用一个新的双向语言模型的流程如下：

1. 准备输入数据和词汇表文件。
2. 训练双向语言模型。
3. 在保留数据上测试（计算困惑度）该双向语言模型。
4. 将训练好的双向语言模型的权重导出到一个 HDF5 文件中。
5. 参阅上述说明，了解如何在下游模型中使用第 4 步的输出。

1. 准备输入数据和词汇表文件。

要训练和评估一个双向语言模型，你需要提供：

• 词汇表文件
• 一组训练文件
• 一组保留文件

词汇表文件是一个文本文件，每行包含一个词元。该文件还必须包含特殊词元 <S>、</S> 和 <UNK>（区分大小写）。

重要提示：词汇表文件应按照训练数据中各词元的出现频率降序排列。前三行应分别为特殊词元（<S>、</S> 和 <UNK>），然后是训练数据中最常见的词元，最后是出现频率最低的词元。

注意：用于训练的词汇表文件可能与用于预测的词汇表文件不同。

训练数据应随机分割成多个训练文件，每个文件包含数据的一个子集。每个文件包含预分词且以空格分隔的文本，每行一个句子。请勿在训练数据中包含 <S> 或 </S> 词元。

所有的分词和归一化处理都应在模型训练之前完成，因此词汇表文件和训练文件都应包含归一化的词元。由于默认设置采用完全基于字符的词元表示方式，通常我们不建议进行除分词之外的其他归一化处理。

最后，从训练数据中保留一小部分作为保留数据，用于评估训练好的双向语言模型。

2. 训练双向语言模型。

用于训练 ELMo 模型的超参数可以在 bin/train_elmo.py 中找到。

ELMo 模型是在 3 个 GPU 上训练的。要使用相同的超参数训练一个新的模型，首先从 10 亿词基准 下载训练数据。然后下载 词汇表文件。最后运行以下命令：

export CUDA_VISIBLE_DEVICES=0,1,2
python bin/train_elmo.py \
    --train_prefix='/path/to/1-billion-word-language-modeling-benchmark-r13output/training-monolingual.tokenized.shuffled/*' \
    --vocab_file /path/to/vocab-2016-09-10.txt \
    --save_dir /output_path/to/checkpoint

3. 评估训练好的模型。

使用 bin/run_test.py 来评估训练好的模型，例如：

export CUDA_VISIBLE_DEVICES=0
python bin/run_test.py \
    --test_prefix='/path/to/1-billion-word-language-modeling-benchmark-r13output/heldout-monolingual.tokenized.shuffled/news.en.heldout-000*' \
    --vocab_file /path/to/vocab-2016-09-10.txt \
    --save_dir /output_path/to/checkpoint

4. 将 TensorFlow 检查点转换为 HDF5 格式，以便使用 bilm 或 allennlp 进行预测。

首先，为新训练的模型创建一个 options.json 文件。为此，请参考现有文件中的模板（例如原始的 options.json），并根据你的超参数进行修改。

重要提示：训练完成后，务必始终将 n_characters 设置为 262（见下文）。

然后运行以下命令：

python bin/dump_weights.py \
    --save_dir /output_path/to/checkpoint
    --outfile /output_path/to/weights.hdf5

常见问题及其他注意事项

能否提供训练时的 TensorFlow 检查点文件？

TensorFlow 检查点可通过下载以下文件获得：

• 词汇表
• 检查点文件
• 选项文件
• 模型数据文件 1
• 模型数据文件 2
• 模型元数据文件

如何在额外的无标签数据上对模型进行微调？

首先下载上述检查点文件。然后按照“在新语料库上训练 biLM”一节中的说明准备数据集，不同之处在于我们将使用现有的词汇表文件，而不是创建新的词汇表。最后，使用脚本 bin/restart.py 在新数据集上从现有检查点继续训练。 对于小型数据集（例如少于 1000 万词），我们建议仅进行少量轮次的微调，并监控保留集上的困惑度；否则模型可能会过拟合小数据集。

softmax 权重是否可用？

它们包含在上述训练检查点中。

能否提供更多关于模型训练方式的细节？

脚本 bin/train_elmo.py 中包含了用于训练模型的超参数。 原始模型是在 3 张 GTX 1080 显卡上训练了 10 个 epoch，耗时约两周。

在输入处理方面，我们使用了原始的 10 亿词基准数据集 这里，以及包含 <S>、</S> 和 <UNK> 的 793,471 个词的现有词汇表。我们的词汇表文件可在 这里 找到。 在模型输入阶段，所有文本都采用完整的字符级表示，包括不在词汇表中的词。对于 softmax 输出，我们将 OOV 词替换为 <UNK>。

模型以固定大小的 20 个词窗口进行训练。批次是通过在句子前后添加 <S> 和 </S> 来构建的，然后将来自一个或多个句子的词打包到每一行中，以完全填满每个批次。部分句子和 LSTM 状态会从一个批次传递到下一个批次，使语言模型能够跨批次利用信息来获取上下文，但反向传播会在每个批次边界处中断。

为什么对同一段文本两次运行预训练模型会得到略有不同的嵌入结果？

由于训练方法的原因（见上文），LSTM 是有状态的，其状态会从一个批次传递到下一个批次。因此，这会引入少量的非确定性，尤其是在前两个批次中。

为什么即使使用我的小数据集，训练似乎也需要很长时间？

训练过程中梯度更新的次数由以下因素决定：

• 训练数据中的词数 (n_train_tokens)
• 批次大小 (batch_size)
• 训练轮次 (n_epochs)

请务必在 bin/train_elmo.py 中根据您的具体数据集设置这些值。

n_characters 和填充有什么关系？

在训练过程中，我们通过在每个句子前后添加 <S> 和 </S>，并将来自一个或多个句子的词打包到每一行中，以确保每个批次恰好包含 20 个词。因此，我们没有为特殊的填充标记预留空间。将词字符串转换为字符 ID 列表的 UnicodeCharsVocabulary 总是使用固定数量的字符嵌入，即 n_characters=261，所以在训练时应始终设置 n_characters=261。

然而，在预测时，我们会确保每个句子完全包含在一个批次中，因此会对不同长度的句子使用特殊的填充 ID 进行填充。这一过程发生在 Batcher 类中 参见此处。因此，在预测时，应在 options.json 中将 n_characters 设置为 262。

如何使用 ELMo 计算句子表示？

简单的方法，如对句子中单词级别的 ELMo 表示取平均值或最大池化，效果很好，通常在基准数据集上优于监督方法。详情请参阅 Perone 等人于 2018 年发表的论文《下游任务和语言学探针任务中句子嵌入的评估》arXiv 链接。

序列化模型时出现警告，这是问题吗？

可以安全地忽略以下警告：

2018-08-24 13:04:08,779 : WARNING : 序列化 lstm_output_embeddings 时遇到错误。
类型不受支持，或者项目类型与 CollectionDef 中的字段类型不匹配。
'list' 对象没有 'name' 属性

bilm-tf 快速上手指南

bilm-tf 是 ELMo（Deep contextualized word representations）预训练双向语言模型（biLM）的 TensorFlow 实现。本工具支持从头训练 biLM 模型，也支持加载预训练模型进行特征提取。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐，特别是使用 GPU 时) 或 macOS
• Python 版本: 3.5 或更高
• TensorFlow 版本: 1.2 (注意：此项目依赖较旧版本的 TF)
• GPU 支持: 如需加速推理或训练，需安装 tensorflow-gpu 并配置好 NVIDIA 驱动及 CUDA 环境。
• 其他依赖: h5py

提示: 由于该项目依赖 TensorFlow 1.2，建议在使用前创建独立的虚拟环境（如 venv 或 conda），以免与现有项目冲突。

安装步骤

方法一：pip 直接安装

1. 安装核心依赖包（建议使用国内镜像源加速下载）：

   pip install -i https://pypi.tuna.tsinghua.edu.cn/simple tensorflow-gpu==1.2 h5py
   

   注：若无 GPU 环境，可将 tensorflow-gpu 替换为 tensorflow==1.2。

2. 克隆源码并安装：

   git clone https://github.com/allenai/bilm-tf.git
   cd bilm-tf
   python setup.py install
   

3. （可选）验证安装是否成功：

   python -m unittest discover tests/
   

方法二：使用 Docker (推荐用于训练)

如果您希望避免复杂的环境配置，特别是需要 GPU 支持时，可以使用官方提供的 Docker 镜像：

sudo nvidia-docker run -t allennlp/bilm-tf:training-gpu

基本使用

本工具主要提供三种使用预训练 ELMo 模型的方式。对于大多数开发者，**方式一（基于字符输入实时计算）**是最通用且最简单的入门方法。

前置准备：下载预训练模型

在使用前，您需要从 AllenNLP 官网下载预训练好的模型文件。每个模型包含两个文件：

1. options 文件: JSON 格式，包含超参数。
2. weights 文件: HDF5 格式，包含模型权重。

下载地址：https://allennlp.org/elmo (国内用户若下载缓慢，可尝试寻找国内镜像或使用代理)

假设您已下载以下两个文件到当前目录：

• elmo_2x4096_512_2048cnn_2xhighway_options.json
• elmo_2x4096_512_2048cnn_2xhighway_weights.hdf5

使用示例：基于字符输入实时计算 (Character Input)

这种方式不需要预先构建词表缓存，可以直接处理任意文本，但计算开销相对较大。

参考项目中的 usage_character.py，核心代码如下：

import tensorflow as tf
import numpy as np
from bilm import Batcher, BidirectionalLanguageModel, weight_layers

# 1. 准备数据
# 输入格式：列表的列表，外层是句子批次，内层是分词后的单词列表
sentences = [
    ['First', 'sentence', '.'],
    ['Another', 'sentence', '.']
]

# 2. 创建 Batcher
# vocab_file 用于提高效率，若没有特定词表文件，可创建一个包含 <S>, </S> 的基础文件
# 这里假设你有一个 vocab.txt，每行一个词
vocab_file = 'vocab.txt' 
batcher = Batcher(vocab_file=vocab_file)

# 将句子转换为字符 ID 的 numpy 数组
# 形状：(n_sentences, max_sentence_length + 2, 50)
char_ids = batcher.batch_sentences(sentences)

# 3. 加载预训练模型
options_file = 'elmo_2x4096_512_2048cnn_2xhighway_options.json'
weights_file = 'elmo_2x4096_512_2048cnn_2xhighway_weights.hdf5'

biLM = BidirectionalLanguageModel(options_file, weights_file)

# 4. 构建计算图并运行
tf.reset_default_graph()

# 创建占位符
chars_op = tf.placeholder(tf.int32, shape=(None, None, 50))

# 运行 biLM 获取所有层的输出
biLM_out = biLM(chars_op)

# 使用 weight_layers 计算最终的 ELMo 表示 (加权求和)
# 这里演示获取顶层输出，实际使用中通常结合多层
elmo_embeddings = weight_layers('elmo', biLM_out, use_top_only=False)

with tf.Session() as sess:
    sess.run(tf.global_variables_initializer())
    
    # 执行推理
    embeddings_val = sess.run(
        elmo_embeddings['weighted_op'],
        feed_dict={chars_op: char_ids}
    )

# 输出形状说明
# embeddings_val 形状为: (n_sentences, 3, max_sentence_length, 1024)
# 其中维度 3 代表：底层、中间层、顶层 的拼接或加权结果
print("Embeddings shape:", embeddings_val.shape)

进阶选项简述

如果您的应用场景对速度有极高要求且词汇表固定，可以考虑以下两种优化方案（详见源码中的 usage_token.py 和 usage_cached.py）：

1. 缓存上下文无关的词向量: 预先计算并保存 token 级别的嵌入，推理时仅通过 biLSTM 计算上下文相关部分。适用于词汇表固定的大型数据集。
2. 离线 dump 整个数据集: 将整个数据集的 ELMo 向量预先计算并保存为 HDF5 文件，下游任务直接读取。适用于小型数据集或跨框架使用。