Flashlight 是一个由 Facebook AI Research 以及 Torch、TensorFlow、Eigen 和 Deep Speech 的创建者共同开发的快速、灵活的机器学习库，完全用 C++ 编写。其核心特性包括：

• 完全可定制性，包括用于张量计算的 内部 API。
• 轻量级，核心代码小于 10 MB，仅有约 2 万行 C++ 代码。
• 高性能默认设置，通过 ArrayFire 张量库以现代 C++ 实现即时编译内核。
• 强调效率与规模。

Flashlight 原生支持 C++，且易于扩展，使其成为一个强大的研究框架，能够在不牺牲性能的前提下，以较少的约束快速迭代新的实验方案和算法。在同一个仓库中，Flashlight 提供了适用于多个领域的研究应用：

• 自动语音识别（前身为 wav2letter 项目）— 文档 | 教程
• 图像分类
• 目标检测
• 语言建模

项目结构

Flashlight 分为几个部分：

• flashlight/lib 包含用于音频处理等任务的内核和独立工具。
• flashlight/fl 是核心张量接口及神经网络库，默认使用 ArrayFire 张量库。
• flashlight/pkg 是基于核心构建的语音、视觉和文本领域专用包。
• flashlight/app 是将核心库应用于不同领域机器学习的具体应用。

快速入门

首先，构建并安装 Flashlight 并将其 链接到您自己的项目。

Sequential 可以将 Flashlight 的 Module 组成序列，用于串联计算。

#include <flashlight/fl/flashlight.h>

Sequential model;

model.add(View(fl::Shape({IM_DIM, IM_DIM, 1, -1})));
model.add(Conv2D(
    1 /* 输入通道 */,
    32 /* 输出通道 */,
    5 /* 卷积核宽度 */,
    5 /* 卷积核高度 */,
    1 /* 步幅 x */,
    1 /* 步幅 y */,
    PaddingMode::SAME; /* 填充模式 */,
    PaddingMode::SAME; /* 填充模式 */));
model.add(ReLU());
model.add(Pool2D(
    2 /* 卷积核宽度 */,
    2 /* 卷积核高度 */,
    2 /* 步幅 x */,
    2 /* 步幅 y */));
model.add(Conv2D(32, 64, 5, 5, 1, 1, PaddingMode::SAME, PaddingMode::SAME));
model.add(ReLU());
model.add(Pool2D(2, 2, 2, 2));
model.add(View(fl::Shape({7 * 7 * 64, -1})));
model.add(Linear(7 * 7 * 64, 1024));
model.add(ReLU());
model.add(Dropout(0.5));
model.add(Linear(1024, 10));
model.add(LogSoftmax());

auto output = model.forward(input);
auto loss = categoricalCrossEntropy(output, target);
loss.backward();

有关完整的训练循环和数据集抽象，请参阅 MNIST 示例。

Variable 是一种基于磁带的抽象，封装了 Flashlight 张量。Flashlight 中基于磁带的 自动微分 简单易用，符合预期。

auto A = Variable(fl::rand({1000, 1000}), true /* calcGrad */);
auto B = 2.0 * A;
auto C = 1.0 + B;
auto D = log(C);
D.backward(); // 会填充 A.grad()，同时计算 B、C 和 D 的梯度。

构建与安装

使用 vcpkg 安装 | 使用 Docker | 从源码构建 | 结合 vcpkg 从源码构建 | 在您的项目中使用 Flashlight

需求

至少需要以下条件才能进行编译：

• 支持良好 C++17 的 C++ 编译器（例如 gcc/g++ >= 7）
• CMake — 版本 3.10 或更高，以及 make
• 基于 Linux 的操作系统。

如果选择 从源码构建，请参阅 完整依赖列表以获取更多详细信息。

关于构建/安装 Python 绑定的说明 可以在这里找到。

手电筒构建设置

如上文所述，手电筒可以分解为多个组件。每个组件都可以通过指定正确的构建选项逐步构建。

使用手电筒有两种方式：

1. 作为已安装的库，与您自己的项目链接。这对于构建依赖于手电筒的独立应用程序最为合适。
2. 源码内开发，即修改并重新构建手电筒项目源码。如果您需要自定义或深入修改核心框架，或者使用手电筒提供的应用二进制文件，则这种方式最为合适。

手电筒可以通过以下两种方式构建：

1. 使用 vcpkg，一个C++ 包管理器。
2. 从源码构建，根据需要安装依赖项。

使用 vcpkg 安装手电筒

使用 vcpkg 安装库

使用 vcpkg 是构建和安装手电筒最简单的方式。vcpkg 同时支持 CUDA 和 CPU 后端。无论选择哪种后端，首先都需要安装 Intel MKL。对于 CUDA 后端，还需安装 CUDA ≥ 9.2、cuDNN 和 NCCL。然后，在安装 vcpkg之后，即可通过以下命令安装库和核心：

