LudwigModel

LudwigModel 类 [源代码]¶

ludwig.api.LudwigModel(
  config,
  logging_level=40,
  backend=None,
  gpus=None,
  gpu_memory_limit=None,
  allow_parallel_threads=True,
  callbacks=None
)

提供访问高级 Ludwig 功能的类。

输入参数

config (Union[str, dict]): 配置的内存表示或 YAML 配置文件的字符串路径。
logging_level (int): 将发送到 stderr 的日志级别。
backend (Union[Backend, str]): 用于执行预处理/训练步骤的 Backend 对象或后端名称字符串。
gpus (Union[str, int, List[int]], 默认值: None): 要使用的 GPU（使用与 CUDA_VISIBLE_DEVICES 相同的语法）。
gpu_memory_limit (float: 默认值: None): 允许每个 GPU 设备分配的最大内存比例 [0, 1]。
allow_parallel_threads (bool, 默认值: True): 允许 Torch 使用多线程并行来提高性能，但这会牺牲确定性。

示例用法

from ludwig.api import LudwigModel

训练模型

config = {...}
ludwig_model = LudwigModel(config)
train_stats, _, _ = ludwig_model.train(dataset=file_path)

或

train_stats, _, _ = ludwig_model.train(dataset=dataframe)

如果您已经训练了一个模型，可以加载它并用于预测

ludwig_model = LudwigModel.load(model_dir)

预测

predictions, _ = ludwig_model.predict(dataset=file_path)

或

predictions, _ = ludwig_model.predict(dataset=dataframe)

评估

eval_stats, _, _ = ludwig_model.evaluate(dataset=file_path)

或

eval_stats, _, _ = ludwig_model.evaluate(dataset=dataframe)

公共 API：此 API 在 Ludwig 版本中保持稳定。

LudwigModel 方法¶

collect_activations¶

collect_activations(
  layer_names,
  dataset,
  data_format=None,
  split='full',
  batch_size=128
)

加载预训练模型和输入数据，以收集张量中包含的激活值。

输入参数

layer_names (list): 模型中要收集激活的层名称字符串列表。
dataset (Union[str, Dict[str, list], pandas.DataFrame]): 包含用于进行预测的数据源。
data_format (str, 默认值: None): 用于解释数据源的格式。如果未指定，将自动推断。有效格式包括 'auto', 'csv', 'df', 'dict', 'excel', 'feather', 'fwf', 'hdf5'（之前训练期间生成的缓存文件）, 'html'（包含单个 HTML <table> 的文件）, 'json', 'jsonl', 'parquet', 'pickle'（Pickle 序列化的 Pandas DataFrame）, 'sas', 'spss', 'stata', 'tsv'。
split (str, 默认值= 'full'):: 如果输入数据集包含分割列，此参数指示要使用的数据分割。可能的值包括 'full', 'training', 'validation', 'test'。
batch_size (int, 默认值: 128): 进行预测时使用的批量大小。

返回值

return (list): 收集到的张量列表。

collect_weights¶

collect_weights(
  tensor_names=None
)

加载预训练模型并收集具有特定名称的张量。

输入参数

tensor_names (list, 默认值: None): 要收集权重的张量名称列表。

返回值

return (list): 张量列表。

create_model¶

create_model(
  config_obj,
  random_seed=42
)

实例化 BaseModel 对象。

输入参数

config_obj (Union[Config, dict]): Ludwig 配置对象。
random_seed (int, 默认值: Ludwig 默认随机种子): 用于权重初始化、分割和任何其他随机函数的随机种子。

返回值

return (ludwig.models.BaseModel): Ludwig 模型对象的实例。

evaluate¶

ludwig.evaluate(
  dataset=None,
  data_format=None,
  split='full',
  batch_size=None,
  skip_save_unprocessed_output=True,
  skip_save_predictions=True,
  skip_save_eval_stats=True,
  collect_predictions=False,
  collect_overall_stats=False,
  output_directory='results',
  return_type=<class 'pandas.core.frame.DataFrame'>
)

此函数用于使用训练好的模型根据输入变量预测输出变量，并计算测试统计数据，如性能指标、混淆矩阵等。

输入参数

