Lingvo

是什么？

Lingvo 是一个用于在 TensorFlow 中构建神经网络的框架，特别是序列模型。

使用 Lingvo 的相关论文列表可以在这里找到 PUBLICATIONS.md。

目录

• 版本发布
  • 重大破坏性变更
• 快速入门
  • 安装
  • 运行 MNIST 图像模型
  • 运行机器翻译模型
  • 运行基于 GShard Transformer 的巨型语言模型
  • 运行 3D 物体检测模型
• 模型
  • 自动语音识别
  • 汽车
  • 图像
  • 语言建模
  • 机器翻译
• 参考文献
• 许可证

版本发布

PyPI 版本	提交记录
0.12.4	--
0.11.0	6fae10077756f54beacd5c454959f20b33fd65e2
0.10.0	075fd1d88fa6f92681f58a2383264337d0e737ee
0.9.1	c1124c5aa7af13d2dd2b6d43293c8ca6d022b008
0.9.0	f826e99803d1b51dccbbbed1ef857ba48a2bbefe

旧版发布

PyPI 版本	提交记录
0.8.2	93e123c6788e934e6b7b1fd85770371becf1e92e
0.7.2	b05642fe386ee79e0d88aa083565c9a93428519e

旧版发布的详细信息暂不可用。

重大破坏性变更

注意：这不是一个完整的列表。Lingvo 发布不提供任何关于向后兼容性的保证。

HEAD

此处无内容。

0.12.0

• 通用
  • 现在需要 TensorFlow 2.9。
  • 已移除对 Python 3.7 的支持。
  • 兼容至多 TensorFlow 2.10 和 Python 3.10。

0.11.0

• 通用
  • 现在需要 TensorFlow 2.7。
  • 已移除对 Python 3.6 的支持。

0.10.0

• 通用
  • 现在需要 TensorFlow 2.6。
  • 已移除 CreateVariable() 方法中的 theta_fn 参数。

0.9.1

• 通用
  • 现在支持 Python 3.9。
  • ops.beam_search_step 现在接收并返回一个额外参数 beam_done。
  • namedtuple beam_search_helper.BeamSearchDecodeOutput 现在移除了字段 done_hyps。

0.9.0

• 通用
  • 现在需要 TensorFlow 2.5。
  • 已移除对 Python 3.5 的支持。
  • py_utils.AddGlobalVN 和 py_utils.AddPerStepVN 已合并为 py_utils.AddVN。
  • BaseSchedule().Value() 不再接受 step 参数。
  • 继承自 BaseSchedule 的类应实现 Value() 而不是 FProp()。
  • theta.global_step 已被移除，取而代之的是 py_utils.GetGlobalStep()。
  • py_utils.GenerateStepSeedPair() 不再接受 global_step 参数。
  • PostTrainingStepUpdate() 不再接受 global_step 参数。
  • 自定义输入操作中的 fatal_errors 参数现在接受错误消息子字符串，而不是整数错误代码。

旧版发布

0.8.2

• 通用
  • NestedMap Flatten/Pack/Transform/Filter 等方法现在也会展开其子字典。
  • 继承自 abc.ABCMeta 的 BaseLayer 子类现在应继承 base_layer.ABCLayerMeta。
  • 在 __init__ 之外调用 self.CreateChild 现在会引发错误。
  • base_layer.initializer 已被移除。子类不再需要装饰其 __init__ 函数。
  • 在 __init__ 或 _CreateLayerVariables 之外调用 self.CreateVariable 现在会引发错误。
  • 在 __init__ 内部无法再访问 self.vars 或 self.theta。请将变量的创建和访问移到 _CreateLayerVariables 中。变量作用域会在 _CreateLayerVariables 中根据层名自动设置。

旧版发布的详细信息暂不可用。

快速入门

安装

有两种方式来设置 Lingvo：通过 pip 安装固定版本，或者克隆仓库并使用 Bazel 构建。每种情况都提供了 Docker 配置。

如果您只想直接使用该框架，最简单的方式是通过 pip 安装。这样可以使用冻结版本的 Lingvo 框架开发和训练自定义模型。然而，这种方式难以修改框架代码或实现新的自定义操作。

