ML.CONFUSION_MATRIX 函数

ML.CONFUSION_MATRIX 函数

使用 ML.CONFUSION_MATRIX 函数会返回给定逻辑回归模型和输入数据的混淆矩阵。ML.CONFUSION_MATRIX 函数可与逻辑回归模型和多类别逻辑回归模型结合使用。ML.CONFUSION_MATRIX 不支持线性回归模型。

ML.CONFUSION_MATRIX 函数的输出列取决于模型。第一个输出列始终为 expected_label。另外还会有 N 个输出列，已训练模型中的每个类别对应一列。这些列的名称取决于训练模型所用的类别标签。

如果训练类别标签全部符合 BigQuery 列命名规则，则标签会直接用作列名称。不符合命名规则的列会被更改为符合规则且独一无二的名称。例如，如果标签为 0 和 1，则输出列名称为 _0 和 _1。

列根据类别标签按升序排列。如果评估数据中的标签与训练数据中的标签匹配，则真正例显示在从左上角到右下角的对角线上。预期的（或实际）标签在每行中列出一个，预测的标签在每列中列出一个。

expected_label 列中的值是评估数据的标签列中传递给 ML.CONFUSION_MATRIX 的确切值和类型。即使它们与训练期间使用的值或类型不完全匹配，也是如此。

ML.CONFUSION_MATRIX 语法

ML.CONFUSION_MATRIX(MODEL model_name
           [, {TABLE table_name | (query_statement)}]
           [, STRUCT(<T> AS threshold)])

model_name

model_name 是要评估的模型的名称。如果您没有配置默认项目，请按照以下格式将项目 ID 添加到模型名称前面：`[PROJECT_ID].[DATASET].[MODEL]`（包括反引号）；例如：`myproject.mydataset.mymodel`。

table_name

（可选）table_name 是包含评估数据的输入表的名称。如果您没有配置默认项目，请按照以下格式将项目 ID 添加到表名称前面：`[PROJECT_ID].[DATASET].[TABLE]`（包括反引号）；例如：`myproject.mydataset.mytable`。

如果指定了 table_name，则表中的输入列名称必须与模型中的列名称匹配，并且根据 BigQuery 隐式强制转换规则，它们的类型应兼容。输入必须有一列与训练期间提供的标签列名称匹配。该值通过 input_label_cols 选项提供。如果未指定 input_label_cols，系统会使用训练数据中名为“标签”的列。

如果 table_name 和 query_statement 均未指定，则 ML.CONFUSION_MATRIX 会按以下方式计算混淆矩阵结果：

• 如果数据在训练期间拆分，则会使用拆分后的评估数据来计算混淆矩阵结果。
• 如果数据在训练期间未拆分，则会使用所有训练输入数据来计算混淆矩阵结果。

注意：对于某些较旧的模型，ML.CONFUSION_MATRIX 需要您提供输入数据，否则将返回错误。在这种情况下，请在搭配这些模型使用 ML.CONFUSION_MATRIX 时提供输入数据。

query_statement

（可选）query_statement 子句指定用于生成评估数据的标准 SQL 查询。请参阅标准 SQL 查询语法页面，了解 query_statement 子句支持的 SQL 语法。

如果指定了 query_statement，则查询中的输入列名称必须与模型中的列名称匹配，并且根据 BigQuery 隐式强制转换规则，它们的类型应兼容。输入必须有一列与训练期间提供的标签列名称匹配。该值通过 input_label_cols 选项提供。如果未指定 input_label_cols，系统会使用训练数据中名为“标签”的列。系统会忽略多余的列。

如果创建 model_name 的 CREATE MODEL 语句中存在 TRANSFORM 子句，则只有 TRANSFORM 子句中的输入列必须出现在 query_statement 中。

如果 table_name 和 query_statement 均未指定，则 ML.CONFUSION_MATRIX 会按以下方式计算混淆矩阵结果：

• 如果数据在训练期间拆分，则会使用拆分后的评估数据来计算混淆矩阵结果。
• 如果数据在训练期间未拆分，则会使用所有训练输入数据来计算混淆矩阵结果。

注意：对于某些较旧的模型，ML.CONFUSION_MATRIX 需要您提供输入数据，否则将返回错误。在这种情况下，请在搭配这些模型使用 ML.CONFUSION_MATRIX 时提供输入数据。

threshold

（可选）threshold 为用于评估的逻辑回归模型的自定义阈值。默认值为 0.5。所提供的阈值必须为 STRUCT 类型。

如果精确率或召回率的值为零，则表示所选阈值不生成任何真正例标签。如果精确率的值为 NaN，则表示所选阈值不生成任何正例标签（包括真正例和假正例）。

注意：threshold 不能与多类别逻辑回归模型结合使用。

ML.CONFUSION_MATRIX 示例

以下示例假定您的模型和输入表位于默认项目中。

以下查询会返回一个逻辑回归模型的混淆矩阵。

SELECT
  *
FROM
  ML.CONFUSION_MATRIX(MODEL `mydataset.mymodel`,
  (
    SELECT
      *
    FROM
      `mydataset.mytable`))

ML.CONFUSION_MATRIX 限制

ML.CONFUSION_MATRIX 函数存在以下限制：

• ML.CONFUSION_MATRIX 不支持导入的 TensorFlow 模型。