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 後啟用或停用模型最佳化，它可以減少身分節點的數量

• verbose – 在轉換模型時顯示進度

傳回:

與輸入 scikit-learn 模型等效的 ONNX 模型（類型：ModelProto）

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 的原因。選項 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)

它被用於範例 使用 ONNX 的 TfIdfVectorizer。

在 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)

呼叫 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 後啟用或停用模型最佳化，它可以減少身分節點的數量

• verbose – 在轉換模型時顯示進度

傳回:

已轉換的模型

此函數檢查模型是否繼承自類別 OnnxOperatorMixin，在這種情況下它會呼叫 to_onnx 方法，否則它會呼叫 convert_sklearn()。

在 1.10.0 版本中變更：新增了參數 naming。

記錄

如果管道包含沒有任何相關轉換器的物件，則管道的轉換會失敗。如果其中一個物件由自訂轉換器對應，也可能會失敗。如果錯誤訊息不夠明確，則可以啟用記錄

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.update_registered_parser(model, parser_fct)

註冊或更新新模型的剖析器。剖析器會傳回模型的預期輸出。

參數:

• model – 模型類別

• parser_fct – 剖析器，簽名與 parse_sklearn 相同

新轉換器的輔助工具

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

將整個 ONNX 圖形新增至現有的圖形，遵循 skl2onnx API，假設此 ONNX 圖形實作 運算子。

參數:

• 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 所需的所有材料，該 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 集合）中找不到，我們可能會加入它。

參數:

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

根據給定的 seed 建立唯一的運算子 ID。

get_unique_variable_name(seed, rename=True)

根據給定的 seed 建立唯一的變數 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 – 移除包含 ‘1.1.2’, ‘1.2’ 等身分節點。

• verbose – 轉換時顯示資訊

傳回:

一個 ONNX ModelProto