Eps

适用于 Ruby 的机器学习

• 快速且轻松地构建预测模型
• 提供由 Ruby、Python、R 等语言构建的模型服务

请查看这篇博文，了解更多关于在 Rails 中使用机器学习的信息。

安装

将以下行添加到您的应用程序的 Gemfile 中：

gem "eps"

在 Mac 上，还需要安装 OpenMP：

brew install libomp

入门

创建一个模型

data = [
  {bedrooms: 1, bathrooms: 1, price: 100000},
  {bedrooms: 2, bathrooms: 1, price: 125000},
  {bedrooms: 2, bathrooms: 2, price: 135000},
  {bedrooms: 3, bathrooms: 2, price: 162000}
]
model = Eps::Model.new(data, target: :price)
puts model.summary

进行预测

model.predict(bedrooms: 2, bathrooms: 1)

存储模型

File.write("model.pmml", model.to_pmml)

加载模型

pmml = File.read("model.pmml")
model = Eps::Model.load_pmml(pmml)

几点说明：

• 目标可以是数值型（回归）或分类型（分类）
• 向 predict 方法传递哈希数组，可同时进行多次预测
• 模型以 PMML 格式存储，这是一种用于模型存储的标准

构建模型

目标

通常，构建模型的目标是在未来数据上做出准确的预测。为此，Eps 在数据点达到 30 个及以上时，会将数据拆分为训练集和验证集。它使用训练集来构建模型，并用验证集来评估模型性能。

如果您的数据带有时间信息，强烈建议使用该字段来进行拆分。

Eps::Model.new(data，target: :price，split: :listed_at)

否则，拆分会随机进行。此外还有许多其他选项可供选择。

性能会在摘要中报告：

• 对于回归问题，会报告验证 RMSE（均方根误差），值越低越好
• 对于分类问题，会报告验证准确率，值越高越好

通常，提升模型性能的最佳方法是特征工程。

特征工程

特征对模型性能至关重要。特征可以是：

1. 数值型
2. 分类型
3. 文本型

数值型

对于数值型特征，可以使用任何数值类型。

{bedrooms: 4, bathrooms: 2.5}

分类型

对于分类型特征，可以使用字符串或布尔值。

{state: "CA", basement: true}

将所有 ID 转换为字符串，以便将其视为分类特征。

{city_id: city_id.to_s}

对于日期，可以创建诸如星期几和月份之类的特征。

{weekday: sold_on.strftime("%a"), month: sold_on.strftime("%b")}

对于时间，可以创建诸如星期几和一天中的小时之类的特征。

{weekday: listed_at.strftime("%a"), hour: listed_at.hour.to_s}

文本型

对于文本特征，可以使用包含多个单词的字符串。

{description: "a beautiful house on top of a hill"}

这会基于词袋模型创建特征。

您可以显式指定文本特征：

Eps::Model.new(data, target: :price，text_features: [:description])

您还可以设置高级选项：

text_features: {
  description: {
    min_occurrences: 5,         # 单词至少出现多少次才会被纳入模型
    max_features: 1000,         # 模型中最多包含多少个单词
    min_length: 1,              # 要包含的单词的最小长度
    case_sensitive: true,       # 如何处理大小写不同的单词
    tokenizer: /\s+/,           # 如何对文本进行分词，默认为空格
    stop_words: ["and", "the"]  # 排除在模型之外的单词
  }
}

完整示例

我们建议将所有模型代码放在一个文件中，这样可以根据需要轻松重建模型。

在 Rails 中，我们建议创建一个 app/ml_models 目录。创建该目录后，请务必重启 Spring，以便自动加载文件。

bin/spring stop

以下是一个完整的模型示例，位于 app/ml_models/price_model.rb 中：

class PriceModel < Eps::Base
  def build
    houses = House.all

    # 训练
    data = houses.map { |v| features(v) }
    model = Eps::Model.new(data, target: :price，split: :listed_at)
    puts model.summary

    # 保存到文件
    File.write(model_file，model.to_pmml)

    # 确保从文件重新加载
    @model = nil
  end

  def predict(house)
    model.predict(features(house))
  end

  private

  def features(house)
    {
      bedrooms: house.bedrooms，
      city_id: house.city_id.to_s，
      month: house.listed_at.strftime("%b")，
      listed_at: house.listed_at，
      price: house.price
    }
  end

  def model
    @model ||= Eps::Model.load_pmml(File.read(model_file))
  end

  def model_file
    File.join(__dir__，"price_model.pmml")
  end