dataset (Union[str, dict, pandas.DataFrame]): 包含要评估的整个数据集的来源。
data_format (str, 默认值: None): 用于解释数据源的格式。如果未指定，将自动推断。有效格式包括 'auto', 'csv', 'df', 'dict', 'excel', 'feather', 'fwf', 'hdf5'（之前训练期间生成的缓存文件）, 'html'（包含单个 HTML <table> 的文件）, 'json', 'jsonl', 'parquet', 'pickle'（Pickle 序列化的 Pandas DataFrame）, 'sas', 'spss', 'stata', 'tsv'。
split (str, 默认值='full'):: 如果输入数据集包含分割列，此参数指示要使用的数据分割。可能的值包括 'full', 'training', 'validation', 'test'。
batch_size (int, 默认值: None): 进行预测时使用的批量大小。默认为模型配置中的 eval_batch_size。
skip_save_unprocessed_output (bool, 默认值: True): 如果此参数为 False，则预测及其概率将保存为包含张量的原始未处理 numpy 文件和后处理的 CSV 文件（每个输出特征一个）。如果此参数为 True，则仅保存 CSV 文件，跳过 numpy 文件。
skip_save_predictions (bool, 默认值: True): 跳过保存测试预测 CSV 文件。
skip_save_eval_stats (bool, 默认值: True): 跳过保存测试统计信息 JSON 文件。
collect_predictions (bool, 默认值: False): 如果为 True，则在评估期间收集后处理的预测。
collect_overall_stats (bool, 默认值: False): 如果为 True，则在评估期间收集总体统计信息。
output_directory (str, 默认值: 'results'): 将包含训练统计数据、TensorBoard 日志、保存的模型和训练进度文件的目录。
return_type (Union[str, dict, pd.DataFrame], 默认值: pandas.DataFrame): 指示返回预测的格式。

返回值

return (evaluation_statistics, predictions, output_directory): evaluation_statistics 包含评估性能统计数据的字典，postprocess_predictions 包含预测值，output_directory 是结果存储的位置。

experiment¶

experiment(
  dataset=None,
  training_set=None,
  validation_set=None,
  test_set=None,
  training_set_metadata=None,
  data_format=None,
  experiment_name='experiment',
  model_name='run',
  model_resume_path=None,
  eval_split='test',
  skip_save_training_description=False,
  skip_save_training_statistics=False,
  skip_save_model=False,
  skip_save_progress=False,
  skip_save_log=False,
  skip_save_processed_input=False,
  skip_save_unprocessed_output=False,
  skip_save_predictions=False,
  skip_save_eval_stats=False,
  skip_collect_predictions=False,
  skip_collect_overall_stats=False,
  output_directory='results',
  random_seed=42
)

在数据集的训练集和验证集上训练模型，并使用它在测试集上进行预测。它会保存训练好的模型以及训练和测试的统计数据。

输入参数

dataset (Union[str, dict, pandas.DataFrame], 默认值: None): 包含实验中使用的整个数据集的来源。如果包含分割列，则将用于分割（训练为 0，验证为 1，测试为 2），否则将随机分割数据集。
training_set (Union[str, dict, pandas.DataFrame], 默认值: None): 包含训练数据来源。
validation_set (Union[str, dict, pandas.DataFrame], 默认值: None): 包含验证数据来源。
test_set (Union[str, dict, pandas.DataFrame], 默认值: None): 包含测试数据来源。
training_set_metadata (Union[str, dict], 默认值: None): 元数据 JSON 文件或已加载的元数据。中间预处理结构，包含输入数据集的映射，当输入文件首次在同一目录中以相同名称和 '.meta.json' 扩展名使用时创建。
data_format (str, 默认值: None): 用于解释数据源的格式。如果未指定，将自动推断。有效格式包括 'auto', 'csv', 'df', 'dict', 'excel', 'feather', 'fwf', 'hdf5'（之前训练期间生成的缓存文件）, 'html'（包含单个 HTML <table> 的文件）, 'json', 'jsonl', 'parquet', 'pickle'（Pickle 序列化的 Pandas DataFrame）, 'sas', 'spss', 'stata', 'tsv'。
experiment_name (str, 默认值: 'experiment'): 实验名称。
model_name (str, 默认值: 'run'): 使用的模型名称。
model_resume_path (str, 默认值: None): 从指定路径恢复模型训练。配置将恢复。除了配置外，还会恢复每个 epoch 的训练统计数据和损失以及优化器的状态，以便可以有效地从之前中断的训练过程继续训练。
eval_split (str, 默认值: test): 执行评估时使用的分割。有效值包括 training, validation 和 test。
skip_save_training_description (bool, 默认值: False): 禁用保存描述 JSON 文件。
skip_save_training_statistics (bool, 默认值: False): 禁用保存训练统计信息 JSON 文件。
skip_save_model (bool, 默认值: False): 每次模型改进时禁用保存模型权重和超参数。默认情况下，当验证指标改进时，Ludwig 会在每个 epoch 后保存模型权重，但如果模型非常大，这可能非常耗时。如果您不想保留权重而只想了解模型在一组超参数下的性能，请使用此参数跳过保存，但之后将无法加载模型，并且返回的模型将是训练结束时获得的权重，而不是验证性能最佳的 epoch 的权重。
skip_save_progress (bool, 默认值: False): 禁用每个 epoch 保存进度。默认情况下，Ludwig 在每个 epoch 后保存权重和统计数据，以便能够恢复训练，但如果模型非常大，这可能非常耗时，并且会占用两倍的空间，使用此参数跳过保存，但之后无法恢复训练。
skip_save_log (bool, 默认值: False): 禁用保存 TensorBoard 日志。默认情况下，Ludwig 会为 TensorBoard 保存日志，但如果不需要，关闭此选项可以稍微提高整体速度。
skip_save_processed_input (bool, 默认值: False): 如果提供了输入数据集，则通过保存 HDF5 和 JSON 文件进行预处理和缓存，以避免再次运行预处理。如果此参数为 False，则不保存 HDF5 和 JSON 文件。
skip_save_unprocessed_output (bool, 默认值: False): 默认情况下，预测及其概率将保存为包含张量的原始未处理 numpy 文件和后处理的 CSV 文件（每个输出特征一个）。如果此参数为 True，则仅保存 CSV 文件，跳过 numpy 文件。
skip_save_predictions (bool, 默认值: False): 跳过保存测试预测 CSV 文件
skip_save_eval_stats (bool, 默认值: False): 跳过保存测试统计信息 JSON 文件
skip_collect_predictions (bool, 默认值: False): 跳过在评估期间收集后处理的预测。
skip_collect_overall_stats (bool, 默认值: False): 跳过在评估期间收集总体统计信息。
output_directory (str, 默认值: 'results'): 将包含训练统计数据、TensorBoard 日志、保存的模型和训练进度文件的目录。
random_seed (int: 默认值: 42): 用于权重初始化、分割和任何其他随机函数的随机种子。

