API 摘要

scikit-onnx 中公开的公共函数和类的摘要。

版本

skl2onnx.get_latest_tested_opset_version()

此模块依赖 onnxruntime 来测试每个转换器。该函数返回使用 onnxruntime 测试的最新目标 opset，或者如果 onnx 包指定的 opset 版本较低（由 onnx.defs.onnx_opset_version() 返回）则返回该版本。

转换器

这两个函数都将 scikit-learn 模型转换为 ONNX。第一个函数允许用户手动定义输入的名称和类型。第二个函数从训练数据中推断这些信息。这两个函数是转换器的主要入口点。如果某个模型在此包中没有实现转换器，则需要其余的 API。然后必须注册一个新转换器，无论是从其他包导入的还是从头开始创建的。

skl2onnx.convert_sklearn(model, name=None, initial_types=None, doc_string='', target_opset=None, custom_conversion_functions=None, custom_shape_calculators=None, custom_parsers=None, options=None, intermediate=False, white_op=None, black_op=None, final_types=None, dtype=None, naming=None, model_optim=True, verbose=0)

此函数生成给定 scikit-learn 模型的等效 ONNX 模型。支持的转换器由函数 supported_converters 返回。

对于 pipeline 转换，用户需要确保每个组件都是我们支持的项目之一。此函数将指定的 scikit-learn 模型转换为其 ONNX 对等项。请注意，对于所有转换，都需要 initial types。ONNX 模型名称也可以指定。

参数:

• model – 一个 scikit-learn 模型

• initial_types – 一个 python 列表。每个元素都是一个元组，包含一个变量名和 data_types.py 中定义的类型

• name – 产生的 ONNX 模型（类型：ModelProto）中图（类型：GraphProto）的名称

• doc_string – 附加到产生的 ONNX 模型上的字符串

• target_opset – 数字，例如，ONNX 1.2 为 7，ONNX 1.3 为 8。如果未指定值，则函数将选择最新测试的 opset（请参阅 skl2onnx.get_latest_tested_opset_version()）

• custom_conversion_functions – 用于指定用户自定义转换函数的字典，它优先于注册的转换器

• custom_shape_calculators – 用于指定用户自定义形状计算器的字典，它优先于注册的形状计算器。

• custom_parsers – 解析器决定了特定任务的预期输出是什么，分类器、回归器、pipeline 的默认解析器已定义，但它们可以被重写，custom_parsers 是一个字典 { type: fct_parser(scope, model, inputs, custom_parsers=None) }

• options – 提供给转换器的特定选项（请参阅 带选项的转换器）

• intermediate – 如果为 True，则函数返回转换后的模型和使用的 Topology 实例，否则返回转换后的模型

• white_op – 转换 pipeline 时允许的 ONNX 节点白名单，如果为空，则允许所有节点

• black_op – 转换 pipeline 时允许的 ONNX 节点黑名单，如果为空，则不包含任何黑名单节点

• final_types – 一个 python 列表。其工作方式与 initial_types 相同，但不是强制性的，它用于覆盖每个输出的类型（如果类型不是 None）和名称。

• dtype – 在版本 1.7.5 中已移除，dtype 现在从输入类型推断，转换器可能会添加 Cast 操作符以在必要时切换到 double。

• naming – 用户可能想更改中间值的命名方式，此参数可以是一个字符串（前缀）或一个函数，其签名如下：get_name(name, existing_names)，然后库会检查此名称是否唯一，如果不是则会修改它。

• model_optim – 在模型转换为 onnx 后启用或禁用模型优化，它会减少 identity 节点的数量。

• verbose – 在转换模型时显示进度

返回:

一个 ONNX 模型（类型：ModelProto），它等效于输入的 scikit-learn 模型。

initial_types 的示例：假设指定的 scikit-learn 模型以异构列表作为输入。如果前 5 个元素是浮点数，最后 10 个元素是整数，我们需要如下指定 initial types。 [None, 5] 中的 [None] 表示批次大小未知。

from skl2onnx.common.data_types import FloatTensorType, Int64TensorType
initial_type = [('float_input', FloatTensorType([None, 5])),
                ('int64_input', Int64TensorType([None, 10]))]