end

通过以下命令构建模型：

PriceModel.build

这会将模型保存到 price_model.pmml 文件中。您可以将其提交到版本控制系统，或使用像 Trove 这样的工具来存储它。

进行预测：

PriceModel.predict(house)

监控

我们建议监控模型随时间的表现。为此，可以将预测结果保存到数据库中，然后与实际值进行比较：

actual = houses.map(&:price)
predicted = houses.map(&:predicted_price)
Eps.metrics(actual，predicted)

对于 RMSE 和 MAE，如果它们超过某个阈值，则发出告警；对于 ME，如果其偏离 0 太远，则发出告警；对于准确率，如果低于某个阈值，则发出告警。

其他语言

Eps 使从其他语言提供模型服务变得容易。您可以使用 Python、R 等语言构建模型，并在 Ruby 中提供这些模型的服务，而无需担心如何部署或运行其他语言。

Eps 可以提供 LightGBM、线性回归和朴素贝叶斯模型。请查看 ONNX Runtime 和 Scoruby 来提供其他模型的服务。

Python

要在 Python 中创建模型，需安装 sklearn2pmml 包：

pip install sklearn2pmml

并查看以下示例：

• LightGBM 回归
• LightGBM 分类
• 线性回归
• 朴素贝叶斯

R

要在 R 中创建模型，需安装 pmml 包：

install.packages("pmml")

并查看以下示例：

• 线性回归
• 朴素贝叶斯

验证

在为使用其他语言创建的模型提供服务时，确保功能实现的一致性非常重要。我们强烈建议通过编程方式进行验证。创建一个包含原始模型生成的 ID 和预测值的 CSV 文件。

house_id	prediction
1	145000
2	123000
3	250000

当模型用 Ruby 实现后，确认预测结果是否匹配。

model = Eps::Model.load_pmml("model.pmml")

# 预加载房屋数据以防止 N+1 查询问题
houses = House.all.index_by(&:id)

CSV.foreach("predictions.csv", headers: true, converters: :numeric) do |row|
  house = houses[row["house_id"]]
  expected = row["prediction"]

  actual = model.predict(bedrooms: house.bedrooms, bathrooms: house.bathrooms)

  success = actual.is_a?(String) ? actual == expected : (actual - expected).abs < 0.001
  raise "房屋 #{house.id} 的预测结果错误（预期：#{expected}, 实际：#{actual})" unless success

  putc "✓"
end

数据

支持多种数据格式。您可以单独传递目标变量。

x = [{x: 1}, {x: 2}, {x: 3}]
y = [1, 2, 3]
Eps::Model.new(x, y)

数据可以是数组的数组：

x = [[1, 2], [2, 0], [3, 1]]
y = [1, 2, 3]
Eps::Model.new(x, y)

或者 Numo 数组：

x = Numo::NArray.cast([[1, 2], [2, 0], [3, 1]])
y = Numo::NArray.cast([1, 2, 3])
Eps::Model.new(x, y)

也可以是 Rover 数据框：

df = Rover.read_csv("houses.csv")
Eps::Model.new(df, target: "price")

直接读取 CSV 文件时，请务必转换数值字段。table 方法会自动完成此操作。

CSV.table("data.csv").map { |row| row.to_h }

算法

可以通过以下方式传入算法：

Eps::Model.new(data, algorithm: :linear_regression)

Eps 支持以下算法：

• LightGBM（默认）
• 线性回归
• 朴素贝叶斯

LightGBM

可以通过以下方式传入学习率：

Eps::Model.new(data, learning_rate: 0.01)

线性回归

默认情况下会包含截距项。如果需要禁用截距项，可以这样设置：

Eps::Model.new(data, intercept: false)

为了加快大型数据集上线性回归的训练速度，可以安装 GSL（参见：https://github.com/ankane/gslr#gsl-installation）。使用 Homebrew 时，可以运行以下命令：

brew install gsl