返回值

return (Tuple[dict, dict, tuple, str)): (evaluation_statistics, training_statistics, preprocessed_data, output_directory) evaluation_statistics 包含测试集上评估性能统计数据的字典，training_statistics 是一个嵌套字典，结构为 dataset -> feature_name -> metric_name -> 指标列表。每个指标对应一个训练检查点。preprocessed_data 是包含预处理后的 (training_set, validation_set, test_set) 的元组，output_directory 是结果存储的文件路径字符串。

forecast¶

forecast(
  dataset,
  data_format=None,
  horizon=1,
  output_directory=None,
  output_format='parquet'
)

free_gpu_memory¶

free_gpu_memory(
)

手动将模型移动到 CPU 以强制释放 GPU 内存。

更多信息请参阅: https://discuss.pytorch.org/t/how-can-we-release-gpu-memory-cache/14530/35

generate¶

generate(
  input_strings,
  generation_config=None,
  streaming=False
)

一个简单的 generate() 方法，直接使用底层的 transformers 库生成文本。

参数: input_strings (Union[str, List[str]]): 用于生成的输入文本或文本列表。generation_config (Optional[dict]): 文本生成配置。streaming (Optional[bool]): 如果为 True，启用流式输出。

返回值: Union[str, List[str]]: 生成的文本或生成的文本列表。

is_merge_and_unload_set¶

is_merge_and_unload_set(
)

检查封装的模型是否为 LLM 类型并配置为 merge_and_unload QLoRA 权重。

返回值

:return (bool): 是否应该执行 merge_and_unload。

load¶

load(
  model_dir,
  logging_level=40,
  backend=None,
  gpus=None,
  gpu_memory_limit=None,
  allow_parallel_threads=True,
  callbacks=None,
  from_checkpoint=False
)

此函数用于加载预训练模型。

输入参数

model_dir (str): 包含模型的目录路径。如果模型由 train 或 experiment 命令训练，模型位于 results_dir/experiment_dir/model 中。
logging_level (int, 默认值: 40): 将发送到 stderr 的日志级别。
backend (Union[Backend, str]): 用于执行预处理/训练步骤的 Backend 对象或后端名称字符串。
gpus (Union[str, int, List[int]], 默认值: None): 要使用的 GPU（使用与 CUDA_VISIBLE_DEVICES 相同的语法）。
gpu_memory_limit (float: 默认值: None): 允许每个 GPU 设备分配的最大内存比例 [0, 1]。
allow_parallel_threads (bool, 默认值: True): 允许 Torch 使用多线程并行来提高性能，但这会牺牲确定性。
callbacks (list, 默认值: None): 提供 Ludwig 管道钩子的 ludwig.callbacks.Callback 对象列表。
from_checkpoint (bool, 默认值: False): 如果为 True，模型将从最新的检查点 (training_checkpoints/) 加载，而不是最终模型权重。

返回值

return (LudwigModel): 一个 LudwigModel 对象。

示例用法

ludwig_model = LudwigModel.load(model_dir)

load_weights¶

load_weights(
  model_dir,
  from_checkpoint=False
)

从预训练模型加载权重。

输入参数

model_dir (str): 预训练模型位置的文件路径字符串。
from_checkpoint (bool, 默认值: False): 如果为 True，模型将从最新的检查点 (training_checkpoints/) 加载，而不是最终模型权重。

返回值

