KServe V1beta1CustomTransformer 模型全解析:自定义 Transformer 的 PodSpec 配置字段与源码实现

原创2026-10-11 12:14:151,984 阅读
文章标签:模型推理服务人工智能大模型云原生后端微服务本地部署

KServe V1beta1CustomTransformer 模型全解析:自定义 Transformer 的 PodSpec 配置字段与源码实现

导读

V1beta1CustomTransformer 是 KServe Python SDK 中用于配置自定义 Transformer(Custom Transformer)的 OpenAPI 数据模型。在 KServe 推理服务中,Transformer 承担请求的前置/后置处理(pre/post processing)职责,而自定义 Transformer 允许用户通过一个完整的 Kubernetes PodSpec 定义自己的预处理/后处理容器。本文将以 V1beta1CustomTransformer.md 为主体,逐字段讲解其全部 43 个属性,并深入 Go 侧 API 实现与 Python SDK 生成代码,同时给出可直接套用的 YAML 与 Python 示例,帮助读者完整掌握"如何在 KServe 中声明一个自定义 Transformer"。

一、Transformer 在 KServe 推理管线中的角色

KServe 的 InferenceService 支持 predictor(预测器)、transformer(转换器)与 explainer(解释器)三类组件。Transformer 位于推理管线中间,负责:

  • 前置处理(pre-processing):将客户端原始请求转换为 Predictor 期望的输入格式;
  • 后置处理(post-processing):将 Predictor 的原始输出转换为客户端期望的响应格式。

从 API 定义看,TransformerSpec 是一个"双重用途"的结构:transformer.go 中的注释明确指出:

  1. 提供一个完整的 PodSpec 用于自定义 Transformer,此时 PodSpec.Containers 与其他 Transformer 类型互斥;
  2. 提供 Transformer 类型并指定 PodSpec 覆盖项,此时不得再提供 PodSpec.Containers。

其中 GetImplementations() 方法展示了分流逻辑:当用户在 spec.transformer 中直接给出了 containers 时,KServe 就把它当作自定义 Transformer 处理(transformer.go):

func (s *TransformerSpec) GetImplementations() []ComponentImplementation {
	implementations := []ComponentImplementation{}
	// This struct is not a pointer, so it will never be nil; include if containers are specified
	if len(s.Containers) != 0 {
		implementations = append(implementations, NewCustomTransformer(&s.PodSpec))
	}
	return implementations
}

也就是说,只要在 transformer 段下声明了 containers,KServe 就会创建 CustomTransformer 实现——这正是本文 V1beta1CustomTransformer 模型所描述的配置对象。

二、V1beta1CustomTransformer 数据模型概览

在 Python SDK 中,V1beta1CustomTransformer 由 OpenAPI Generator 自动生成(见 v1beta1_custom_transformer.py),其本质是对 Kubernetes corev1.PodSpec 的完整映射。Go 侧的类型定义则更为直接——transformer_custom.go 中:

// CustomTransformer defines arguments for configuring a custom transformer.
type CustomTransformer struct {
	corev1.PodSpec `json:",inline"`
}

CustomTransformer 直接内嵌(inline)了整个 Kubernetes PodSpec,因此 V1beta1CustomTransformer 的属性表几乎与 PodSpec 一一对应,覆盖容器定义、网络、DNS、调度、生命周期、安全、存储等全部维度。

值得注意的是,该模型有且只有一个必填字段:containers。这一点在 OpenAPI 定义(swagger.json)与 Python 校验逻辑中均有体现:

"v1beta1.CustomTransformer": {
  "description": "CustomTransformer defines arguments for configuring a custom transformer.",
  "type": "object",
  "required": [ "containers" ],
  ...
}

Python 侧对应校验(v1beta1_custom_transformer.py):

if self.local_vars_configuration.client_side_validation and containers is None:
    raise ValueError("Invalid value for `containers`, must not be `None`")

三、全部字段属性参考(43 个字段完整清单)

下表完整继承原文档的全部属性,按用途划分为 5 组,保留原始类型定义与语义描述(全部字段均为 [optional],除 containers 外)。