注意

如果 pipeline 包含 ColumnTransformer 的实例，scikit-learn 允许用户按名称指定列。sklearn-onnx 不支持此选项，因为特征名称可能与输入数据和 ONNX 图（由参数 initial_types 定义）不同，只支持整数。

转换器选项

一些 ONNX 操作符公开了 sklearn-onnx 无法从原始模型推断的参数。通常会建议一些默认值，但用户可能需要手动覆盖它们。当模型包含在 pipeline 中时，这种需求并不明显。因此，这些选项可以作为字典 {model_type: parameters in a dictionary} 或 {model_id: parameters in a dictionary} 提供给 convert_sklearn 函数。选项 sep 用于在 ONNX 图需要对字符串进行分词时指定单词之间的分隔符。默认值很短，可能不包含所有必要的值。它可以被覆盖为

extra = {TfidfVectorizer: {"separators": [' ', '[.]', '\\?',
            ',', ';', ':', '\\!', '\\(', '\\)']}}
model_onnx = convert_sklearn(
    model, "tfidf",
    initial_types=[("input", StringTensorType([None, 1]))],
    options=extra)

但是，如果 pipeline 包含同一类的两个模型，则可以使用函数 id 来区分它们。

extra = {id(model): {"separators": [' ', '.', '\\?', ',', ';',
            ':', '\\!', '\\(', '\\)']}}
model_onnx = convert_sklearn(
    pipeline, "pipeline-with-2-tfidf",
    initial_types=[("input", StringTensorType([None, 1]))],
    options=extra)

它在示例 TfIdfVectorizer with ONNX 中使用。

已于 1.10.0 版本更改： 添加了参数 naming。

skl2onnx.to_onnx(model: BaseEstimator, X: array | None = None, name: str | None = None, initial_types: List[Tuple[str, Sequence[int | str | None]]] | None = None, target_opset: Dict[str, int] | int | None = None, options: Dict | None = None, white_op: Set[str] | None = None, black_op: Set[str] | None = None, final_types: List[Tuple[str, Sequence[int | str | None]]] | None = None, dtype: dtype | None = None, naming: Callable | None = None, model_optim: bool = True, verbose: int = 0)

调用 convert_sklearn() 并使用简化的参数。

参数:

• model – 要转换的模型

• X – 训练集，可以是 None，它用于推断输入类型（initial_types）

• initial_types – 如果 X 为 None，则必须定义 initial_types。

• target_opset – 使用特定的目标 opset 进行转换。

• options – 提供给转换器的特定选项（请参阅 带选项的转换器）

• name – 模型名称

• white_op – 转换 pipeline 时允许的 ONNX 节点白名单，如果为空，则允许所有节点

• black_op – 转换 pipeline 时允许的 ONNX 节点黑名单，如果为空，则不包含任何黑名单节点

• final_types – 一个 python 列表。其工作方式与 initial_types 相同，但不是强制性的，它用于覆盖每个输出的类型（如果类型不是 None）和名称。

• dtype – 在版本 1.7.5 中已移除，dtype 现在从输入类型推断，转换器可能会添加 Cast 操作符以在必要时切换到 double。

• naming – 用户可能想更改中间值的命名方式，此参数可以是一个字符串（前缀）或一个函数，其签名如下：get_name(name, existing_names)，然后库会检查此名称是否唯一，如果不是则会修改它。

• model_optim – 在模型转换为 onnx 后启用或禁用模型优化，它会减少 identity 节点的数量。

• verbose – 在转换模型时显示进度

返回:

转换后的模型

此函数检查模型是否继承自类 OnnxOperatorMixin，如果是则调用其 to_onnx 方法，否则调用 convert_sklearn()。

已于 1.18.0 版本更改： 主 opset 现在等于 target_opset，而不是小于或等于给定值的某个值。

日志记录

如果 pipeline 包含没有关联转换器的对象，则转换会失败。如果其中一个对象被自定义转换器映射，也可能失败。如果错误消息不够明确，可以启用日志记录。

import logging
logger = logging.getLogger('skl2onnx')
logger.setLevel(logging.DEBUG)

示例 Logging, verbose 说明了它的样子。