return ( None):None`

示例用法

ludwig_model.load_weights(model_dir)

predict¶

ludwig.predict(
  dataset=None,
  data_format=None,
  split='full',
  batch_size=128,
  generation_config=None,
  skip_save_unprocessed_output=True,
  skip_save_predictions=True,
  output_directory='results',
  return_type=<class 'pandas.core.frame.DataFrame'>,
  callbacks=None
)

使用训练好的模型，从提供的数据集中进行预测。

输入参数

dataset (Union[str, dict, pandas.DataFrame]):: 包含要评估的整个数据集的来源。
data_format (str, 默认值: None): 用于解释数据源的格式。如果未指定，将自动推断。有效格式包括 'auto', 'csv', 'df', 'dict', 'excel', 'feather', 'fwf', 'hdf5'（之前训练期间生成的缓存文件）, 'html'（包含单个 HTML <table> 的文件）, 'json', 'jsonl', 'parquet', 'pickle'（Pickle 序列化的 Pandas DataFrame）, 'sas', 'spss', 'stata', 'tsv'。
split (str, 默认值= 'full'):: 如果输入数据集包含分割列，此参数指示要使用的数据分割。可能的值包括 'full', 'training', 'validation', 'test'。
batch_size (int, 默认值: 128): 进行预测时使用的批量大小。
generation_config (Dict, 默认值: None): 预测生成配置。如果为 None，则使用模型训练期间使用的配置。此参数仅在模型类型为 LLM 时使用。否则，此参数将被忽略。有关生成配置示例，请参阅大型语言模型下的“生成”部分。
skip_save_unprocessed_output (bool, 默认值: True): 如果此参数为 False，则预测及其概率将保存为包含张量的原始未处理 numpy 文件和后处理的 CSV 文件（每个输出特征一个）。如果此参数为 True，则仅保存 CSV 文件，跳过 numpy 文件。
skip_save_predictions (bool, 默认值: True): 跳过保存测试预测 CSV 文件。
output_directory (str, 默认值: 'results'): 将包含训练统计数据、TensorBoard 日志、保存的模型和训练进度文件的目录。
return_type (Union[str, dict, pandas.DataFrame], 默认值: pd.DataFrame): 指示返回预测的格式。
callbacks (Optional[List[Callback]], 默认值: None): 在此预测操作期间使用的可选回调列表。已注册到模型的任何回调将被保留。

返回值

:return (predictions, output_directory): (Tuple[Union[dict, pd.DataFrame], str]) predictions 来自提供数据集的预测，output_directory 数据存储位置的文件路径字符串。

preprocess¶

preprocess(
  dataset=None,
  training_set=None,
  validation_set=None,
  test_set=None,
  training_set_metadata=None,
  data_format=None,
  skip_save_processed_input=True,
  random_seed=42
)

此函数用于预处理数据。

参数

dataset (Union[str, dict, pandas.DataFrame], 默认值: None): 包含实验中使用的整个数据集的来源。如果包含分割列，则将用于分割（训练为 0，验证为 1，测试为 2），否则将随机分割数据集。
training_set (Union[str, dict, pandas.DataFrame], 默认值: None): 包含训练数据来源。
validation_set (Union[str, dict, pandas.DataFrame], 默认值: None): 包含验证数据来源。
test_set (Union[str, dict, pandas.DataFrame], 默认值: None): 包含测试数据来源。
training_set_metadata (Union[str, dict], 默认值: None): 元数据 JSON 文件或已加载的元数据。中间预处理结构，包含输入数据集的映射，当输入文件首次在同一目录中以相同名称和 '.meta.json' 扩展名使用时创建。
data_format (str, 默认值: None): 用于解释数据源的格式。如果未指定，将自动推断。有效格式包括 'auto', 'csv', 'df', 'dict', 'excel', 'feather', 'fwf', 'hdf5'（之前训练期间生成的缓存文件）, 'html'（包含单个 HTML <table> 的文件）, 'json', 'jsonl', 'parquet', 'pickle'（Pickle 序列化的 Pandas DataFrame）, 'sas', 'spss', 'stata', 'tsv'。
skip_save_processed_input (bool, 默认值: False): 如果提供了输入数据集，则通过保存 HDF5 和 JSON 文件进行预处理和缓存，以避免再次运行预处理。如果此参数为 False，则不保存 HDF5 和 JSON 文件。
random_seed (int, 默认值: 42): 将用于任何随机数生成器调用的随机种子：数据分割、参数初始化和训练集洗牌。

返回值

__:return__: (PreprocessedDataset) 包含 (proc_training_set, proc_validation_set, proc_test_set, training_set_metadata) 的数据结构。

引发异常

RuntimeError: 数据预处理期间发生错误。示例包括预处理后训练数据集为空，RayBackend 不支持延迟加载等。

save¶

save(
  save_path
)

此函数允许将模型保存到磁盘。

输入参数

__ save_path__ (str): 模型将保存到的目录路径。包含模型架构超参数的 JSON 文件和包含模型权重的检查点文件都将保存。

返回值

return (None): None

示例用法

ludwig_model.save(save_path)

save_config¶

save_config(
  save_path
)

将配置保存到指定位置。

输入参数

save_path (str): 将配置保存为 JSON 文件的文件路径字符串。

返回值

return ( None):None`