如果您希望进一步开发框架并可能贡献 Pull Request，则应避免使用 pip，而选择克隆仓库。

pip:

可以通过 pip3 install lingvo 安装 Lingvo pip 包。

有关如何开始使用 pip 包，请参阅 codelab。

从源码安装:

所需条件如下：

• TensorFlow 2.7 的安装（安装指南），
• C++ 编译器（官方仅支持 g++ 7.3），以及
• Bazel 构建系统。

请参考 docker/dev.Dockerfile 以获取一组可行的配置。

使用 git clone 克隆仓库，然后使用 Bazel 直接构建和运行目标。Codelab 中的 python -m module 命令需要映射为 bazel run 命令。

Docker:

两种情况下都有可用的 Docker 配置。具体说明可在每个文件顶部的注释中找到。

• lib.dockerfile 已预装 Lingvo pip 包。
• dev.Dockerfile 可用于从源码构建 Lingvo。

Docker 安装指南

运行 MNIST 图像模型

准备输入数据

pip:

mkdir -p /tmp/mnist
python3 -m lingvo.tools.keras2ckpt --dataset=mnist

bazel:

mkdir -p /tmp/mnist
bazel run -c opt //lingvo/tools:keras2ckpt -- --dataset=mnist

以下文件将在 /tmp/mnist 中创建：

• mnist.data-00000-of-00001: 53MB。
• mnist.index: 241 字节。

运行模型

pip:

cd /tmp/mnist
curl -O https://raw.githubusercontent.com/tensorflow/lingvo/master/lingvo/tasks/image/params/mnist.py
python3 -m lingvo.trainer --run_locally=cpu --mode=sync --model=mnist.LeNet5 --logdir=/tmp/mnist/log

bazel:

(cpu) bazel build -c opt //lingvo:trainer
(gpu) bazel build -c opt --config=cuda //lingvo:trainer
bazel-bin/lingvo/trainer --run_locally=cpu --mode=sync --model=image.mnist.LeNet5 --logdir=/tmp/mnist/log --logtostderr

大约 20 秒后，损失应降至 0.3 以下，并会保存一个检查点，如下所示。使用 Ctrl+C 终止训练程序。

trainer.py:518] step:   205, steps/sec: 11.64 ... loss:0.25747201 ...
checkpointer.py:115] 保存检查点
checkpointer.py:117] 检查点保存完成：/tmp/mnist/log/train/ckpt-00000205

在 /tmp/mnist/log/control 中会产生一些文件：

• params.txt: 超参数。
• model_analysis.txt: 各层的模型大小。
• train.pbtxt: 训练用的 tf.GraphDef。
• events.*: TensorBoard 事件文件。

同时，在 /tmp/mnist/log/train 中也会生成：

• checkpoint: 包含检查点文件信息的文本文件。
• ckpt-*: 检查点文件。

现在，让我们在“测试”数据集上评估模型。在正常的训练设置中，训练器和评估器应作为两个独立的进程同时运行。

pip:

python3 -m lingvo.trainer --job=evaler_test --run_locally=cpu --mode=sync --model=mnist.LeNet5 --logdir=/tmp/mnist/log

bazel:

bazel-bin/lingvo/trainer --job=evaler_test --run_locally=cpu --mode=sync --model=image.mnist.LeNet5 --logdir=/tmp/mnist/log --logtostderr

当它开始等待新的检查点时，使用 Ctrl+C 终止任务。

base_runner.py:177] 未找到新检查点：/tmp/mnist/log/train/ckpt-00000205

评估准确率可以在日志中稍早的位置找到。

base_runner.py:111] eval_test: step:   205, acc5: 0.99775392, accuracy: 0.94150388, ..., loss: 0.20770954, ...

运行机器翻译模型

要运行更复杂的模型，您需要一个配备 GPU 的集群。更多信息请参阅 third_party/py/lingvo/tasks/mt/README.md。

运行基于 GShard 变压器的巨型语言模型

要在 GCP 上使用 CloudTPUs v3-512 和 512 路模型并行性训练具有一万亿参数的 GShard 语言模型，请参阅 third_party/py/lingvo/tasks/lm/README.md 获取更多信息。

运行 3D 对象检测模型

