ai.onnx.ml - TreeEnsemble¶

TreeEnsemble - 5 (ai.onnx.ml)¶

版本¶

名稱: TreeEnsemble (GitHub)
網域: ai.onnx.ml
since_version: 5
函式: False
支援層級: SupportType.COMMON
形狀推斷: True

此版本的運算子自網域 ai.onnx.ml 的版本 5 開始提供。

摘要¶

樹狀集成運算子。傳回批次中每個輸入的迴歸值。輸入的維度為 [N, F]，其中 N 是輸入批次大小，而 F 是輸入特徵的數量。輸出的維度為 [N, num_targets]，其中 N 是批次大小，而 num_targets 是目標數量，這是一個可設定的屬性。

此屬性的編碼會沿著樹狀結構的內部節點和葉子分割。值得注意的是，以 nodes_* 作為前置詞的屬性與內部節點相關聯，而以 leaf_* 作為前置詞的屬性則與葉子相關聯。nodes_* 屬性都必須具有相同的長度，並編碼一系列的元組，如在給定位置取得所有 nodes_* 欄位所定義。

所有以 leaf_* 作為前置詞的欄位都代表樹葉，並類似地定義葉子的元組，而且必須具有相同的長度。

此運算子可用於實作先前的 TreeEnsembleRegressor 和 TreeEnsembleClassifier 節點。TreeEnsembleRegressor 節點會直接對應到此節點，並且需要變更節點的表示方式。TreeEnsembleClassifier 節點可以透過在此節點之後新增一個 ArgMax 節點來實作，以決定最上層的類別。若要編碼類別標籤，可以使用 LabelEncoder 或 GatherND 運算子。

屬性¶

aggregate_function - INT (預設值為 '1')

定義如何在目標內聚合葉子值。
下列其中一項：「AVERAGE」(0)、「SUM」(1)、「MIN」(2)、「MAX」(3)，預設為「SUM」(1)
leaf_targetids - INTS (必要)

此葉子貢獻的目標索引 (必須在範圍 [0, n_targets) 內)。
leaf_weights - TENSOR (必要)

每個葉子的權重。
membership_values - TENSOR :

要針對每個集合成員資格節點測試其成員資格的成員。依照 node_modes 中「BRANCH_MEMBER」模式出現的順序，列出所有要再次測試的成員，並以 NaN 分隔。其數值集合數量會與模式為「BRANCH_MEMBER」的節點數量相同。如果節點不包含任何「BRANCH_MEMBER」節點，則可以省略此值。
n_targets - INT :

目標總數。
nodes_falseleafs - INTS (必要)

如果每個節點的 false 分支是葉子，則為 1，如果為內部節點，則為 0。若要表示一個身為葉子的樹狀結構 (只有一個節點)，可以使用單一 nodes_* 項目，其 true 和 false 分支參照相同的 leaf_* 項目
nodes_falsenodeids - INTS (必要)

如果某個條目的 nodes_falseleafs 為 false，則代表該節點的假分支位置。此位置可用於索引至 nodes_* 條目。如果 nodes_falseleafs 為 false，則表示索引至 leaf_* 屬性。
nodes_featureids - INTS (必要)

每個節點的特徵 ID。
nodes_hitrates - TENSOR :

每個節點的熱門程度，用於效能考量，可省略。
nodes_missing_value_tracks_true - INTS :

針對每個節點，定義當輸入特徵為 NaN 時，是否應遵循真分支（如果屬性值為 1）或假分支（如果屬性值為 0）。此屬性可以保持未定義，所有節點的預設值為 false (0)。
nodes_modes - TENSOR (必要)

節點執行的比較運算。此運算編碼為枚舉值，分別為 0 (‘BRANCH_LEQ’，小於等於), 1 (‘BRANCH_LT’，小於), 2 (‘BRANCH_GTE’，大於等於), 3 (‘BRANCH_GT’，大於), 4 (‘BRANCH_EQ’，等於), 5 (‘BRANCH_NEQ’，不等於), 和 6 (‘BRANCH_MEMBER’，成員)。請注意，這是一個 uint8 類型的張量。
nodes_splits - TENSOR (必要)

對於模式不是 ‘BRANCH_MEMBER’ 的每個節點，用於分割的閾值。
nodes_trueleafs - INTS (必要)

如果每個節點的真分支是葉節點，則為 1，否則為內部節點則為 0。若要表示僅有一個節點的葉節點樹，可以透過單個 nodes_* 條目，使其真分支和假分支都參考相同的 leaf_* 條目來實現。
nodes_truenodeids - INTS (必要)

