Yoyodyne 🪀

Yoyodyne提供带有和没有特征条件的小词汇量序列到序列生成的神经模型。

这些模型使用PyTorch和Lightning实现。

虽然我们提供了经典的LSTM和transformer模型，但其中一些模型特别适用于源-目标对齐大致单调的问题（例如transducer和hard_attention_lstm）以及源和目标词汇表有大量重叠的情况（例如pointer_generator_lstm）。

设计理念

Yoyodyne受到FairSeq（Ott等人，2019年）的启发，但在设计上有几个关键点有所不同

• 它适用于小词汇量序列到序列生成，因此不包含机器翻译或语言模型的功能。正因为如此
  • 它没有插件接口，提供的架构旨在尽可能全面。
  • 几乎不需要数据预处理；它支持使用TSV文件。
• 它支持使用特征来条件解码，架构特定的代码处理特征信息。
• 它支持使用验证准确率（而非损失）进行模型选择和提前停止。
• 定期发布。
• 🚧 施工中 🚧：它有详尽的测试套件。
• 🚧 施工中 🚧：它有性能基准。

作者

Yoyodyne是由Adam Wiemerslage、Kyle Gorman、Travis Bartley和其他像您一样的贡献者创建的。

安装

本地安装

Yoyodyne目前支持Python 3.9到3.12。

首先安装依赖项

pip install -r requirements.txt

然后安装

pip install .

然后它可以像常规Python模块一样导入

import yoyodyne

Google Colab

Yoyodyne与Google Colab GPU运行时兼容。此笔记本提供了一个示例。Colab还提供对TPU运行时的访问，但据我们所知，目前还不兼容Yoyodyne。

用法

训练

训练是通过yoyodyne-train脚本进行的。必须指定以下必需参数

• --model_dir：模型元数据和检查点的路径
• --experiment：实验名称（选择一个独特的名称）
• --train：包含训练数据的TSV文件路径
• --val：包含验证数据的TSV文件路径

用户还可以指定各种可选的训练和架构参数。请参阅以下内容或运行yoyodyne-train --help获取更多信息。

验证

验证是在用户请求的间隔内运行的。请参阅--val_check_interval和--check_val_every_n_epoch 此处。还可以请求其他评估指标，使用--eval_metric。例如

yoyodyne-train --eval_metric ser ...

将在每次验证时额外计算符号错误率（SER）。可以添加到evaluators.py的附加指标。

预测

预测是通过yoyodyne-predict脚本进行的。必须指定以下必需参数

• --model_dir：模型元数据的路径
• --experiment：实验名称
• --checkpoint：检查点的路径
• --predict：包含要预测的数据的文件路径
• --output：预测的路径

--predict文件可以是TSV文件，也可以是每行一个源字符串的普通TXT文件；在后一种情况下，指定--target_col 0。运行yoyodyne-predict --help获取更多信息。

数据格式

默认数据格式是两列TSV文件，其中第一列是源字符串，第二列是目标字符串。

source   target

要启用特征列的使用，需要指定一个非零的--features_col参数。例如，在SIGMORPHON 2017 共享任务中，第一列是源（一个词元），第二列是目标（屈折形式），第三列包含分号分隔的特征字符串。

source   target    feat1;feat2;...

此格式通过--features_col 3指定。

对于SIGMORPHON 2016 共享任务数据

source   feat1,feat2,...    target

此格式通过--features_col 2 --features_sep , --target_col 3指定。

为了确保在预测期间忽略目标，可以指定--target_col 0。

保留符号

Yoyodyne保留<...>形式的符号供内部使用。特征条件模型也使用[...]以避免特征符号与源和目标符号冲突，而--no_tie_embeddings使用{...}以避免源和目标符号冲突。因此，用户不应提供任何<...>、[...]或{...}形式的符号。

模型检查点

检查点由Lightning处理。模型信息（包括检查点）的路径由--model_dir和--experiment的组合指定，以便我们构建路径model_dir/experiment/version_n，其中每个具有相同model_dir和experiment的实验运行都使用一个新的版本号进行命名空间划分。一个版本存储了重新加载模型所需的所有内容，包括超参数（model_dir/experiment_name/version_n/hparams.yaml）和检查点目录（model_dir/experiment_name/version_n/checkpoints）。

默认情况下，每次运行都会从零开始初始化一个新模型，除非指定了--train_from参数。要从特定检查点继续训练，应使用--train_from参数指定检查点的完整路径。这将创建一个新版本，但开始从提供的模型检查点进行训练。