要在 GCP 上使用 CloudTPUs 运行 StarNet 模型，请参阅 third_party/py/lingvo/tasks/car/README.md。

模型

自动语音识别

• Listen, Attend and Spell。
  William Chan、Navdeep Jaitly、Quoc V. Le 和 Oriol Vinyals。ICASSP 2016。

  基于注意力的循环神经网络的端到端连续语音识别：初步结果。
  Jan Chorowski、Dzmitry Bahdanau、Kyunghyun Cho 和 Yoshua Bengio。arXiv 2014。

  • asr.librispeech.Librispeech960Grapheme
  • asr.librispeech.Librispeech960Wpm

汽车

• DeepFusion：用于多模态 3D 对象检测的激光雷达-摄像头深度融合。
  Yingwei Li、Adams Wei Yu、Tianjian Meng、Ben Caine、Jiquan Ngiam、Daiyi Peng、Junyang Shen、Bo Wu、Yifeng Lu、Denny Zhou、Quoc V. Le、Alan Yuille、Mingxing Tan。CVPR 2022。

  • car.waymo_deepfusion.DeepFusionCenterPointPed

• StarNet：点云中对象检测的定向计算。
  Jiquan Ngiam、Benjamin Caine、Wei Han、Brandon Yang、Yuning Chai、Pei Sun、Yin Zhou、Xi Yi、Ouais Alsharif、Patrick Nguyen、Zhifeng Chen、Jonathon Shlens 和 Vijay Vasudevan。arXiv 2019。

  • car.kitti.StarNetCarModel0701
  • car.kitti.StarNetPedCycModel0704
  • car.waymo.StarNetVehicle
  • car.waymo.StarNetPed

图像

• 应用于文档识别的基于梯度的学习。
  Yann LeCun、Leon Bottou、Yoshua Bengio 和 Patrick Haffner。IEEE 1998。

  • image.mnist.LeNet5

语言建模

• 探索语言模型的极限。
  Rafal Jozefowicz、Oriol Vinyals、Mike Schuster、Noam Shazeer 和 Yonghui Wu。arXiv 2016。

  • lm.one_billion_wds.WordLevelOneBwdsSimpleSampledSoftmax

• GShard：利用条件计算和自动分片扩展巨型模型。
  Dmitry Lepikhin、HyoukJoong Lee、Yuanzhong Xu、Dehao Chen、Orhan Firat、Yanping Huang、Maxim Krikun、Noam Shazeer 和 Zhifeng Chen。arXiv 2020。

  • lm.synthetic_packed_input.DenseLm1T16x16

机器翻译

• 两全其美：结合神经机器翻译的最新进展。
  Mia X. Chen、Orhan Firat、Ankur Bapna、Melvin Johnson、Wolfgang Macherey、George Foster、Llion Jones、Mike Schuster、Noam Shazeer、Niki Parmar、Ashish Vaswani、Jakob Uszkoreit、Lukasz Kaiser、Zhifeng Chen、Yonghui Wu 和 Macduff Hughes。ACL 2018。

  • mt.wmt14_en_de.WmtEnDeTransformerBase
  • mt.wmt14_en_de.WmtEnDeRNMT
  • mt.wmtm16_en_de.WmtCaptionEnDeTransformer

• 资源丰富的神经机器翻译中的自监督与监督联合训练。
  Yong Cheng、Wei Wang、Lu Jiang 和 Wolfgang Macherey。ICML 2021。

  • mt.xendec.wmt14_en_de.WmtEnDeXEnDec

参考文献

• API 文档
• Codelab

引用 Lingvo 时，请引用此论文。

@misc{shen2019lingvo,
    title={Lingvo：一个模块化且可扩展的序列到序列建模框架},
    author={Jonathan Shen、Patrick Nguyen、Yonghui Wu、Zhifeng Chen 等},
    year={2019},
    eprint={1902.08295},
    archivePrefix={arXiv},
    primaryClass={cs.LG}
}

许可证

Apache 许可证 2.0

Lingvo 快速上手指南

