StringLookup 層

[原始碼]

StringLookup 類別

keras.layers.StringLookup(
    max_tokens=None,
    num_oov_indices=1,
    mask_token=None,
    oov_token="[UNK]",
    vocabulary=None,
    idf_weights=None,
    invert=False,
    output_mode="int",
    pad_to_max_tokens=False,
    sparse=False,
    encoding="utf-8",
    name=None,
    **kwargs
)

一個將字串對應到（可能經過編碼的）索引的預處理層。

此層透過基於表格的詞彙查找，將一組任意字串轉換為整數輸出。此層不會對輸入字串執行分割或轉換。對於可以分割和標記自然語言的層，請參閱 keras.layers.TextVectorization 層。

此層的詞彙必須在建構時提供，或透過 adapt() 學習。在 adapt() 期間，此層將分析資料集，確定個別字串標記的頻率，並從中建立詞彙。如果詞彙的大小受到限制，則將使用最頻繁的標記來建立詞彙，所有其他標記將被視為詞彙外 (OOV)。

此層有兩種可能的輸出模式。當 output_mode 為 "int" 時，輸入字串會轉換為其在詞彙中的索引（整數）。當 output_mode 為 "multi_hot"、"count" 或 "tf_idf" 時，輸入字串會編碼為一個陣列，其中每個維度對應於詞彙中的一個元素。

詞彙可以選擇性地包含遮罩標記以及 OOV 標記（可以選擇性地佔用詞彙中的多個索引，由 num_oov_indices 設定）。這些標記在詞彙中的位置是固定的。當 output_mode 為 "int" 時，詞彙將以遮罩標記（如果設定）開始，後接 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：僅在 invert 為 True 時使用。要為 OOV 索引傳回的標記。預設為 "[UNK]"。
• vocabulary：選用。整數陣列或文字檔案的字串路徑。如果傳遞陣列，則可以傳遞包含整數詞彙項目的元組、列表、1D NumPy 陣列或 1D 張量。如果傳遞檔案路徑，則該檔案應包含每個詞彙項目一行。如果設定了此參數，則不需要 adapt() 此層。
• vocabulary_dtype：詞彙項目的 dtype，例如 "int64" 或 "int32"。預設為 "int64"。
• idf_weights：僅當 output_mode 為 "tf_idf" 時有效。一個元組、列表、1D NumPy 陣列或 1D 張量，其長度與詞彙相同，其中包含浮點反向文件頻率權重，這些權重將乘以每個樣本的詞彙計數，以獲得最終的 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。
• encoding：選用。用於解譯輸入字串的文字編碼。預設為 "utf-8"。

範例

使用已知詞彙建立查找層

此範例會使用預先存在的詞彙建立查找層。

>>> vocab = ["a", "b", "c", "d"]
>>> data = [["a", "c", "d"], ["d", "z", "b"]]
>>> layer = StringLookup(vocabulary=vocab)
>>> layer(data)
array([[1, 3, 4],
       [4, 0, 2]])

使用調整的詞彙建立查找層

此範例會建立一個查找層，並透過分析資料集產生詞彙。

>>> data = [["a", "c", "d"], ["d", "z", "b"]]
>>> layer = StringLookup()
>>> layer.adapt(data)
>>> layer.get_vocabulary()
['[UNK]', 'd', 'z', 'c', 'b', 'a']

請注意，OOV 標記 "[UNK]" 已新增至詞彙。其餘標記依頻率排序（出現 2 次的 "d" 排在第一位），然後依反向排序順序排序。

>>> data = [["a", "c", "d"], ["d", "z", "b"]]
>>> layer = StringLookup()
>>> layer.adapt(data)
>>> layer(data)
array([[5, 3, 1],
       [1, 2, 4]])

具有多個 OOV 索引的查找

此範例示範如何使用具有多個 OOV 索引的查找層。當建立具有多個 OOV 索引的層時，任何 OOV 值都會雜湊到 OOV 儲存桶的數量中，以確定性的方式在集合中分配 OOV 值。

