TensorStream

TensorStream 是一个面向 Ruby 的开源机器学习框架，旨在让机器学习模型的构建和在不同硬件（如 GPU 和 CPU）上的运行变得更加简单。它深度借鉴了 TensorFlow 的设计理念，目标是能够轻松移植其高层库和模型示例。因此，TensorStream 也基于数据流图，通过定义计算及其之间的数据流动来实现预期的输出。

TensorStream 设计为支持多种后端，包括纯 Ruby 实现和 OpenCL 实现。这些实现可以协同工作：你可以在具有 GPU 的 OpenCL 后端上进行训练，然后将训练好的模型部署到任何可以运行 Ruby 的环境中，使用纯 Ruby 后端执行推理。TensorStream 已经在大多数 Ruby 实现上进行了测试，例如 MRI、JRuby 和 TruffleRuby。

目标与特性

• 易于使用 - 提升模型的可读性
• 复刻了 TensorFlow 中常用的大部分低层操作（tf.add、tf.constant、tf.placeholder、tf.matmul、tf.sin 等）
• 支持基于形式导数的自动微分
• 可扩展 - 使用自定义的运算符求值器（目前支持 OpenCL 和纯 Ruby）
• 广泛兼容 - 可在大多数 Ruby 实现上运行，并在支持 OpenCL 的硬件上实现加速

兼容性

TensorStream 默认提供了纯 Ruby 和 OpenCL 两种实现。纯 Ruby 实现已知可在大多数 Ruby 实现上运行，包括 TruffleRuby、JRuby 以及启用了 JIT 的 MRI 版本（Ruby 2.6.0）。

OpenCL 仅支持 MRI 版本的 Ruby。可以通过添加 OpenCL 求值器 gem 来启用（请确保系统已正确安装 OpenCL 驱动程序）：

gem 'tensor_stream-opencl'

然后（无需 Bundler）：

require 'tensor_stream/opencl'

对于深度学习和图像处理任务，OpenCL 几乎是必需的，因为即使使用最新版本的 Ruby 并启用 JIT 加速，Ruby 实现的速度仍然太慢。

TensorStream 使用的 OpenCL 内核位于 tensor_stream/lib/evaluator/opencl/kernels。这些内核不特定于任何设备，应能在任何支持 OpenCL 的设备上运行，包括 Intel 的 GPU 和 CPU，以及 NVIDIA 和 AMD 的 GPU。

安装

安装非常简单，无需折腾 Docker、Python、Clang 等工具，MRI 和 JRuby 均可开箱即用。

将以下行添加到你的应用 Gemfile 中：

gem 'tensor_stream'

然后执行：

$ bundle

或者直接安装：

$ gem install tensor_stream

使用

使用方式类似于 TensorFlow，只是采用了 Ruby 语法。此外，还对语法进行了优化，使其尽可能简洁。

线性回归示例：

require 'tensor_stream'

tf = TensorStream

learning_rate = 0.01
training_epochs = 1000
display_step = 50

train_x = [3.3, 4.4, 5.5, 6.71, 6.93, 4.168, 9.779, 6.182, 7.59, 2.167,
           7.042, 10.791, 5.313, 7.997, 5.654, 9.27, 3.1]

train_y = [1.7, 2.76, 2.09, 3.19, 1.694, 1.573, 3.366, 2.596, 2.53, 1.221,
           2.827, 3.465, 1.65, 2.904, 2.42, 2.94, 1.3]

n_samples = train_x.size

x_value = Float.placeholder
y_value = Float.placeholder

# 设置模型权重
weight = rand.t.var name: "weight"

bias = rand.t.var name: "bias"

# 构建线性模型
pred = x_value * weight + bias

# 均方误差
cost = ((pred - y_value)**2).reduce / (2 * n_samples)