save_dequantized_base_model¶

save_dequantized_base_model(
  save_path
)

将模型的量化权重放大到 fp16 并将结果保存到指定文件夹。

参数: save_path (str): 将保存放大后的模型权重的文件夹路径。

引发异常: ValueError: 如果模型类型不是 'llm'，或者未启用量化，或者位数不是 4 或 8。RuntimeError: 如果没有可用的 GPU，因为量化模型需要 GPU。

返回值: None

save_torchscript¶

save_torchscript(
  save_path,
  model_only=False,
  device=None
)

将 Torchscript 模型保存到磁盘。

输入参数

save_path (str) (str):: 模型将保存到的目录路径。
model_only (bool, optional) (bool, optional):: 如果为 True，则仅将 ECD 模型转换为 Torchscript。否则，预处理和后处理步骤也将转换为 Torchscript。
device (TorchDevice, optional) (TorchDevice, optional):: 如果为 None，模型将在同一设备上转换为 Torchscript，以确保最大限度的模型一致性。

返回值

return ( None):None`

set_logging_level¶

set_logging_level(
  logging_level
)

设置日志消息的级别。

输入参数

logging_level (int): 设置/更新日志级别。使用日志常量，如 logging.DEBUG , logging.INFO 和 logging.ERROR。

返回值

return ( None):None`

to_torchscript¶

to_torchscript(
  model_only=False,
  device=None
)

将训练好的模型转换为 Torchscript。

输入参数

__ model_only (bool, optional)__ (bool, optional):: 如果为 True，则仅将 ECD 模型转换为 Torchscript。否则，预处理和后处理步骤也将转换为 Torchscript。
device (TorchDevice, optional) (TorchDevice, optional):: 如果为 None，模型将在同一设备上转换为 Torchscript，以确保最大限度的模型一致性。

返回值

return ( 可以用于对输入字典进行预测的 torch.jit.ScriptModule): 一个可以用于对输入字典进行预测的 torch.jit.ScriptModule。

train¶

train(
  dataset=None,
  training_set=None,
  validation_set=None,
  test_set=None,
  training_set_metadata=None,
  data_format=None,
  experiment_name='api_experiment',
  model_name='run',
  model_resume_path=None,
  skip_save_training_description=False,
  skip_save_training_statistics=False,
  skip_save_model=False,
  skip_save_progress=False,
  skip_save_log=False,
  skip_save_processed_input=False,
  output_directory='results',
  random_seed=42
)

此函数用于在指定数据集上执行模型的完整训练。

训练期间，如果跳过参数为 False，则模型和统计数据将保存在目录 [output_dir]/[experiment_name]_[model_name]_n 中，其中所有变量都解析为用户指定的变量，而 n 是一个从 0 开始递增的数字，用于区分重复运行。

输入参数

dataset (Union[str, dict, pandas.DataFrame], 默认值: None): 包含实验中使用的整个数据集的来源。如果包含分割列，则将用于分割（训练为 0，验证为 1，测试为 2），否则将随机分割数据集。
training_set (Union[str, dict, pandas.DataFrame], 默认值: None): 包含训练数据来源。
validation_set (Union[str, dict, pandas.DataFrame], 默认值: None): 包含验证数据来源。
test_set (Union[str, dict, pandas.DataFrame], 默认值: None): 包含测试数据来源。
training_set_metadata (Union[str, dict], 默认值: None): 元数据 JSON 文件或已加载的元数据。中间预处理结构，包含输入数据集的映射，当输入文件首次在同一目录中以相同名称和 '.meta.json' 扩展名使用时创建。
data_format (str, 默认值: None): 用于解释数据源的格式。如果未指定，将自动推断。有效格式包括 'auto', 'csv', 'df', 'dict', 'excel', 'feather', 'fwf', 'hdf5'（之前训练期间生成的缓存文件）, 'html'（包含单个 HTML <table> 的文件）, 'json', 'jsonl', 'parquet', 'pickle'（Pickle 序列化的 Pandas DataFrame）, 'sas', 'spss', 'stata', 'tsv'。
experiment_name (str, 默认值: 'experiment'): 实验名称。
model_name (str, 默认值: 'run'): 使用的模型名称。
model_resume_path (str, 默认值: None): 从指定路径恢复模型训练。配置将恢复。除了配置外，还会恢复每个 epoch 的训练统计数据、损失以及优化器的状态，以便可以有效地从之前中断的训练过程继续训练。
skip_save_training_description (bool, 默认值: False): 禁用保存描述 JSON 文件。
skip_save_training_statistics (bool, 默认值: False): 禁用保存训练统计信息 JSON 文件。
skip_save_model (bool, 默认值: False): 每次模型改进时禁用保存模型权重和超参数。默认情况下，当验证指标改进时，Ludwig 会在每个 epoch 后保存模型权重，但如果模型非常大，这可能非常耗时。如果您不想保留权重而只想了解模型在一组超参数下的性能，请使用此参数跳过保存，但之后将无法加载模型，并且返回的模型将是训练结束时获得的权重，而不是验证性能最佳的 epoch 的权重。
skip_save_progress (bool, 默认值: False): 禁用每个 epoch 保存进度。默认情况下，Ludwig 在每个 epoch 后保存权重和统计数据，以便能够恢复训练，但如果模型非常大，这可能非常耗时，并且会占用两倍的空间，使用此参数跳过保存，但之后无法恢复训练。
skip_save_log (bool, 默认值: False): 禁用保存 TensorBoard 日志。默认情况下，Ludwig 会为 TensorBoard 保存日志，但如果不需要，关闭此选项可以稍微提高整体速度。
skip_save_processed_input (bool, 默认值: False): 如果提供了输入数据集，则通过保存 HDF5 和 JSON 文件进行预处理和缓存，以避免再次运行预处理。如果此参数为 False，则不保存 HDF5 和 JSON 文件。
output_directory (str, 默认值: 'results'): 将包含训练统计数据、TensorBoard 日志、保存的模型和训练进度文件的目录。
random_seed (int, 默认值: 42): 将用于任何随机数生成器调用的随机种子：数据分割、参数初始化和训练集洗牌。
kwargs (dict, 默认值: {}): 可选参数的字典。