然后在应用程序的 Gemfile 中添加一行：

gem "gslr", group: :development

该 gem 只需在用于构建模型的环境中可用即可。

概率

对于分类预测，若需获取每个类别的概率，可以使用以下方法：

model.predict_probability(data)

需要注意的是，朴素贝叶斯算法通常会产生较差的概率估计，因此如果需要准确的概率值，建议使用 LightGBM。

验证选项

可以通过以下方式传入自定义的验证集：

Eps::Model.new(data, validation_set: validation_set)

按特定值分割数据集：

Eps::Model.new(data, split: {column: :listed_at, value: Date.parse("2025-01-01")})

指定验证集的比例（默认为 25%，即 0.25）：

Eps::Model.new(data, split: {validation_size: 0.2})

完全禁用验证集：

Eps::Model.new(data, split: false)

数据库存储

数据库是另一种存储模型的方式。如果您需要自动重新训练模型，这种方式非常合适。

我们建议在自动重新训练的情况下，同时添加监控和防护机制。

创建一个 Active Record 模型来存储预测模型：

rails generate model Model key:string:uniq data:text

使用以下代码存储模型：

store = Model.where(key: "price").first_or_initialize
store.update(data: model.to_pmml)

加载模型时，可以使用以下代码：

data = Model.find_by!(key: "price").data
model = Eps::Model.load_pmml(data)

Jupyter & IRuby

您可以使用 IRuby 在 Jupyter 笔记本中运行 Eps。以下是将 IRuby 与 Rails 集成的方法：Jupyter 与 Rails 的集成指南。

权重

可以为每个数据点指定权重：

Eps::Model.new(data, weight: :weight)

也可以传入一个数组：

Eps::Model.new(data, weight: [1, 2, 3])

权重同样适用于评估指标：

Eps.metrics(actual, predicted, weight: weight)

重新加权是缓解训练数据中偏见的一种方法（参见：https://fairlearn.org/）。

历史

查看 变更日志。

贡献

我们鼓励所有人参与改进该项目。以下是一些您可以贡献的方式：

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

开始开发之前，请执行以下步骤：

git clone https://github.com/ankane/eps.git
cd eps
bundle install
bundle exec rake test

Eps 快速上手指南

Eps 是一个专为 Ruby 设计的机器学习库，支持快速构建预测模型，并能无缝加载由 Python、R 等语言训练并导出为 PMML 格式的模型。

环境准备

• 系统要求：macOS、Linux 或 Windows（需配置 Ruby 开发环境）
• Ruby 版本：建议 Ruby 2.7+
• 前置依赖：
  • macOS 用户需安装 OpenMP 库以支持并行计算：

    brew install libomp
    

  • （可选）若使用线性回归处理大规模数据，建议安装 GSL：

    brew install gsl
    

    并在 Gemfile 中添加：

    gem "gslr", group: :development
    

注：国内用户可使用清华或中科大镜像加速 Homebrew 或 gem 源，例如：

gem sources --add https://mirrors.tuna.tsinghua.edu.cn/rubygems/
gem sources --remove https://rubygems.org/

安装步骤

1. 在项目的 Gemfile 中添加：

   gem "eps"
   

2. 执行安装命令：

   bundle install
   

基本使用

1. 创建模型

准备训练数据（数组哈希格式），指定目标字段（如 :price）：

data = [
  {bedrooms: 1, bathrooms: 1, price: 100000},
  {bedrooms: 2, bathrooms: 1, price: 125000},
  {bedrooms: 2, bathrooms: 2, price: 135000},
  {bedrooms: 3, bathrooms: 2, price: 162000}
]

model = Eps::Model.new(data, target: :price)
puts model.summary

2. 进行预测

传入新数据即可获取预测结果：

prediction = model.predict(bedrooms: 2, bathrooms: 1)
puts prediction

3. 保存与加载模型

模型默认以标准 PMML 格式存储，便于跨语言复用：

# 保存模型
File.write("model.pmml", model.to_pmml)

# 加载模型
pmml = File.read("model.pmml")
loaded_model = Eps::Model.load_pmml(pmml)

提示：目标字段可以是数值型（回归任务）或类别型（分类任务）。如需批量预测，可向 predict 传入哈希数组。