Keras 3 API 文档 / 模型 API / 模型训练 API

模型训练 API

[source]

compile 方法

Model.compile(
    optimizer="rmsprop",
    loss=None,
    loss_weights=None,
    metrics=None,
    weighted_metrics=None,
    run_eagerly=False,
    steps_per_execution=1,
    jit_compile="auto",
    auto_scale_loss=True,
)

配置模型用于训练。

示例

model.compile(
    optimizer=keras.optimizers.Adam(learning_rate=1e-3),
    loss=keras.losses.BinaryCrossentropy(),
    metrics=[
        keras.metrics.BinaryAccuracy(),
        keras.metrics.FalseNegatives(),
    ],
)

参数

  • optimizer:字符串(优化器名称)或优化器实例。详见 keras.optimizers
  • loss:损失函数。可以是字符串(损失函数名称),或 keras.losses.Loss 实例。详见 keras.losses。损失函数可以是任何带有签名 loss = fn(y_true, y_pred) 的可调用对象,其中 y_true 是真实值,y_pred 是模型的预测值。y_true 的形状应为 (batch_size, d0, .. dN)(稀疏损失函数(如稀疏分类交叉熵)除外,它需要形状为 (batch_size, d0, .. dN-1) 的整数数组)。y_pred 的形状应为 (batch_size, d0, .. dN)。损失函数应返回一个浮点张量。
  • loss_weights:可选的列表或字典,指定用于加权不同模型输出的损失贡献的标量系数(Python 浮点数)。模型将最小化的损失值将是所有单个损失的加权和,权重由 loss_weights 系数指定。如果是列表,应与模型的输出一一对应。如果是字典,应将输出名称(字符串)映射到标量系数。
  • metrics:在训练和测试期间由模型评估的指标列表。每个指标可以是字符串(内置函数的名称)、函数或 keras.metrics.Metric 实例。详见 keras.metrics。通常会使用 metrics=['accuracy']。函数可以是任何带有签名 result = fn(y_true, _pred) 的可调用对象。对于多输出模型,为了为不同输出指定不同的指标,您还可以传递一个字典,例如 metrics={'a':'accuracy', 'b':['accuracy', 'mse']}。您也可以传递一个列表,为每个输出指定一个或多个指标,例如 metrics=[['accuracy'], ['accuracy', 'mse']]metrics=['accuracy', ['accuracy', 'mse']]。当您传递字符串 'accuracy' 或 'acc' 时,我们将根据目标和模型输出的形状将其转换为 keras.metrics.BinaryAccuracykeras.metrics.CategoricalAccuracykeras.metrics.SparseCategoricalAccuracy 中的一个。对于字符串 "crossentropy""ce" 也进行类似的转换。此处传递的指标在评估时不会考虑样本权重;如果您希望应用样本权重,可以通过 weighted_metrics 参数指定指标。
  • weighted_metrics:在训练和测试期间,根据 sample_weightclass_weight 加权评估的指标列表。
  • run_eagerly:布尔值。如果为 True,则此模型的前向传播将不会被编译。建议在训练时将其设为 False(以获得最佳性能),并在调试时设为 True
  • steps_per_execution:整数。每次单个编译函数调用期间运行的批次数量。在单个编译函数调用中运行多个批次可以显著提高在 TPU 或具有较大 Python 开销的小型模型上的性能。每次执行最多运行一个完整的 epoch。如果传入的数字大于 epoch 的大小,执行将被截断为 epoch 的大小。请注意,如果 steps_per_execution 设置为 N,则 Callback.on_batch_beginCallback.on_batch_end 方法仅在每 N 个批次后(即每次编译函数执行之前/之后)调用。PyTorch 后端不支持此功能。
  • jit_compile:布尔值或 "auto"。编译模型时是否使用 XLA 编译。对于 jaxtensorflow 后端,如果模型支持 XLA 编译,则 jit_compile="auto" 会启用它,否则禁用。对于 torch 后端,"auto" 默认为 eager execution,jit_compile=True 将使用 torch.compile"inductor" 后端运行。
  • auto_scale_loss:布尔值。如果为 True 且模型 dtype 策略为 "mixed_float16",则传入的优化器将自动包装在 LossScaleOptimizer 中,该优化器将动态缩放损失以防止下溢。