注册新转换器

如果某个模型在此包中没有实现转换器，则必须注册一个新转换器，无论是从其他包导入的还是从头创建的。第 Covered Converters 节列出了所有可用的转换器。

skl2onnx.supported_converters(from_sklearn=False)

返回支持的转换器列表。为了找到与特定模型关联的转换器，库会获取模型类的名称，添加 'Sklearn' 作为前缀，并检索关联的转换器（如果可用）。

参数:

from_sklearn – 每个支持的模型都通过以 'Sklearn' 为前缀的名称映射到转换器，如果此参数为 False，则移除前缀，但该函数仅返回名称以 'Sklearn' 为前缀的转换器。

返回:

支持的模型列表（字符串形式）。

skl2onnx.update_registered_converter(model, alias, shape_fct, convert_fct, overwrite=True, parser=None, options=None)

为新模型注册或更新转换器，以便在将其插入 scikit-learn pipeline 时可以进行转换。

参数:

• model – 模型类

• alias – 用于注册模型的别名

• shape_fct – 用于检查或修改预期输出的函数，此函数应快速执行，以便整个图可以计算，然后（并行或不并行）转换每个模型。

• convert_fct – 转换模型的函数

• overwrite – 如果转换器已存在，则为 False 以引发异常

• parser – 如果不为空，则也覆盖解析器

• options – 为此转换器注册的选项

别名通常是库名后跟模型名称。示例

from skl2onnx.common.shape_calculator import (
    calculate_linear_classifier_output_shapes,
)
from skl2onnx.operator_converters.RandomForest import (
    convert_sklearn_random_forest_classifier,
)
from skl2onnx import update_registered_converter
update_registered_converter(
        SGDClassifier, 'SklearnLinearClassifier',
        calculate_linear_classifier_output_shapes,
        convert_sklearn_random_forest_classifier,
        options={'zipmap': [True, False, 'columns'],
                 'output_class_labels': [False, True],
                 'raw_scores': [True, False]})

除非在列表中添加了选项 'zipmap'，否则该函数不会更新解析器。每个分类器都必须声明此选项，以便默认解析器自动处理该选项。

skl2onnx.update_registered_parser(model, parser_fct)

为新模型注册或更新解析器。解析器返回模型的预期输出。

参数:

• model – 模型类

• parser_fct – 解析器，签名与 parse_sklearn 相同

新转换器的辅助函数

skl2onnx.helpers.add_onnx_graph(scope: Scope, operator: Operator, container: ModelComponentContainer, onx: ModelProto)

根据 skl2onnx API，将整个 ONNX 图添加到现有图中，假设此 ONNX 图实现了 operator。

参数:

• scope – 作用域（用于获取唯一名称）

• operator – 操作符

• container – 容器

• onx – ONNX 图

操作 ONNX 图

skl2onnx.helpers.onnx_helper.enumerate_model_node_outputs(model, add_node=False)

枚举模型的所有节点。

参数:

• model – ONNX 图

• add_node – 如果为 False，则函数枚举来自每个节点的所有输出名称；否则，它枚举（输出名称，节点）元组。

返回:

枚举器

skl2onnx.helpers.onnx_helper.load_onnx_model(onnx_file_or_bytes)

加载 ONNX 文件。

参数:

onnx_file_or_bytes – ONNX 文件或字节

返回:

ONNX 模型

skl2onnx.helpers.onnx_helper.select_model_inputs_outputs(model, outputs=None, inputs=None)

接收一个模型并更改其输出。

参数:

• model – ONNX 模型

• inputs – 新输入

• outputs – 新输出

返回:

修改后的模型

该函数删除不需要的文件。

skl2onnx.helpers.onnx_helper.save_onnx_model(model, filename=None)

将模型保存为文件或字节。

参数:

• model – ONNX 模型

• filename – 文件名或 None 返回字节

返回:

字节

解析器

skl2onnx._parse.parse_sklearn(scope, model, inputs, custom_parsers=None, final_types=None)

这是一个委托函数。它不做任何事情，但会根据输入模型的类型调用正确的解析函数。

参数:

• scope – Scope 对象

