Hasktorch

Hasktorch 是一个用于 Haskell 中张量和神经网络的库。 它是一个独立的开源社区项目，利用了 PyTorch 共享的核心 C++ 库。

该项目目前处于积极开发中，因此随着其演进，库的 API 可能会发生变化。 我们诚挚邀请新用户加入我们的 Hasktorch Discord 社区（贡献指南），以进行问题讨论和交流。我们也鼓励大家提交 贡献/拉取请求。

Hasktorch 的第二个主要版本 (0.2) 目前已在 hackage 和 nixpkgs 上发布。

文档

文档分为几个部分：

• 入门视频
• 快速上手
• 已知问题
• 贡献指南
• 库开发者注意事项

入门视频

• @austinvhuang 的 高级 MuniHac 演讲
• @tscholak 的 动手实操直播编码演示
• @junjihashimoto 的 低级 FFI 演讲

快速上手

以下步骤将帮助您快速开始使用。这些步骤假设您刚刚克隆了 hasktorch 仓库。设置完成后，请阅读 在线教程 和 API 文档。

• Linux + Cabal + CPU
• Linux + Cabal + CUDA 11
• macOS + Cabal + CPU
• Linux + Stack + CPU
• macOS + Stack + CPU
• NixOS + Cabal + CPU
• NixOS + Cabal + CUDA 11
• Docker + JupyterLab + CUDA 11

Linux + Cabal + CPU

从项目的根目录开始，运行：

$ ./setup-cabal.sh # 创建一个 Cabal 项目文件

要构建并测试 Hasktorch 库，运行：

$ cabal build hasktorch  # 构建 Hasktorch 库。
$ cabal test hasktorch   # 构建并运行 Hasktorch 库的测试套件。

要构建并测试随 Hasktorch 一起提供的示例可执行文件，运行：

$ cabal build examples  # 构建 Hasktorch 示例。
$ cabal test examples   # 构建并运行 Hasktorch 示例的测试套件。

要运行 MNIST CNN 示例，运行：

$ cd examples                            # 切换到 examples 目录。
$ ./datasets/download-mnist.sh           # 下载 MNIST 数据集。
$ export DEVICE=cpu                      # 将设备设置为 CPU 以运行 MNIST CNN 示例。
$ cabal run static-mnist-cnn -- ./mnist/ # 运行 MNIST CNN 示例。

Linux + Cabal + CUDA

首先将 LIBTORCH_CUDA_VERSION 环境变量设置为您当前使用的 CUDA 版本。例如：

对于 CUDA 11.8，运行 export LIBTORCH_CUDA_VERSION=cu118。

如果未指定，Hasktorch 默认会下载 CPU 版本。

从项目的根目录开始，运行：

$ ./setup-cabal.sh        # 创建一个 Cabal 项目文件

要构建并测试 Hasktorch 库，运行：

$ cabal build hasktorch  # 构建 Hasktorch 库。
$ cabal test hasktorch   # 构建并运行 Hasktorch 库的测试套件。

要构建并测试随 Hasktorch 一起提供的示例可执行文件，运行：

$ cabal build examples  # 构建 Hasktorch 示例。
$ cabal test examples   # 构建并运行 Hasktorch 示例的测试套件。

要运行 MNIST CNN 示例，运行：

$ cd examples                            # 切换到 examples 目录。
$ ./datasets/download-mnist.sh           # 下载 MNIST 数据集。
$ export DEVICE="cuda:0"                 # 将设备设置为 CUDA 以运行 MNIST CNN 示例。
$ cabal run static-mnist-cnn -- ./mnist/ # 运行 MNIST CNN 示例。

macOS + Cabal + CPU

从项目的根目录开始，运行：

$ ./setup-cabal.sh # 创建一个 Cabal 项目文件

要构建并测试 Hasktorch 库，运行：

$ cabal build hasktorch  # 构建 Hasktorch 库。
$ cabal test hasktorch   # 构建并运行 Hasktorch 库的测试套件。

要构建并测试随 Hasktorch 一起提供的示例可执行文件，运行：

$ cabal build examples  # 构建 Hasktorch 示例。
$ cabal test examples   # 构建并运行 Hasktorch 示例的测试套件。

