KServe V1beta1CustomTransformer 模型全解析:自定义 Transformer 的 PodSpec 配置字段与源码实现
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 中的注释明确指出:
- 提供一个完整的 PodSpec 用于自定义 Transformer,此时
PodSpec.Containers与其他 Transformer 类型互斥;- 提供 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 虽然是自动生成代码,但其结构与行为仍有值得关注的点:
-
openapi_types定义字段类型(v1beta1_custom_transformer.py):覆盖上表全部 43 个字段,类型既有原生int/str/bool,也有 Kubernetes Python 客户端的V1Container、V1Affinity、V1PodDNSConfig、V1ResourceRequirements、V1PodSecurityContext等复合类型,以及list[...]与dict(...)组合类型。 -
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 结构。 -
to_dict()递归序列化(v1beta1_custom_transformer.py):对列表元素、嵌套对象、字典值统一调用各自的to_dict(),支持任意深度嵌套的 PodSpec 结构。 -
__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.md、V1beta1TransformerSpec.md、V1beta1TransformerConfig.md
- 模型索引(Models 列表):python/kserve/README.md
- Go 侧实现:transformer_custom.go、transformer.go
- 常量定义:constants.go
- OpenAPI 定义:swagger.json(
v1beta1.CustomTransformer定义位于 L3235-L3240 起) - 示例:collocation.yaml、driver_transformer.yaml、认证转发指南
小结:V1beta1CustomTransformer 本质上是 Kubernetes PodSpec 的 KServe 定制化映射,43 个字段覆盖了容器、网络、调度、生命周期与安全五大维度,唯一必填字段 containers。理解其字段语义、controller 侧的参数注入规则(--model_name、--predictor_host、--http_port、--workers)以及 STORAGE_URI/PROTOCOL 环境变量约定,即可在 KServe 中自如地构建带自定义预处理/后处理逻辑的推理服务。