整数查找层

[源代码]

IntegerLookup

keras.layers.IntegerLookup(
    max_tokens=None,
    num_oov_indices=1,
    mask_token=None,
    oov_token=-1,
    vocabulary=None,
    vocabulary_dtype="int64",
    idf_weights=None,
    invert=False,
    output_mode="int",
    sparse=False,
    pad_to_max_tokens=False,
    name=None,
    **kwargs
)

一个将整数映射到(可能编码的)索引的预处理层。

此层通过基于表的词汇表查找,将一组任意整数输入标记映射到带索引的整数输出。即使输入标记不连续或无界,该层的输出索引也会按词汇表最大大小连续排列。此层支持通过 output_mode 对输出进行编码的多种选项,并可选支持词汇表外 (OOV) 标记和掩码。

该层的词汇表必须在构建时提供或通过 adapt() 学习。在 adapt() 期间,层将分析数据集,确定各个整数标记的频率,并从中创建词汇表。如果词汇表的大小受限,则最常见的标记将用于创建词汇表,所有其他标记将被视为 OOV。

该层有两种可能的输出模式。当 output_mode"int" 时,输入整数将转换为其在词汇表中的索引(一个整数)。当 output_mode"multi_hot""count""tf_idf" 时,输入整数将被编码为一个数组,其中每个维度对应于词汇表中的一个元素。

词汇表可以选择包含一个掩码标记以及一个 OOV 标记(可以根据 num_oov_indices 的设置,可选地在词汇表中占据多个索引)。这些标记在词汇表中的位置是固定的。当 output_mode"int" 时,词汇表将以索引 0 处的掩码标记开头,后跟 OOV 索引,再后跟词汇表的其余部分。当 output_mode"multi_hot""count""tf_idf" 时,词汇表将以 OOV 索引开头,并且输入中的掩码标记实例将被丢弃。

注意:此层在内部使用 TensorFlow。在模型编译的计算图中,它不能与除 TensorFlow 以外的任何后端一起使用。但是,在急切执行模式下,它可以与任何后端一起使用。它也始终可以在任何后端作为输入预处理流水线的一部分使用(在模型本身之外),这也是我们推荐使用此层的方式。

注意:此层可在 tf.data 流水线中安全使用(无论您使用哪种后端)。

参数

  • max_tokens:此层的词汇表最大大小。仅在自适应词汇表或设置 pad_to_max_tokens=True 时应指定此参数。如果为 None,则词汇表大小没有上限。请注意,此大小包含 OOV 和掩码标记。默认为 None
  • num_oov_indices:要使用的词汇表外标记的数量。如果此值大于 1,OOV 输入将被调制以确定其 OOV 值。如果此值为 0,调用该层时 OOV 输入将导致错误。默认为 1
  • mask_token:表示掩码输入的整数标记。当 output_mode"int" 时,该标记包含在词汇表中并映射到索引 0。在其他输出模式下,该标记将不会出现在词汇表中,并且输入中的掩码标记实例将被丢弃。如果设置为 None,则不添加掩码项。默认为 None
  • oov_token:仅当 invertTrue 时使用。对于 OOV 索引返回的标记。默认为 -1
  • vocabulary:可选。可以是整数数组或文本文件的字符串路径。如果传入数组,可以传入包含整数词汇表项的元组、列表、一维 NumPy 数组或一维张量。如果传入文件路径,文件应包含词汇表中每项的单独行。如果设置了此参数,则无需对层进行 adapt()
  • vocabulary_dtype:词汇表项的数据类型,例如 "int64""int32"。默认为 "int64"
  • idf_weights:仅当 output_mode"tf_idf" 时有效。一个与词汇表长度相同的元组、列表、一维 NumPy 数组或一维张量,包含浮点逆文档频率权重,这些权重将乘以每个样本的词项计数,以计算最终的 TF-IDF 权重。如果设置了 vocabulary 参数,并且 output_mode"tf_idf",则必须提供此参数。
  • invert:仅当 output_mode"int" 时有效。如果为 True,此层将把索引映射到词汇表项,而不是将词汇表项映射到索引。默认为 False
  • output_mode:层输出的规范。值可以是 "int""one_hot""multi_hot""count""tf_idf",配置如下:
    • "int":返回输入标记在词汇表中的索引。
    • "one_hot":将输入中的每个单独元素编码为一个与词汇表大小相同的数组,在元素索引处包含一个 1。如果最后一个维度的大小为 1,则在该维度上进行编码。如果最后一个维度的大小不为 1,则会为编码输出附加一个新维度。
    • "multi_hot":将输入中的每个样本编码为一个与词汇表大小相同的单个数组,对于样本中存在的每个词汇表项包含一个 1。如果输入形状为 (..., sample_length),则将最后一个维度视为样本维度,输出形状将为 (..., num_tokens)
    • "count":与 "multi_hot" 类似,但整数数组包含该索引处的标记在样本中出现的次数计数。
    • "tf_idf":与 "multi_hot" 类似,但应用 TF-IDF 算法来找到每个标记槽中的值。对于 "int" 输出,支持任何形状的输入和输出。对于所有其他输出模式,目前仅支持最高秩为 2 的输出。默认为 "int"
  • pad_to_max_tokens:仅当 output_mode"multi_hot""count""tf_idf" 时适用。如果为 True,即使词汇表中唯一标记的数量少于 max_tokens,输出的特征轴也会填充到 max_tokens,从而无论词汇表大小如何,都得到形状为 (batch_size, max_tokens) 的张量。默认为 False
  • sparse:布尔值。仅适用于 "multi_hot""count""tf_idf" 输出模式。仅支持 TensorFlow 后端。如果为 True,则返回一个 SparseTensor 而不是密集 Tensor。默认为 False

