sklearn-porter

将训练好的 scikit-learn 估计器转译为 C、Java、JavaScript 等语言。
推荐用于资源受限的嵌入式系统以及对性能要求极高的关键应用。

导航： 估计器 • 安装 • 使用 • 已知问题 • 开发 • 引用 • 许可证

估算器

此表格概述了所有受支持的估算器、编程语言和模板的组合。

✓✓×✓✓×✓✓×✓✓×✓✓×

	编程语言
	C			Go			Java			JS			PHP			Ruby
svm.SVC	✓		×	✓	✓	×	✓	✓	×	✓	✓	×	✓	✓	×	✓	✓	×
svm.NuSVC	✓		×	✓	✓	×	✓	✓	×	✓	✓	×	✓	✓	×	✓	✓	×
svm.LinearSVC	✓		×	✓	✓	×	✓	✓	×	✓	✓	×	✓	✓	×	✓	✓	×
tree.DecisionTreeClassifier	✓ᴾ		✓ᴾ	✓ᴾ	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓
ensemble.RandomForestClassifier				×	✓	×	×	✓	✓	✓	✓	✓	✓	✓	×
ensemble.ExtraTreesClassifier				×	✓	×	×	✓	✓	✓	✓	✓	✓	✓	×
ensemble.AdaBoostClassifier							×	✓	×	✓	✓	✓
neighbors.KNeighborsClassifier				✓	✓	×	✓	✓	×	✓	✓	×	✓	✓	×
naive_bayes.BernoulliNB							✓	✓	×	✓	✓	×
naive_bayes.GaussianNB
neural_network.MLPClassifier
neural_network.MLPRegressor
	ᴀ	ᴇ	ᴄ	ᴀ	ᴇ	ᴄ	ᴀ	ᴇ	ᴄ	ᴀ	ᴇ	ᴄ	ᴀ	ᴇ	ᴄ	ᴀ	ᴇ	ᴄ
	模板

✓ = 支持 predict，　ᴾ = 支持 predict_proba，　× = 不支持或不可行
ᴀ = 附带模型数据，　ᴇ = 导出模型数据（JSON），　ᴄ = 组合模型数据

安装

用途	版本	分支	构建状态	命令
生产环境	v0.7.4	stable		pip install sklearn-porter
开发环境	v1.0.0	main		pip install https://github.com/nok/sklearn-porter/zipball/main

在两种环境下，唯一的先决条件是 scikit-learn >= 0.17, <= 0.22。

使用方法

Binder

您可以通过启动 Binder 中的交互式笔记本自行尝试： 

基础用法

from sklearn.datasets import load_iris
from sklearn.tree import DecisionTreeClassifier

from sklearn_porter import port, save, make, test

# 1. 加载数据并训练一个示例分类器：
X, y = load_iris(return_X_y=True)
clf = DecisionTreeClassifier()
clf.fit(X, y)

# 2. 导出或转译模型：
output = port(clf, language='js', template='attached')
print(output)

# 3. 保存导出的模型：
src_path, json_path = save(clf, language='js', template='exported', directory='/tmp')
print(src_path, json_path)

# 4. 使用导出的模型进行预测：
y_classes, y_probas = make(clf, X[:10], language='js', template='exported')
print(y_classes, y_probas)

# 5. 始终通过完整性检查来测试导出的模型：
score = test(clf, X[:10], language='js', template='exported')
print(score)

面向对象编程

from sklearn.datasets import load_iris
from sklearn.tree import DecisionTreeClassifier

from sklearn_porter import Estimator

# 1. 加载数据并训练一个示例分类器：
X, y = load_iris(return_X_y=True)
clf = DecisionTreeClassifier()
clf.fit(X, y)

# 2. 导出或转译模型：
est = Estimator(clf, language='js', template='attached')
output = est.port()
print(output)

# 3. 保存导出的模型：
est.template = 'exported'
src_path, json_path = est.save(directory='/tmp')
print(src_path, json_path)

# 4. 使用导出的模型进行预测：
y_classes, y_probas = est.make(X[:10])
print(y_classes, y_probas)

# 5. 始终通过完整性检查来测试导出的模型：
score = est.test(X[:10])
print(score)

命令行工具

此外，您还可以在命令行中使用 sklearn-porter。安装完成后即可使用 porter 命令。

porter {show,port,save} [-h] [-v]