[source]

fit 方法

Model.fit(
    x=None,
    y=None,
    batch_size=None,
    epochs=1,
    verbose="auto",
    callbacks=None,
    validation_split=0.0,
    validation_data=None,
    shuffle=True,
    class_weight=None,
    sample_weight=None,
    initial_epoch=0,
    steps_per_epoch=None,
    validation_steps=None,
    validation_batch_size=None,
    validation_freq=1,
)

按固定数量的 epoch(数据集迭代次数)训练模型。

参数

  • x:输入数据。可以是
    • NumPy 数组(或类似数组),或数组列表(如果模型有多个输入)。
    • 后端原生张量,或张量列表(如果模型有多个输入)。
    • 如果模型有命名输入,则为将输入名称映射到相应数组/张量的字典。
    • 一个 keras.utils.PyDataset,返回 (inputs, targets)(inputs, targets, sample_weights)
    • 一个 tf.data.Dataset,产生 (inputs, targets)(inputs, targets, sample_weights)
    • 一个 torch.utils.data.DataLoader,产生 (inputs, targets)(inputs, targets, sample_weights)
    • 一个 Python 生成器函数,产生 (inputs, targets)(inputs, targets, sample_weights)
  • y:目标数据。与输入数据 x 类似,可以是 NumPy 数组或后端原生张量。如果 xkeras.utils.PyDatasettf.data.Datasettorch.utils.data.DataLoader 或 Python 生成器函数,则不应指定 y,因为目标将从 x 中获取。
  • batch_size:整数或 None。每次梯度更新的样本数量。如果未指定,batch_size 将默认为 32。如果您的输入数据 xkeras.utils.PyDatasettf.data.Datasettorch.utils.data.DataLoader 或 Python 生成器函数,则不要指定 batch_size,因为它们会生成批次。
  • epochs:整数。训练模型的 epoch 数量。一个 epoch 是对提供的整个 xy 数据进行一次迭代(除非 steps_per_epoch 标志设置为 None 以外的值)。请注意,结合 initial_epochepochs 应理解为“最终 epoch”。模型不会按照 epochs 指定的迭代次数进行训练,而只是训练到索引为 epochs 的 epoch 结束。
  • verbose"auto"、0、1 或 2。详细模式。0 = 静默,1 = 进度条,2 = 每 epoch 一行。“auto”在大多数情况下变为 1。请注意,当记录到文件时,进度条不是特别有用,因此在非交互式运行(例如在生产环境中)时建议使用 verbose=2。默认为 "auto"
  • callbackskeras.callbacks.Callback 实例列表。训练期间要应用的 callback 列表。详见 keras.callbacks。请注意,keras.callbacks.ProgbarLoggerkeras.callbacks.History callback 是自动创建的,无需传递给 model.fit()keras.callbacks.ProgbarLogger 是否创建取决于 model.fit() 中的 verbose 参数。
  • validation_split:0 到 1 之间的浮点数。用作验证数据的训练数据比例。模型将划分出这部分训练数据,不在此部分上进行训练,并在每个 epoch 结束时评估此数据上的损失和任何模型指标。验证数据在打乱之前,从提供的 xy 数据中的最后样本中选取。此参数仅在 xy 是 NumPy 数组或张量时受支持。如果同时提供 validation_datavalidation_split,则 validation_data 将覆盖 validation_split
  • validation_data:在每个 epoch 结束时用于评估损失和任何模型指标的数据。模型不会在此数据上训练。因此,请注意,使用 validation_splitvalidation_data 提供的数据的验证损失不受噪声和 dropout 等正则化层的影响。validation_data 将覆盖 validation_split。它可以是
    • 包含 NumPy 数组或张量的元组 (x_val, y_val)
    • 包含 NumPy 数组的元组 (x_val, y_val, val_sample_weights)
    • 一个 keras.utils.PyDatasettf.data.Dataset、产生 (inputs, targets)torch.utils.data.DataLoader 或产生 (x_val, y_val)(inputs, targets, sample_weights) 的 Python 生成器函数。
  • shuffle:布尔值,表示是否在每个 epoch 之前打乱训练数据。当 xkeras.utils.PyDatasettf.data.Datasettorch.utils.data.DataLoader 或 Python 生成器函数时,此参数将被忽略。
  • class_weight:可选字典,将类别索引(整数)映射到权重(浮点数),用于加权损失函数(仅在训练期间)。这对于让模型“更关注”来自代表性不足的类别的样本非常有用。当指定 class_weight 且目标具有 2 或更高秩时,y 必须是 one-hot 编码,或者对于稀疏类别标签,必须包含一个显式的最终维度 1
  • sample_weight:可选的 NumPy 数组或训练样本权重的张量,用于加权损失函数(仅在训练期间)。您可以传递一个扁平(1D)NumPy 数组或张量,其长度与输入样本相同(权重与样本一一对应),或者在时间序列数据的情况下,可以传递形状为 (samples, sequence_length) 的 2D NumPy 数组或张量,以便对每个样本的每个时间步应用不同的权重。当 xkeras.utils.PyDatasettf.data.Datasettorch.utils.data.DataLoader 或 Python 生成器函数时,不支持此参数。此时应将 sample_weights 作为 x 的第三个元素提供。请注意,样本加权不适用于通过 compile()metrics 参数指定的指标。要将样本加权应用于指标,可以通过 compile() 中的 weighted_metrics 参数指定。
  • initial_epoch:整数。开始训练的 epoch(对于恢复先前的训练运行很有用)。
  • steps_per_epoch:整数或 None。在声明一个 epoch 完成并开始下一个 epoch 之前所需的总步数(样本批次)。当使用输入张量或 NumPy 数组进行训练时,默认值 None 表示使用的值是数据集中样本数量除以批次大小,如果无法确定则为 1。如果 xkeras.utils.PyDatasettf.data.Datasettorch.utils.data.DataLoader 或 Python 生成器函数,则 epoch 将运行直到输入数据集耗尽。当传递一个无限重复的数据集时,必须指定 steps_per_epoch 参数,否则训练将无限期运行。
  • validation_steps:整数或 None。仅在提供 validation_data 时相关。在每个 epoch 结束时执行验证之前,需要绘制的总步数(样本批次)。如果 validation_stepsNone,验证将运行直到 validation_data 数据集耗尽。对于无限重复的数据集,它将无限期运行。如果指定了 validation_steps 且只消耗了数据集的一部分,则评估将在每个 epoch 从数据集的开头开始。这确保每次都使用相同的验证样本。
  • validation_batch_size:整数或 None。每个验证批次的样本数量。如果未指定,将默认为 batch_size。如果您的数据是 keras.utils.PyDatasettf.data.Datasettorch.utils.data.DataLoader 或 Python 生成器函数,则不要指定 validation_batch_size,因为它们会生成批次。
  • validation_freq:仅在提供验证数据时相关。指定在执行新的验证运行之前运行多少个训练 epoch,例如 validation_freq=2 表示每隔 2 个 epoch 运行一次验证。

