Torch.rb

:fire: 基于 LibTorch 的 Ruby 深度学习库

你还可以查看：

• TorchVision 用于计算机视觉任务
• TorchText 用于文本和 NLP 任务
• TorchAudio 用于音频任务
• TorchCodec 用于音频和视频编码
• TorchRec 用于推荐系统
• TorchData 用于数据加载

以及：

• Transformers 用于 Transformer 模型
• Safetensors 用于存储张量

安装

首先，下载 LibTorch。对于 Mac arm64，请使用以下命令：

curl -L https://download.pytorch.org/libtorch/cpu/libtorch-macos-arm64-2.10.0.zip > libtorch.zip
unzip -q libtorch.zip

对于 Linux x86-64，请使用与你的 CUDA 版本匹配的构建版本。对于其他平台，请从源代码编译 LibTorch。

然后运行：

bundle config set build.torch-rb --with-torch-dir=/path/to/libtorch

并在你的应用 Gemfile 中添加以下行：

gem "torch-rb"

扩展编译可能需要 5–10 分钟。目前不支持 Windows。

入门

一个好的起点是 用 Torch.rb 进行深度学习：60 分钟速成。

教程

• 迁移学习
• 序列模型
• 词嵌入

示例

• 使用 MNIST 进行图像分类（日文版）
• 使用 MovieLens 进行协同过滤
• 生成对抗网络

API

该库遵循 PyTorch API。为了使其更符合 Ruby 风格，做了一些调整：

• 执行原地修改的方法以 ! 结尾，而不是 _（例如 add! 而不是 add_）
• 返回布尔值的方法使用 ? 而不是 is_（例如 tensor? 而不是 is_tensor）
• 使用 Numo 替代 NumPy（例如 x.numo 而不是 x.numpy()）

在许多情况下，你可以参考 PyTorch 教程并将代码转换为 Ruby。如果遇到问题，请随时提交 issue。

概述

以下示例摘自 用 PyTorch 进行深度学习：60 分钟速成。

张量

从 Ruby 数组创建张量

x = Torch.tensor([[1, 2, 3], [4, 5, 6]])

获取张量的形状

x.shape

还有 许多函数 可用于创建张量，例如：

a = Torch.rand(3)
b = Torch.zeros(2, 3)

每个张量有四个属性：

• dtype — 数据类型 — :uint8, :int8, :int16, :int32, :int64, :float32, :float64, 或 :bool
• layout — :strided（密集）或 :sparse
• device — 计算设备，如 CPU 或 GPU
• requires_grad — 是否需要记录梯度

你可以在创建张量时指定这些属性：

Torch.rand(2, 3, dtype: :float64, layout: :strided, device: "cpu", requires_grad: true)

操作

创建一个张量

x = Torch.tensor([10, 20, 30])

加法

x + 5 # tensor([15, 25, 35])

减法

x - 5 # tensor([5, 15, 25])

乘法

x * 5 # tensor([50, 100, 150])

除法

x / 5 # tensor([2, 4, 6])

取余数

x % 3 # tensor([1, 2, 0])

求幂

x**2 # tensor([100, 400, 900])

与其他张量进行操作

y = Torch.tensor([1, 2, 3])
x + y # tensor([11, 22, 33])

原地操作

x.add!(5)
x # tensor([15, 25, 35])

你也可以指定输出张量：

result = Torch.empty(3)
Torch.add(x, y, out: result)
result # tensor([15, 25, 35])

Numo

将张量转换为 Numo 数组

a = Torch.ones(5)
a.numo

将 Numo 数组转换为张量

b = Numo::NArray.cast([1, 2, 3])
Torch.from_numo(b)

自动求导

创建一个带有 requires_grad: true 的张量

x = Torch.ones(2, 2, requires_grad: true)

执行操作

y = x + 2
z = y * y * 3
out = z.mean

反向传播

out.backward

获取梯度

x.grad # tensor([[4.5, 4.5], [4.5, 4.5]])

停止自动求导跟踪历史

x.requires_grad # true
(x**2).requires_grad # true

Torch.no_grad do
  (x**2).requires_grad # false
end

神经网络

定义一个神经网络

class MyNet < Torch::NN::Module
  def initialize
    super()
    @conv1 = Torch::NN::Conv2d.new(1, 6, 3)
    @conv2 = Torch::NN::Conv2d.new(6, 16, 3)
    @fc1 = Torch::NN::Linear.new(16 * 6 * 6, 120)
    @fc2 = Torch::NN::Linear.new(120, 84)
    @fc3 = Torch::NN::Linear.new(84, 10)
  end

  def forward(x)
    x = Torch::NN::F.max_pool2d(Torch::NN::F.relu(@conv1.call(x)), [2, 2])
    x = Torch::NN::F.max_pool2d(Torch::NN::F.relu(@conv2.call(x)), 2)
    x = Torch.flatten(x, 1)
    x = Torch::NN::F.relu(@fc1.call(x))
    x = Torch::NN::F.relu(@fc2.call(x))
    @fc3.call(x)
  end
