Seldon Core V2 Explainers 实战:基于 Alibi-Explain 与 MLServer 的模型/流水线可解释性配置指南
Seldon Core V2 Explainers 实战:基于 Alibi-Explain 与 MLServer 的模型/流水线可解释性配置指南
导读
本文以 Seldon Core V2 的 Explainers 文档 为主线,系统讲解如何通过为 Model 资源添加 explainer 配置块,把 Alibi-Explain 库中的黑盒解释器(如 AnchorTabular、AnchorText)以独立模型的形式部署到 MLServer 运行时上,从而为普通模型或完整 Pipeline 提供局部可解释性。读完本文,你将掌握 Explainer 资源的字段语义、modelRef 与 pipelineRef 的选择规则、Pipeline 级解释的配置方法,以及从加载、推理到卸载的完整 CLI 操作流程,并理解该功能在 Operator、Scheduler 与 Agent 三层中的底层实现机制。
一、Explainer 是什么:带额外设置的 Model 资源
在 Seldon Core V2 中,Explainer 本质上是普通的 Model 资源,只是在其 spec 中多了一个 explainer 配置块。这个配置块告诉调度器与运行时:该模型不是一个普通推理模型,而是一个基于 Alibi-Explain 库构建的解释器。这样,用户不需要单独学习一套新的 API,只需遵循既有的模型加载、状态查看、推理与卸载流程,即可获得模型预测的局部解释。
官方文档明确指出其核心能力:
Explainers are Model resources with some extra settings. They allow a range of explainers from the Alibi-Explain library to be run on MLServer.
这意味着:
- 解释器与模型共用同一套
mlops.seldon.io/v1alpha1API; - 解释器的执行运行时是 MLServer(其
alibi-explain运行时由 MLServer 项目提供); - 解释器的模型工件通过
storageUri指向一个已保存的 Alibi-Explain 解释器对象。
二、最小可运行示例:Anchor Tabular 黑盒解释器
下面是官方文档给出的 Anchors 解释器定义示例,完整文件位于 samples/models/income-explainer.yaml:
apiVersion: mlops.seldon.io/v1alpha1
kind: Model
metadata:
name: income-explainer
spec:
storageUri: "gs://seldon-models/scv2/samples/mlserver_1.6.0/income-sklearn/anchor-explainer"
explainer:
type: anchor_tabular
modelRef: income
这个配置与普通模型的差异全部集中在 spec.explainer 中,文档将其称为"关键新增项"(key additions):
| 字段 | 含义 | 约束 |
|---|---|---|
type |
解释器类型 | 必须是 Alibi-Explain runtime 在 MLServer 中支持的 Alibi Explainer 类型之一 |
modelRef |
黑盒解释器所要解释的目标模型名称 | 用于解释模型,与 pipelineRef 二选一 |
pipelineRef |
黑盒解释器所要解释的目标流水线名称 | 用于解释流水线,与 modelRef 二选一 |
modelRef 与 pipelineRef 只能且必须设置其中一个——官方文档用 "Only one of modelRef and pipelineRef is allowed" 明确约束了这一规则。其中 type 的取值决定了解释器运行时加载哪种 Alibi 算法(如表格数据的 anchor_tabular、文本数据的 anchor_text),该值会在部署时被注入到 MLServer 的模型设置文件中,详见本文第五节的源码分析。
字段级别的源码印证
在 CRD 的类型定义 operator/apis/mlops/v1alpha1/model_types.go 中,ExplainerSpec 的结构与上述三个字段一一对应:
// Either ModelRef or PipelineRef is required
type ExplainerSpec struct {
// type of explainer
Type string `json:"type,omitempty"`
// one of the following need to be set for blackbox explainers
// Reference to Model
// +optional
ModelRef *string `json:"modelRef,omitempty"`
// Reference to Pipeline
// +optional
PipelineRef *string `json:"pipelineRef,omitempty"`
}
代码注释 "Either ModelRef or PipelineRef is required" 与文档表述完全一致。此外,ModelSpec 还定义了 Explainer 与 Llm(LLM 网关配置)互斥的校验规则(model_types.go):
func (m *ModelSpec) Validate() error {
if m.Explainer != nil && m.Llm != nil {
return fmt.Errorf("Can't have both explainer and llm in model spec.")
}
return nil
}
三、支持的解释器类型
type 字段的可选值由 MLServer 的 Alibi Explain 运行时维护(原文档指向 MLServer 仓库中 mlserver_alibi_explain 包内的 alibi_dependency_reference.py)。就本仓库而言,可以从以下两处确认实际可用的类型:
- 官方示例中使用了
anchor_tabular(表格数据 Anchor 解释器)与anchor_text(文本数据 Anchor 解释器),分别见 samples/models/income-explainer.yaml 与 samples/models/hf-sentiment-explainer.yaml。 - 仓库内的解释器模型生成脚本 samples/scripts/explainers/make_test_models.py 导入了 Alibi 的多种解释器(
ALE, AnchorImage, AnchorTabular, AnchorText, KernelShap, TreeShap等),并分别提供make_anchor_tabular、make_anchor_tabular_income、make_anchor_text_moviesentiment等生成函数,可作为构建自定义解释器工件的参考。
需要注意的是:具体某个 type 能否运行,还取决于承载它的服务器是否具备 alibi-explain 能力(见第五节的调度过滤逻辑)。在使用前应确保 type 值在目标 MLServer 版本的 Alibi Explain 运行时受支持。
四、Pipeline 级解释:Explainer 解释整个流水线
黑盒解释器不仅可以解释单个模型,还可以解释一个 Pipeline。此时不再引用 modelRef,而是通过 pipelineRef 指向已加载的流水线。
官方文档给出的示例来自 Huggingface 情感分析演示(speech-to-sentiment),完整文件位于 samples/models/hf-sentiment-explainer.yaml:
apiVersion: mlops.seldon.io/v1alpha1
kind: Model
metadata:
name: sentiment-explainer
spec:
storageUri: "gs://seldon-models/scv2/examples/huggingface/speech-sentiment/explainer"
explainer:
type: anchor_text
pipelineRef: sentiment-explain
这里 pipelineRef: sentiment-explain 表示该 AnchorText 解释器将对名为 sentiment-explain 的流水线进行黑盒解释。仓库中还有一个类似的反例配置——samples/models/income-explainer-pipeline.yaml 使用 type: anchor_tabular 搭配 pipelineRef: income-prod,展示了同一解释器类型既可用于模型也可用于流水线的灵活性。
为什么可以解释 Pipeline? 从底层实现看,解释器与被解释对象之间通过"推理 URI"建立联系。黑盒解释器在运行时会向该 URI 发起推理请求来反复探测预测结果,从而构造解释。当目标是一个 Pipeline 时,这个 URI 就指向流水线的推理端点(见第五节 infer_uri 的构造逻辑)。
五、源码视角:Explainer 在 Seldon Core V2 中的完整实现链路
为了深入理解 explainer 配置块的实际作用,下面沿着"Operator → Scheduler → Agent → MLServer"这条链路追踪其实现。
5.1 Operator:CRD 到 Scheduler Proto 的转换
当用户提交包含 explainer 的 Model 资源后,Operator 会调用 Model.AsSchedulerModel() 方法将其转换为调度器可识别的 protobuf 消息(operator/apis/mlops/v1alpha1/model_types.go):
if m.Spec.Explainer != nil {
md.ModelSpec.ModelSpec = &scheduler.ModelSpec_Explainer{
Explainer: &scheduler.ExplainerSpec{
Type: m.Spec.Explainer.Type,
ModelRef: m.Spec.Explainer.ModelRef,
PipelineRef: m.Spec.Explainer.PipelineRef,
},
}
}
可以看到 type、modelRef、pipelineRef 三个字段被原样传入 scheduler.ExplainerSpec,随后由调度器依据该信息决定在哪个服务器副本上加载此解释器。对应的单元测试见 operator/apis/mlops/v1alpha1/model_types_test.go,其中构造了带 ExplainerSpec 的复杂模型并断言其转换为 ModelSpec_Explainer 的结果。
5.2 Scheduler:解释器模型的调度过滤
并非所有服务器都能承载解释器。调度器的 ExplainerFilter(scheduler/pkg/scheduler/filters/explainer.go)规定:只有当服务器副本声明了 alibi-explain 能力时,带有 explainer 配置的模型才能被调度到该副本:
const (
alibiExplainerRequiredCapability = "alibi-explain"
)
func (s ExplainerFilter) Filter(model *store.ModelVersion, replica *store.ServerReplica) bool {
if model.GetModel().GetModelSpec().GetExplainer() != nil {
for _, capability := range replica.GetCapabilities() {
if alibiExplainerRequiredCapability == capability {
return true
}
}
return false
}
return true
}
在仓库自带的 MLServer 服务器配置 operator/config/serverconfigs/mlserver.yaml 中,SELDON_SERVER_CAPABILITIES 环境变量明确包含了 alibi-explain:
value: "mlserver,alibi-detect,alibi-explain,huggingface,lightgbm,mlflow,python,sklearn,spark-mlib,xgboost"
这就是为什么 Anchor 类解释器可以默认跑在标准 MLServer 服务器上的原因。
5.3 Agent:把解释器信息写入 MLServer 设置
模型工件被下载并拷贝到模型仓库后,Agent 会调用 SetExplainer 为解释器模型生成/改写 MLServer 的 model-settings.json(scheduler/pkg/agent/repository/mlserver/mlserver.go):
func (m *MLServerRepositoryHandler) SetExplainer(modelRepoPath string, explainerSpec *scheduler.ExplainerSpec, envoyHost string, envoyPort int) error {
if explainerSpec != nil {
return m.setExtraParameters(
modelRepoPath,
explainerSpec.ModelRef,
explainerSpec.PipelineRef,
envoyHost,
envoyPort,
map[string]interface{}{
explainerTypeKey: explainerSpec.Type,
},
)
}
return nil
}
其核心逻辑 setExtraParameters(mlserver.go)会向模型设置中写入两个关键参数:
explainer_type(explainerTypeKey):即配置中的type,MLServer 的 Alibi Explain 运行时据此选择解释算法;infer_uri(inferUriKey):黑盒解释器执行时用来探测被解释对象推理结果的地址。它由modelRef与pipelineRef二选一决定,两个常量定义在 mlserver.go:
func (m *MLServerRepositoryHandler) setExtraParameters(...) error {
...
var inferUri string
if modelRef != nil {
inferUri = fmt.Sprintf("%s://%s:%d/v2/models/%s/infer", scheme, envoyHost, envoyPort, *modelRef)
} else {
inferUri = fmt.Sprintf("%s://%s:%d/v2/pipelines/%s/infer", scheme, envoyHost, envoyPort, *pipelineRef)
}
...
}
这正是"只能设置一个 modelRef 或 pipelineRef"这一规则的实现原因——二者在代码层面是 if/else 互斥的,且分别对应 /v2/models/{name}/infer 与 /v2/pipelines/{name}/infer 两个不同的推理端点。此外,该方法还会把 parallelWorkers 临时置为 0(源码注释说明这是针对 MLServer 解释器的临时修复)。
SetExplainer 的调用点位于 Agent 的模型下载流程 scheduler/pkg/agent/repository/model_repository.go:DownloadModelVersion 从 modelSpec.GetExplainer() 取出解释器规格,在模型版本目录准备就绪后调用 SetExplainer 写入配置。
5.4 单元测试佐证
仓库为上述行为提供了充分的单元测试,见 scheduler/pkg/agent/repository/mlserver/mlserver_test.go。其中 "set explainer - basic" 用例断言了写入 model-settings.json 的结果:
explainerTypeKey: "anchor_tabular",
inferUriKey: "http://0.0.0.0:9000/v2/models/mymodel/infer",
即 anchor_tabular 类型被写入 explainer_type,而 infer_uri 指向了 modelRef 对应的 /v2/models/mymodel/infer 端点,与源码逻辑互相印证。
六、端到端实操:加载、推理与卸载一个 Anchor Tabular 解释器
下面以仓库自带的收入分类(income)示例为主线,展示从模型加载到获得解释结果的完整流程。完整步骤记录在 samples/explainer-examples.md。
6.1 先加载被解释的目标模型
解释器要正常工作,其 modelRef 指向的模型必须已经可用。首先加载收入分类模型(samples/models/income.yaml):
seldon model load -f ./models/income.yaml
{}
seldon model status income -w ModelAvailable
{}
此时可以对模型发起一次普通推理,得到基线预测结果(predict 输出为 0,即收入不超过阈值):
seldon model infer income \
'{"inputs": [{"name": "predict", "shape": [1, 12], "datatype": "FP32", "data": [[47,4,1,1,1,3,4,1,0,0,40,9]]}]}'
{
"model_name": "income_1",
"model_version": "1",
"id": "c65b8302-85af-4bac-aac5-91e3bedebee8",
"outputs": [
{
"name": "predict",
"shape": [1, 1],
"datatype": "INT64",
"data": [0]
}
]
}
6.2 加载解释器
接着加载解释器模型(即本文第二节的配置):
seldon model load -f ./models/income-explainer.yaml
{}
seldon model status income-explainer -w ModelAvailable
{}
在 Kubernetes 集群环境中,也可以改用 kubectl 完成同样的操作(参见 samples/k8s-explainers.md):
kubectl create -f ./models/income-explainer.yaml -n ${NAMESPACE}
kubectl wait --for condition=ready --timeout=300s model --all -n ${NAMESPACE}
6.3 请求解释
对解释器发起与目标模型完全相同的推理请求,输出名称变为 explanation,datatype 为 BYTES、content_type 为 str,其中携带完整的 Anchor 解释 JSON:
seldon model infer income-explainer \
'{"inputs": [{"name": "predict", "shape": [1, 12], "datatype": "FP32", "data": [[47,4,1,1,1,3,4,1,0,0,40,9]]}]}'
{
"model_name": "income-explainer_1",
"model_version": "1",
"id": "a22c3785-ff3b-4504-9b3c-199aa48a62d6",
"outputs": [
{
"name": "explanation",
"shape": [1, 1],
"datatype": "BYTES",
"parameters": {
"content_type": "str"
},
"data": ["{\"meta\": {...}, \"data\": {...}}"]
}
]
}
6.4 解读 Anchor 解释结果
上述 JSON 字符串的结构包含两个部分:
meta:解释器元信息,包括算法名AnchorTabular、类型["blackbox"]、解释范围["local"]、参数(如threshold: 0.95、delta: 0.1、tau: 0.15、beam_size: 1、coverage_samples: 10000等)以及 Alibi 版本号。data:解释结果,核心字段为:anchor:锚点特征条件列表,例如["Marital Status = Never-Married", "Relationship = Own-child"]——即只要这些条件成立,模型就以较高概率维持当前预测;precision:锚点在探测样本上的精确度(如0.9518716577540107);coverage:锚点覆盖的样本比例(如0.07165109034267912);prediction与instance:被解释实例的原始预测与输入。
6.5 卸载清理
演示结束后依次卸载解释器与目标模型:
seldon model unload income-explainer
{}
seldon model unload income
{}
七、第二个示例:Anchor Text 电影情感解释器
仓库的 samples/explainer-examples.md 还提供了针对文本分类的完整示例。被解释模型为 SKLearn 电影情感模型(samples/models/moviesentiment.yaml),解释器配置见 samples/models/moviesentiment-explainer.yaml:
apiVersion: mlops.seldon.io/v1alpha1
kind: Model
metadata:
name: sentiment-explainer
spec:
storageUri: "gs://seldon-models/scv2/samples/mlserver_1.6.0/moviesentiment-sklearn-explainer"
explainer:
type: anchor_text
modelRef: sentiment
文本推理时请求需要带 content_type: str 参数:
seldon model infer sentiment \
'{"parameters": {"content_type": "str"}, "inputs": [{"name": "foo", "data": ["I am good"], "datatype": "BYTES","shape": [1]}]}'
对解释器发起同样请求:
seldon model infer sentiment-explainer \
'{"parameters": {"content_type": "str"}, "inputs": [{"name": "foo", "data": ["I am good"], "datatype": "BYTES","shape": [1]}]}'
注意:官方示例中该请求会返回 500 错误,其堆栈显示错误源自 MLServer 的 Alibi Explain 运行时(mlserver_alibi_explain/runtime.py 中的 _async_explain_impl 与 black_box_runtime.py 中的 input_data[0] 抛出 KeyError: 0)。这提示我们:黑盒解释器对请求张量的组织形式有严格要求,实际使用中若遇到类似错误,应检查输入张量的 datatype、shape 与批量维度是否符合解释器运行时的预期。这也说明文档示例保留了真实运行中可能遇到的失败场景,具有很高的参考价值。
八、更多官方示例与延伸阅读
围绕 Explainer 主题,仓库提供了三个可深入研读的官方示例(均为本文关联文档所引用):
- Tabular income classification model with Anchor Tabular black box model explainer:收入分类模型的完整生产部署流程,包括模型、漂移检测、异常检测与解释器共存的流水线示例,以及
seldon model infer income-explainer的实际返回 JSON; - Huggingface Sentiment model with Anchor Text black box pipeline explainer:语音转情感流水线的 Pipeline 级解释演示;
- Anchor Text movies sentiment explainer:电影情感文本解释器示例(该页面内容直接 include 自 samples/explainer-examples.md)。
如果需要构建自己的解释器工件,可以复用仓库的生成脚本 samples/scripts/explainers/Makefile 与 samples/scripts/explainers/make_test_models.py:该脚本使用 Alibi 的 AnchorTabular、AnchorText 等解释器在训练数据上 fit 后 save 到目录,再通过 gsutil 上传为 storageUri 指向的存储位置,从而形成与官方示例一致的"可加载解释器"。
九、小结
Seldon Core V2 通过"带额外设置的 Model 资源"这一简洁抽象,将 Alibi-Explain 生态无缝接入其统一的模型管理、调度与推理体系:
- 配置面:只需在
Model的spec.explainer中声明type与modelRef/pipelineRef(二选一),即可把解释器当作普通模型加载、推理与卸载; - 能力面:调度器通过
alibi-explain能力标签保证解释器只会被调度到合适的 MLServer 副本; - 运行面:Agent 在加载阶段自动生成
explainer_type与infer_uri等 MLServer 设置,黑盒解释器通过infer_uri探测目标模型或流水线,最终以BYTES类型的explanation输出返回可读的 Anchor 解释结果。
这套机制使得模型解释能力与模型推理能力平起平坐,为生产环境中的模型审计、特征归因与结果验证提供了开箱即用的基础设施。