>>> vocab = ["a", "b", "c", "d"]
>>> data = [["a", "c", "d"], ["m", "z", "b"]]
>>> layer = StringLookup(vocabulary=vocab, num_oov_indices=2)
>>> layer(data)
array([[2, 4, 5],
       [0, 1, 3]])

請注意，OOV 值 'm' 的輸出為 0，而 OOV 值 "z" 的輸出為 1。為了為額外的 OOV 值騰出空間，詞彙內詞彙的輸出索引比之前的範例增加了 1（a 對應到 2，等等）。

獨熱輸出

使用 output_mode='one_hot' 配置此層。請注意，獨熱編碼中的前 num_oov_indices 個維度代表 OOV 值。

>>> vocab = ["a", "b", "c", "d"]
>>> data = ["a", "b", "c", "d", "z"]
>>> layer = StringLookup(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=int64)

多熱輸出

使用 output_mode='multi_hot' 配置此層。請注意，多熱編碼中的前 num_oov_indices 個維度代表 OOV 值。

>>> vocab = ["a", "b", "c", "d"]
>>> data = [["a", "c", "d", "d"], ["d", "z", "b", "z"]]
>>> layer = StringLookup(vocabulary=vocab, output_mode='multi_hot')
>>> layer(data)
array([[0., 1., 0., 1., 1.],
       [1., 0., 1., 0., 1.]], dtype=int64)

標記計數輸出

使用 output_mode='count' 配置此層。與多熱輸出一樣，輸出中的前 num_oov_indices 個維度代表 OOV 值。

>>> vocab = ["a", "b", "c", "d"]
>>> data = [["a", "c", "d", "d"], ["d", "z", "b", "z"]]
>>> layer = StringLookup(vocabulary=vocab, output_mode='count')
>>> layer(data)
array([[0., 1., 0., 1., 2.],
       [2., 0., 1., 0., 1.]], dtype=int64)

TF-IDF 輸出

使用 output_mode="tf_idf" 配置此層。與多熱輸出一樣，輸出中的前 num_oov_indices 個維度代表 OOV 值。

每個標記 bin 將輸出 token_count * idf_weight，其中 idf 權重是每個標記的反向文件頻率權重。這些應該與詞彙一起提供。請注意，OOV 值的 idf_weight 將預設為傳入的所有 idf 權重的平均值。

>>> vocab = ["a", "b", "c", "d"]
>>> idf_weights = [0.25, 0.75, 0.6, 0.4]
>>> data = [["a", "c", "d", "d"], ["d", "z", "b", "z"]]
>>> layer = StringLookup(output_mode="tf_idf")
>>> layer.set_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 = ["[UNK]", "a", "b", "c", "d"]
>>> idf_weights = [0.9, 0.25, 0.75, 0.6, 0.4]
>>> data = [["a", "c", "d", "d"], ["d", "z", "b", "z"]]
>>> layer = StringLookup(output_mode="tf_idf")
>>> layer.set_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 = ["a", "b", "c", "d"]
>>> data = [[1, 3, 4], [4, 0, 2]]
>>> layer = StringLookup(vocabulary=vocab, invert=True)
>>> layer(data)
array([[b'a', b'c', b'd'],
       [b'd', b'[UNK]', b'b']], dtype=object)

請注意，預設情況下，第一個索引對應於詞彙表外的 (oov) 標記。

正向和反向查詢配對

此範例示範如何使用標準查詢層的詞彙表來建立反向查詢層。

>>> vocab = ["a", "b", "c", "d"]
>>> data = [["a", "c", "d"], ["d", "z", "b"]]
>>> layer = StringLookup(vocabulary=vocab)
>>> i_layer = StringLookup(vocabulary=vocab, invert=True)
>>> int_data = layer(data)
>>> i_layer(int_data)
array([[b'a', b'c', b'd'],
       [b'd', b'[UNK]', b'b']], dtype=object)

在這個範例中，輸入值 "z" 導致輸出為 "[UNK]"，因為 1000 不在詞彙表中 - 它被表示為詞彙表外 (OOV) 的詞，並且所有 OOV 值在反向層中都以 "[UNK]" 返回。此外，請注意，為了使反向查詢運作，您必須在呼叫 get_vocabulary() 之前，直接或透過 adapt() 設定正向層的詞彙表。