API 摘要

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

版本

skl2onnx.get_latest_tested_opset_version()[source]

此模块依赖于 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)[source]

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

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

参数：

  • model – scikit-learn 模型

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

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

  • 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 操作符在必要时切换到双精度数

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

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

  • 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]))]

注意

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

转换器选项

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

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)

它在示例 TfIdfVectorizer with ONNX 中使用。

版本 1.10.0 中的更改: 添加了参数 *naming*。

skl2onnx.to_onnx(model, X=None, name=None, initial_types=None, target_opset=None, options=None, white_op=None, black_op=None, final_types=None, dtype=None, naming=None, model_optim=True, verbose=0)[source]

使用简化的参数调用 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 操作符在必要时切换到双精度数

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

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

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

返回值：

转换后的模型

此函数检查模型是否继承自类 OnnxOperatorMixin，在这种情况下，它会调用该方法中的 *to_onnx*，否则它会调用 convert_sklearn()。

版本 1.10.0 中的更改: 添加了参数 *naming*。

日志记录

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

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

示例 Logging, verbose 说明了它的外观。

注册新的转换器

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

skl2onnx.supported_converters(from_sklearn=False)[source]

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

参数：

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

返回值：

作为字符串的受支持模型列表

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

为新模型注册或更新转换器，以便在插入 *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.update_registered_parser(model, parser_fct)[source]

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

参数：

  • model – 模型类

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

新转换器的帮助程序

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

将整个 ONNX 图添加到现有图中，遵循 skl2onnx API，假设此 ONNX 图实现了 算子。

参数：

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

  • operator – 算子

  • container – 容器

  • onx – ONNX 图

操作 ONNX 图

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

枚举模型的所有节点。

参数：

  • model – ONNX 图

  • add_node – 如果为 False，则该函数枚举每个节点的所有输出名称，否则，它枚举元组 (输出名称，节点)

返回值：

枚举器

skl2onnx.helpers.onnx_helper.load_onnx_model(onnx_file_or_bytes)[source]

加载ONNX文件。

参数：

onnx_file_or_bytes – ONNX文件或字节

返回值：

ONNX模型

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

获取一个模型并更改其输出。

参数：

  • model – ONNX模型

  • inputs – 新的输入

  • outputs – 新的输出

返回值：

修改后的模型

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

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

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

参数：

  • model – ONNX模型

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

返回值：

字节

解析器

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

这是一个委托函数。它除了根据输入模型的类型调用正确的解析函数之外什么也不做。

参数：

  • 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)[source]

将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)[source]

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

参数：

  • 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)[source]

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

参数：

  • 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)[source]

一个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)[source]

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

add_initializer(name, onnx_type, shape, content)[source]

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

参数：

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

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

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

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

返回值：

创建的张量

add_input(variable)[source]

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

参数：

variable – 要添加的Variable对象

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

将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)[source]

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

参数：

variable – 要添加的Variable对象

节点

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

定义ONNX中可用的运算符。

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

定义一个变量，该变量保存从ONNX类型定义的任何数据。

范围

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

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

get_unique_operator_name(seed)[source]

基于给定的种子创建唯一的运算符ID。

get_unique_variable_name(seed, rename=True)[source]

基于给定的种子创建唯一的变量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)[source]

保存Scope和SklearnModelContainer的实例。在转换管道时，转换器会填充这些实例。

call_converter(operator, container, verbose=0)[source]

调用运算符 *operator* 的转换器。

call_shape_calculator(operator)[source]

调用运算符 *operator* 的形状计算器。

convert_operators(container=None, verbose=0)[source]

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

declare_scope(seed, parent_scopes=None, options=None, naming=None)[source]

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

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

此函数用于将我们在 _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”等。

  • verbose – 在转换时显示信息

返回值：

一个 ONNX ModelProto