迭代器类输入的解包行为:一种常见模式是将类似迭代器的对象(如 tf.data.Datasetkeras.utils.PyDataset)传递给 fit() 方法,它实际上不仅产生特征 (x),还可选地产生目标 (y) 和样本权重 (sample_weight)。Keras 要求此类迭代器的输出必须是明确的。迭代器应返回长度为 1、2 或 3 的元组,其中可选的第二个和第三个元素将分别用于 ysample_weight。提供的任何其他类型将被包装在长度为一的元组中,从而有效地将所有内容视为 x。当产生字典时,它们仍应遵循顶层元组结构,例如 ({"x0": x0, "x1": x1}, y)。Keras 不会尝试从单个字典的键中分离特征、目标和权重。一个值得注意的不受支持的数据类型是 namedtuple。原因是它既表现得像有序数据类型(元组),又表现得像映射数据类型(字典)。因此,给定形式为 namedtuple("example_tuple", ["y", "x"]) 的 namedtuple,解释值时是否颠倒元素的顺序是不明确的。更糟糕的是形式为 namedtuple("other_tuple", ["x", "y", "z"]) 的元组,其中不清楚该元组是否旨在解包为 xysample_weight,还是作为一个单一元素传递给 x

返回值

一个 History 对象。其 History.history 属性记录了连续 epoch 的训练损失值和指标值,以及验证损失值和验证指标值(如果适用)。