示例

使用已知词汇表创建查找层

此示例使用预先存在的词汇表创建了一个查找层。

>>> vocab = [12, 36, 1138, 42]
>>> data = np.array([[12, 1138, 42], [42, 1000, 36]])  # Note OOV tokens
>>> layer = IntegerLookup(vocabulary=vocab)
>>> layer(data)
array([[1, 3, 4],
       [4, 0, 2]])

使用自适应词汇表创建查找层

此示例创建了一个查找层,并通过分析数据集生成了词汇表。

>>> data = np.array([[12, 1138, 42], [42, 1000, 36]])
>>> layer = IntegerLookup()
>>> layer.adapt(data)
>>> layer.get_vocabulary()
[-1, 42, 1138, 1000, 36, 12]

注意,OOV 标记 -1 已被添加到词汇表中。其余标记按频率排序(出现 2 次的 42排在首位),然后按逆序排序。

>>> data = np.array([[12, 1138, 42], [42, 1000, 36]])
>>> layer = IntegerLookup()
>>> layer.adapt(data)
>>> layer(data)
array([[5, 2, 1],
       [1, 3, 4]])

使用多个 OOV 索引进行查找

此示例演示如何使用具有多个 OOV 索引的查找层。当使用多个 OOV 索引创建层时,任何 OOV 标记都会哈希到 OOV 桶的数量中,以确定性的方式将 OOV 标记分布在集合中。

>>> vocab = [12, 36, 1138, 42]
>>> data = np.array([[12, 1138, 42], [37, 1000, 36]])
>>> layer = IntegerLookup(vocabulary=vocab, num_oov_indices=2)
>>> layer(data)
array([[2, 4, 5],
       [1, 0, 3]])

请注意,OOV 标记 37 的输出为 1,而 OOV 标记 1000 的输出为 0。为了给额外的 OOV 标记腾出空间,词汇表中的项的输出索引相对于之前的示例增加了 1(例如 12 映射到 2)。

One-hot 输出

使用 output_mode='one_hot' 配置层。请注意,one_hot 编码中的前 num_oov_indices 个维度表示 OOV 值。

>>> vocab = [12, 36, 1138, 42]
>>> data = np.array([12, 36, 1138, 42, 7])  # Note OOV tokens
>>> layer = IntegerLookup(vocabulary=vocab, output_mode='one_hot')
>>> layer(data)
array([[0., 1., 0., 0., 0.],
        [0., 0., 1., 0., 0.],
        [0., 0., 0., 1., 0.],
        [0., 0., 0., 0., 1.],
        [1., 0., 0., 0., 0.]], dtype=float32)

Multi-hot 输出

使用 output_mode='multi_hot' 配置层。请注意,multi_hot 编码中的前 num_oov_indices 个维度表示 OOV 标记。