3.1 容器与卷(核心负载定义)

字段名(Python / JSON) 类型 说明
containers list[V1Container] 属于该 Pod 的容器列表。容器目前不能被添加或移除;一个 Pod 中必须至少有一个容器;创建后不可更新。(必填字段)
init_containers list[V1Container] 初始化容器列表,在普通容器启动前按顺序执行。任一初始化容器失败,Pod 视为失败并按 restartPolicy 处理。初始化容器不允许配置 Lifecycle、Readiness、Liveness 或 Startup 探针;创建后不可增删、不可更新。
ephemeral_containers list[V1EphemeralContainer] 在现有 Pod 中运行的临时容器(用于调试等用户主动操作)。创建 Pod 时不能指定,也不能通过更新 PodSpec 修改;只能通过 Pod 的 ephemeralcontainers 子资源添加。
volumes list[V1Volume] 可被 Pod 内容器挂载的卷列表。
image_pull_secrets list[V1LocalObjectReference] 同一命名空间内、用于拉取 Pod 镜像的 Secret 引用列表。
resources V1ResourceRequirements Pod 内容器的资源请求与限制(requests/limits)。

3.2 网络、DNS 与主机命名

字段名(Python / JSON) 类型 说明
dns_policy str Pod 的 DNS 策略,默认 ClusterFirst。合法值:ClusterFirstWithHostNet、ClusterFirst、Default、None。DNSConfig 中的参数会与 DNSPolicy 选择的策略合并;要在 hostNetwork 下设置 DNS 选项,必须显式指定 ClusterFirstWithHostNet。
dns_config V1PodDNSConfig Pod 的 DNS 参数配置(nameservers、searches、options)。
host_network bool 请求使用宿主机网络命名空间,默认 false。启用时端口定义中的 hostPort 必须与 containerPort 一致,未指定的 hostPort 会被默认成 containerPort。
host_pid bool 使用宿主机的 PID 命名空间,默认 false。
host_ipc bool 使用宿主机的 IPC 命名空间,默认 false。
host_users bool 使用宿主机用户命名空间,默认 true。设为 true 或不设置时 Pod 运行在宿主机用户命名空间(适用于需要 CAP_SYS_MODULE 加载内核模块等场景);设为 false 时为 Pod 创建新的 userns,可缓解容器逃逸漏洞。
host_aliases list[V1HostAlias] 可选的主机名与 IP 列表,若指定会注入到 Pod 的 hosts 文件中。
hostname str 指定 Pod 的 hostname;未指定时使用系统定义值。
hostname_override str 对 Pod 感知到的 hostname 的显式覆盖。设置非空字符串时:优先于 hostname 和 subdomain;Pod hostname 被设为该值;setHostnameAsFQDN 必须为 nil 或 false;hostNetwork 必须为 false。必须是 RFC 1123 合法 DNS 子域名且不超过 64 字符。
set_hostname_as_fqdn bool 若为 true,Pod hostname 配置为 Pod 的 FQDN 而非叶名称,默认 false。
subdomain str 若指定,Pod 的完全限定主机名为 <hostname>.<subdomain>.<pod namespace>.svc.<cluster domain>。
enable_service_links bool 是否将集群服务信息以 Docker links 语法注入 Pod 环境变量,默认 true。

3.3 调度、亲和性与拓扑约束