[source]

evaluate 方法

Model.evaluate(
    x=None,
    y=None,
    batch_size=None,
    verbose="auto",
    sample_weight=None,
    steps=None,
    callbacks=None,
    return_dict=False,
    **kwargs
)

在测试模式下返回模型的损失值和指标值。

计算按批次进行(参见 batch_size 参数)。

参数

  • x:输入数据。可以是
    • NumPy 数组(或类似数组),或数组列表(如果模型有多个输入)。
    • 后端原生张量,或张量列表(如果模型有多个输入)。
    • 如果模型有命名输入,则为将输入名称映射到相应数组/张量的字典。
    • 一个 keras.utils.PyDataset,返回 (inputs, targets)(inputs, targets, sample_weights)
    • 一个 tf.data.Dataset,产生 (inputs, targets)(inputs, targets, sample_weights)
    • 一个 torch.utils.data.DataLoader,产生 (inputs, targets)(inputs, targets, sample_weights)
    • 一个 Python 生成器函数,产生 (inputs, targets)(inputs, targets, sample_weights)
  • y:目标数据。与输入数据 x 类似,可以是 NumPy 数组或后端原生张量。如果 xkeras.utils.PyDatasettf.data.Datasettorch.utils.data.DataLoader 或 Python 生成器函数,则不应指定 y,因为目标将从 x 中获取。
  • batch_size:整数或 None。每次计算批次的样本数量。如果未指定,batch_size 将默认为 32。如果您的输入数据 xkeras.utils.PyDatasettf.data.Datasettorch.utils.data.DataLoader 或 Python 生成器函数,则不要指定 batch_size,因为它们会生成批次。
  • verbose"auto"、0、1 或 2。详细模式。0 = 静默,1 = 进度条,2 = 单行。“auto”在大多数情况下变为 1。请注意,当记录到文件时,进度条不是特别有用,因此在非交互式运行(例如在生产环境中)时建议使用 verbose=2。默认为 "auto"
  • sample_weight:可选的 NumPy 数组或训练样本权重的张量,用于加权损失函数(仅在训练期间)。您可以传递一个扁平(1D)NumPy 数组或张量,其长度与输入样本相同(权重与样本一一对应),或者在时间序列数据的情况下,可以传递形状为 (samples, sequence_length) 的 2D NumPy 数组或张量,以便对每个样本的每个时间步应用不同的权重。当 xkeras.utils.PyDatasettf.data.Datasettorch.utils.data.DataLoader 或 Python 生成器函数时,不支持此参数。此时应将 sample_weights 作为 x 的第三个元素提供。请注意,样本加权不适用于通过 compile()metrics 参数指定的指标。要将样本加权应用于指标,可以通过 compile() 中的 weighted_metrics 参数指定。
  • steps:整数或 None。在声明评估轮次完成之前需要绘制的总步数(样本批次)。如果 stepsNone,它将运行直到 x 耗尽。对于无限重复的数据集,它将无限期运行。
  • callbackskeras.callbacks.Callback 实例列表。评估期间要应用的 callback 列表。
  • return_dict:如果为 True,则损失和指标结果将作为字典返回,其中每个键是指标的名称。如果为 False,则作为列表返回。

返回值

标量测试损失(如果模型具有单个输出且无指标)或标量列表(如果模型具有多个输出和/或指标)。属性 model.metrics_names 将提供标量输出的显示标签。


[source]

predict 方法

Model.predict(x, batch_size=None, verbose="auto", steps=None, callbacks=None)

为输入样本生成输出预测。

计算按批次进行。此方法专为处理大量输入的批处理而设计。它不适用于在循环内部迭代数据并一次处理少量输入的情况。