>>> vocab = [12, 36, 1138, 42]
>>> data = np.array([[12, 1138, 42, 42],
...                  [42,    7, 36,  7]])  # Note OOV tokens
>>> layer = IntegerLookup(vocabulary=vocab, output_mode='multi_hot')
>>> layer(data)
array([[0., 1., 0., 1., 1.],
       [1., 0., 1., 0., 1.]], dtype=float32)

标记计数输出

使用 output_mode='count' 配置层。与 multi_hot 输出一样,输出中的前 num_oov_indices 个维度表示 OOV 标记。

>>> vocab = [12, 36, 1138, 42]
>>> data = np.array([[12, 1138, 42, 42],
...                  [42,    7, 36,  7]])  # Note OOV tokens
>>> layer = IntegerLookup(vocabulary=vocab, output_mode='count')
>>> layer(data)
array([[0., 1., 0., 1., 2.],
       [2., 0., 1., 0., 1.]], dtype=float32)

TF-IDF 输出

使用 output_mode='tf_idf' 配置层。与 multi_hot 输出一样,输出中的前 num_oov_indices 个维度表示 OOV 标记。

每个标记 bin 将输出 token_count * idf_weight,其中 idf 权重是每个标记的逆文档频率权重。这些应与词汇表一起提供。请注意,OOV 标记的 idf_weight 将默认为所有传入 idf 权重的平均值。

>>> vocab = [12, 36, 1138, 42]
>>> idf_weights = [0.25, 0.75, 0.6, 0.4]
>>> data = np.array([[12, 1138, 42, 42],
...                  [42,    7, 36,  7]])  # Note OOV tokens
>>> layer = IntegerLookup(
...     output_mode='tf_idf', vocabulary=vocab, idf_weights=idf_weights)
>>> layer(data)
array([[0.  , 0.25, 0.  , 0.6 , 0.8 ],
        [1.0 , 0.  , 0.75, 0.  , 0.4 ]], dtype=float32)

要指定 OOV 标记的 idf 权重,您需要传入完整的词汇表,包括开头的 OOV 标记。

>>> vocab = [-1, 12, 36, 1138, 42]
>>> idf_weights = [0.9, 0.25, 0.75, 0.6, 0.4]
>>> data = np.array([[12, 1138, 42, 42],
...                  [42,    7, 36,  7]])  # Note OOV tokens
>>> layer = IntegerLookup(
...     output_mode='tf_idf', vocabulary=vocab, idf_weights=idf_weights)
>>> layer(data)
array([[0.  , 0.25, 0.  , 0.6 , 0.8 ],
        [1.8 , 0.  , 0.75, 0.  , 0.4 ]], dtype=float32)

"tf_idf" 模式下自适应层时,每个输入样本将被视为一个文档,每个标记的 IDF 权重将计算为:log(1 + num_documents / (1 + token_document_count))

反向查找

此示例演示如何使用此层将索引映射到标记。(您也可以使用 adapt() 并设置 inverse=True,但为简单起见,在此示例中我们将直接传入词汇表。)

>>> vocab = [12, 36, 1138, 42]
>>> data = np.array([[1, 3, 4], [4, 0, 2]])
>>> layer = IntegerLookup(vocabulary=vocab, invert=True)
>>> layer(data)
array([[  12, 1138,   42],
       [  42,   -1,   36]])

请注意,默认情况下第一个索引对应于 OOV 标记。

前向查找和反向查找配对

此示例演示如何使用标准查找层的词汇表来创建一个反向查找层。

>>> vocab = [12, 36, 1138, 42]
>>> data = np.array([[12, 1138, 42], [42, 1000, 36]])
>>> layer = IntegerLookup(vocabulary=vocab)
>>> i_layer = IntegerLookup(
...     vocabulary=layer.get_vocabulary(), invert=True)
>>> int_data = layer(data)
>>> i_layer(int_data)
array([[  12, 1138,   42],
       [  42,   -1,   36]])

在此示例中,输入标记 1000 的输出为 -1,因为 1000 不在词汇表中——它被表示为 OOV,并且所有 OOV 标记在反向层中都返回 -1。此外,请注意,要使反向查找工作,您必须在调用 get_vocabulary() 之前,通过直接设置或通过 adapt() 设置了前向层的词汇表。