Seldon Core v2 CLI 实战：seldon pipeline list 命令完整指南

本篇技术指南聚焦 Seldon Core v2 控制平面 CLI 中的 seldon pipeline list 命令。该命令用于向 Scheduler 服务查询并列出当前已加载的全部推理管线（Pipeline），以表格形式展示每个管线的名称、运行状态与状态原因。通过本文，你将掌握该命令的完整用法、全部参数含义、底层 gRPC 调用链与输出格式，并了解如何通过配置文件覆盖 Scheduler 地址，从而在日常 MLOps 运维中快速定位管线状态。

命令概述与适用场景

seldon pipeline list 是 seldon pipeline 子命令族（管理管线的入口命令）下的一个成员，其作用是列出当前 Seldon 控制平面中所有已加载的 Pipeline。在 Seldon Core v2 中，Pipeline 允许将多个模型拼接成推理图（inference graph），实现多模型串联、条件分支、数据变换等复杂推理流程。

在实际运维中，该命令最常出现在以下场景：

• 部署一批 Pipeline 后，快速确认哪些已成功加载、哪些处于创建中或失败状态；
• 排查推理异常时，核对目标管线是否存在及其当前状态原因（reason）；
• 配合 seldon pipeline load、seldon pipeline unload、seldon pipeline status 等命令，完成管线的完整生命周期管理。

其兄弟命令包括：seldon pipeline infer（对管线执行推理）、seldon pipeline inspect（检查管线中的数据）、seldon pipeline load（加载管线）、seldon pipeline status（查询单个管线状态）、seldon pipeline unload（卸载管线），命令族入口见 seldon pipeline。

命令用法与参数详解

命令语法

seldon pipeline list [flags]

该命令不需要任何位置参数，直接执行即可列出全部管线。

支持的 Flags

Flag	类型	默认值	说明
--authority string	string	空	authority（HTTP/2）或 virtual host（HTTP/1），用于自定义 gRPC 连接的主机名/虚拟主机头
-h, --help	bool	-	显示 list 子命令的帮助信息
--scheduler-host string	string	0.0.0.0:9004	Seldon Scheduler 服务的主机与端口
-v, --verbose	bool	false	输出详细的请求信息（打印发送给 Scheduler 的 gRPC 请求报文）

其中 --verbose 标志在官方 CLI 帮助文档（seldon_pipeline_list.md）中未列出，但从源码 pipeline_list.go 可以看到，实际命令同时注册了 -v/--verbose 标志：

flags := cmd.Flags()
flags.BoolP(flagVerbose, "v", false, "verbose output")
flags.String(flagSchedulerHost, env.GetString(envScheduler, defaultSchedulerHost), helpSchedulerHost)
flags.String(flagAuthority, "", helpAuthority)

参数优先级与配置覆盖

--scheduler-host 的解析遵循"命令行 > 环境变量 > CLI 配置文件 > 内置默认值"的优先级顺序，这一点从源码可以明确看出：

1. 内置默认值：defaultSchedulerHost = "0.0.0.0:9004"，定义于 flags.go；
2. 环境变量覆盖：flags.String(flagSchedulerHost, env.GetString(envScheduler, defaultSchedulerHost), ...) 会读取环境变量 SELDON_SCHEDULE_HOST 作为默认值（注意环境变量名为 SELDON_SCHEDULE_HOST，而非 SELDON_SCHEDULER_HOST），见 flags.go；
3. CLI 配置文件覆盖：在 scheduler.go 的 NewSchedulerClient 中，当命令行未显式设置 --scheduler-host（通过 flags.Changed(flagSchedulerHost) 判断）时，会进一步读取 $HOME/.config/seldon/cli/config.json 中的 controlplane.schedulerHost 字段覆盖地址：

// Overwrite host if set in config
if !schedulerHostIsSet && config.Controlplane != nil && config.Controlplane.SchedulerHost != "" {
    schedulerHost = config.Controlplane.SchedulerHost
}

配置文件结构定义于 config.go，示例如下：

{
  "controlplane": {
    "schedulerHost": "scheduler.namespace.svc.cluster.local:9004",
    "tls": true,
    "keyPath": "/path/to/client.key",
    "crtPath": "/path/to/client.crt",
    "caPath": "/path/to/ca.crt"
  }
}

当配置了 tls 与证书路径时，CLI 会通过 loadKeyPair 加载双向 TLS 证书与 CA 建立加密连接；未配置时则使用非安全连接（insecure credentials）。

底层实现：从命令到 gRPC 的调用链

命令入口

seldon pipeline list 的实现位于 pipeline_list.go，采用 Cobra 框架定义 list 子命令。执行流程为：解析 --scheduler-host、--authority、--verbose 三个标志 → 调用 cli.NewSchedulerClient(...) 构建 Scheduler 客户端 → 调用 schedulerClient.ListPipelines()。

