Python & NumPy 工具

[原始碼]

set_random_seed 函數

keras.utils.set_random_seed(seed)

設定所有隨機種子 (Python、NumPy 和後端框架，例如 TF)。

您可以使用此工具使幾乎所有 Keras 程式完全確定。在涉及網路通訊（例如參數伺服器分佈，這會產生額外的隨機性來源）或涉及某些非決定性的 cuDNN 運算時，會有一些限制。

呼叫此工具等同於以下操作

import random
random.seed(seed)

import numpy as np
np.random.seed(seed)

import tensorflow as tf  # Only if TF is installed
tf.random.set_seed(seed)

import torch  # Only if the backend is 'torch'
torch.manual_seed(seed)

請注意，即使您未使用 TensorFlow 作為後端框架，TensorFlow 種子也會被設定，因為許多工作流程會利用 tf.data 管道（具有隨機洗牌功能）。同樣地，許多工作流程可能會利用 NumPy API。

參數

• seed：整數，要使用的隨機種子。

[原始碼]

split_dataset 函數

keras.utils.split_dataset(
    dataset, left_size=None, right_size=None, shuffle=False, seed=None
)

將資料集分割成左半部分和右半部分（例如，訓練/測試）。

參數

• dataset：tf.data.Dataset、torch.utils.data.Dataset 物件或具有相同長度的陣列/元組列表。
• left_size：如果為浮點數（在範圍 [0, 1] 內），則表示要將資料放入左側資料集的分數。如果為整數，則表示要將樣本放入左側資料集的數量。如果為 None，則預設為 right_size 的補數。預設為 None。
• right_size：如果為浮點數（在範圍 [0, 1] 內），則表示要將資料放入右側資料集的分數。如果為整數，則表示要將樣本放入右側資料集的數量。如果為 None，則預設為 left_size 的補數。預設為 None。
• shuffle：布林值，是否在分割資料之前對其進行洗牌。
• seed：用於洗牌的隨機種子。

回傳值

• 兩個 tf.data.Dataset 物件的元組：左側和右側分割。

範例

>>> data = np.random.random(size=(1000, 4))
>>> left_ds, right_ds = keras.utils.split_dataset(data, left_size=0.8)
>>> int(left_ds.cardinality())
800
>>> int(right_ds.cardinality())
200

[原始碼]

pack_x_y_sample_weight 函數

keras.utils.pack_x_y_sample_weight(x, y=None, sample_weight=None)

將使用者提供的資料打包成元組。

這是一個將資料打包成 Model.fit() 使用的元組格式的便捷工具。

範例

>>> x = ops.ones((10, 1))
>>> data = pack_x_y_sample_weight(x)
>>> isinstance(data, ops.Tensor)
True
>>> y = ops.ones((10, 1))
>>> data = pack_x_y_sample_weight(x, y)
>>> isinstance(data, tuple)
True
>>> x, y = data

參數

• x：要傳遞給 Model 的特徵。
• y：要傳遞給 Model 的真實目標。
• sample_weight：每個元素的樣本權重。

回傳值

以 Model.fit() 中使用的格式表示的元組。

[原始碼]

get_file 函數

keras.utils.get_file(
    fname=None,
    origin=None,
    untar=False,
    md5_hash=None,
    file_hash=None,
    cache_subdir="datasets",
    hash_algorithm="auto",
    extract=False,
    archive_format="auto",
    cache_dir=None,
    force_download=False,
)

如果快取中還沒有檔案，則從 URL 下載該檔案。

預設情況下，URL origin 中的檔案會下載到快取目錄 ~/.keras，放置在快取子目錄 datasets 中，並給予檔案名稱 fname。因此，檔案 example.txt 的最終位置將會是 ~/.keras/datasets/example.txt。也可以解壓縮 .tar、.tar.gz、.tar.bz 和 .zip 格式的檔案。

傳遞雜湊值將在下載後驗證檔案。命令列程式 shasum 和 sha256sum 可以計算雜湊值。

範例

path_to_downloaded_file = get_file(
    origin="https://storage.googleapis.com/download.tensorflow.org/example_images/flower_photos.tgz",
    extract=True,
)

參數

• fname：如果目標是單個檔案，這是您想要的檔案本機名稱。如果為 None，將使用 origin 處的檔案名稱。如果下載並解壓縮目錄存檔，提供的 fname 將用作解壓縮目錄名稱（僅當它沒有副檔名時）。
• origin：檔案的原始 URL。
• untar：已棄用，請改用 extract 參數。布林值，檔案是否為應該解壓縮的 tar 存檔。
• md5_hash：已棄用，請改用 file_hash 參數。用於檔案完整性驗證的檔案 md5 雜湊值。
• file_hash：下載後檔案的預期雜湊字串。支援 sha256 和 md5 雜湊演算法。
• cache_subdir：Keras 快取目錄下儲存檔案的子目錄。如果指定絕對路徑，例如 "/path/to/folder"，則檔案將儲存在該位置。
• hash_algorithm：選擇用於驗證檔案的雜湊演算法。選項為 "md5"、"sha256" 和 "auto"。預設的 "auto" 會偵測正在使用的雜湊演算法。
• extract：如果為 True，則解壓縮存檔。僅適用於 tar 或 zip 等壓縮存檔檔案。
• archive_format：嘗試解壓縮檔案的存檔格式。選項為 "auto"、"tar"、"zip" 和 None。"tar" 包括 tar、tar.gz 和 tar.bz 檔案。預設的 "auto" 對應於 ["tar", "zip"]。None 或空列表將不會找到任何匹配項。
• cache_dir：儲存快取檔案的位置，如果為 None，則預設為設定 KERAS_HOME 環境變數時為 $KERAS_HOME，或 ~/.keras/。
• force_download：如果為 True，則無論快取狀態如何，都會重新下載檔案。