字段名(Python / JSON) 类型 说明
affinity V1Affinity Pod 的调度约束(节点亲和、Pod 亲和/反亲和)。
node_name str 指定 Pod 调度的节点。若为空,则交由 schedulerName 指定的调度器调度。该字段不应被用来表达"希望调度到某节点"的意图(应使用 nodeSelector/affinity)。
node_selector dict(str, str) 节点选择器,节点标签必须全部匹配 Pod 才能被调度到该节点。
tolerations list[V1Toleration] Pod 的容忍度(容忍节点污点)。
topology_spread_constraints list[V1TopologySpreadConstraint] Pod 组在拓扑域间的分布约束,多个约束之间为 AND 关系。
priority int 优先级数值,值越高优先级越高。
priority_class_name str 优先级类名。system-node-critical 与 system-cluster-critical 是最高优先级的两个特殊关键字(前者更高);其他名称需先创建 PriorityClass 对象。未指定时使用默认优先级或 0。
preemption_policy str 抢占策略:Never 或 PreemptLowerPriority,未设置时默认 PreemptLowerPriority。
scheduler_name str 若指定,Pod 由指定调度器调度;否则由默认调度器调度。
scheduling_gates list[V1PodSchedulingGate] 不透明的调度门列表,非空时 Pod 停留在 SchedulingGated 状态且调度器不会尝试调度它。只能在创建时设置,之后只能移除。
scheduling_group V1PodSchedulingGroup PodGroup 相关配置(用于批量调度场景)。
os V1PodOS Pod 运行的操作系统(如 Linux/Windows)。
runtime_class_name str node.k8s.io 组的 RuntimeClass 对象名。若不存在匹配的 RuntimeClass,Pod 不会运行;未设置时使用 "legacy" 隐式 RuntimeClass(默认运行时 handler)。
overhead dict(str, ResourceQuantity) 运行该 Pod 所需的资源开销,由 RuntimeClass admission controller 在准入阶段自动填充。

3.4 生命周期、探针与优雅终止

字段名(Python / JSON) 类型 说明
active_deadline_seconds int Pod 相对 StartTime 在节点上可存活的最大秒数(须为正整数),超时后系统会主动标记其失败并杀死容器。
termination_grace_period_seconds int Pod 优雅终止的秒数,须为非负整数。0 表示立即通过 kill 信号停止;nil 时使用默认宽限期(默认 30 秒)。建议大于进程的清理时间。
restart_policy str Pod 内所有容器的重启策略:Always、OnFailure、Never,默认 Always。
readiness_gates list[V1PodReadinessGate] Pod 就绪门控列表。Pod 就绪要求所有容器就绪 且 所有就绪门控条件为 True。
eviction_responders list[V1EvictionResponder] 响应基于 EvictionRequest 的驱逐操作的 responder 列表,按 priority 顺序依次选择。responder 需周期性地更新 Eviction 对象的 status.responders[].heartbeatTime;超过心跳期限(当前 20 分钟)未更新则移交给下一个低优先级 responder;无其他 responder 时,默认的 imperative-eviction.k8s.io/evictor(priority 100)通过 pods/<name>/eviction 子资源强制驱逐。列表最长 10 项;Pod 属于 PodGroup 时不支持;只能在创建时设置且不可变。
resource_claims list[V1PodResourceClaim] 在 Pod 启动前必须分配并预留的 ResourceClaim。需要启用 DynamicResourceAllocation feature gate;该字段不可变。

3.5 安全与身份

字段名(Python / JSON) 类型 说明
security_context V1PodSecurityContext Pod 级安全上下文(用户、组、SELinux、seccomp 等)。
service_account_name str 运行 Pod 所使用的 ServiceAccount 名称。
service_account str DeprecatedServiceAccount,serviceAccountName 的废弃别名,已弃用,请改用 serviceAccountName。
automount_service_account_token bool 是否自动挂载 ServiceAccount Token。
share_process_namespace bool 是否在 Pod 所有容器间共享单一进程命名空间(默认 false)。设置后容器可查看并信号其他容器进程,每个容器首进程不再是 PID 1。HostPID 与 ShareProcessNamespace 不能同时设置。

说明:Python 字段名均为 snake_case,JSON/YAML 中为 camelCase。例如 Python 的 termination_grace_period_seconds 对应 YAML 的 terminationGracePeriodSeconds,完整映射见模型的 attribute_map(v1beta1_custom_transformer.py)。

四、源码实现剖析:模型生成与序列化机制

