mlflow.shap

mlflow.shap.get_default_conda_env()

返回:

通过调用 save_explainer() 和 log_explainer() 生成的 MLflow 模型的默认 Conda 环境。

mlflow.shap.get_default_pip_requirements()

此flavor生成的MLflow Models的默认pip需求列表。调用 save_explainer() 和 log_explainer() 会生成一个pip环境，该环境至少包含这些需求。

mlflow.shap.get_underlying_model_flavor(model)

查找底层模型的风格。

参数:

model – 解释器的底层模型。

mlflow.shap.load_explainer(model_uri)

从本地文件或运行中加载一个 SHAP 解释器。

参数:

model_uri – MLflow 模型的位置，采用 URI 格式。例如： - /Users/me/path/to/local/model - relative/path/to/local/model - s3://my_bucket/path/to/model - runs:/<mlflow_run_id>/run-relative/path/to/model - models:/<model_name>/<model_version> - models:/<model_name>/<stage> 有关支持的 URI 方案的更多信息，请参阅 引用工件。

返回:

一个 SHAP 解释器。

mlflow.shap.log_explainer(explainer, artifact_path, serialize_model_using_mlflow=True, conda_env=None, code_paths=None, registered_model_name=None, signature: ModelSignature = None, input_example: DataFrame | ndarray | dict | list | csr_matrix | csc_matrix | str | bytes | tuple = None, await_registration_for=300, pip_requirements=None, extra_pip_requirements=None, metadata=None)

将 SHAP 解释器记录为当前运行的 MLflow 工件。

参数:

• explainer – 要保存的 SHAP 解释器。

• artifact_path – 运行相对的工件路径。

• serialize_model_using_mlflow – 当设置为 True 时，MLflow 将提取底层模型并将其序列化为 MLmodel，否则使用 SHAP 的内部序列化。默认为 True。目前 MLflow 序列化仅支持 ‘sklearn’ 或 ‘pytorch’ 风味的模型。

• conda_env –

  一个Conda环境的字典表示形式，或Conda环境yaml文件的路径。如果提供，这将描述模型应运行的环境。至少，它应指定包含在 get_default_conda_env() 中的依赖项。如果为 None，则通过 mlflow.models.infer_pip_requirements() 推断的pip要求添加一个conda环境到模型中。如果要求推断失败，则回退到使用 get_default_pip_requirements()。来自 conda_env 的pip要求被写入一个pip requirements.txt 文件，完整的conda环境被写入 conda.yaml。以下是一个conda环境的字典表示形式的*示例*:

  {
      "name": "mlflow-env",
      "channels": ["conda-forge"],
      "dependencies": [
          "python=3.8.15",
          {
              "pip": [
                  "shap==x.y.z"
              ],
          },
      ],
  }
  

• code_paths – 本地文件系统路径列表，指向Python文件依赖项（或包含文件依赖项的目录）。这些文件在加载模型时会被*前置*到系统路径中。如果为给定模型声明了依赖关系，则应从公共根路径声明相对导入，以避免在加载模型时出现导入错误。有关``code_paths``功能的详细解释、推荐的使用模式和限制，请参阅`code_paths使用指南 <https://mlflow.org/docs/latest/model/dependencies.html?highlight=code_paths#saving-extra-code-with-an-mlflow-model>`_。

• registered_model_name – 如果指定，在 registered_model_name 下创建一个模型版本，如果给定名称的注册模型不存在，则同时创建一个注册模型。

• signature – ModelSignature 描述了模型的输入和输出 Schema。模型签名可以从具有有效模型输入（例如，省略目标列的训练数据集）和有效模型输出（例如，在训练数据集上生成的模型预测）的数据集中 推断，例如： .. code-block:: python

• input_example – 一个或多个有效的模型输入实例。输入示例用作提示，指示应向模型提供哪些数据。它将被转换为Pandas DataFrame，然后使用Pandas的面向分割的格式序列化为json，或者是一个numpy数组，其中示例将通过将其转换为列表来序列化为json。字节被base64编码。当``signature``参数为``None``时，输入示例用于推断模型签名。

• await_registration_for – 等待模型版本完成创建并处于 READY 状态的秒数。默认情况下，函数等待五分钟。指定 0 或 None 以跳过等待。