对于适合单个批次的小量输入,直接使用 __call__() 以获得更快的执行速度,例如 model(x),或者如果您的层(如 BatchNormalization)在推断期间行为不同,则使用 model(x, training=False)

注意:有关 Model 方法 predict()__call__() 之间差异的更多详细信息,请参见 此常见问题解答条目

参数

  • x:输入数据。可以是
    • NumPy 数组(或类似数组),或数组列表(如果模型有多个输入)。
    • 后端原生张量,或张量列表(如果模型有多个输入)。
    • 如果模型有命名输入,则为将输入名称映射到相应数组/张量的字典。
    • 一个 keras.utils.PyDataset
    • 一个 tf.data.Dataset
    • 一个 torch.utils.data.DataLoader
    • 一个 Python 生成器函数。
  • batch_size:整数或 None。每次计算批次的样本数量。如果未指定,batch_size 将默认为 32。如果您的输入数据 xkeras.utils.PyDatasettf.data.Datasettorch.utils.data.DataLoader 或 Python 生成器函数,则不要指定 batch_size,因为它们会生成批次。
  • verbose"auto"、0、1 或 2。详细模式。0 = 静默,1 = 进度条,2 = 单行。“auto”在大多数情况下变为 1。请注意,当记录到文件时,进度条不是特别有用,因此在非交互式运行(例如在生产环境中)时建议使用 verbose=2。默认为 "auto"
  • steps:在声明预测轮次完成之前需要绘制的总步数(样本批次)。如果 stepsNone,它将运行直到 x 耗尽。对于无限重复的数据集,它将无限期运行。
  • callbackskeras.callbacks.Callback 实例列表。预测期间要应用的 callback 列表。

返回值

NumPy 预测数组。


[source]

train_on_batch 方法

Model.train_on_batch(
    x, y=None, sample_weight=None, class_weight=None, return_dict=False
)

在单个数据批次上运行一次梯度更新。

参数

  • x:输入数据。必须是类似数组的对象。
  • y:目标数据。必须是类似数组的对象。
  • sample_weight:可选数组,其长度与 x 相同,包含应用于每个样本的模型损失的权重。对于时间序列数据,您可以传递形状为 (samples, sequence_length) 的 2D 数组,以便对每个样本的每个时间步应用不同的权重。
  • class_weight:可选字典,将类别索引(整数)映射到权重(浮点数),用于在训练期间应用于此类样本的模型损失。这对于让模型“更关注”来自代表性不足的类别的样本非常有用。当指定 class_weight 且目标具有 2 或更高秩时,y 必须是 one-hot 编码,或者对于稀疏类别标签,必须包含一个显式的最终维度 1。
  • return_dict:如果为 True,则损失和指标结果将作为字典返回,其中每个键是指标的名称。如果为 False,则作为列表返回。

返回值

标量损失值(当没有指标且 return_dict=False 时),损失和指标值列表(如果存在指标且 return_dict=False 时),或指标和损失值的字典(如果 return_dict=True 时)。


[source]

test_on_batch 方法

Model.test_on_batch(x, y=None, sample_weight=None, return_dict=False)

在单个样本批次上测试模型。

参数

  • x:输入数据。必须是类似数组的对象。
  • y:目标数据。必须是类似数组的对象。
  • sample_weight:可选数组,其长度与 x 相同,包含应用于每个样本的模型损失的权重。对于时间序列数据,您可以传递形状为 (samples, sequence_length) 的 2D 数组,以便对每个样本的每个时间步应用不同的权重。
  • return_dict:如果为 True,则损失和指标结果将作为字典返回,其中每个键是指标的名称。如果为 False,则作为列表返回。

返回值

标量损失值(当没有指标且 return_dict=False 时),损失和指标值列表(如果存在指标且 return_dict=False 时),或指标和损失值的字典(如果 return_dict=True 时)。


[source]

predict_on_batch 方法

Model.predict_on_batch(x)

返回单个样本批次的预测。

参数

  • x:输入数据。它必须是类似数组的对象。

返回值

NumPy 预测数组。