返回值

return (Tuple[Dict, Union[Dict, pd.DataFrame], str]): 包含 (training_statistics, preprocessed_data, output_directory) 的元组。training_statistics 是一个嵌套字典，结构为 dataset -> feature_name -> metric_name -> 指标列表。每个指标对应一个训练检查点。preprocessed_data 是包含这三个数据集 (training_set, validation_set, test_set) 的元组。output_directory 是训练结果存储的文件路径。

train_online¶

train_online(
  dataset,
  training_set_metadata=None,
  data_format='auto',
  random_seed=42
)

对 dataset 上的模型执行一个 epoch 的训练。

输入参数

dataset (Union[str, dict, pandas.DataFrame], 默认值: None): 包含实验中使用的整个数据集的来源。如果包含分割列，则将用于分割（训练为 0，验证为 1，测试为 2），否则将随机分割数据集。
training_set_metadata (Union[str, dict], 默认值: None): 元数据 JSON 文件或已加载的元数据。中间预处理结构，包含输入数据集的映射，当输入文件首次在同一目录中以相同名称和 '.meta.json' 扩展名使用时创建。
data_format (str, 默认值: None): 用于解释数据源的格式。如果未指定，将自动推断。有效格式包括 'auto', 'csv', 'df', 'dict', 'excel', 'feather', 'fwf', 'hdf5'（之前训练期间生成的缓存文件）, 'html'（包含单个 HTML <table> 的文件）, 'json', 'jsonl', 'parquet', 'pickle'（Pickle 序列化的 Pandas DataFrame）, 'sas', 'spss', 'stata', 'tsv'。
random_seed (int, 默认值: 42): 将用于任何随机数生成器调用的随机种子：数据分割、参数初始化和训练集洗牌。

返回值

return (None): None

upload_to_hf_hub¶

ludwig.upload_to_hf_hub(
  repo_id,
  model_path,
  repo_type='model',
  private=False,
  commit_message='Upload trained [Ludwig](https://ludwig.net.cn/latest/) model weights',
  commit_description=None
)

将训练好的模型工件上传到 HuggingFace Hub。

输入参数

repo_id (str): 一个命名空间（用户或组织）和仓库名称，用 / 分隔。
model_path (str): 保存模型的路径。可以是 (a) 存储 'model_weights' 文件夹和 'model_hyperparameters.json' 文件的文件夹，或 (b) 该文件夹的父级文件夹。
private (bool, 可选, 默认值: False): 模型仓库是否应为私有。
repo_type (str, 可选): 如果上传到数据集或空间，设置为 "dataset" 或 "space"；如果上传到模型，设置为 None 或 "model"。默认值为 None。
commit_message (str, 可选): 生成提交的摘要/标题/第一行。默认值: f"Upload {path_in_repo} with huggingface_hub"
commit_description (str 可选): 生成提交的描述。

返回值

return (bool): 成功返回 True，失败返回 False。

模块函数¶

kfold_cross_validate¶

ludwig.api.kfold_cross_validate(
  num_folds,
  config,
  dataset=None,
  data_format=None,
  skip_save_training_description=False,
  skip_save_training_statistics=False,
  skip_save_model=False,
  skip_save_progress=False,
  skip_save_log=False,
  skip_save_processed_input=False,
  skip_save_predictions=False,
  skip_save_eval_stats=False,
  skip_collect_predictions=False,
  skip_collect_overall_stats=False,
  output_directory='results',
  random_seed=42,
  gpus=None,
  gpu_memory_limit=None,
  allow_parallel_threads=True,
  backend=None,
  logging_level=20
)

