mlflow.shap

mlflow.shap.get_default_conda_env()[source]

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

mlflow.shap.get_default_pip_requirements()[source]: 此 flavor 生成的 MLflow Models 的默认 pip 依赖项列表。对 save_explainer() 和 log_explainer() 的调用会生成一个 pip 环境，该环境至少包含这些依赖项。

mlflow.shap.get_underlying_model_flavor(model)[source]

查找底层模型的 flavor。

Parameters: model – 解释器的底层模型。

mlflow.shap.load_explainer(model_uri)[source]

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

Parameters

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 方案的更多信息，请参见 Referencing Artifacts.

Returns

一个 SHAP 解释器。

mlflow.shap.log_explainer(explainer, artifact_path: str | None = None, serialize_model_using_mlflow=True, conda_env=None, code_paths=None, registered_model_name=None, signature: mlflow.models.signature.ModelSignature = None, input_example: Union[pandas.core.frame.DataFrame, numpy.ndarray, dict, list, csr_matrix, csc_matrix, str, bytes, tuple] = None, await_registration_for=300, pip_requirements=None, extra_pip_requirements=None, name: str | None = None, metadata=None, params: dict[str, typing.Any] | None = None, tags: dict[str, typing.Any] | None = None, model_type: str | None = None, step: int = 0, model_id: str | None = None)[source]

将 SHAP explainer 作为当前运行的 MLflow 工件记录。

Parameters

explainer – 要保存的 SHAP explainer。
artifact_path – 已弃用。请改用 name。
serialize_model_using_mlflow – 设置为 True 时，MLflow 将提取底层模型并将其序列化为 MLmodel，否则使用 SHAP 的内部序列化。默认值为 True。目前仅支持对 ‘sklearn’ 或 ‘pytorch’ 风格的模型进行 MLflow 序列化。
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 usage guide。
registered_model_name – 如果提供，则在 registered_model_name 下创建一个模型版本，如果没有具有给定名称的已注册模型，还会创建一个已注册模型。
signature –
ModelSignature 描述模型输入和输出 Schema。模型签名可以 inferred 从具有有效模型输入（例如省略目标列的训练数据集）和有效模型输出（例如在训练数据集上生成的模型预测）的数据集中推断，例如：
```
from mlflow.models import infer_signature

train = df.drop_column("target_label")
predictions = ...  # 计算模型预测
signature = infer_signature(train, predictions)
```
input_example – 一个或多个有效模型输入实例。输入示例用于提示应向模型提供何种数据。它将被转换为一个 Pandas DataFrame，然后使用 Pandas 的 split-oriented 格式序列化为 json，或者转换为一个 numpy array，其中示例将通过将其转换为列表的方式序列化为 json。字节使用 base64 编码。当 signature 参数为 None 时，输入示例用于推断模型签名。
await_registration_for – 等待模型版本完成创建并处于 READY 状态的秒数。默认情况下，该函数等待五分钟。指定 0 或 None 可跳过等待。
pip_requirements – 要么是一个 pip 依赖字符串的可迭代对象（例如 ["shap", "-r requirements.txt", "-c constraints.txt"]）或者本地文件系统上 pip requirements 文件的字符串路径（例如 "requirements.txt"）。如果提供了，它描述了应在其中运行该模型的环境。如果 None，则从当前软件环境通过 mlflow.models.infer_pip_requirements() 推断出默认的 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 文件的字符串路径（例如 "requirements.txt"）。如果提供，该参数描述了附加的 pip 依赖，这些依赖会被追加到基于用户当前软件环境自动生成的默认 pip 依赖集合中。requirements 和 constraints 会被自动解析并分别写入 requirements.txt 和 constraints.txt 文件，并作为模型的一部分存储。依赖项也会被写入模型的 conda 环境（conda.yaml）文件的 pip 部分。
警告

以下参数不能同时指定：
- conda_env
- pip_requirements
- extra_pip_requirements
This example 演示了如何使用 pip_requirements 和 extra_pip_requirements 指定 pip 依赖。
name – 模型名称。
metadata – 传递给模型并存储在 MLmodel 文件中的自定义元数据字典。
params – 一个用于与模型一同记录的参数字典。
tags – 一个要与模型一起记录的标签字典。
model_type – 模型的类型。
step – 在该步记录模型输出和指标
model_id – 模型的 ID。

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

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

