Seldon Core v2 CLI 模型状态查询指南:`seldon model status` 用法、等待条件与底层实现解析

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

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)

需要特别说明两点:

  1. --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 时才采用配置文件值)。

  2. -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. 轮询频率为 1 秒:每次查询后 time.Sleep(1 * time.Second);
  2. 只检查第一个版本:res.Versions[0],即最新/当前版本的状态;
  3. 状态为字符串精确匹配:比较的是 State.GetState().String() 与 -w 传入的字符串,所以 -w 的值必须与枚举字符串完全一致(如 ModelAvailable,大小写敏感);
  4. 超时由 -t 控制:超时后返回 Model wait status timeout 错误,命令以非零退出码结束;
  5. 无 -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):

  1. 命令行 --scheduler-host 显式指定;
  2. 未指定时,若存在已激活的 CLI 配置文件且 controlplane.schedulerHost 非空,则使用该值;
  3. 否则使用环境变量 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。

登录后查看全文
seldon-core