回傳值

下載檔案的路徑。

⚠️ 關於惡意下載的警告 ⚠️

從網際網路下載任何東西都存在風險。如果您不信任來源，請永遠不要下載檔案/存檔。我們建議您指定 file_hash 參數（如果知道來源檔案的雜湊值）以確保您取得的檔案是您期望的檔案。

[原始碼]

Progbar 類別

keras.utils.Progbar(
    target, width=20, verbose=1, interval=0.05, stateful_metrics=None, unit_name="step"
)

顯示進度列。

參數

• target：預期的總步數，如果未知，則為 None。
• width：螢幕上的進度列寬度。
• verbose：詳細模式，0（靜音）、1（詳細）、2（半詳細）
• stateful_metrics：應該不隨時間平均的指標字串名稱的可迭代物件。此列表中的指標將按原樣顯示。所有其他指標將在顯示之前由進度列平均。
• interval：最小視覺進度更新間隔（以秒為單位）。
• unit_name：步數的顯示名稱（通常為「步」或「樣本」）。

[原始碼]

PyDataset 類別

keras.utils.PyDataset(workers=1, use_multiprocessing=False, max_queue_size=10)

用於使用 Python 程式碼定義平行資料集的基本類別。

每個 PyDataset 都必須實作 __getitem__() 和 __len__() 方法。如果您想在 epoch 之間修改資料集，您可以額外實作 on_epoch_end()，或在每個 epoch 開始時呼叫 on_epoch_begin。__getitem__() 方法應傳回完整的批次（而不是單個樣本），而 __len__ 方法應傳回資料集中批次的數量（而不是樣本的數量）。

參數

• workers：在多執行緒或多處理中使用的 worker 數量。
• use_multiprocessing：是否使用 Python 多處理進行平行處理。將此設定為 True 表示您的資料集將在多個分支程序中複製。為了從平行處理中獲得計算級別（而不是 I/O 級別）的好處，這是必要的。但是，只有當您的資料集可以安全地 pickled 時，才能將其設定為 True。
• max_queue_size：在多執行緒或多處理設定中迭代資料集時，保留在佇列中的最大批次數量。減少此值可減少資料集的 CPU 記憶體消耗。預設為 10。

注意事項

• PyDataset 是一種更安全的多處理方法。此結構保證模型在每個 epoch 中只會對每個樣本訓練一次，而 Python 生成器則不然。
• workers、use_multiprocessing 和 max_queue_size 參數用於配置 fit() 如何使用平行處理來迭代資料集。它們不是由 PyDataset 類別直接使用。當您手動迭代 PyDataset 時，不會應用任何平行處理。

範例

from skimage.io import imread
from skimage.transform import resize
import numpy as np
import math

# Here, `x_set` is list of path to the images
# and `y_set` are the associated classes.

class CIFAR10PyDataset(keras.utils.PyDataset):

    def __init__(self, x_set, y_set, batch_size, **kwargs):
        super().__init__(**kwargs)
        self.x, self.y = x_set, y_set
        self.batch_size = batch_size

    def __len__(self):
        # Return number of batches.
        return math.ceil(len(self.x) / self.batch_size)

    def __getitem__(self, idx):
        # Return x, y for batch idx.
        low = idx * self.batch_size
        # Cap upper bound at array length; the last batch may be smaller
        # if the total number of items is not a multiple of batch size.
        high = min(low + self.batch_size, len(self.x))
        batch_x = self.x[low:high]
        batch_y = self.y[low:high]

        return np.array([
            resize(imread(file_name), (200, 200))
               for file_name in batch_x]), np.array(batch_y)

[原始碼]

to_categorical 函數

keras.utils.to_categorical(x, num_classes=None)

將類別向量（整數）轉換為二元類別矩陣。

例如，用於 categorical_crossentropy。

參數

• x：類別值陣列形式，將被轉換成矩陣（從 0 到 num_classes - 1 的整數）。
• num_classes：類別總數。如果為 None，則會推斷為 max(x) + 1。預設為 None。

回傳值

以 NumPy 陣列形式表示的輸入二元矩陣。類別軸放置在最後。

範例

>>> a = keras.utils.to_categorical([0, 1, 2, 3], num_classes=4)
>>> print(a)
[[1. 0. 0. 0.]
 [0. 1. 0. 0.]
 [0. 0. 1. 0.]
 [0. 0. 0. 1.]]

>>> b = np.array([.9, .04, .03, .03,
...               .3, .45, .15, .13,
...               .04, .01, .94, .05,
...               .12, .21, .5, .17],
...               shape=[4, 4])
>>> loss = keras.ops.categorical_crossentropy(a, b)
>>> print(np.around(loss, 5))
[0.10536 0.82807 0.1011  1.77196]

>>> loss = keras.ops.categorical_crossentropy(a, a)
>>> print(np.around(loss, 5))
[0. 0. 0. 0.]

[原始碼]

normalize 函數

keras.utils.normalize(x, axis=-1, order=2)

正規化陣列。

如果輸入是 NumPy 陣列，將回傳 NumPy 陣列。如果它是後端張量，則將回傳後端張量。

參數

• x：要正規化的陣列。
• axis：沿著正規化的軸。
• order：正規化順序（例如，L2 範數的 order=2）。

回傳值

陣列的正規化副本。