如果某個條目的 nodes_trueleafs 為 false，則代表該節點的真分支位置。此位置可用於索引至 nodes_* 條目。如果 nodes_trueleafs 為 false，則表示索引至 leaf_* 屬性。
post_transform - INT (預設值為 '0')

指示要套用至分數的轉換。
值可以是 ‘NONE’ (0)、 ‘SOFTMAX’ (1)、 ‘LOGISTIC’ (2)、 ‘SOFTMAX_ZERO’ (3) 或 ‘PROBIT’ (4) 其中之一，預設為 ‘NONE’ (0)
tree_roots - INTS (必要)

每個樹的根節點在 nodes_* 中的索引。樹狀結構是從每個節點的分支衍生而來的。

輸入¶

X (異質) - T

形狀為 [批次大小, 特徵數量] 的輸入。

輸出¶

Y (異質) - T

形狀為 [批次大小, 目標數量] 的輸出。

類型約束¶

T in ( tensor(double), tensor(float), tensor(float16) )

輸入類型必須為數值類型的張量。

範例¶

_tree_ensemble_single_tree¶

import numpy as np
import onnx

node = onnx.helper.make_node(
    "TreeEnsemble",
    ["X"],
    ["Y"],
    domain="ai.onnx.ml",
    n_targets=2,
    membership_values=None,
    nodes_missing_value_tracks_true=None,
    nodes_hitrates=None,
    aggregate_function=1,
    post_transform=0,
    tree_roots=[0],
    nodes_modes=make_tensor(
        "nodes_modes",
        onnx.TensorProto.UINT8,
        (3,),
        np.array([0, 0, 0], dtype=np.uint8),
    ),
    nodes_featureids=[0, 0, 0],
    nodes_splits=make_tensor(
        "nodes_splits",
        onnx.TensorProto.DOUBLE,
        (3,),
        np.array([3.14, 1.2, 4.2], dtype=np.float64),
    ),
    nodes_truenodeids=[1, 0, 1],
    nodes_trueleafs=[0, 1, 1],
    nodes_falsenodeids=[2, 2, 3],
    nodes_falseleafs=[0, 1, 1],
    leaf_targetids=[0, 1, 0, 1],
    leaf_weights=make_tensor(
        "leaf_weights",
        onnx.TensorProto.DOUBLE,
        (4,),
        np.array([5.23, 12.12, -12.23, 7.21], dtype=np.float64),
    ),
)

x = np.array([1.2, 3.4, -0.12, 1.66, 4.14, 1.77], np.float64).reshape(3, 2)
y = np.array([[5.23, 0], [5.23, 0], [0, 12.12]], dtype=np.float64)
expect(
    node,
    inputs=[x],
    outputs=[y],
    name="test_ai_onnx_ml_tree_ensemble_single_tree",
)

_tree_ensemble_set_membership¶

import numpy as np
import onnx

node = onnx.helper.make_node(
    "TreeEnsemble",
    ["X"],
    ["Y"],
    domain="ai.onnx.ml",
    n_targets=4,
    aggregate_function=1,
    membership_values=make_tensor(
        "membership_values",
        onnx.TensorProto.FLOAT,
        (8,),
        [1.2, 3.7, 8, 9, np.nan, 12, 7, np.nan],
    ),
    nodes_missing_value_tracks_true=None,
    nodes_hitrates=None,
    post_transform=0,
    tree_roots=[0],
    nodes_modes=make_tensor(
        "nodes_modes",
        onnx.TensorProto.UINT8,
        (3,),
        np.array([0, 6, 6], dtype=np.uint8),
    ),
    nodes_featureids=[0, 0, 0],
    nodes_splits=make_tensor(
        "nodes_splits",
        onnx.TensorProto.FLOAT,
        (3,),
        np.array([11, 232344.0, np.nan], dtype=np.float32),
    ),
    nodes_trueleafs=[0, 1, 1],
    nodes_truenodeids=[1, 0, 1],
    nodes_falseleafs=[1, 0, 1],
    nodes_falsenodeids=[2, 2, 3],
    leaf_targetids=[0, 1, 2, 3],
    leaf_weights=make_tensor(
        "leaf_weights", onnx.TensorProto.FLOAT, (4,), [1, 10, 1000, 100]
    ),
)

x = np.array([1.2, 3.4, -0.12, np.nan, 12, 7], np.float32).reshape(-1, 1)
expected = np.array(
    [
        [1, 0, 0, 0],
        [0, 0, 0, 100],
        [0, 0, 0, 100],
        [0, 0, 1000, 0],
        [0, 0, 1000, 0],
        [0, 10, 0, 0],
    ],
    dtype=np.float32,
)
expect(
    node,
    inputs=[x],
    outputs=[expected],
    name="test_ai_onnx_ml_tree_ensemble_set_membership",
)