porter show [-l {c,go,java,js,php,ruby}] [-h]

porter port <estimator> [-l {c,go,java,js,php,ruby}]
                        [-t {attached,combined,exported}]
                        [--skip-warnings] [-h]

porter save <estimator> [-l {c,go,java,js,php,ruby}]
                        [-t {attached,combined,exported}]
                        [--directory DIRECTORY]
                        [--skip-warnings] [-h]

您可以序列化一个模型并将其本地保存。有关更多详细信息，请参阅 模型持久化 的说明。

from joblib import dump

dump(clf, 'estimator.joblib', compress=0)

之后，可以使用子命令 port 将模型转译：

porter port estimator.joblib -l js -t attached > estimator.js

为进一步处理，您可以将结果传递给其他应用程序，例如 UglifyJS。

porter port estimator.joblib -l js -t attached | uglifyjs --compress -o estimator.min.js

已知问题

• 在某些罕见情况下，支持向量机的回归测试，即 SVC 和 NuSVC，由于 scikit-learn>=0.22 而会失败。因此会引发 QualityWarning 警告，提醒您使用 test 方法评估结果。

开发

别名

以下命令可在日常开发中节省时间：

# 使用 conda 安装 Python 环境：
make setup

# 启动包含示例的 Jupyter 笔记本：
make notebook

# 在主机或独立的 Docker 容器中运行测试：
make tests
make tests-docker

# 使用 pylint 检查源代码：
make lint

# 使用 jupytext 生成笔记本：
make examples

# 使用 twine 部署新版本：
make deploy

依赖项

先决条件是 Python 3.6，您可以通过 conda 安装：

conda env create -n sklearn-porter_3.6 python=3.6
conda activate sklearn-porter_3.6

之后，您需要安装所有必需的包：

pip install --no-cache-dir -e ".[development,examples]"

环境

所有测试均在以下 scikit-learn 和 Python 版本的组合上运行：

		Python
		3.5	3.6	3.7	3.8
scikit-learn	0.17	cython 0.27.3	cython 0.27.3	scikit-learn 不支持	scikit-learn 不支持
		numpy 1.9.3	numpy 1.9.3
		scipy 0.16.0	scipy 0.16.0
	0.18	cython 0.27.3	cython 0.27.3	scikit-learn 不支持	scikit-learn 不支持
		numpy 1.9.3	numpy 1.9.3
		scipy 0.16.0	scipy 0.16.0
	0.19	cython 0.27.3	cython 0.27.3	scikit-learn 不支持	scikit-learn 不支持
		numpy 1.14.5	numpy 1.14.5
		scipy 1.1.0	scipy 1.1.0
	0.20	cython 0.27.3	cython 0.27.3	cython 0.27.3	joblib 不支持
		numpy	numpy	numpy
		scipy	scipy	scipy
	0.21	cython	cython	cython	cython
		numpy	numpy	numpy	numpy
		scipy	scipy	scipy	scipy
	0.22	cython	cython	cython	cython
		numpy	numpy	numpy	numpy
		scipy	scipy	scipy	scipy

对于回归测试，我们必须使用特定的编译器和解释器：

名称	来源	版本
GCC	https://gcc.gnu.org	10.2.1
Go	https://golang.org	1.15.15
Java (OpenJDK)	https://openjdk.java.net	1.8.0
Node.js	https://nodejs.org	12.22.5
PHP	https://www.php.net	7.4.28
Ruby	https://www.ruby-lang.org	2.7.4

请注意，通常情况下，您可以使用较旧的编译器和解释器来处理生成的源代码。例如，您可以使用 Java 1.6 来编译和运行模型。

日志记录

您可以通过更改 logging.level 选项来启用日志记录。

from sklearn_porter import options

from logging import DEBUG

options['logging.level'] = DEBUG

测试

您可以在本地机器（主机）或单独运行的 Docker 容器中运行单元测试和回归测试。

pytest tests -v \
  --cov=sklearn_porter \
  --disable-warnings \
  --numprocesses=auto \
  -p no:doctest \
  -o python_files="EstimatorTest.py" \
  -o python_functions="test_*"

docker build \
  -t sklearn-porter \
  --build-arg PYTHON_VER=${PYTHON_VER:-python=3.6} \
  --build-arg SKLEARN_VER=${SKLEARN_VER:-scikit-learn=0.21} \
  .