默认情况下保存1个检查点。要保存多个检查点，请使用--num_checkpoints标志。要每轮保存一个检查点，请设置--num_checkpoints -1。默认情况下，保存的检查点是那些最大化验证精度的检查点。要选择那些最小化验证损失的检查点，请设置--checkpoint_metric loss。

模型

用户使用--arch标志指定模型的总体架构。此标志的值指定了解码器的架构以及是否存在注意力机制。此标志还指定了编码器（s）的默认架构，但可以使用其他标志覆盖它。支持--arch的值包括

• attentive_lstm：这是一个具有LSTM编码器（默认）和注意力机制的LSTM解码器。初始隐藏状态被视为学习参数。
• hard_attention_lstm：这是一个将生成建模为马尔可夫过程的LSTM编码器/解码器。默认情况下，它假定源字符串的非单调进展，但使用--enforce_monotonic则模型必须按顺序遍历每个源字符。非零的--attention_context值（默认：0）扩展了条件状态转换的上下文窗口，包括一个或多个先前状态。
• lstm：这是一个具有LSTM编码器（默认）的LSTM解码器；在没有注意力机制的情况下，编码器的最后一个非填充隐藏状态与解码器隐藏状态连接。
• pointer_generator_lstm：这是一个具有 LSTM 编码器（默认）和指针生成机制的 LSTM 解码器。由于此模型包含复制机制，当源词汇表和目标词汇表重叠显著时，它可能优于普通的注意力 LSTM。请注意，此模型要求 --encoder_layers 和 --decoder_layers 的数量匹配。
• pointer_generator_transformer：这是一个具有 transformer 编码器（默认）和指针生成机制的 transformer 解码器。与 pointer_generator_lstm 类似，当源词汇表和目标词汇表重叠显著时，它可能优于普通的 transformer。当使用特征时，用户可能希望指定特征注意力头数（使用 --features_attention_heads；默认：1）。
• transducer：这是一个具有 LSTM 编码器（默认）和神经转换器机制的 LSTM 解码器。在模型创建时，使用期望最大化学习一系列编辑操作，并使用模仿学习训练模型以实现 oracle 策略，通过 --oracle_factor 标志（默认：1）控制卷入。由于此模型假设单调对齐，当输入和输出之间的对齐大致单调且输入和输出词汇表重叠显著时，它可能优于注意力模型。
• transformer：这是一个具有 transformer 编码器（默认）的 transformer 解码器。使用正弦波位置编码和层归一化。用户可能希望指定注意力头数（使用 --source_attention_heads；默认：4）。

用户可以覆盖默认编码器架构。可以使用 --source_encoder_arch 标志覆盖源编码器。

• feature_invariant_transformer：这是用于特征的一个 transformer 编码器的变体；它连接源和特征，并使用学习到的嵌入来区分源和特征符号。
• linear：这是一个线性编码器。
• lstm：这是一个 LSTM 编码器。
• transformer：这是一个 transformer 编码器。

当使用特征时，用户还可以使用 --features_encoder_arch 标志指定非默认的特征编码器（linear、lstm、transformer）。

对于所有模型，用户还可以指定以下选项：

• --decoder_layers（默认：1）：解码器层数
• --embedding（默认：128）：嵌入大小
• --encoder_layers（默认：1）：编码器层数
• --hidden_size（默认：512）：隐藏层大小

默认情况下，LSTM 编码器是双向的。可以通过 --no_bidirectional 标志禁用此功能。

训练选项

以下是一些非详尽列表：

• 批大小
  • --batch_size（默认：32）
  • --accumulate_grad_batches（默认：未启用）
• 正则化
  • --dropout（默认：0.2）
  • --label_smoothing（默认：0.0）
  • --gradient_clip_val（默认：未启用）
• 优化器
  • --learning_rate（默认：0.001）
  • --optimizer（默认："adam"）
  • --beta1（默认：0.9）：Adam 优化器（--optimizer adam）的 $\beta_1$ 超参数
  • --beta2（默认：0.99）：Adam 优化器（--optimizer adam）的 $\beta_2$ 超参数
  • --scheduler（默认：未启用）
• 持续时间
  • --max_epochs
  • --min_epochs
  • --max_steps
  • --min_steps
  • --max_time
• 随机数种子
  • --seed
• 权重与偏差:
  • --log_wandb（默认：False）：启用 Weights & Biases 跟踪

以下将讨论其他额外的训练选项。

早期停止

要启用提前停止，请使用 --patience 和 --patience_metric 标志。在没有改进的情况下（如果 --patience_metric loss 则验证损失停止下降，如果 --patience_metric accuracy 则验证准确度停止增加），在 --patience 个epoch之后发生提前停止。默认情况下，不启用提前停止。

调度器