./vcpkg/vcpkg install flashlight-cuda # CUDA 后端，或
./vcpkg/vcpkg install flashlight-cpu  # CPU 后端

要安装手电筒应用，可以运行 ./vcpkg search flashlight-cuda 或 ./vcpkg search flashlight-cpu 查看可安装的功能。每个应用都对应一个“功能”：例如，./vcpkg install flashlight-cuda[asr] 将安装带有 CUDA 后端的 ASR 应用程序。

以下是当前支持的功能列表（适用于 flashlight-cuda 和 flashlight-cpu）：

flashlight-{cuda/cpu}[lib]      # 手电筒库
flashlight-{cuda/cpu}[nn]       # 手电筒神经网络库
flashlight-{cuda/cpu}[asr]      # 手电筒语音识别应用
flashlight-{cuda/cpu}[lm]       # 手电筒语言建模应用
flashlight-{cuda/cpu}[imgclass] # 手电筒图像分类应用

手电筒的应用二进制文件也会针对所选功能进行构建，并安装到 vcpkg 安装目录的 tools 目录中。

使用 vcpkg 的CMake 工具链集成，将手电筒集成到您自己的项目中非常简单（详见下文使用 vcpkg 安装的手电筒）。

使用 vcpkg 从源码构建

首先，使用 vcpkg 安装您所选后端的依赖项（点击展开下方内容）：

./vcpkg install \
    cuda intel-mkl fftw3 cub kenlm                \ # 如果构建手电筒库
    arrayfire[cuda] cudnn nccl openmpi cereal stb \ # 如果构建手电筒神经网络库
    gflags glog                                   \ # 如果构建任何手电筒应用
    libsndfile                                    \ # 如果构建手电筒 ASR 应用
    gtest                                           # 可选，如果构建测试

./vcpkg install \
    intel-mkl fftw3 kenlm                              \ # 用于手电筒库
    arrayfire[cpu] gloo[mpi] openmpi onednn cereal stb \ # 用于手电筒神经网络库
    gflags glog                                        \ # 用于手电筒运行时包（任何使用它的手电筒应用）
    libsndfile                                         \ # 用于手电筒语音包
    gtest                                                # 可选，用于测试

使用 vcpkg 工具链文件构建

要使用这些依赖项从源码构建手电筒，首先克隆仓库：

git clone https://github.com/flashlight/flashlight.git && cd flashlight
mkdir -p build && cd build

然后，使用 vcpkg 的CMake 工具链从源码构建：

cmake .. \
    -DCMAKE_BUILD_TYPE=Release \
    -DFL_BUILD_ARRAYFIRE=ON \
    -DCMAKE_TOOLCHAIN_FILE=[您的 vcpkg 克隆路径]/scripts/buildsystems/vcpkg.cmake
make -j$(nproc)
make install -j$(nproc) # 仅当您希望将手电筒安装以供外部使用时

要构建手电筒的部分功能，可参阅下方的构建选项。

从源码构建

要从源码构建，首先需要安装以下依赖项。大多数依赖项可通过您系统的本地包管理器获取。

部分标记为自动下载和安装的依赖项，若本地系统未找到，则会自动下载并安装。FL_BUILD_STANDALONE 控制此行为——如果禁用，构建手电筒时将不会下载和构建这些依赖项。

在所有依赖项安装完毕后，克隆仓库：

git clone https://github.com/flashlight/flashlight.git && cd flashlight
mkdir -p build && cd build

然后，使用以下命令构建手电筒的所有组件：

cmake .. -DCMAKE_BUILD_TYPE=Release -DFL_BUILD_ARRAYFIRE=ON [...构建选项]
make -j$(nproc)
make install

设置 MKLROOT 环境变量（在大多数基于 Linux 的系统上，可设置为 export MKLROOT=/opt/intel/oneapi/mkl/latest 或 export MKLROOT=/opt/intel/mkl），有助于 CMake 在未自动找到 Intel MKL 时定位该库。

要构建手电筒更小范围的功能或应用，请参阅下方的构建选项，以获取完整的选项列表。

要在自定义目录中安装 Flashlight，请使用 CMake 的 CMAKE_INSTALL_PREFIX 参数。Flashlight 库可以使用 CMake 的 BUILD_SHARED_LIBS 参数构建为共享库。

Flashlight 对大多数依赖项使用现代 CMake 和 IMPORTED 目标。如果未找到某个依赖项，可以在 cmake 命令中传递 -D<package>_DIR 参数，或将 <package>_DIR 导出为环境变量，并将其值设置为 <package>Config.cmake 文件的路径，这样可以帮助在您的系统上定位依赖项。有关更多详细信息，请参阅 文档。如果 CMake 无法找到某个包，请先检查是否已存在相应的 问题，再自行创建新问题。