• model – 一个 scikit-learn 对象（例如，OneHotEncoder 和 LogisticRegression）

• inputs – 变量列表

• custom_parsers – 解析器决定了特定任务的预期输出是什么，分类器、回归器、pipeline 的默认解析器已定义，但它们可以被重写，custom_parsers 是一个字典 { type: fct_parser(scope, model, inputs, custom_parsers=None) }

• final_types – 一个 python 列表。其工作方式与 initial_types 相同，但不是强制性的，它用于覆盖每个输出的类型（如果类型不是 None）和名称。

返回:

输入模型生成的输出变量。

skl2onnx._parse.parse_sklearn_model(model, initial_types=None, target_opset=None, custom_conversion_functions=None, custom_shape_calculators=None, custom_parsers=None, options=None, white_op=None, black_op=None, final_types=None, naming=None)

将 scikit-learn 对象放入抽象容器中，以便我们的框架能够无缝地处理使用不同机器学习工具创建的模型。

参数:

• model – 一个 scikit-learn 模型

• initial_types – 一个 python 列表。每个元素都是一个元组，包含一个变量名和 data_types.py 中定义的类型。

• target_opset – 数字，例如，ONNX 1.2 为 7，ONNX 1.3 为 8。

• custom_conversion_functions – 如果未注册，用于指定用户自定义转换函数的字典。

• custom_shape_calculators – 如果未注册，用于指定用户自定义形状计算器的字典。

• custom_parsers – 解析器决定了特定任务的预期输出是什么，分类器、回归器、pipeline 的默认解析器已定义，但它们可以被重写，custom_parsers 是一个字典 { type: fct_parser(scope, model, inputs, custom_parsers=None) }

• options – 提供给转换器的特定选项（请参阅 带选项的转换器）

• white_op – 转换 pipeline 时允许的 ONNX 节点白名单，如果为空，则允许所有节点

• black_op – 转换 pipeline 时允许的 ONNX 节点黑名单，如果为空，则不包含任何黑名单节点

• final_types – 一个 python 列表。其工作方式与 initial_types 相同，但不是强制性的，它用于覆盖每个输出的类型（如果类型不是 None）和名称。

• naming – 用户可能想更改中间值的命名方式，此参数可以是一个字符串（前缀）或一个函数，其签名如下：get_name(name, existing_names)，然后库会检查此名称是否唯一，如果不是则会修改它。

返回:

拓扑结构

已于 1.10.0 版本更改： 添加了参数 naming。

贡献者实用工具

skl2onnx.common.utils.check_input_and_output_numbers(operator, input_count_range=None, output_count_range=None)

检查输入/输出的数量是否正确。

参数:

• operator – Operator 对象

• input_count_range – 两个整数的列表或一个整数。如果是一个列表，第一个/第二个元素是最小/最大输入数量。如果是一个整数，则等同于在列表中指定该数字两次。对于无限范围，如 5 到无穷大，您需要使用 [5, None]。

• output_count_range – 两个整数的列表或一个整数。有关格式，请参阅 input_count_range。

skl2onnx.common.utils.check_input_and_output_types(operator, good_input_types=None, good_output_types=None)

检查输入/输出的类型是否正确。

参数:

• operator – Operator 对象

• good_input_types – 允许的输入类型列表（例如，[FloatTensorType, Int64TensorType]）或 None。None 表示跳过输入类型检查。

• good_output_types – 允许的输出类型列表。有关格式，请参阅 good_input_types。

概念

容器

class skl2onnx.common._container.SklearnModelContainerNode(sklearn_model, white_op=None, black_op=None, verbose=0)

一个 scikit-learn 模型的主要容器。每个转换器将节点添加到现有容器中，该容器由 Topology 的实例转换为 ONNX 图。

property input_names

此函数应返回一个字符串列表。每个字符串对应一个输入变量名。 :return: 字符串列表

property output_names

此函数应返回一个字符串列表。每个字符串对应一个输出变量名。 :return: 字符串列表

class skl2onnx.common._container.ModelComponentContainer(target_opset, options=None, registered_models=None, white_op=None, black_op=None, verbose=0, as_function=False)

在转换阶段，此类用于收集构建 ONNX GraphProto 所需的所有材料，该 GraphProto 封装在 ONNX ModelProto 中。