默认情况下，Yoyodyne在训练期间使用恒定学习率，但最佳实践是使用调度器逐渐降低学习率，当模型接近收敛时。支持三个（非空）调度器，并使用--scheduler进行选择。

• lineardecay：以线性方式降低学习率（将其乘以--start_factor），持续--total_decay_steps步，然后以--end_factor降低学习率。
• reduceonplateau：在--reduceonplateau_patience个epoch内没有改进的情况下（如果--reduceonplateau loss则验证损失停止下降，如果--reduceonplateau_metric accuracy则验证准确度停止增加）降低学习率（将其乘以--reduceonplateau_factor），直到学习率小于或等于--min_learning_rate。
• warmupinvsqrt：以线性方式将学习率从0增加到--learning_rate，持续--warmup_steps步，然后根据逆平方根计划降低学习率。

关联嵌入

默认情况下，源和目标词汇表是共享的。这可以通过使用--no_tie_embeddings标志来禁用，该标志使用{...}来避免源和目标符号之间的冲突。

批大小技巧

选择合适的批大小对快速训练和最佳性能至关重要。批大小通过--batch_size标志指定。

可能希望使用比“in core”中能容纳的更大的批大小进行训练。例如，假设希望使用4,096个批大小进行拟合，但这样做会导致内存不足（OOM）异常。然后，通过最小的开销，可以通过使用1,024大小的批次，每更新一次累积4个批次的梯度来模拟4,096个有效批次的批大小。

yoyodyne-train --batch_size 1024 --accumulate_grad_batches 4 ...

--find_batch_size标志启用了自动计算批大小。使用--find_batch_size max，它简单地使用最大批大小，忽略--batch_size。使用--find_batch_size opt，它会找到最大批大小，然后按以下方式解释

• 如果最大批大小大于--batch_size，则使用--batch_size作为批大小。
• 然而，如果最大批大小小于--batch_size，则求解最佳梯度累积技巧，并使用最大的批大小和最小的梯度累积步骤数，其乘积为--batch_size。

如果希望在不实际训练的情况下求解这些量，请传递--find_batch_size opt和--max_epochs 0。这将计算并记录解决方案后停止。

超参数调整

没有适当的超参数调整，不应部署任何神经网络模型。然而，默认选项为注意力的biLSTM提供了一个合理的初始设置。对于基于transformer的架构，请尝试多个编码器和解码器层、更大的批大小和预热加逆平方根衰减调度器。

权重 & 偏差调整

wandb_sweeps展示了如何使用Weights & Biases运行超参数扫描。

加速器

在训练或预测期间可以使用硬件加速器。除了CPU（默认）和GPU（--accelerator gpu）之外，其他加速器也可能被支持，但尚未全部经过测试。

精度

默认情况下，训练使用32位精度。然而，--precision 标志允许用户使用半精度（16）或如果加速器支持的话，使用 bfloat16 半精度格式 进行训练。这可能会减小模型和内存中的批处理大小，从而允许使用更大的批处理。注意，只有默认精度才适用于CPU训练。

示例

examples 目录包含一些有趣的示例，包括

• wandb_sweeps展示了如何使用Weights & Biases运行超参数扫描。

开发者

开发者，开发者，开发者！ - 史蒂夫·鲍尔默

本节包含针对 Yoyodyne 维护者的说明。

发布

1. 创建一个新的分支。例如，如果您想将此分支命名为 "release"，请执行：git checkout -b release
2. 将您分叉的分支与上游的 master 分支同步。例如，如果上游远程名为 "upstream"，请执行：git pull upstream master
3. 在 pyproject.toml 中增加版本字段。
4. 暂存您的更改：git add pyproject.toml。
5. 提交您的更改：git commit -m "您的提交信息"
6. 推送您的更改。例如，如果您的分支名为 "release"，请执行：git push origin release
7. 提交您的发布请求，并等待它被合并到 master 分支。
8. 标记 master 分支的最后提交。标记应以 v 开头；例如，如果新版本是 3.1.4，标记应为 v3.1.4。这可以通过以下方式完成：
   • 在 GitHub 本身：点击 Yoyodyne GitHub 页面右侧的 "Releases" 或 "创建新版本" 链接）并按照对话框操作。
   • 使用命令行中的 git tag 命令。
9. 构建新的发布版本：python -m build
10. 将结果上传到 PyPI：twine upload dist/*

参考

Ott, M.，Edunov, S.，Baevski, A.，Fan, A.，Gross, S.，Ng, N.，Grangier, D.，和 Auli, M. 2019. fairseq：一个快速、可扩展的序列建模工具包。在 2019 年北美计算语言学会会议论文集（演示），第 48-53 页。