macOS 上的最小化设置

在 macOS 上，可以使用 Homebrew 安装 ArrayFire，并按以下方式构建 Flashlight 核心：

brew install arrayfire
cmake .. \
      -DFL_ARRAYFIRE_USE_OPENCL=ON \
      -DFL_USE_ONEDNN=OFF \
      -DFL_BUILD_TESTS=OFF \
      -DFL_BUILD_EXAMPLES=OFF \
      -DFL_BUILD_SCRIPTS=OFF \
      -DFL_BUILD_DISTRIBUTED=OFF
make -j$(nproc)

依赖项

标有 * 的依赖项会在系统中未找到时自动从源代码下载并构建。将 FL_BUILD_STANDALONE 设置为 OFF 可禁用此行为。

标有 ^ 的依赖项是在启用分布式训练（FL_BUILD_DISTRIBUTED — 请参阅下方的 [构建选项]）时必需的。所有应用程序都需要分布式训练功能。

标有 † 的依赖项可以通过 vcpkg 安装。有关执行 Flashlight 源码构建时如何安装这些依赖项的说明，请参阅上方的 [通过 vcpkg 进行源码构建] 部分。

构建选项

Flashlight 的 CMake 构建支持以下构建选项（在命令行运行 CMake 时需以 -D 作为前缀）：

使用 Flashlight 构建您自己的项目

Flashlight 最容易通过 CMake 进行链接。安装后，Flashlight 会导出以下 CMake 目标：

• flashlight::flashlight — 包含 Flashlight 库以及核心自动微分和神经网络库。
• flashlight::fl_pkg_runtime — 包含 Flashlight 核心以及用于训练的常用工具（日志记录 / 标志 / 分布式工具）。
• flashlight::fl_pkg_vision — 包含 Flashlight 核心以及视觉流水线中的常用工具。
• flashlight::fl_pkg_text — 包含 Flashlight 核心以及处理文本数据的常用工具。
• flashlight::fl_pkg_speech — 包含 Flashlight 核心以及处理语音数据的常用工具。
• flashlight::fl_pkg_halide — 包含 Flashlight 核心及与 Halide 轻松对接的扩展。

假设有一个简单的 project.cpp 文件，它包含了 Flashlight 并与其链接：

#include <iostream>

#include <flashlight/fl/flashlight.h>

int main() {
  fl::init();
  fl::Variable v(fl::full({1}, 1.), true);
  auto result = v + 10;
  std::cout << "张量值为 " << result.tensor() << std::endl; // 11.000
  return 0;
}

以下 CMake 配置将链接 Flashlight 并设置包含目录：

cmake_minimum_required(VERSION 3.10)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_executable(myProject project.cpp)

find_package(flashlight CONFIG REQUIRED)
target_link_libraries(myProject PRIVATE flashlight::flashlight)

使用 vcpkg 安装的 Flashlight

如果您使用 vcpkg 安装了 Flashlight，则可以通过运行以下命令来构建上述 myProject 的 CMake 配置：

cd project && mkdir build && cd build
cmake .. \
  -DCMAKE_TOOLCHAIN_FILE=[vcpkg 克隆路径]/scripts/buildsystems/vcpkg.cmake \
  -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

使用源码安装的 Flashlight

如果您使用的是从源码安装的 Flashlight，CMake 将会自动找到 Flashlight：

cd project && mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

如果 Flashlight 安装在自定义位置，并使用了 CMAKE_INSTALL_PREFIX，则可以在 cmake 命令中添加 -Dflashlight_DIR=[安装前缀]/share/flashlight/cmake 参数，以帮助 CMake 找到 Flashlight。

使用 Docker 构建和运行 Flashlight

Flashlight 及其依赖项也可以使用提供的 Dockerfile 进行构建；有关更多信息，请参阅随附的 Docker 文档。

贡献与联系信息

联系人：vineelkpratap@fb.com, awni@fb.com, jacobkahn@fb.com, qiantong@fb.com, antares@fb.com, padentomasello@fb.com, jcai@fb.com, gab@fb.com, vitaliy888@fb.com, locronan@fb.com

Flashlight 正在积极开发中。有关如何参与贡献的更多信息，请参阅 CONTRIBUTING。

致谢

Flashlight 的部分代码源自 arrayfire-ml。

引用

您可以使用以下方式引用 Flashlight：

@misc{kahn2022flashlight,
      title={Flashlight: Enabling Innovation in Tools for Machine Learning},
      author={Jacob Kahn and Vineel Pratap and Tatiana Likhomanenko and Qiantong Xu and Awni Hannun and Jeff Cai and Paden Tomasello and Ann Lee and Edouard Grave and Gilad Avidov and Benoit Steiner and Vitaliy Liptchinsky and Gabriel Synnaeve and Ronan Collobert},
      year={2022},
      eprint={2201.12465},
      archivePrefix={arXiv},
      primaryClass={cs.LG}
}