docker run \
  -v $(pwd):/home/abc/repo \
  --detach \
  --entrypoint=/bin/bash \
  --name test \
  -t sklearn-porter

docker exec -it test ./docker-entrypoint.sh \
  pytest tests -v \
    --cov=sklearn_porter \
    --disable-warnings \
    --numprocesses=auto \
    -p no:doctest \
    -o python_files="EstimatorTest.py" \
    -o python_functions="test_*"

docker rm -f $(docker ps --all --filter name=test -q)

引用

如果您在工作中使用了此实现，请添加对该论文的引用。您可以使用以下 BibTeX 条目：

@unpublished{sklearn_porter,
  author = {Darius Morawiec},
  title = {sklearn-porter},
  note = {将训练好的 scikit-learn 估计器转译为 C、Java、JavaScript 等},
  url = {https://github.com/nok/sklearn-porter}
}

许可证

该软件包是根据 BSD 3-Clause 许可证发布的开源软件。

sklearn-porter 快速上手指南

sklearn-porter 是一个将训练好的 scikit-learn 模型转译为 C、Java、JavaScript、Go、PHP 或 Ruby 代码的工具。它特别适用于资源受限的嵌入式系统或对性能要求极高的关键应用场景，让你能在非 Python 环境中直接运行机器学习模型。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：支持 Python 2.7 及 Python 3.x
• 核心依赖：
  • scikit-learn (版本要求：>= 0.17 且 <= 0.22)
  • joblib (用于模型序列化)

注意：由于该工具对 scikit-learn 版本有严格限制（最高支持到 0.22），建议在独立的虚拟环境中使用，以免与项目中其他需要新版 scikit-learn 的代码冲突。

安装步骤

1. 创建虚拟环境（推荐）

为了避免依赖冲突，建议先创建一个隔离环境并安装指定版本的 scikit-learn：

python -m venv skporter-env
source skporter-env/bin/activate  # Windows 用户请使用: skporter-env\Scripts\activate

# 安装兼容版本的 scikit-learn (国内用户可使用清华源加速)
pip install scikit-learn==0.22.0 -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 安装 sklearn-porter

生产环境推荐安装稳定版：

pip install sklearn-porter -i https://pypi.tuna.tsinghua.edu.cn/simple

若需体验最新开发版功能：

pip install https://github.com/nok/sklearn-porter/zipball/main

基本使用

以下示例演示如何将一个训练好的决策树模型转译为 JavaScript 代码，并进行预测验证。

1. 训练模型并转译代码

from sklearn.datasets import load_iris
from sklearn.tree import DecisionTreeClassifier
from sklearn_porter import port

# 1. 加载数据并训练模型
X, y = load_iris(return_X_y=True)
clf = DecisionTreeClassifier()
clf.fit(X, y)

# 2. 将模型转译为 JavaScript 代码 (模板模式：attached，即模型数据嵌入代码中)
js_code = port(clf, language='js', template='attached')

# 打印生成的代码，可保存为 .js 文件
print(js_code)

2. 保存模型文件（分离模式）

如果你希望将模型数据与逻辑代码分离（例如生成一个 .js 文件和一个 .json 数据文件）：

from sklearn_porter import save

# 保存为 exported 模式，生成源文件路径和 JSON 数据路径
src_path, json_path = save(clf, language='js', template='exported', directory='/tmp')
print(f"Source: {src_path}, Data: {json_path}")

3. 在 Python 中验证转译后的模型

sklearn-porter 提供了 make 和 test 方法，可以在不离开 Python 环境的情况下，调用生成的外部代码逻辑进行预测和完整性校验：

from sklearn_porter import make, test

# 使用前 10 条数据进行预测
y_classes, y_probas = make(clf, X[:10], language='js', template='attached')
print("预测类别:", y_classes)
print("预测概率:", y_probas)

# 进行完整性测试（对比原始模型与转译后模型的输出一致性）
score = test(clf, X[:10], language='js', template='attached')
print("一致性得分:", score)

4. 命令行使用 (CLI)

你也可以先将模型保存为本地文件，再通过命令行工具进行转译：

# 1. 在 Python 中保存模型
# from joblib import dump
# dump(clf, 'model.joblib')

# 2. 使用 porter 命令转译
porter port model.joblib -l js -t attached > model.js

# 3. 结合其他工具（如 UglifyJS）进行压缩
porter port model.joblib -l js -t attached | uglifyjs --compress -o model.min.js