# 其他优化器 --
#
# optimizer = TensorStream::Train::MomentumOptimizer.new(learning_rate, momentum, use_nesterov: true).minimize(cost)
# optimizer = TensorStream::Train::AdamOptimizer.new(learning_rate).minimize(cost)
# optimizer = TensorStream::Train::AdadeltaOptimizer.new(1.0).minimize(cost)
# optimizer = TensorStream::Train::AdagradOptimizer.new(0.01).minimize(cost)
# optimizer = TensorStream::Train::RMSPropOptimizer.new(0.01, centered: true).minimize(cost)
optimizer = TensorStream::Train::GradientDescentOptimizer.new(learning_rate).minimize(cost)

# 初始化变量（即为其设置默认值）
init = tf.global_variables_initializer

tf.session do |sess|
  start_time = Time.now
  sess.run(init)

  (0..training_epochs).each do |epoch|
    train_x.zip(train_y).each do |x, y|
      sess.run(optimizer, feed_dict: { x_value => x, y_value => y })
    end

    if (epoch + 1) % display_step == 0
      c = sess.run(cost, feed_dict: { x_value => train_x, y_value => train_y })
      puts("Epoch:", '%04d' % (epoch + 1), "cost=", c, \
           "W=", sess.run(weight), "b=", sess.run(bias))
    end
  end

  puts "Optimization Finished!"
  training_cost = sess.run(cost, feed_dict: { x_value => train_x, y_value => train_y })
  puts "Training cost=", training_cost, "W=", sess.run(weight), "b=", sess.run(bias), '\n'
  puts "time elapsed ", Time.now.to_i - start_time.to_i
end

你可以在 spec/tensor_stream/operation_spec.rb 中查看支持的操作列表以及各种示例和测试用例。当然，这些内容只是 TensorFlow 能力的一小部分，欢迎提交 PR 添加所需的操作和测试用例。

其他可用的示例也可以在 tensor_stream/samples 中找到。

用于开发且仍在调试中的示例则位于 test_samples 目录下。

Python 到 Ruby 指南

并非所有操作都可用。可用的操作定义在 lib/tensor_stream/ops.rb 中，对应的梯度则位于 lib/tensor_stream/math_gradients。

命名规范和命名参数方面也有一些差异：

变量与常量

为了更方便参考 Python 示例，建议将 TensorStream 的命名空间设为 “tf”。

在开头：

tf = TensorStream # 推荐使用 tf，因为网络上的大多数示例模型都使用这个命名空间
ts = TensorStream # 如果你只打算使用 TensorStream 的特定功能，可以使用 ts，以便其他开发者了解你的意图

注意命名参数和可选参数的区别：

Python

w = ts.Variable(0, name='weights')
w = ts.Variable(0, 'weights')

Ruby

w = ts.variable(0, name: 'weights')
c = ts.constant(1.0)

# 使用常量初始化时的简洁写法
w = 0.t.var name: 'weights'
c = 1.0.t

对 Integer、Array 和 Float 类型调用 .t 方法会将其转换为张量。

形状

Python

x = tf.placeholder(tf.float32, shape=(1024, 1024))
x = tf.placeholder(tf.float32, shape=(None, 1024))

Ruby 支持使用符号来指定数据类型，nil 可以用于表示 None。

Ruby

x = ts.placeholder(:float32, shape: [1024, 1024])
x = ts.placeholder(:float32, shape: [nil, 1024])

# 另一种更简洁的方式
x = Float.placeholder shape: [1024, 1024]
y = Float.placeholder shape: [nil, 1024]

为了调试，每个操作或张量都支持 to_math 方法。

X = ts.placeholder("float")
Y = ts.placeholder("float")
W = ts.variable(rand, name: "weight")
b = ts.variable(rand, name: "bias")
pred = X * W + b
cost = ts.reduce_sum(ts.pow(pred - Y, 2)) / ( 2 * 10)
cost.to_math # "(reduce_sum(|((((Placeholder: * weight) + bias) - Placeholder_2:)^2)|) / 20.0)"

还可以设置断点，块会在计算过程中被评估。

a = ts.constant([2,2])
b = ts.constant([3,3])

f = ts.matmul(a, b).breakpoint! { |tensor, a, b, result_value| binding.pry }