• pip_requirements – 可以是 pip 需求字符串的可迭代对象（例如 ["shap", "-r requirements.txt", "-c constraints.txt"]），或者是本地文件系统上 pip 需求文件的字符串路径（例如 "requirements.txt"）。如果提供，这将描述该模型应运行的环境。如果为 None，则通过 mlflow.models.infer_pip_requirements() 从当前软件环境中推断出默认的需求列表。如果需求推断失败，则回退到使用 get_default_pip_requirements()。需求和约束都会自动解析并分别写入 requirements.txt 和 constraints.txt 文件，并作为模型的一部分存储。需求也会写入模型 conda 环境（conda.yaml）文件的 pip 部分。

• extra_pip_requirements – 可以是 pip 需求字符串的可迭代对象（例如 ["pandas", "-r requirements.txt", "-c constraints.txt"]），或者是本地文件系统上的 pip 需求文件的字符串路径（例如 "requirements.txt"）。如果提供，这将描述附加的 pip 需求，这些需求会被追加到根据用户当前软件环境自动生成的一组默认 pip 需求中。需求和约束会分别自动解析并写入 requirements.txt 和 constraints.txt 文件，并作为模型的一部分存储。需求也会被写入模型的 conda 环境（conda.yaml）文件的 pip 部分。 .. 警告:: 以下参数不能同时指定： - conda_env - pip_requirements - extra_pip_requirements 这个示例 展示了如何使用 pip_requirements 和 extra_pip_requirements 指定 pip 需求。

• metadata – 传递给模型并在 MLmodel 文件中存储的自定义元数据字典。

mlflow.shap.log_explanation(predict_function, features, artifact_path=None)

给定一个能够计算提供的 features 上的 ML 模型输出的 predict_function，计算并记录 ML 模型输出的解释。解释以包含以下由 `SHAP`_（SHapley Additive exPlanations）生成的项目的工件目录的形式记录。

• 基本值

• SHAP 值（使用 shap.KernelExplainer 计算）

• 摘要条形图（显示每个特征对模型输出的平均影响）

参数:

• predict_function – 一个用于计算模型输出的函数（例如 scikit-learn 分类器的 predict_proba 方法）。必须具有以下签名： .. code-block:: python def predict_function(X) -> pred: … - X：一个类似数组的对象，其形状应为（# 样本数，# 特征数）。 - pred：一个类似数组的对象，其形状应为（# 样本数）用于回归器，或（# 类别数，# 样本数）用于分类器。对于分类器，pred 中的值应对应于每个类别的预测概率。 可接受的类似数组的对象类型： - numpy.array - pandas.DataFrame - shap.common.DenseData - scipy.sparse matrix

• features – 用于计算 SHAP 值的特征矩阵。提供的特征应具有形状（# 样本，# 特征），并且可以是上述数组类对象类型之一。 .. note:: shap.KernelExplainer 的背景数据是通过使用 shap.kmeans 对 features 进行子采样生成的。出于性能原因，背景数据的大小限制为 100 行。

• artifact_path – 解释保存的运行相对工件路径。如果未指定，默认为“model_explanations_shap”。

返回:

记录解释的工件URI。

示例

import os

import numpy as np
import pandas as pd
from sklearn.datasets import load_diabetes
from sklearn.linear_model import LinearRegression

import mlflow
from mlflow import MlflowClient

# prepare training data
X, y = dataset = load_diabetes(return_X_y=True, as_frame=True)
X = pd.DataFrame(dataset.data[:50, :8], columns=dataset.feature_names[:8])
y = dataset.target[:50]

# train a model
model = LinearRegression()
model.fit(X, y)

# log an explanation
with mlflow.start_run() as run:
    mlflow.shap.log_explanation(model.predict, X)

# list artifacts
client = MlflowClient()
artifact_path = "model_explanations_shap"
artifacts = [x.path for x in client.list_artifacts(run.info.run_id, artifact_path)]
print("# artifacts:")
print(artifacts)

# load back the logged explanation
dst_path = client.download_artifacts(run.info.run_id, artifact_path)
base_values = np.load(os.path.join(dst_path, "base_values.npy"))
shap_values = np.load(os.path.join(dst_path, "shap_values.npy"))

print("\n# base_values:")
print(base_values)
print("\n# shap_values:")
print(shap_values[:3])

输出

# artifacts:
['model_explanations_shap/base_values.npy',
 'model_explanations_shap/shap_values.npy',
 'model_explanations_shap/summary_bar_plot.png']

# base_values:
20.502000000000002

# shap_values:
[[ 2.09975523  0.4746513   7.63759026  0.        ]
 [ 2.00883109 -0.18816665 -0.14419184  0.        ]
 [ 2.00891772 -0.18816665 -0.14419184  0.        ]]

记录的工件