end

创建它的实例

net = MyNet.new
input = Torch.randn(1, 1, 32, 32)
net.call(input)

获取可训练参数

net.parameters

清零梯度缓冲区并用随机梯度反向传播

net.zero_grad
out.backward(Torch.randn(1, 10))

定义损失函数

output = net.call(input)
target = Torch.randn(10)
target = target.view(1, -1)
criterion = Torch::NN::MSELoss.new
loss = criterion.call(output, target)

反向传播

net.zero_grad
p net.conv1.bias.grad
loss.backward
p net.conv1.bias.grad

更新权重

learning_rate = 0.01
net.parameters.each do |f|
  f.data.sub!(f.grad.data * learning_rate)
end

使用优化器

optimizer = Torch::Optim::SGD.new(net.parameters, lr: 0.01)
optimizer.zero_grad
output = net.call(input)
loss = criterion.call(output, target)
loss.backward
optimizer.step

保存和加载模型

保存模型

Torch.save(net.state_dict, "net.pth")

加载模型

net = MyNet.new
net.load_state_dict(Torch.load("net.pth"))
net.eval

当从 Python 保存模型以便在 Ruby 中加载时，由于 LibTorch 中存在未修复的 bug，需要将参数转换为张量：

state_dict = {k: v.data if isinstance(v, torch.nn.Parameter) else v for k, v in state_dict.items()}
torch.save(state_dict, "net.pth")

张量创建

以下是用于创建张量的函数列表（描述来自 C++ 文档）：

• arange 返回一个包含整数序列的张量

  Torch.arange(3) # tensor([0, 1, 2])
  

• empty 返回一个未初始化值的张量

  Torch.empty(3) # tensor([7.0054e-45, 0.0000e+00, 0.0000e+00])
  

• eye 返回一个单位矩阵

  Torch.eye(2) # tensor([[1, 0], [0, 1]])
  

• full 返回一个由单一值填充的张量

  Torch.full([3], 5) # tensor([5, 5, 5])
  

• linspace 返回一个在某个区间内线性等距分布的张量

  Torch.linspace(0, 10, 5) # tensor([0, 5, 10])
  

• logspace 返回一个在某个区间内对数等距分布的张量

  Torch.logspace(0, 10, 5) # tensor([1, 1e5, 1e10])
  

• ones 返回一个全为 1 的张量

  Torch.ones(3) # tensor([1, 1, 1])
  

• rand 返回一个由 [0, 1) 区间内的均匀分布随机数填充的张量

  Torch.rand(3) # tensor([0.5444, 0.8799, 0.5571])
  

• randint 返回一个由指定区间内的随机整数组成的张量

  Torch.randint(1, 10, [3]) # tensor([7, 6, 4])
  

• randn 返回一个由标准正态分布随机数填充的张量

  Torch.randn(3) # tensor([-0.7147,  0.6614,  1.1453])
  

• randperm 返回一个由指定区间内整数的随机排列组成的张量

  Torch.randperm(3) # tensor([2, 0, 1])
  

• zeros 返回一个全为 0 的张量

  Torch.zeros(3) # tensor([0, 0, 0])
  

LibTorch 兼容性

以下是兼容版本列表。

Torch.rb	LibTorch
0.24.x	2.11.x
0.23.x	2.10.x
0.22.x	2.9.x
0.21.x	2.8.x
0.20.x	2.7.x
0.19.x	2.6.x
0.18.x	2.5.x

性能

深度学习在 GPU 上运行时速度显著更快。

Linux

在 Linux 系统上，安装 CUDA 和 cuDNN，然后重新安装 gem。

检查 CUDA 是否可用：

Torch::CUDA.available?

将神经网络移动到 GPU：

net.cuda

如果您没有支持 CUDA 的 GPU，建议使用云服务。Paperspace 提供了一个非常好的免费方案。我们已经准备了一个 Docker 镜像，方便您快速入门。在 Paperspace 上，创建一个自定义容器的笔记本。在高级选项中，将容器名称设置为：

ankane/ml-stack:torch-gpu

并保持该部分的其他字段为空。笔记本启动后，您可以运行 MNIST 示例。

Mac

对于搭载 Apple 芯片的 Mac，检查 Metal Performance Shaders (MPS) 是否可用：

Torch::Backends::MPS.available?