ts.session.run(f)

OpenCL

要使用 OpenCL 支持，请确保您的硬件已正确安装所需的 OpenCL 驱动程序。此外，目前 OpenCL 仅支持 Ruby MRI。

要使用，只需在项目中包含以下 gem：

gem 'tensor_stream-opencl'

要使用 OpenCL 求解器而不是 Ruby 求解器，只需将其引入即可（如果使用 Rails，它应该会自动加载）。

require 'tensor_stream/opencl'

添加 OpenCL 求解器后，TensorStream 将会显示额外的可用设备。

ts.list_local_devices
# ["job:localhost/ts:ruby:cpu", "job:localhost/ts:opencl:apple:0", "job:localhost/ts:opencl:apple:1"]

这里我们看到 1 个 “ruby” CPU 设备和 2 个 OpenCL “apple” 设备（Intel CPU、Intel Iris GPU）。

默认情况下，TensorStream 会根据给定的求解器为每个张量操作选择最佳的执行位置。

require 'tensor_stream/opencl'

# 设置会话使用 OpenCL 求解器
sess = ts.session

sess.run(....) # 执行一些操作

您也可以手动使用 ts.device 来放置操作，例如：

ts = TensorStream
# 创建一个图，并将其放置在第一个 OpenCL CPU 设备上

a, b = ts.device('/cpu:0') do
  a = ts.constant([1.0, 2.0, 3.0, 4.0, 5.0, 6.0], shape: [2, 3], name: 'a')
  b = ts.constant([1.0, 2.0, 3.0, 4.0, 5.0, 6.0], shape: [3, 2], name: 'b')
  [a, b]
end

c = ts.device('/device:GPU:0') do
  ts.matmul(a, b)
end

# 创建一个启用 log_device_placement 的会话。
sess = ts.session(log_device_placement: true)
# 运行该操作。
print(sess.run(c))

# a : apple:0
# b : apple:0
# a_1 : apple:0
# b_1 : apple:0
# matmul:0 : apple:1
# [[22.0, 28.0], [49.0, 64.0]] => nil

即使加载了 OpenCL 求解器，如果您想强制使用 Ruby 求解器，可以这样做：

ts.device('/ts:ruby:cpu') do
    # 在这里放置操作
end

需要注意的是，OpenCL 求解器在处理大型张量时会带来速度提升，而对于只涉及标量的操作（如线性回归示例），实际上可能会更慢。

samples/nearest_neighbor.rb 包含一个使用 OpenCL 的示例。

OpenCL 支持作为独立项目维护在以下地址：

https://github.com/jedld/tensor_stream-opencl

从 TensorFlow 导出和导入模型

目前支持解析和导出 pbtext 文件的实验性功能：

导出

a = ts.constant([1.0, 1.0])
b = ts.constant([1.5, 1.5])
f = a + b

File.write('my_model.pbtext', f.graph.as_graph_def)

导入（实验性）

请注意，并非所有 TensorFlow 操作都受支持；如果某些操作尚未支持，将会显示警告。

  pbtext = File.read(File.join('linear_regression.pbtxt'))

  # 从 pbtext 文件创建图
  graph = TensorStream::Graph.parse_from_string(pbtext)

  # 通过名称引用图中的张量，例如有一个名为 out 的张量
  tensor = graph.get_tensor_by_name("out")

  # 将图设为默认图并在此基础上进行操作
  graph.as_default do
    sess = ts.session
    expect(tr(sess.run(tensor))).to eq([[1.0, 1.0], [1.0, 1.0]])
  end

可视化

TensorStream 目前还不支持 TensorBoard，但包含了一个 GraphML 生成器：

tf = TensorStream
a = tf.constant(1.0)
b = tf.constant(2.0)
result = a + b
sess = tf.session
sess.run(result)

File.write('gradients.graphml', TensorStream::Graphml.new.get_string(result)) # 只转储图
File.write('gradients.graphml', TensorStream::Graphml.new.get_string(result, sess)) # 同时转储会话中的值

