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 返回。

对于管线转换，用户需要确保每个组件是我们的支持项之一。此函数将指定的 scikit-learn 模型转换为其 ONNX 对应项。请注意，对于所有转换，都需要初始类型。也可以指定 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 – 解析器决定特定任务需要哪些输出，分类器、回归器和管线有默认的解析器定义，但它们可以被重写，custom_parsers 是一个字典 { type: fct_parser(scope, model, inputs, custom_parsers=None) }

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

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

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

• black_op – 在转换管线时禁止的 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 个元素是整数，我们需要按如下方式指定初始类型。 [None, 5] 中的 [None] 表示此处的批量大小未知。

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

注意

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

转换器选项

一些 ONNX 算子暴露了 sklearn-onnx 无法从原始模型猜测的参数。通常会建议一些默认值，但用户可能需要手动覆盖它们。当模型包含在管线中时，这种需求并不容易实现。这就是为什么可以将这些选项作为字典 {model_type: parameters in a dictionary} 或 {model_id: parameters in a dictionary} 提供给函数 convert_sklearn。当 ONNX 图需要对字符串进行分词时，选项 sep 用于指定两个单词之间的分隔符。默认值很短，可能不包含所有必要的值。它可以被覆盖为

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

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

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

它用于示例 带有 ONNX 的 TfIdfVectorizer。

版本 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 – 在转换管线时允许的 ONNX 节点白名单，如果为空，则允许所有节点

• black_op – 在转换管线时禁止的 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.10.0 中的更改： 添加了参数 naming。

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

日志记录

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

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

示例 日志记录，详细模式 说明了它的样子。

注册新转换器

如果模型在此包中没有实现转换器，则必须注册一个新的转换器，无论是从另一个包导入还是从头创建。部分 覆盖的转换器 列出了所有可用的转换器。

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 管线时可以进行转换。

参数:

• 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._parse.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 图中，假设此 ONNX 图实现了 一个算子。

参数:

• scope – 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 – 解析器决定特定任务需要哪些输出，分类器、回归器和管线有默认的解析器定义，但它们可以被重写，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 – 解析器决定特定任务需要哪些输出，分类器、回归器和管线有默认的解析器定义，但它们可以被重写，custom_parsers 是一个字典 { type: fct_parser(scope, model, inputs, custom_parsers=None) }

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

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

• black_op – 在转换管线时禁止的 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)

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

add_initializer(name, onnx_type, shape, content)

将 TensorProto 添加到最终 ONNX 模型的初始化器列表中。

参数:

• name – 生成的 ONNX 模型中的变量名称。

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

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

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

返回:

创建的张量

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 set）中找不到输入算子的域-版本信息，我们可能会添加它。

参数:

• 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 类型定义的任何数据。

Scope

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 的实例。这些在转换管线时由转换器填充。

call_converter(operator, container, verbose=0)

调用算子 operator 的转换器。

call_shape_calculator(operator)

调用算子 operator 的形状计算器。

convert_operators(container=None, verbose=0)

调用现有算子的所有转换器和形状计算器。它还会处理由转换器创建的新算子。

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

创建一个新的 Scope 并将其附加到现有 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 – 移除包括 ‘1.1.2’、‘1.2’ 等 identity 节点。

• verbose – 在转换时显示信息

返回:

一个 ONNX ModelProto