将神经网络移动到 GPU：

device = Torch.device("mps")
net.to(device)

历史

查看 变更日志

贡献

我们鼓励所有人帮助改进这个项目。以下是一些您可以参与的方式：

• 报告问题
• 修复问题并 提交拉取请求
• 编写、澄清或修正文档
• 提出或添加新功能

要开始开发：

git clone https://github.com/ankane/torch.rb.git
cd torch.rb
bundle install
bundle exec rake compile -- --with-torch-dir=/path/to/libtorch
bundle exec rake test

您可以使用 此脚本 在 AWS Deep Learning Base AMI（Ubuntu 18.04）上的 GPU 上进行测试。

以下是一些对贡献者有帮助的资源：

• PyTorch API
• PyTorch C++ API
• 张量创建 API
• 使用 PyTorch C++ 前端

Torch.rb 快速上手指南

Torch.rb 是一个基于 LibTorch 的 Ruby 深度学习库，让 Ruby 开发者能够直接使用 PyTorch 的强大功能。

环境准备

系统要求

• 操作系统：Linux (x86-64) 或 macOS (arm64/x86_64)
• 不支持：Windows
• Ruby 版本：需安装 Ruby 及 Bundler

前置依赖

在使用 gem 之前，必须先下载并配置 LibTorch。

1. macOS (Apple Silicon arm64)

   curl -L https://download.pytorch.org/libtorch/cpu/libtorch-macos-arm64-2.10.0.zip > libtorch.zip
   unzip -q libtorch.zip
   

2. Linux (x86-64) 请访问 PyTorch 官网 下载与你的 CUDA 版本匹配的 LibTorch 包。 注：若无合适预编译包，需从源码构建 LibTorch。

3. GPU 加速（可选）

   • Linux: 需安装 CUDA 和 cuDNN。
   • macOS (Apple Silicon): 支持 MPS (Metal Performance Shaders) 后端。

安装步骤

1. 配置编译路径 将 /path/to/libtorch 替换为你实际解压 LibTorch 的目录路径：

   bundle config set build.torch-rb --with-torch-dir=/path/to/libtorch
   

2. 添加依赖 在项目的 Gemfile 中添加：

   gem "torch-rb"
   

3. 安装 Gem 运行以下命令进行安装（首次编译扩展可能需要 5-10 分钟）：

   bundle install
   

基本使用

Torch.rb 的 API 设计高度遵循 PyTorch，但做了一些符合 Ruby 习惯的调整（如原地操作符以 ! 结尾）。

1. 创建张量 (Tensors)

require 'torch'

# 从 Ruby 数组创建张量
x = Torch.tensor([[1, 2, 3], [4, 5, 6]])

# 获取形状
puts x.shape # => [2, 3]

# 创建随机张量
a = Torch.rand(3)
b = Torch.zeros(2, 3)

2. 基本运算

x = Torch.tensor([10, 20, 30])

# 加减乘除
puts x + 5       # tensor([15, 25, 35])
puts x * 5       # tensor([50, 100, 150])

# 原地操作 (注意末尾的 !)
x.add!(5)
puts x           # tensor([15, 25, 35])

# 与其他张量运算
y = Torch.tensor([1, 2, 3])
puts x + y       # tensor([16, 27, 38])

3. 自动求导 (Autograd)

# 创建需要梯度的张量
x = Torch.ones(2, 2, requires_grad: true)

# 构建计算图
y = x + 2
z = y * y * 3
out = z.mean

# 反向传播
out.backward

# 获取梯度
puts x.grad 
# => tensor([[4.5, 4.5], [4.5, 4.5]])

4. 定义神经网络

class MyNet < Torch::NN::Module
  def initialize
    super()
    @fc1 = Torch::NN::Linear.new(10, 5)
    @fc2 = Torch::NN::Linear.new(5, 2)
  end

  def forward(x)
    x = Torch::NN::F.relu(@fc1.call(x))
    @fc2.call(x)
  end
end

# 实例化并使用
net = MyNet.new
input = Torch.randn(1, 10)
output = net.call(input)

# 获取参数
params = net.parameters

5. 训练循环示例

criterion = Torch::NN::MSELoss.new
optimizer = Torch::Optim::SGD.new(net.parameters, lr: 0.01)

# 模拟一次迭代
optimizer.zero_grad
output = net.call(input)
target = Torch.randn(1, 2)
loss = criterion.call(output, target)
loss.backward
optimizer.step

6. GPU 加速

# Linux (CUDA)
if Torch::CUDA.available?
  net.cuda
end

# macOS (MPS)
if Torch::Backends::MPS.available?
  device = Torch.device("mps")
  net.to(device)
end