Lingvo 是一个基于 TensorFlow 构建神经网络的框架，特别适用于序列模型（如语音识别、机器翻译等）。本指南将帮助中国开发者快速完成环境配置并运行第一个示例。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux (推荐 Ubuntu) 或 macOS。
• Python: 3.7 - 3.10 (推荐使用 3.8 或 3.9)。
• TensorFlow: 2.9 或更高版本 (兼容至 2.10)。
• 编译器: g++ 7.3 (仅当从源码构建时需要)。
• 构建工具: Bazel (仅当从源码构建时需要)。

注意：如果您仅需使用框架进行模型开发或训练，推荐通过 pip 安装，无需配置 C++ 编译器和 Bazel。

安装步骤

您可以选择通过 pip 安装稳定版，或通过源码克隆进行开发。

方式一：通过 pip 安装（推荐）

这是最简单的方式，适合大多数用户。

pip3 install lingvo

国内加速建议：如果下载速度较慢，可使用国内镜像源：

pip3 install lingvo -i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后，建议参考官方 Colab 教程熟悉基础用法： https://colab.research.google.com/github/tensorflow/lingvo/blob/master/codelabs/introduction.ipynb

方式二：从源码构建（进阶）

如果您需要修改框架代码或贡献 PR，请克隆仓库并使用 Bazel 构建。

1. 克隆仓库：

   git clone https://github.com/tensorflow/lingvo.git
   cd lingvo
   

2. 构建与运行： 使用 Bazel 直接构建和运行目标。注意，python -m module 命令需映射为 bazel run 命令。

   参考 Docker 配置: 项目提供了 docker/dev.Dockerfile，其中包含了完整的构建依赖环境，建议优先参考该文件配置本地环境。

基本使用

以下以运行 MNIST 图像分类模型 为例，演示完整流程。

1. 准备数据

首先需要将 MNIST 数据集转换为 Lingvo 所需的 checkpoint 格式。

如果你使用 pip 安装：

mkdir -p /tmp/mnist
python3 -m lingvo.tools.keras2ckpt --dataset=mnist

如果你使用 bazel 构建：

mkdir -p /tmp/mnist
bazel run -c opt //lingvo/tools:keras2ckpt -- --dataset=mnist

执行成功后，/tmp/mnist 目录下将生成 mnist.data-00000-of-00001 和 mnist.index 文件。

2. 获取模型配置文件

下载 MNIST 模型的参数配置文件：

cd /tmp/mnist
curl -O https://raw.githubusercontent.com/tensorflow/lingvo/master/lingvo/tasks/image/params/mnist.py

(注：国内网络若无法访问 raw.githubusercontent.com，可手动下载该文件或使用代理)

3. 开始训练

启动训练任务。以下命令将在 CPU 上同步运行 LeNet5 模型。

如果你使用 pip 安装：

python3 -m lingvo.trainer --run_locally=cpu --mode=sync --model=mnist.LeNet5 --logdir=/tmp/mnist/log

如果你使用 bazel 构建：

# CPU 构建
bazel build -c opt //lingvo:trainer
# 运行
bazel-bin/lingvo/trainer --run_locally=cpu --mode=sync --model=image.mnist.LeNet5 --logdir=/tmp/mnist/log --logtostderr

预期输出： 约 20 秒后，Loss 应降至 0.3 以下，并保存 checkpoint：

trainer.py:518] step:   205, steps/sec: 11.64 ... loss:0.25747201 ...
checkpointer.py:115] Save checkpoint
checkpointer.py:117] Save checkpoint done: /tmp/mnist/log/train/ckpt-00000205

按 Ctrl+C 停止训练。

4. 评估模型

训练完成后，使用测试集评估模型准确率。

如果你使用 pip 安装：

python3 -m lingvo.trainer --job=evaler_test --run_locally=cpu --mode=sync --model=mnist.LeNet5 --logdir=/tmp/mnist/log

如果你使用 bazel 构建：

bazel-bin/lingvo/trainer --job=evaler_test --run_locally=cpu --mode=sync --model=image.mnist.LeNet5 --logdir=/tmp/mnist/log --logtostderr

预期输出： 日志中将显示评估结果，例如：

base_runner.py:111] eval_test: step:   205, acc5: 0.99775392, accuracy: 0.94150388, ..., loss: 0.20770954, ...

---

更多复杂模型（如机器翻译、GShard 大语言模型、3D 物体检测）的运行方法，请参考项目仓库中对应任务目录下的 README.md 文件。