Seldon Core v2 CLI 模型状态查询指南:`seldon model status` 用法、等待条件与底层实现解析
Seldon Core v2 CLI 模型状态查询指南:seldon model status 用法、等待条件与底层实现解析
本文围绕 Seldon Core(v2,即 seldon-core 2.x)命令行工具中的
seldon model status子命令展开,讲解如何通过该命令查询已加载模型在调度器(scheduler)中的实时状态、各状态枚举的含义、-w等待条件的用法,并结合仓库源码剖析其基于 gRPC 流式接口的实现原理,帮助开发者把"模型是否就绪、能否推理"的判断自动化地集成到脚本与 CI 流程中。
seldon model status 是 Seldon Core v2 CLI 中用于查询单个模型状态的命令,位于 seldon model 命令组之下,与 seldon model load、seldon model unload、seldon model list 等命令并列。其官方命令文档位于 seldon_model_status.md,本文以该文档为骨架,结合 model_status.go 与 scheduler.go 等源码进行纵深解读。
一、命令概览与使用场景
1.1 命令位置与职责
在 CLI 命令树中,status 是 seldon model 的子命令。从 root.go 可以看出,seldon 根命令挂载了 model、server、experiment、pipeline、config 五个命令组,而 model 命令组又挂载了 load、unload、status、infer、metadata、list 六个子命令:
seldon
├── model
│ ├── load
│ ├── unload
│ ├── status ← 本文主题
│ ├── infer
│ ├── metadata
│ └── list
├── server
├── experiment
├── pipeline
└── config
status 的职责非常明确:获取指定名称模型的当前状态(Synopsis 原文为 "get the status for a model")。它通常配合 load 命令使用——先加载模型,再用 status 确认模型是否已经成功部署到某个模型服务器并处于可服务状态。
1.2 命令语法
seldon model status <modelName> [flags]
<modelName> 是必填的位置参数,且只能传一个。对应源码 model_status.go 中 Args: cobra.ExactArgs(1),传多传少都会直接报错。modelName 即通过 seldon model load(或在 Kubernetes 中创建 Model 自定义资源)时指定的模型名称。
二、完整命令选项说明
原文档给出的选项如下:
| 选项 | 短标志 | 默认值 | 说明 |
|---|---|---|---|
--authority string |
无 | 空字符串 | authority(HTTP/2)或虚拟主机(HTTP/1) |
-h, --help |
-h |
— | 显示 status 命令的帮助信息 |
--scheduler-host string |
无 | "0.0.0.0:9004" |
Seldon scheduler 主机地址 |
-r, --show-request |
-r |
false |
显示请求(见下方说明) |
-o, --show-response |
-o |
true |
显示响应(见下方说明) |
-w, --wait string |
-w |
空字符串 | 模型等待条件(model wait condition) |
需要特别说明两点:
-
--scheduler-host的默认值与环境变量:"0.0.0.0:9004"是 CLI 内置默认值。从源码 flags.go 可以看到,该标志的实际默认值由env.GetString(envScheduler, defaultSchedulerHost)决定,即优先读取环境变量SELDON_SCHEDULE_HOST,未设置时才回退到defaultSchedulerHost = "0.0.0.0:9004"。此外,若通过seldon config命令激活了 CLI 配置文件,则配置文件中controlplane.schedulerHost会覆盖命令行标志(详见 config.go 与 scheduler.go 中NewSchedulerClient的优先级逻辑:仅当命令行未显式指定--scheduler-host时才采用配置文件值)。 -
-r/-o标志的"保留"性质:虽然原文档的 Options 列表中列出了--show-request与--show-response,但在当前仓库的status子命令实现 model_status.go 中,实际注册的标志是-t/--timeout-secs、-v/--verbose、--scheduler-host、--authority、-w/--wait,并未注册-r/-o两个标志(--show-request/--show-response只出现在server status与model infer命令中,如 server_status.go)。因此在使用seldon model status时不要依赖这两个选项,它们更可能属于文档自动生成时的历史残留。下文以源码实际支持的五类标志为准。
2.1 源码中实际生效的完整标志
根据 model_status.go 的 RunE 与 flags 注册代码,seldon model status 实际支持:
seldon model status <modelName> [flags]
Flags:
-t, --timeout-secs int timeout seconds(默认 5)
-v, --verbose verbose output
--scheduler-host string seldon scheduler host(默认 "0.0.0.0:9004",可用 SELDON_SCHEDULE_HOST 覆盖)
--authority string authority (HTTP/2) or virtual host (HTTP/1)
-w, --wait string model wait condition
-h, --help help for status
-t, --timeout-secs:等待超时秒数,默认5秒(flagTimeoutDefault = int64(5),见 pipeline_inspect.go 中定义的同一常量,被各 status 类命令共用)。仅在指定-w等待条件时有意义。-v, --verbose:详细输出模式,开启后会把发出的 gRPC 请求ModelStatusRequest以 JSON 形式打印到标准输出(见 scheduler.go)。--authority:gRPC 连接的 authority 字段,用于 HTTP/2 场景下的虚拟主机名,或 HTTP/1 场景下的虚拟主机。在多集群或多租户通过同一入口访问 scheduler 时用于路由。-w, --wait:模型等待条件,取值为模型状态枚举的字符串形式(如ModelAvailable)。指定后命令会轮询等待直到模型进入该状态或超时,详见下文第三节。
三、模型状态的语义:proto 枚举与状态机
要正确使用 -w 等待条件,必须先理解 Seldon Core v2 中模型状态的全部取值。这些状态定义在 gRPC 接口的 proto 文件中:scheduler.proto 的 ModelStatus.ModelState 枚举:
ModelStateUnknown = 0 // 未知状态
ModelProgressing = 1 // 模型正在加载过程中
ModelAvailable = 2 // 模型可用(已就绪,可接受推理请求)
ModelFailed = 3 // 模型加载失败
ModelTerminating = 4 // 模型正在终止
ModelTerminated = 5 // 模型已终止
ModelTerminateFailed = 6 // 模型终止失败
ScheduleFailed = 7 // 调度失败
ModelScaledDown = 8 // 模型副本已缩容至 0
ModelCreate = 9 // 模型创建中
ModelTerminate = 10 // 模型终止中
其中与日常运维最相关的是:
ModelAvailable:目标就绪态,表示模型已成功加载到服务器副本并处于可用状态,可以开始接收推理流量。这是-w ModelAvailable最常见的等待目标。ModelProgressing/ModelCreate:加载过程中的中间态,load刚提交后通常会先观察到此类状态。ModelFailed/ScheduleFailed:失败态。ModelFailed表示模型在服务器上加载失败(如模型文件损坏、依赖缺失),ScheduleFailed表示调度器未能为该模型找到可用的服务器资源。ModelScaledDown:模型因缩容(如 HPA 将副本缩至 0)而暂时不可用,但并未被卸载。
3.1 响应结构:不仅是状态
从 proto 定义 scheduler.proto 可知,ModelStatusResponse 的完整结构为:
modelName:模型名称;versions:ModelVersionStatus列表,每个版本包含version(版本号)、serverName(承载该模型的服务器名)、modelReplicaState(每个副本的ModelReplicaStatus映射)、state(ModelStatus,含 state、reason、availableReplicas、unavailableReplicas、lastChangeTimestamp 等)、modelDefn(模型定义);deleted:模型是否已删除;timestamp、operation:事件时间戳与操作类型(ModelCreate/ModelDelete)。
ModelStatus 中还有两个对排障很有价值的字段:reason(状态原因描述,如加载失败的具体原因)和 availableReplicas / unavailableReplicas(可用/不可用副本数)。seldon model list 命令输出的 model / state / reason 三列正是取自这些字段(见 scheduler.go)。
四、-w 等待条件:把状态查询变成状态等待
4.1 用法示例
在脚本中,load 模型后通常需要等待模型真正可用,而不是立刻开始推理。两种常用做法:
做法一:使用 -w 让命令本身等待
# 加载模型
seldon model load -f mymodel.yaml
# 等待模型进入 ModelAvailable 状态(最长等待 60 秒)
seldon model status mymodel -w ModelAvailable -t 60
# 等待后即可放心调用推理
seldon model infer mymodel --inference-mode grpc
命令在模型未达到目标状态时会每秒轮询一次;达到目标状态后立即退出(退出码 0);超过 -t 指定的秒数仍未达到则返回错误 Model wait status timeout。
做法二:不指定 -w,单次查询状态后自行判断
seldon model status mymodel
此时命令只查询一次并立即返回当前状态的 JSON 输出,由调用方解析 versions[0].state.state 字段自行决定后续动作。
4.2 等待实现的源码解析
等待逻辑位于 scheduler.go 的 ModelStatus 方法:
if waitCondition != "" {
secsStart := time.Now().Unix()
for {
res, err := sc.getModelStatus(grpcClient, req)
if err != nil {
return nil, err
}
if len(res.Versions) > 0 {
modelStatus := res.Versions[0].State.GetState().String()
if modelStatus == waitCondition {
break
}
}
time.Sleep(1 * time.Second)
if time.Now().Unix()-secsStart > (timeout.Milliseconds() / 1000) {
return nil, fmt.Errorf("Model wait status timeout")
}
}
}
关键行为可以总结为:
- 轮询频率为 1 秒:每次查询后
time.Sleep(1 * time.Second); - 只检查第一个版本:
res.Versions[0],即最新/当前版本的状态; - 状态为字符串精确匹配:比较的是
State.GetState().String()与-w传入的字符串,所以-w的值必须与枚举字符串完全一致(如ModelAvailable,大小写敏感); - 超时由
-t控制:超时后返回Model wait status timeout错误,命令以非零退出码结束; - 无
-w时单次查询:直接调用getModelStatus返回第一次收到的响应。
4.3 底层 gRPC 接口
ModelStatus 的底层是对 scheduler 服务的流式 RPC 调用。proto 中 scheduler.proto 定义:
rpc ModelStatus(ModelStatusRequest) returns (stream ModelStatusResponse) {}
也就是说 ModelStatus 是一个 server-streaming RPC:CLI 作为订阅者以 subscriberName = "seldon CLI"(见 scheduler.go)身份发起 ModelStatusRequest,scheduler 持续推送该模型的状态更新流。CLI 在 getModelStatus 中通过 stream.Recv() 收取第一条消息即作为当前快照返回(见 scheduler.go 注释 "There should only be one result")。整个连接过程还配置了指数退避重试(grpc_retry.BackoffExponential(100 * time.Millisecond))以及最大消息尺寸(math.MaxInt32),并对 TLS 与普通连接做了兼容处理(见 scheduler.go)。
4.4 与通用 seldon status 命令的关系
值得注意的是,CLI 还提供了一个通用的 seldon status 命令(区别于 model status)。它读取 YAML 文件中的资源并批量查询状态,其实现 generic.go 内部正是复用了 ModelStatus:
case model:
if wait {
waitCondition = "ModelAvailable"
}
res, err = sc.ModelStatus(resource.name, waitCondition, timeout)
也就是说,无论通过 seldon model status mymodel -w ModelAvailable 还是 seldon status -f models.yaml(带 wait 标志),最终都会走到同一个 ModelStatus 轮询逻辑,且通用命令对模型约定的等待条件固定为 ModelAvailable。这进一步印证了 ModelAvailable 就是"模型可用"的标准等待目标。
五、输出格式与典型返回示例
命令成功时,CLI 通过 cli.PrintProto(res)(见 scheduler.go)将 proto 消息以 protojson 序列化为 JSON 打印到标准输出。典型输出形如:
{
"modelName": "mymodel",
"versions": [
{
"version": 1,
"serverName": "mlserver-0",
"state": {
"state": "ModelAvailable",
"reason": "",
"availableReplicas": 1,
"unavailableReplicas": 0
}
}
],
"deleted": false,
"timestamp": "1710000000",
"operation": "ModelCreate"
}
实际字段以 proto 定义为准(lastChangeTimestamp、modelReplicaState 等字段在副本异常时也会出现)。解析时建议关注 versions[0].state.state 与 versions[0].state.reason 两个字段;在 Kubernetes 环境下,versions 中还可能携带 kubernetesMeta(namespace、generation)信息。
配合 -v 标志可以同时看到 CLI 发出的 ModelStatusRequest 请求体(verbose 输出在 scheduler.go):
{"subscriberName":"seldon CLI","model":{"name":"mymodel"}}
这在排查"查不到状态/连不上 scheduler"问题时非常有用。
六、连接配置与常见问题
6.1 scheduler 地址的解析优先级
scheduler-host 最终值的确定顺序为(对应 NewSchedulerClient):
- 命令行
--scheduler-host显式指定; - 未指定时,若存在已激活的 CLI 配置文件且
controlplane.schedulerHost非空,则使用该值; - 否则使用环境变量
SELDON_SCHEDULE_HOST(默认值0.0.0.0:9004)。
6.2 开启 TLS 控制面
若 scheduler 启用了 TLS(如 values-tls-dataplane-controlplane-example.yaml 演示的集群场景),需要在 CLI 配置中提供证书路径。配置结构定义在 config.go:
{
"controlplane": {
"schedulerHost": "scheduler.seldon:9004",
"tls": true,
"keyPath": "/path/to/client.key",
"crtPath": "/path/to/client.crt",
"caPath": "/path/to/ca.crt"
}
}
连接建立时,若配置中 Controlplane.KeyPath 非空则加载双向 TLS 证书(见 scheduler.go),否则使用不加密连接。具体配置文件的添加与激活方式见 seldon_config_add.md。
6.3 典型排障路径
Model wait status timeout:模型在-t秒内未进入目标状态。用不带-w的查询看当前卡在哪个状态;若为ModelFailed,查看reason字段;若为ModelProgressing长期不推进,检查模型存储 URI 是否可达、服务器副本是否健康。- 连接报错(
connection refused等):确认 scheduler 地址、端口与 TLS 配置是否正确;本地开发时默认0.0.0.0:9004对应scheduler部署暴露的控制面端口。 cobra.ExactArgs相关报错:status只接受一个模型名,多传或漏传都会报错。
七、总结
seldon model status 是 Seldon Core v2 CLI 中连接"加载模型"与"开始推理"这两个环节的关键命令。通过 -w ModelAvailable -t <秒> 的组合,开发者可以把"等待模型就绪"这一易错环节交给 CLI 以 1 秒粒度的轮询自动完成,从而安全地在脚本、Notebook 与 CI 流水线中串起 load → wait → infer 的完整流程。理解其背后的 ModelStatus 流式 RPC、ModelAvailable 等状态枚举以及 scheduler-host 的解析优先级,能帮助你在多集群、TLS 等复杂环境下快速定位问题。
如需了解完整的 CLI 命令体系,可继续阅读 seldon_model.md(model 命令组总览)与 seldon.md(CLI 全局说明);模型加载与推理命令分别见 seldon_model_load.md 与 seldon_model_infer.md。