执行 k 折交叉验证并返回结果数据结构。

输入参数

num_folds (int): 交叉验证要创建的折数。
config (Union[dict, str]): 构建模型所需的模型规范。参数可以是字典或指定 yaml 配置文件路径的字符串。详情请参阅用户指南。
dataset (Union[str, dict, pandas.DataFrame], 默认值: None): 包含用于 k 折处理的整个数据集的来源。
data_format (str, 默认值: None): 用于解释数据源的格式。如果未指定，将自动推断。有效格式包括 'auto', 'csv', 'df', 'dict', 'excel', 'feather', 'fwf', 'html'（包含单个 HTML <table> 的文件）, 'json', 'jsonl', 'parquet', 'pickle'（Pickle 序列化的 Pandas DataFrame）, 'sas', 'spss', 'stata', 'tsv'。目前 k 折交叉验证不支持 hdf5 格式。
skip_save_training_description (bool, 默认值: False): 禁用保存描述 JSON 文件。
skip_save_training_statistics (bool, 默认值: False): 禁用保存训练统计信息 JSON 文件。
skip_save_model (bool, 默认值: False): 每次模型改进时禁用保存模型权重和超参数。默认情况下，当验证指标改进时，Ludwig 会在每个 epoch 后保存模型权重，但如果模型非常大，这可能非常耗时。如果您不想保留权重而只想了解模型在一组超参数下的性能，请使用此参数跳过保存，但之后将无法加载模型，并且返回的模型将是训练结束时获得的权重，而不是验证性能最佳的 epoch 的权重。
skip_save_progress (bool, 默认值: False): 禁用每个 epoch 保存进度。默认情况下，Ludwig 在每个 epoch 后保存权重和统计数据，以便能够恢复训练，但如果模型非常大，这可能非常耗时，并且会占用两倍的空间，使用此参数跳过保存，但之后无法恢复训练。
skip_save_log (bool, 默认值: False): 禁用保存 TensorBoard 日志。默认情况下，Ludwig 会为 TensorBoard 保存日志，但如果不需要，关闭此选项可以稍微提高整体速度。
skip_save_processed_input (bool, 默认值: False): 如果提供了输入数据集，则通过保存 HDF5 和 JSON 文件进行预处理和缓存，以避免再次运行预处理。如果此参数为 False，则不保存 HDF5 和 JSON 文件。
skip_save_predictions (bool, 默认值: False): 跳过保存测试预测 CSV 文件。
skip_save_eval_stats (bool, 默认值: False): 跳过保存测试统计信息 JSON 文件。
skip_collect_predictions (bool, 默认值: False): 跳过在评估期间收集后处理的预测。
skip_collect_overall_stats (bool, 默认值: False): 跳过在评估期间收集总体统计信息。
output_directory (str, 默认值: 'results'): 将包含训练统计数据、TensorBoard 日志、保存的模型和训练进度文件的目录。
random_seed (int, 默认值: 42): 用于权重初始化、分割和任何其他随机函数的随机种子。
gpus (list, 默认值: None): 可用于训练的 GPU 列表。
gpu_memory_limit (float: 默认值: None): 允许每个 GPU 设备分配的最大内存比例 [0, 1]。
allow_parallel_threads (bool, 默认值: True): 允许 Torch 使用多线程并行来提高性能，但这会牺牲确定性。
backend (Union[Backend, str]): 用于执行预处理/训练步骤的 Backend 对象或后端名称字符串。
logging_level (int, 默认值: INFO): 发送到 stderr 的日志级别。

返回值

return (tuple(kfold_cv_statistics, kfold_split_indices), dict): 字典元组。kfold_cv_statistics: 包含 CV 运行的指标。kfold_split_indices: 将训练数据分割为训练折叠和测试折叠的索引。

公共 API：此 API 在 Ludwig 版本中保持稳定。

hyperopt¶

ludwig.hyperopt.run.hyperopt(
  config,
  dataset=None,
  training_set=None,
  validation_set=None,
  test_set=None,
  training_set_metadata=None,
  data_format=None,
  experiment_name='hyperopt',
  model_name='run',
  resume=None,
  skip_save_training_description=False,
  skip_save_training_statistics=False,
  skip_save_model=False,
  skip_save_progress=False,
  skip_save_log=False,
  skip_save_processed_input=True,
  skip_save_unprocessed_output=False,
  skip_save_predictions=False,
  skip_save_eval_stats=False,
  skip_save_hyperopt_statistics=False,
  output_directory='results',
  gpus=None,
  gpu_memory_limit=None,
  allow_parallel_threads=True,
  callbacks=None,
  tune_callbacks=None,
  backend=None,
  random_seed=42,
  hyperopt_log_verbosity=3
)

此方法执行超参数优化。

输入参数

