Seldon Core V2 Explainers 实战:基于 Alibi-Explain 与 MLServer 的模型/流水线可解释性配置指南

原创2026-10-14 15:37:241,750 阅读
文章标签:人工智能机器学习MLOpsLLMOps模型推理服务云原生容器编排微服务服务网格可观测性灰度发布后端

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/v1alpha1 API;
  • 解释器的执行运行时是 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)。就本仓库而言,可以从以下两处确认实际可用的类型:

  1. 官方示例中使用了 anchor_tabular(表格数据 Anchor 解释器)与 anchor_text(文本数据 Anchor 解释器),分别见 samples/models/income-explainer.yaml 与 samples/models/hf-sentiment-explainer.yaml。
  2. 仓库内的解释器模型生成脚本 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 主题,仓库提供了三个可深入研读的官方示例(均为本文关联文档所引用):

如果需要构建自己的解释器工件,可以复用仓库的生成脚本 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 解释结果。

这套机制使得模型解释能力与模型推理能力平起平坐,为生产环境中的模型审计、特征归因与结果验证提供了开箱即用的基础设施。

登录后查看全文
seldon-core