生成的 GraphML 文件设计用于与 yED 配合使用。加载图后，将布局更改为“流程图”以获得最佳效果。

导出到 TensorFlow

目前仍处于 Alpha 阶段，但 TensorStream 支持 TensorFlow 的 as_graph_def 序列化方法：

tf = TensorStream
a = tf.constant(1.0)
b = tf.constant(2.0)
result = a + b
File.write("model.pbtext", result.graph.as_graph_def)

性能说明

与其他 Ruby 库相比，性能尚未进行比较。然而，值得注意的是，TruffleRuby 和 Ruby 2.6.0 在性能上明显优于之前的 Ruby 版本（< 2.6）。

使用 AMD(R) Ryzen(TM) 3 1300X CPU，在运行 samples/linear_regression.rb 样本时，TensorStream 1.0.0 的基准测试结果如下：

Ruby 2.5

$ ruby -v
ruby 2.5.1p57 (2018-03-29 revision 63029) [x86_64-linux]
$ ruby samples/linear_regression.rb
296 秒，3000 次迭代

Ruby 2.6.0

$ ruby -v
ruby 2.6.0p0 (2018-12-25 revision 66547) [x86_64-linux]
$ ruby samples/linear_regression.rb
232 秒，10000 次迭代

ruby --jit samples/linear_regression.rb
222 秒，10000 次迭代

Truffleruby

$ ruby -v
truffleruby 1.0.0-rc10，类似 ruby 2.4.4，GraalVM CE Native [x86_64-linux]
246 秒，10000 次迭代

JRuby

$ ruby -v
jruby 9.2.0.0 (2.5.0) 2018-05-24 81156a8 OpenJDK 64-Bit Server VM 25.191-b12 on 1.8.0_191-8u191-b12-0ubuntu0.18.04.1-b12 +jit [linux-x86_64]
205 秒，10000 次迭代

对于基于图像的大型网络训练，OpenCL 求解器是唯一可行的选择。

路线图

• 文档
• 完整的低级操作支持
• SciRuby 求解器
• OpenCL 求解器
• TensorFlow savemodel 兼容性

问题

• 这是一个早期预览版本，许多功能仍未完善。
• 性能尚不理想，至少在 OpenCL 和/或 SciRuby 后端完成之前是如此。
• 不过，如果您确实需要某个操作的支持，请随时提交包含相应失败测试的拉取请求（参见 spec/operation_spec.rb）。

开发

检出仓库后，运行 bin/setup 安装依赖。然后，运行 rake spec 来执行测试。你还可以运行 bin/console 启动一个交互式提示符，以便进行实验。

要将此 gem 安装到本地机器上，请运行 bundle exec rake install。要发布新版本，先更新 version.rb 中的版本号，然后运行 bundle exec rake release，它会为该版本创建一个 Git 标签，推送 Git 提交和标签，并将 .gem 文件发布到 rubygems.org。

贡献

欢迎在 GitHub 上通过 https://github.com/[USERNAME]/tensor_stream 提交 bug 报告和拉取请求。本项目旨在成为一个安全、友好的协作空间，贡献者应遵守 Contributor Covenant 行为准则。

许可证

该 gem 以开源形式提供，遵循 MIT 许可证 的条款。

TensorStream 快速上手指南

TensorStream 是一个专为 Ruby 设计的开源机器学习框架。它基于数据流图理念，语法高度兼容 TensorFlow，支持纯 Ruby 和 OpenCL 后端。你可以利用 GPU 进行模型训练，并将训练好的模型部署到任何支持 Ruby 的环境中运行。

环境准备

系统要求

• Ruby 版本：支持 MRI (推荐 2.6.0+)、JRuby 和 TruffleRuby。
• 操作系统：Linux, macOS, Windows。

前置依赖