config (Union[str, dict]): 定义模型、特征、预处理和训练不同参数的配置。如果为 str，则是 yaml 配置文件的文件路径。
dataset (Union[str, dict, pandas.DataFrame], 默认值: None): 包含实验中使用的整个数据集的来源。如果包含分割列，则将用于分割（训练为 0，验证为 1，测试为 2），否则将随机分割数据集。
training_set (Union[str, dict, pandas.DataFrame], 默认值: None): 包含训练数据来源。
validation_set (Union[str, dict, pandas.DataFrame], 默认值: None): 包含验证数据来源。
test_set (Union[str, dict, pandas.DataFrame], 默认值: None): 包含测试数据来源。
training_set_metadata (Union[str, dict], 默认值: None): 元数据 JSON 文件或已加载的元数据。中间预处理结构，包含输入数据集的映射，当输入文件首次在同一目录中以相同名称和 '.meta.json' 扩展名使用时创建。
data_format (str, 默认值: None): 用于解释数据源的格式。如果未指定，将自动推断。有效格式包括 'auto', 'csv', 'df', 'dict', 'excel', 'feather', 'fwf', 'hdf5'（之前训练期间生成的缓存文件）, 'html'（包含单个 HTML <table> 的文件）, 'json', 'jsonl', 'parquet', 'pickle'（Pickle 序列化的 Pandas DataFrame）, 'sas', 'spss', 'stata', 'tsv'。
experiment_name (str, 默认值: 'experiment'): 实验名称。
model_name (str, 默认值: 'run'): 使用的模型名称。
resume (bool): 如果为 true，则从输出目录中具有相同实验名称的上一次运行的状态继续超参优化。如果为 false，将创建新的试验，忽略任何先前的状态，即使它们存在于 output_directory 中也是如此。默认情况下，如果存在具有相同名称的现有实验，将尝试恢复；否则将创建新的试验。
skip_save_training_description (bool, 默认值: False): 禁用保存描述 JSON 文件。
skip_save_training_statistics (bool, 默认值: False): 禁用保存训练统计信息 JSON 文件。
skip_save_model (bool, 默认值: False): 每次模型改进时禁用保存模型权重和超参数。默认情况下，当验证指标改进时，Ludwig 会在每个 epoch 后保存模型权重，但如果模型非常大，这可能非常耗时。如果您不想保留权重而只想了解模型在一组超参数下的性能，请使用此参数跳过保存，但之后将无法加载模型，并且返回的模型将是训练结束时获得的权重，而不是验证性能最佳的 epoch 的权重。
skip_save_progress (bool, 默认值: False): 禁用每个 epoch 保存进度。默认情况下，Ludwig 在每个 epoch 后保存权重和统计数据，以便能够恢复训练，但如果模型非常大，这可能非常耗时，并且会占用两倍的空间，使用此参数跳过保存，但之后无法恢复训练。
skip_save_log (bool, 默认值: False): 禁用保存 TensorBoard 日志。默认情况下，Ludwig 会为 TensorBoard 保存日志，但如果不需要，关闭此选项可以稍微提高整体速度。
skip_save_processed_input (bool, 默认值: False): 如果提供了输入数据集，则通过保存 HDF5 和 JSON 文件进行预处理和缓存，以避免再次运行预处理。如果此参数为 False，则不保存 HDF5 和 JSON 文件。
skip_save_unprocessed_output (bool, 默认值: False): 默认情况下，预测及其概率将保存为包含张量的原始未处理 numpy 文件和后处理的 CSV 文件（每个输出特征一个）。如果此参数为 True，则仅保存 CSV 文件，跳过 numpy 文件。
skip_save_predictions (bool, 默认值: False): 跳过保存测试预测 CSV 文件。
skip_save_eval_stats (bool, 默认值: False): 跳过保存测试统计信息 JSON 文件。
skip_save_hyperopt_statistics (bool, 默认值: False): 跳过保存超参优化统计文件。
output_directory (str, 默认值: 'results'): 将包含训练统计数据、TensorBoard 日志、保存的模型和训练进度文件的目录。
gpus (list, 默认值: None): 可用于训练的 GPU 列表。
gpu_memory_limit (float: 默认值: None): 允许每个 GPU 设备分配的最大内存比例 [0, 1]。
allow_parallel_threads (bool, 默认值: True): 允许 PyTorch 使用多线程并行来提高性能，但这会牺牲确定性。
callbacks (list, 默认值: None): 提供 Ludwig 管道钩子的 ludwig.callbacks.Callback 对象列表。
backend (Union[Backend, str]): 用于执行预处理/训练步骤的 Backend 对象或后端名称字符串。
random_seed (int: 默认值: 42): 用于权重初始化、分割和任何其他随机函数的随机种子。
hyperopt_log_verbosity (int: 默认值: 3): 控制 ray tune 日志消息的详细程度。有效值: 0 = 静默, 1 = 仅状态更新, 2 = 状态和简要试验结果, 3 = 状态和详细试验结果。

返回值

return (List[dict]): 按目标指标的降序性能排列的每个试验的结果列表。