V1beta1CustomTransformer 虽然是自动生成代码,但其结构与行为仍有值得关注的点:

  1. openapi_types 定义字段类型(v1beta1_custom_transformer.py):覆盖上表全部 43 个字段,类型既有原生 int/str/bool,也有 Kubernetes Python 客户端的 V1Container、V1Affinity、V1PodDNSConfig、V1ResourceRequirements、V1PodSecurityContext 等复合类型,以及 list[...] 与 dict(...) 组合类型。

  2. attribute_map 完成 snake_case ↔ camelCase 转换(v1beta1_custom_transformer.py):例如 active_deadline_seconds → activeDeadlineSeconds、image_pull_secrets → imagePullSecrets、set_hostname_as_fqdn → setHostnameAsFQDN,确保 Python 对象能正确序列化为 KServe API 期望的 JSON/YAML 结构。

  3. to_dict() 递归序列化(v1beta1_custom_transformer.py):对列表元素、嵌套对象、字典值统一调用各自的 to_dict(),支持任意深度嵌套的 PodSpec 结构。

  4. __eq__ 基于序列化结果比较(v1beta1_custom_transformer.py):两个实例相等当且仅当 to_dict() 结果相同,方便测试与断言。

五、Go 侧实现:参数注入与默认行为

了解模型字段后,再看 KServe controller 如何消费这些配置。CustomTransformer 在 Go 侧实现了 ComponentImplementation 接口,核心逻辑在 transformer_custom.go:

5.1 Default:容器命名与资源默认值(L51-L57)

func (c *CustomTransformer) Default(config *InferenceServicesConfig) {
	if len(c.Containers) == 0 {
		c.Containers = append(c.Containers, corev1.Container{})
	}
	c.Containers[0].Name = constants.InferenceServiceContainerName
	setResourceRequirementDefaults(config, &c.Containers[0].Resources)
}

若未声明容器,会自动补一个;首个容器名固定为 kserve-container(见 constants.go),并填充资源默认值。

5.2 GetContainer:自动注入启动参数(L74-L117)

GetContainer 会为自定义 Transformer 容器自动追加以下命令行参数(若用户未显式提供),对应常量见 constants.go:

参数 来源 含义
--model_name metadata.Name(InferenceService 名) 模型名
--predictor_host <predictorHost>.<namespace> Predictor 服务地址
--http_port constants.InferenceServiceDefaultHttpPort HTTP 监听端口
--workers extensions.ContainerConcurrency 并发工作线程数(仅在设置了 containerConcurrency 时注入)

在 ModelMesh 部署模式下(通过 metadata.Annotations[constants.DeploymentMode] 判断),Predictor 主机与协议改从 PredictorHostAnnotationKey、PredictorProtocolAnnotationKey 注解读取,并在容器未显式携带 --protocol 参数时自动追加(L79-L91)。

5.3 存储 URI 与协议约定(L59-L67, L119-L126)

  • STORAGE_URI 环境变量(键为 STORAGE_URI,见 constants.go):GetStorageUri() 会读取容器首个 env 中该变量值,用于触发存储初始化流程;
  • PROTOCOL 环境变量(键为 PROTOCOL,见 constants.go):GetProtocol() 返回该 env 指定的推理协议(v1/v2),未设置时默认 ProtocolV1。

这解释了示例 YAML 中 --model_name、--protocol、--http_port、--predictor_host 这些参数为何"看起来是手写的"——它们与 controller 自动注入的规则一致,用户手写时可以覆盖默认值。

六、实战示例:自定义 Transformer 的 YAML 声明

仓库提供了可直接运行的示例 collocation.yaml,演示**预测器容器与自定义 Transformer 容器共置(collocation)**在同一个 Pod 中:

apiVersion: serving.kserve.io/v1beta1
kind: InferenceService
metadata:
  name: custom-transformer-collocation
spec:
  predictor:
    containers:
      - name: kserve-container        # 预测器容器,名称不可改
        image: "pytorch/torchserve:0.9.0-cpu"
        args:
          - "torchserve"
          - "--start"
          - "--model-store=/mnt/models/model-store"
          - "--ts-config=/mnt/models/config/config.properties"
        env:
          - name: TS_SERVICE_ENVELOPE
            value: kserve
          - name: STORAGE_URI          # 触发存储初始化;仅应出现在 predictor 容器
            value: "gs://kfserving-examples/models/torchserve/image_classifier/v1"
        resources:
          requests: { cpu: 100m, memory: 256Mi }
          limits:   { cpu: 1,  memory: 1Gi }

      - name: transformer-container    # 自定义 Transformer 容器,名称不可改
        image: kserve/image-transformer:latest
        args:
          - --model_name=mnist
          - --protocol=v1              # predictor 的协议;用于转换输入
          - --http_port=8080
          - --grpc_port=8081
          - --predictor_host=localhost:8085   # predictor 监听端口
        ports:
          - containerPort: 8080
            protocol: TCP
        resources:
          requests: { cpu: 100m, memory: 256Mi }
          limits:   { cpu: 1,  memory: 1Gi }