许可证

Flashlight 采用 MIT 许可证。有关更多信息，请参阅 LICENSE。

Flashlight 快速上手指南

Flashlight 是一个由 Facebook AI Research 开发的快速、灵活的 C++ 机器学习库。它完全用 C++ 编写，具有小巧的体积（核心代码约 2 万行）、高性能默认配置以及对自动微分和张量计算的全面支持。

1. 环境准备

在开始之前，请确保您的开发环境满足以下最低要求：

• 操作系统: Linux (推荐 Ubuntu/CentOS)
• 编译器: 支持 C++17 的编译器 (如 gcc/g++ >= 7)
• 构建工具: CMake (版本 3.10+) 和 make
• 包管理器: 推荐使用 vcpkg 进行依赖管理

前置依赖

根据您选择的后端（CPU 或 CUDA），需要安装不同的基础库：

• 通用依赖: Intel MKL (用于数学计算)
• CPU 后端: 无额外特殊要求（MKL 已涵盖主要需求）
• GPU 后端 (CUDA):
  • CUDA Toolkit (>= 9.2)
  • cuDNN
  • NCCL (用于多卡通信)

提示: 国内开发者若遇到依赖下载缓慢问题，可配置 vcpkg 使用国内镜像源，或在构建时通过代理加速。

2. 安装步骤

推荐使用 vcpkg 进行安装，这是最简便的方式，可自动处理复杂的依赖关系。

第一步：安装 vcpkg

如果尚未安装 vcpkg，请先克隆并引导它：

git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh

第二步：安装 Flashlight

根据您的硬件环境选择以下任一命令安装：

选项 A：安装 CPU 版本

./vcpkg install flashlight-cpu

选项 B：安装 CUDA (GPU) 版本 (请确保已预先安装好 CUDA, cuDNN 和 NCCL)

./vcpkg install flashlight-cuda

可选：安装特定应用组件 如果您需要使用语音识别 (ASR)、图像分类等预置应用，可以通过特性标志安装：

# 示例：安装带有 ASR 功能的 CUDA 版本
./vcpkg install flashlight-cuda[asr]

第三步：集成到项目

在您的 CMakeLists.txt 中，通过 toolchain 文件引入 vcpkg 即可自动链接 Flashlight：

set(CMAKE_TOOLCHAIN_FILE ${VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake CACHE STRING "Vcpkg toolchain file")
find_package(flashlight CONFIG REQUIRED)
target_link_libraries(your_target PRIVATE flashlight::fl)

3. 基本使用

Flashlight 的核心在于其简洁的 API 设计，支持通过 Sequential 串联网络层，并利用 Variable 实现基于 Tape 的自动微分。

构建一个简单的卷积神经网络 (ConvNet)

以下示例展示了如何定义一个包含卷积、池化和全连接层的模型：

#include <flashlight/fl/flashlight.h>

// 定义序列模型
Sequential model;

// 添加层
model.add(View(fl::Shape({IM_DIM, IM_DIM, 1, -1})));
model.add(Conv2D(
    1, 32, 5, 5, 1, 1, 
    PaddingMode::SAME, PaddingMode::SAME)); // 输入通道，输出通道，核大小，步长等
model.add(ReLU());
model.add(Pool2D(2, 2, 2, 2));
model.add(Conv2D(32, 64, 5, 5, 1, 1, PaddingMode::SAME, PaddingMode::SAME));
model.add(ReLU());
model.add(Pool2D(2, 2, 2, 2));
model.add(View(fl::Shape({7 * 7 * 64, -1})));
model.add(Linear(7 * 7 * 64, 1024));
model.add(ReLU());
model.add(Dropout(0.5));
model.add(Linear(1024, 10));
model.add(LogSoftmax());

前向传播与反向传播

Flashlight 的前向和反向计算非常直观：

// 假设 input 和 target 已定义
auto output = model.forward(input);

// 计算损失 (交叉熵)
auto loss = categoricalCrossEntropy(output, target);

// 执行反向传播，自动计算梯度
loss.backward();

自动微分示例

直接使用 Variable 包装张量即可启用自动求导：

// 创建需要计算梯度的变量
auto A = Variable(fl::rand({1000, 1000}), true /* calcGrad */);

// 构建计算图
auto B = 2.0 * A;
auto C = 1.0 + B;
auto D = log(C);

// 反向传播，梯度将填充到 A.grad() 以及中间变量中
D.backward(); 

现在您可以开始使用 Flashlight 进行高效的 C++ 深度学习开发了。更多详细教程（如 MNIST 完整训练循环）请参考官方文档。