gRPC 调用与输出格式化

核心逻辑 ListPipelines() 定义于 scheduler.go，实现要点如下：

1. 构造 scheduler.PipelineStatusRequest，设置 SubscriberName: "seldon CLI"，且不指定具体的 name 字段（proto 注释明确说明"Leave empty for all pipelines"，即留空表示查询全部管线）；
2. 建立 gRPC 连接并调用 PipelineStatus 双向流式 RPC，见 scheduler.proto；
3. 通过 tabwriter 输出对齐的表格，表头为 pipeline、state、reason 三列；
4. 对每个管线，取 res.Versions 中的最后一个元素（即最新版本）打印其状态与原因：

writer := tabwriter.NewWriter(os.Stdout, 0, 8, 1, '\t', tabwriter.AlignRight)
fmt.Fprintln(writer, "pipeline\tstate\treason")
fmt.Fprintln(writer, "--------\t-----\t------")
// 遍历流式响应
pv := res.Versions[len(res.Versions)-1]
fmt.Fprintf(writer, "%s\t%s\t%s\n", res.PipelineName, pv.State.Status.String(), pv.State.Reason)

与 ListModels 不同，ListPipelines 不会过滤已终止的管线，所有版本信息都会被列出。

输出的状态字段含义

PipelineVersionState 定义于 scheduler.proto，其状态枚举（status 字段）含义如下：

状态值	说明
PipelineStatusUnknown (0)	未知状态
PipelineCreate (1)	管线已提交创建
PipelineCreating (2)	管线正在创建中
PipelineReady (3)	管线已就绪，可接收推理请求
PipelineFailed (4)	管线创建失败
PipelineTerminate (5)	管线已请求终止
PipelineTerminating (6)	管线正在终止
PipelineTerminated (7)	管线已终止
PipelineRebalancing (8)	管线正在重新平衡（模型迁移/副本调整中）
PipelineFailedTerminating (9)	失败后的管线正在终止清理

reason 字段则记录了状态变更的具体原因文本（如 created pipeline）。此外，PipelineVersionState 还包含 modelsReady（底层模型是否就绪）、pipelineGwStatus（Pipeline Gateway 状态）、pipelineGwReason、lastChangeTimestamp（最后变更时间）等字段，可用于更深入的排查。

真实运行示例

以下示例取自仓库中的 CLI 端到端测试 cli-tests.md（对应的 Notebook 版本见 cli-tests.ipynb），展示了加载 cifar10-production 管线后的实际输出：

seldon pipeline list

pipeline		state		reason
--------		-----		------
cifar10-production	PipelineReady	created pipeline

可以看到：管线 cifar10-production 当前处于 PipelineReady 状态，原因记录为 created pipeline，说明其已成功加载并可以参与推理。若管线处于 PipelineCreating 或 PipelineFailed 状态，则 reason 列会给出相应的失败原因或进度说明，便于定位问题。

常见使用技巧与注意事项

指定远程 Scheduler

当 CLI 与 Scheduler 不在同一主机时，使用 --scheduler-host 指定地址：

seldon pipeline list --scheduler-host scheduler.mynamespace.svc:9004

启用 Verbose 调试

加 -v 可打印发送给 Scheduler 的请求内容，便于确认连接目标与请求参数：

seldon pipeline list -v

结合其他命令进行管线生命周期管理

• 加载管线后立即核对：seldon pipeline load -f pipeline.yaml && seldon pipeline list；
• 卸载后确认清理：seldon pipeline unload <name> && seldon pipeline list（已卸载管线将不再出现在列表中）；
• 单个管线深度状态查询：seldon pipeline status <name>。

注意事项

• 命令要求当前网络可达 Scheduler 的 gRPC 端口（默认 9004），否则会报连接错误；
• --scheduler-host 的值既支持 IP:Port，也支持 Kubernetes 内部 DNS 域名；
• 若同时配置了 CLI 配置文件与环境变量，优先顺序为命令行参数 > 配置文件 > 环境变量 > 默认值；
• 该命令只读，不会对控制平面产生任何副作用，可放心在排障时反复执行。

相关文档导航

• 父命令：seldon pipeline（管理管线的命令族入口）
• 同级命令：seldon pipeline infer、seldon pipeline inspect、seldon pipeline load、seldon pipeline status、seldon pipeline unload
• 顶层入口：seldon

如需深入源码：命令实现见 operator/cmd/seldon/cli/pipeline_list.go，Scheduler 客户端与输出逻辑见 operator/pkg/cli/scheduler.go，gRPC 接口定义见 apis/mlops/scheduler/scheduler.proto，端到端测试示例见 samples/cli-tests.md。