要点解读:

  • 在 spec.transformer 下声明 containers 即构成自定义 Transformer,与本文模型一一对应;
  • 容器名必须保持 kserve-container(预测器)与 transformer-container(转换器),这是 KServe 的约定名称;
  • --model_name、--protocol、--http_port、--predictor_host 与第五节中 GetContainer 的注入逻辑完全对应,用户可按需覆盖;
  • 自定义 Transformer 的典型用途就是 image-transformer 这类实现:把客户端 HTTP 请求(如图片)转换成 Predictor 支持的协议格式。

仓库中另有 Feast 特征注入的 Transformer 示例 driver_transformer.yaml 及其 ModelMesh 变体,其结构均为:

spec:
  transformer:
    containers:
      - image: "kserve/driver-transformer:latest"

七、Python SDK 编程式使用

在 KServe Python SDK 中,V1beta1CustomTransformer 通过 V1beta1InferenceServiceSpec 的 transformer 字段(类型为 V1beta1TransformerSpec,见 v1beta1_inference_service_spec.py)接入推理服务。模型实例的构造方式(参考官方单元测试 test_v1beta1_custom_transformer.py):

from kserve.models.v1beta1_custom_transformer import V1beta1CustomTransformer

# 仅必填字段
minimal = V1beta1CustomTransformer(containers=[...])

# 完整字段示例(各字段均可选)
full = V1beta1CustomTransformer(
    active_deadline_seconds=56,
    automount_service_account_token=True,
    containers=[...],
    dns_policy="ClusterFirst",
    enable_service_links=True,
    host_network=False,
    hostname="my-host",
    image_pull_secrets=[...],
    init_containers=[...],
    node_selector={"disktype": "ssd"},
    priority=56,
    priority_class_name="high-priority",
    restart_policy="Always",
    runtime_class_name="gvisor",
    scheduler_name="default-scheduler",
    security_context=None,
    service_account_name="kserve-transformer-sa",
    share_process_namespace=False,
    subdomain="kserve",
    termination_grace_period_seconds=56,
    tolerations=[...],
    topology_spread_constraints=[...],
    volumes=[...],
)

# 序列化为 dict / 字符串
print(full.to_dict())
print(full.to_str())

注意:containers 为唯一必填参数,构造时缺省会抛出 ValueError(v1beta1_custom_transformer.py)。

八、测试与验证

仓库为模型提供了完整单元测试 test_v1beta1_custom_transformer.py:

  • make_instance(include_optional=False) 仅构造必填字段(containers=[None]),验证模型的必填约束;
  • make_instance(include_optional=True) 构造全部可选字段,验证 43 个字段的读写路径;
  • testV1beta1CustomTransformer 同时构造两种实例并断言无异常。

Go 侧同样有 CustomTransformer 的测试覆盖:transformer_custom_test.go 中包括 TestCustomTransformer_GetContainer(验证参数注入)与 TestCustomTransformer_GetStorageUri(验证 STORAGE_URI 读取)等用例,可作为实现行为的直接证据。

九、相关文档与进一步阅读

小结:V1beta1CustomTransformer 本质上是 Kubernetes PodSpec 的 KServe 定制化映射,43 个字段覆盖了容器、网络、调度、生命周期与安全五大维度,唯一必填字段 containers。理解其字段语义、controller 侧的参数注入规则(--model_name、--predictor_host、--http_port、--workers)以及 STORAGE_URI/PROTOCOL 环境变量约定,即可在 KServe 中自如地构建带自定义预处理/后处理逻辑的推理服务。

登录后查看全文
kserve