要运行 MNIST CNN 示例，运行：

$ cd examples                            # 切换到 examples 目录。
$ ./datasets/download-mnist.sh           # 下载 MNIST 数据集。
$ export DEVICE=cpu                      # 将设备设置为 CPU 以运行 MNIST CNN 示例。
$ cabal run static-mnist-cnn -- ./mnist/ # 运行 MNIST CNN 示例。

Linux + Stack + CPU

如果您尚未安装 Haskell Tool Stack，请按照 此处的说明 进行安装。

要构建并测试 Hasktorch 库，运行：

$ stack build hasktorch  # 构建 Hasktorch 库。
$ stack test hasktorch   # 构建并运行 Hasktorch 库的测试套件。

要构建并测试随 Hasktorch 一起提供的示例可执行文件，运行：

$ stack build examples  # 构建 Hasktorch 示例。
$ stack test examples   # 构建并运行 Hasktorch 示例的测试套件。

要运行 MNIST CNN 示例，运行：

$ cd examples                            # 切换到 examples 目录。
$ ./datasets/download-mnist.sh           # 下载 MNIST 数据集。
$ export DEVICE=cpu                      # 将设备设置为 CPU 以运行 MNIST CNN 示例。
$ cabal run static-mnist-cnn -- ./mnist/ # 运行 MNIST CNN 示例。

macOS + Stack + CPU

如果您尚未安装 Haskell Tool Stack，请按照 此处的说明 进行安装。

要构建并测试 Hasktorch 库，运行：

$ stack build hasktorch  # 构建 Hasktorch 库。
$ stack test hasktorch   # 构建并运行 Hasktorch 库的测试套件。

要构建并测试随 Hasktorch 一起提供的示例可执行文件，运行：

$ stack build examples  # 构建 Hasktorch 示例。
$ stack test examples   # 构建并运行 Hasktorch 示例的测试套件。

要运行 MNIST CNN 示例，运行：

$ cd examples                            # 切换到 examples 目录。
$ ./datasets/download-mnist.sh           # 下载 MNIST 数据集。
$ export DEVICE=cpu                      # 将设备设置为 CPU 以运行 MNIST CNN 示例。
$ cabal run static-mnist-cnn -- ./mnist/ # 运行 MNIST CNN 示例。

NixOS + Cabal + CPU

（可选）安装并设置 Cachix：

$ nix-env -iA cachix -f https://cachix.org/api/v1/install  # （可选）安装 Cachix。

# （可选）使用 IOHK 的缓存。请参阅 https://input-output-hk.github.io/haskell.nix/tutorials/getting-started/#setting-up-the-binary-cache
$ cachix use hasktorch                                     # （可选）使用 hasktorch 的缓存。

从项目的顶级目录开始，运行：

$ nix develop  # 进入 Hasktorch 的 Nix shell 环境。

要构建并测试 Hasktorch 库，运行：

$ cabal build hasktorch  # 构建 Hasktorch 库。
$ cabal test hasktorch   # 构建并运行 Hasktorch 库的测试套件。

要构建并测试随 Hasktorch 一起提供的示例可执行文件，运行：

$ cabal build examples  # 构建 Hasktorch 示例。
$ cabal test examples   # 构建并运行 Hasktorch 示例的测试套件。

要运行 MNIST CNN 示例，运行：

$ cd examples                            # 切换到 examples 目录。
$ ./datasets/download-mnist.sh           # 下载 MNIST 数据集。
$ export DEVICE=cpu                      # 将设备设置为 CPU，用于 MNIST CNN 示例。
$ cabal run static-mnist-cnn -- ./mnist/ # 运行 MNIST CNN 示例。

nixos+cabal+cuda11

（可选）安装并设置 Cachix：

$ nix-env -iA cachix -f https://cachix.org/api/v1/install  # （可选）安装 Cachix。
# （可选）使用 IOHK 的缓存。请参阅 https://input-output-hk.github.io/haskell.nix/tutorials/getting-started/#setting-up-the-binary-cache
$ cachix use hasktorch                                     # （可选）使用 hasktorch 的缓存。

从项目的顶级目录开始，运行：