add_initializer(name, onnx_type, shape, content)

将 TensorProto 添加到最终 ONNX 模型的 initializer 列表中。

参数:

• name – 最终 ONNX 模型中的变量名。

• onnx_type – ONNX 张量中允许的元素类型，例如 TensorProto.FLOAT 和 TensorProto.STRING。

• shape – 张量形状，整数列表。

• content – 展平的张量值（即，float 列表或 float 数组）。

返回:

创建的张量

add_input(variable)

将 _parser.py 中定义的 Variable 对象添加到最终 ONNX 模型的输入列表中。

参数:

variable – 要添加的 Variable 对象。

add_node(op_type, inputs, outputs, op_domain='', op_version=None, name=None, **attrs)

将 NodeProto 添加到最终 ONNX 模型的节点列表中。如果输入操作的域-版本信息在我们域-版本池（一个 Python 集合）中找不到，我们可能会添加它。

参数:

• op_type – 一个字符串（例如，Pool 和 Conv），指示 NodeProto 的类型。

• inputs – 字符串列表。它们是所考虑的 NodeProto 的输入变量名。

• outputs – 字符串列表。它们是所考虑的 NodeProto 的输出变量名。

• op_domain – 要添加的操作的域名（例如，ai.onnx.ml）。

• op_version – 要添加的操作的版本号（例如，0 和 1）。

• name – 节点的名称，此名称不能为空。

• attrs – 一个 Python 字典。键和值分别是属性名称和属性值。

add_output(variable)

将 _parser.py 中定义的 Variable 对象添加到最终 ONNX 模型的输出列表中。

参数:

variable – 要添加的 Variable 对象。

节点

class skl2onnx.common._topology.Operator(onnx_name, scope, type, raw_operator, target_opset, scope_inst)

定义 ONNX 中可用的操作符。

class skl2onnx.common._topology.Variable(raw_name, onnx_name, scope, type=None)

定义一个变量，该变量保存由 ONNX 类型定义的所有数据。

作用域

class skl2onnx.common._topology.Scope(name, target_opset=None, custom_shape_calculators=None, options=None, registered_models=None, naming=None)

ONNX 图的每个节点都必须是唯一的。此类保存图中已定义的所有节点现有名称的列表。它还提供创建唯一未使用的名称的函数。

get_unique_operator_name(seed)

基于给定的种子创建唯一的操作符 ID。

get_unique_variable_name(seed, rename=True)

基于给定的种子创建唯一的变量 ID。

拓扑结构

class skl2onnx.common._topology.Topology(model, default_batch_size=1, initial_types=None, target_opset=None, custom_conversion_functions=None, custom_shape_calculators=None, registered_models=None)

持有 Scope 和 SklearnModelContainer 的实例。这些是在转换 pipeline 时由转换器填充的。

call_converter(operator, container, verbose=0)

为操作符 operator 调用转换器。

call_shape_calculator(operator)

为操作符 operator 调用 shape_calculator。

convert_operators(container=None, verbose=0)

为现有操作符调用所有转换器和 shape_calculator。它还处理由转换器创建的新操作符。

declare_scope(seed, parent_scopes=None, options=None, naming=None)

创建一个新的 Scope 并将其附加到现有作用域列表中。

skl2onnx.common._topology.convert_topology(topology, model_name, doc_string, target_opset, options=None, remove_identity=True, verbose=0)

此函数用于将 _parser.py 中定义的 Topology 对象转换为 ONNX 模型（类型：ModelProto）。

参数:

• topology – 我们将要转换的 Topology 对象。

• model_name – GraphProto 的名称。令“model”表示返回的模型。字符串“model_name”将被分配给“model.graph.name”。

• doc_string – 附加到生成的模型上的字符串。

• target_opset – 数字或字典，例如，ONNX 1.2 为 7，ONNX 1.3 为 8，字典用于指示不同域的不同 opset。

• options – 请参阅 带选项的转换器。

• remove_identity – 删除 identity 节点，包括“1.1.2”、“1.2”等。

• verbose – 在转换时显示信息。

返回:

一个 ONNX ModelProto。