基础值

SHAP 值 (使用 shap.KernelExplainer 计算)

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

Parameters

predict_function –
一个用于计算模型输出的函数（例如 scikit-learn 分类器的 predict_proba 方法）。必须具有以下签名：
```
def predict_function(X) -> pred: ...
```
- X：一个类数组对象，其形状应为（# samples, # features）。
- pred：一个类数组对象，对于回归器，其形状应为（# samples）；对于分类器，应为（# classes, # samples）。对于分类器，pred 中的值应对应于每个类别的预测概率。
可接受的类数组对象类型：
- numpy.array
- pandas.DataFrame
- shap.common.DenseData
- scipy.sparse matrix
features –
用于计算 SHAP 值的特征矩阵。所提供的 features 应具有形状 (# samples, # features)，并且可以是上面列出的任一类类数组对象。

注意

对于 shap.KernelExplainer 的背景数据，是通过对 features 使用 shap.kmeans 进行子抽样生成的。出于性能原因，背景数据的行数限制为 100 行。
artifact_path – 保存解释的相对于运行的 artifact 路径。如果未指定，默认为 “model_explanations_shap”。

Returns

已记录解释的 Artifact URI。

Example

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

Output

# 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: mlflow.models.signature.ModelSignature = None, input_example: Union[pandas.core.frame.DataFrame, numpy.ndarray, dict, list, csr_matrix, csc_matrix, str, bytes, tuple] = None, pip_requirements=None, extra_pip_requirements=None, metadata=None)[source]

将 SHAP 解释器保存到本地文件系统的路径。生成一个包含以下 flavors 的 MLflow Model：

mlflow.shap

mlflow.pyfunc

Parameters

explainer – 要保存的 SHAP explainer。
path – 用于保存解释器的本地路径。
serialize_model_using_mlflow – 当设置为 True 时，MLflow 将提取底层模型并将其序列化为一个 MLmodel，否则它使用 SHAP 的内部序列化。默认值为 True。目前 MLflow 序列化仅支持 ‘sklearn’ 或 ‘pytorch’ 风格的模型。
conda_env –
可以是 Conda 环境的字典表示，也可以是指向 conda 环境 yaml 文件的路径。若提供，则描述了该模型应在其中运行的环境。至少，应指定 get_default_conda_env() 中包含的依赖项。如果 None，则会为模型添加一个 conda 环境，其 pip 依赖由 mlflow.models.infer_pip_requirements() 推断得到。如果依赖推断失败，则退回使用 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 usage guide。
mlflow_model – mlflow.models.Model 此 flavor 正在被添加到。
signature –
ModelSignature 描述模型的输入和输出 Schema。模型签名可以从具有有效模型输入（例如省略目标列的训练数据集）和有效模型输出（例如在训练数据集上生成的模型预测）的数据集中通过 inferred 推断出来，例如：
```
from mlflow.models import infer_signature

train = df.drop_column("target_label")
predictions = ...  # 计算模型预测结果
signature = infer_signature(train, predictions)
```
input_example – 一个或多个有效模型输入实例。输入示例用于提示应向模型提供何种数据。它将被转换为一个 Pandas DataFrame，然后使用 Pandas 的 split-oriented 格式序列化为 json，或者转换为一个 numpy array，其中示例将通过将其转换为列表的方式序列化为 json。字节使用 base64 编码。当 signature 参数为 None 时，输入示例用于推断模型签名。
pip_requirements – 要么是一个可迭代的 pip 依赖字符串（例如 ["shap", "-r requirements.txt", "-c constraints.txt"]）要么是本地文件系统上 pip requirements 文件的字符串路径（例如 "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 文件的字符串路径（例如 "requirements.txt"）。如果提供，该参数描述了附加的 pip 依赖，这些依赖会被追加到基于用户当前软件环境自动生成的默认 pip 依赖集合中。requirements 和 constraints 会被自动解析并分别写入 requirements.txt 和 constraints.txt 文件，并作为模型的一部分存储。依赖项也会被写入模型的 conda 环境（conda.yaml）文件的 pip 部分。
警告

以下参数不能同时指定：
- conda_env
- pip_requirements
- extra_pip_requirements
This example 演示了如何使用 pip_requirements 和 extra_pip_requirements 指定 pip 依赖。
metadata – 传递给模型并存储在 MLmodel 文件中的自定义元数据字典。