$ cat > nix/dev-config.nix
{
  profiling = true;
  cudaSupport = true;
  cudaMajorVersion = "11";
}
$ nix develop  # 进入 Hasktorch 的 Nix shell 环境。

要构建并测试 Hasktorch 库，运行：

$ cabal build hasktorch  # 构建 Hasktorch 库。
$ cabal test hasktorch   # 构建并运行 Hasktorch 库的测试套件。

要构建并测试随 Hasktorch 一起提供的示例可执行文件，运行：

$ cabal build examples  # 构建 Hasktorch 示例。
$ cabal test examples   # 构建并运行 Hasktorch 示例的测试套件。

要运行 MNIST CNN 示例，运行：

$ cd examples                            # 切换到 examples 目录。
$ ./datasets/download-mnist.sh           # 下载 MNIST 数据集。
$ export DEVICE="cuda:0"                 # 将设备设置为 CUDA，用于 MNIST CNN 示例。
$ cabal run static-mnist-cnn -- ./mnist/ # 运行 MNIST CNN 示例。

docker+jupyterlab+cuda11

这个 Docker Hub 仓库 提供了 JupyterLab 的 Docker 镜像。 它支持 CUDA 11、CUDA 10 和仅 CPU 模式。当您使用带有 Hasktorch 的 JupyterLab 时，请键入以下命令，然后单击控制台中的 URL。

$ docker run --gpus all -it --rm -p 8888:8888 htorch/hasktorch-jupyter
或
$ docker run --gpus all -it --rm -p 8888:8888 htorch/hasktorch-jupyter:latest-cu11

已知问题

macOS 上的 MPS（Metal Performance Shaders）支持

在支持 MPS 设备的 Apple Silicon Mac 上使用 Hasktorch 时，必须在运行程序之前设置环境变量 PYTORCH_ENABLE_MPS_FALLBACK=1：

$ export PYTORCH_ENABLE_MPS_FALLBACK=1
$ cabal test hasktorch   # 在启用 MPS 回退的情况下运行测试

或者直接运行：

$ PYTORCH_ENABLE_MPS_FALLBACK=1 cabal test hasktorch

这是必需的，因为某些操作（如 erfc）尚未在 PyTorch 的 MPS 后端中原生实现，需要回退到 CPU 计算。如果没有设置此环境变量，您将看到类似以下的错误：

运算符 'aten::erfc.out' 当前未在 MPS 设备上实现。

注意：当未设置此环境变量时，MPS 测试将自动跳过，以防止失败。

张量无法移动到 CUDA

在极少数情况下，您可能会看到类似以下的错误：

无法将张量移动到 "CUDA:0"

尽管您的机器配备了 CUDA 功能硬件，并且已按照 CUDA 支持的入门说明进行了操作。

如果发生这种情况，请检查 /run/opengl-driver/lib 是否存在。如果不存在，请确保正确安装了 CUDA 驱动程序。

从仅 CPU 切换到启用 CUDA 的 Nix Shell 时的奇怪行为

如果您之前曾在仅 CPU 的 Hasktorch Nix Shell 中运行过 cabal，您可能需要：

• 使用 cabal clean 清理 dist-newstyle 文件夹。
• 删除 Hasktorch 根目录中的 .ghc.environment* 文件。

否则，最好的情况是您将无法将张量移动到 CUDA，最坏的情况则是会出现奇怪的链接器错误，例如：

gcc: 错误：hasktorch/dist-newstyle/build/x86_64-linux/ghc-8.8.3/libtorch-ffi-1.5.0.0/build/Torch/Internal/Unmanaged/Autograd.dyn_o：没有这样的文件或目录
`cc' 在阶段 `Linker' 中失败。（退出代码：1）

贡献

我们欢迎新的贡献者。

请联系获取 hasktorch Discord 频道 的访问权限。 您可以发送电子邮件至 hasktorch@gmail.com，或通过 Twitter 联系 @austinvhuang、@SamStites、@tscholak 或 @junjihashimoto3。

库开发者注意事项

有关开发人员注意事项，请参阅 维基。

项目文件夹结构

基本功能：