mlflow.shap.save_explainer(explainer, path, serialize_model_using_mlflow=True, conda_env=None, code_paths=None, mlflow_model=None, signature: ModelSignature = None, input_example: DataFrame | ndarray | dict | list | csr_matrix | csc_matrix | str | bytes | tuple = None, pip_requirements=None, extra_pip_requirements=None, metadata=None)

将 SHAP 解释器保存到本地文件系统中的路径。生成包含以下风格的 MLflow 模型：

• mlflow.shap

• mlflow.pyfunc

参数:

• explainer – 要保存的 SHAP 解释器。

• path – 解释器要保存的本地路径。

• serialize_model_using_mlflow – 当设置为 True 时，MLflow 将提取底层模型并将其序列化为 MLmodel，否则使用 SHAP 的内部序列化。默认为 True。目前 MLflow 序列化仅支持 ‘sklearn’ 或 ‘pytorch’ 风味的模型。

• conda_env –

  一个Conda环境的字典表示形式，或Conda环境yaml文件的路径。如果提供，这将描述模型应运行的环境。至少，它应指定包含在 get_default_conda_env() 中的依赖项。如果为 None，则通过 mlflow.models.infer_pip_requirements() 推断的pip要求添加一个conda环境到模型中。如果要求推断失败，则回退到使用 get_default_pip_requirements()。来自 conda_env 的pip要求被写入一个pip requirements.txt 文件，完整的conda环境被写入 conda.yaml。以下是一个conda环境的字典表示形式的*示例*:

  {
      "name": "mlflow-env",
      "channels": ["conda-forge"],
      "dependencies": [
          "python=3.8.15",
          {
              "pip": [
                  "shap==x.y.z"
              ],
          },
      ],
  }
  

• code_paths – 本地文件系统路径列表，指向Python文件依赖项（或包含文件依赖项的目录）。这些文件在加载模型时会被*前置*到系统路径中。如果为给定模型声明了依赖关系，则应从公共根路径声明相对导入，以避免在加载模型时出现导入错误。有关``code_paths``功能的详细解释、推荐的使用模式和限制，请参阅`code_paths使用指南 <https://mlflow.org/docs/latest/model/dependencies.html?highlight=code_paths#saving-extra-code-with-an-mlflow-model>`_。

• mlflow_model – mlflow.models.Model 正在添加此风格。

• signature – ModelSignature 描述了模型的输入和输出 Schema。模型签名可以从具有有效模型输入（例如，省略目标列的训练数据集）和有效模型输出（例如，在训练数据集上生成的模型预测）的数据集中 推断，例如： .. code-block:: python

• input_example – 一个或多个有效的模型输入实例。输入示例用作提示，指示应向模型提供哪些数据。它将被转换为Pandas DataFrame，然后使用Pandas的面向分割的格式序列化为json，或者是一个numpy数组，其中示例将通过将其转换为列表来序列化为json。字节被base64编码。当``signature``参数为``None``时，输入示例用于推断模型签名。

• pip_requirements – 可以是 pip 需求字符串的可迭代对象（例如 ["shap", "-r requirements.txt", "-c constraints.txt"]），或者是本地文件系统上 pip 需求文件的字符串路径（例如 "requirements.txt"）。如果提供，这将描述该模型应运行的环境。如果为 None，则通过 mlflow.models.infer_pip_requirements() 从当前软件环境中推断出默认的需求列表。如果需求推断失败，则回退到使用 get_default_pip_requirements()。需求和约束都会自动解析并分别写入 requirements.txt 和 constraints.txt 文件，并作为模型的一部分存储。需求也会写入模型 conda 环境（conda.yaml）文件的 pip 部分。

• extra_pip_requirements – 可以是 pip 需求字符串的可迭代对象（例如 ["pandas", "-r requirements.txt", "-c constraints.txt"]），或者是本地文件系统上的 pip 需求文件的字符串路径（例如 "requirements.txt"）。如果提供，这将描述附加的 pip 需求，这些需求会被追加到根据用户当前软件环境自动生成的一组默认 pip 需求中。需求和约束会分别自动解析并写入 requirements.txt 和 constraints.txt 文件，并作为模型的一部分存储。需求也会被写入模型的 conda 环境（conda.yaml）文件的 pip 部分。 .. 警告:: 以下参数不能同时指定： - conda_env - pip_requirements - extra_pip_requirements 这个示例 展示了如何使用 pip_requirements 和 extra_pip_requirements 指定 pip 需求。

• metadata – 传递给模型并在 MLmodel 文件中存储的自定义元数据字典。