• 基础模式（CPU）：无需额外依赖，安装 Ruby 即可。
• 加速模式（GPU/OpenCL）：
  • 仅支持 MRI Ruby。
  • 必须正确安装对应硬件的 OpenCL 驱动程序（支持 Intel CPU/GPU, Nvidia GPU, AMD GPU）。
  • 需安装 tensor_stream-opencl gem。

安装步骤

1. 安装核心库

将以下行添加到项目的 Gemfile 中：

gem 'tensor_stream'

然后执行安装命令：

bundle

或者直接使用 gem 安装：

gem install tensor_stream

2. （可选）安装 OpenCL 加速支持

如果你需要使用 GPU 加速或处理深度学习任务，请额外安装 OpenCL 扩展：

# 在 Gemfile 中添加
gem 'tensor_stream-opencl'

执行安装：

bundle

注意：国内开发者若遇到 gem 源下载缓慢，可临时切换至国内镜像源：

gem sources --add https://gems.ruby-china.com/ --remove https://rubygems.org/
gem sources -l # 确认列表只有 ruby-china 源

基本使用

TensorStream 的用法与 TensorFlow 类似，但采用 Ruby 语法风格。以下是一个完整的线性回归示例，展示了如何定义占位符、变量、构建计算图、选择优化器并执行训练。

require 'tensor_stream'

# 推荐使用 tf 作为命名空间，以便参考 Python 版 TensorFlow 文档
tf = TensorStream

learning_rate = 0.01
training_epochs = 1000
display_step = 50

# 训练数据
train_x = [3.3, 4.4, 5.5, 6.71, 6.93, 4.168, 9.779, 6.182, 7.59, 2.167,
           7.042, 10.791, 5.313, 7.997, 5.654, 9.27, 3.1]

train_y = [1.7, 2.76, 2.09, 3.19, 1.694, 1.573, 3.366, 2.596, 2.53, 1.221,
           2.827, 3.465, 1.65, 2.904, 2.42, 2.94, 1.3]

n_samples = train_x.size

# 定义占位符 (Placeholder)
x_value = Float.placeholder
y_value = Float.placeholder

# 定义模型权重和偏置 (Variables)
weight = rand.t.var name: "weight"
bias = rand.t.var name: "bias"

# 构建线性模型: pred = x * weight + bias
pred = x_value * weight + bias

# 定义损失函数：均方误差 (Mean Squared Error)
cost = ((pred - y_value)**2).reduce / (2 * n_samples)

# 定义优化器 (梯度下降)
optimizer = TensorStream::Train::GradientDescentOptimizer.new(learning_rate).minimize(cost)

# 初始化变量
init = tf.global_variables_initializer

# 创建会话并运行
tf.session do |sess|
  start_time = Time.now
  sess.run(init)

  (0..training_epochs).each do |epoch|
    # 逐个样本进行训练
    train_x.zip(train_y).each do |x, y|
      sess.run(optimizer, feed_dict: { x_value => x, y_value => y })
    end

    # 每隔一定步数打印日志
    if (epoch + 1) % display_step == 0
      c = sess.run(cost, feed_dict: { x_value => train_x, y_value => train_y })
      puts("Epoch:", '%04d' % (epoch + 1), "cost=", c, \
           "W=", sess.run(weight), "b=", sess.run(bias))
    end
  end

  puts "Optimization Finished!"
  training_cost = sess.run(cost, feed_dict: { x_value => train_x, y_value => train_y })
  puts "Training cost=", training_cost, "W=", sess.run(weight), "b=", sess.run(bias)
  puts "time elapsed ", Time.now.to_i - start_time.to_i
end

启用 OpenCL 加速

若已安装 tensor_stream-opencl，只需在代码开头引入即可自动启用 GPU 加速（针对大张量运算）：

require 'tensor_stream/opencl'

# 查看可用设备
puts TensorStream.list_local_devices
# 输出示例：["job:localhost/ts:ruby:cpu", "job:localhost/ts:opencl:apple:0"]

# 后续代码无需修改，框架会自动将合适的操作调度到 OpenCL 设备
ts = TensorStream
sess = ts.session
# ... 执行训练或推理 ...