• deps/ - 用于构建依赖项（libtorch、mklml、pytorch）的子模块和下载内容——如果您使用 Nix，则可以忽略此部分
• examples/ - 高层次示例模型（异或 MLP、类型化 CNN 等）
• experimental/ - 实验性项目或技巧
• hasktorch/ - 更高层次的面向用户的库，调用 ffi/，由 examples/ 使用

内部结构（供贡献开发者参考）：

• codegen/ - 代码生成，解析来自 PyTorch 的 Declarations.yaml 规范，并生成 ffi/ 内容
• inline-c/ - 用于 C++ FFI 的 inline-cpp 分支子模块
• libtorch-ffi/ - 低级的 libtorch FFI 绑定
• spec/ - 用于 codegen/ 的规范文件

Hasktorch 快速上手指南

Hasktorch 是一个基于 Haskell 的张量与神经网络库，它复用了 PyTorch 的核心 C++ 库。本指南将帮助你在不同环境下快速搭建并运行第一个示例。

环境准备

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

• 操作系统: Linux, macOS 或 NixOS (Windows 用户建议使用 Docker 或 WSL2)。
• Haskell 工具链: 需安装 cabal 或 stack。
  • 推荐安装 GHC (Glasgow Haskell Compiler) 版本与项目兼容（通常较新版本即可）。
  • Stack 用户请参考 官方安装文档。
• GPU 支持 (可选): 若需使用 CUDA，请确保已正确安装 NVIDIA 驱动及对应的 CUDA Toolkit (如 CUDA 11.x)。
• 网络环境: 首次构建时会自动下载 LibTorch 二进制文件，请确保网络连接通畅。

安装步骤

根据你的操作系统和构建工具选择以下一种方案。所有命令请在克隆 hasktorch 仓库后的根目录下执行。

方案 A：Linux / macOS + Cabal (CPU 模式)

最通用的安装方式，适用于大多数开发场景。

# 1. 生成 Cabal 项目配置文件
./setup-cabal.sh

# 2. 构建并测试 Hasktorch 核心库
cabal build hasktorch
cabal test hasktorch

# 3. 构建示例程序
cabal build examples

方案 B：Linux + Cabal (CUDA 模式)

如需使用 GPU 加速，需先指定 CUDA 版本。

# 1. 设置 CUDA 版本环境变量 (例如 CUDA 11.8)
export LIBTORCH_CUDA_VERSION=cu118

# 2. 生成配置文件并构建
./setup-cabal.sh
cabal build hasktorch
cabal build examples

方案 C：NixOS / Nix Shell (推荐用于隔离环境)

如果你使用 Nix，可以获得最一致的环境体验。

CPU 模式:

nix develop
cabal build hasktorch

CUDA 模式:

# 创建启用 CUDA 的配置
cat > nix/dev-config.nix <<EOF
{
  profiling = true;
  cudaSupport = true;
  cudaMajorVersion = "11";
}
EOF

# 进入开发环境
nix develop
cabal build hasktorch

方案 D：Docker + JupyterLab (免配置体验)

如果你希望立即尝试而不想配置本地环境，可以使用预构建的 Docker 镜像（支持 CUDA 11）。

# 启动 JupyterLab 容器 (需安装 Docker 且支持 GPU)
docker run --gpus all -it --rm -p 8888:8888 htorch/hasktorch-jupyter:latest-cu11

启动后，点击终端输出的 URL 即可在浏览器中使用。

基本使用

构建完成后，你可以运行自带的 MNIST CNN 示例来验证安装是否成功。

1. 准备数据

进入示例目录并下载数据集：

cd examples
./datasets/download-mnist.sh

2. 运行示例

CPU 模式:

export DEVICE=cpu
cabal run static-mnist-cnn -- ./mnist/

CUDA 模式:

export DEVICE="cuda:0"
cabal run static-mnist-cnn -- ./mnist/

3. 开始编码

环境验证无误后，你可以参考 在线教程 和 API 文档 开始编写自己的 Haskell 神经网络代码。

提示: 如果你在 Apple Silicon Mac 上使用 MPS 设备遇到算子不支持的错误，请在运行前设置环境变量： export PYTORCH_ENABLE_MPS_FALLBACK=1