KServe V1beta1LoggerStorageSpec 详解:推理日志对象存储配置的完整指南
KServe V1beta1LoggerStorageSpec 详解:推理日志对象存储配置的完整指南
导读
V1beta1LoggerStorageSpec 是 KServe Python SDK 中用于描述推理日志(Inference Logger)对象存储位置的模型类,它在 logger.storage 配置块中定义日志事件(CloudEvents)最终写入的存储桶、路径与凭据。通过本篇文章,你将掌握该模型四个字段(key、parameters、path、service_account_name)的确切含义、与 Go 端 CRD 定义的对应关系,以及它在 agent 注入与 pkg/logger 存储链路中的真实作用,并能直接在 Python SDK 或 YAML 中完成配置。
模型概述:一个自动生成的 SDK 数据类
V1beta1LoggerStorageSpec 位于 python/kserve/kserve/models/v1beta1_logger_storage_spec.py,由 OpenAPI Generator 从 KServe 的 OpenAPI 规范自动生成(源码文件头注释标明 "This class is auto generated by OpenAPI Generator")。它不是一个业务逻辑类,而是一个纯数据结构模型,用于在 Python 客户端中表示 CRD 的 LoggerStorageSpec JSON 结构。
从源码可以看出,该类通过 openapi_types 声明属性类型,通过 attribute_map 完成 Python 属性名与 JSON 字段名的映射:
openapi_types = {
'key': 'str',
'parameters': 'dict(str, str)',
'path': 'str',
'service_account_name': 'str'
}
attribute_map = {
'key': 'key',
'parameters': 'parameters',
'path': 'path',
'service_account_name': 'serviceAccountName'
}
需要注意的映射细节:service_account_name 在 JSON/YAML 中对应 serviceAccountName(驼峰命名),其余三个字段与属性名一致。该类还实现了标准的 to_dict()、to_str()、__eq__/__ne__ 方法,便于序列化与比较。
字段属性详解
下表完整列出了 V1beta1LoggerStorageSpec 的全部属性(对应 python/kserve/docs/V1beta1LoggerStorageSpec.md 中的属性表,并结合底层实现补充说明):
| 属性名 | 类型 | 描述 | 是否必填 |
|---|---|---|---|
| key | str | 该对象在 Secret 中的存储密钥(Storage Key) | optional |
| parameters | dict(str, str) | 覆盖默认存储凭据和配置的参数 | optional |
| path | str | 对象在存储中的路径,注意:该路径是相对于存储 URI 的 | optional |
| service_account_name | str | 用于访问存储的 Kubernetes ServiceAccount 名称 | optional |
所有字段均为可选(optional)。从 Go 端 CRD 定义看,这些字段对应的 JSON tag 分别为 key、parameters、path、serviceAccountName,与 Python 端的 attribute_map 完全一致。
与 Go 端 CRD 定义的对应关系
V1beta1LoggerStorageSpec 直接对应 Kubernetes CRD 中 pkg/apis/serving/v1beta1/inference_service.go 定义的 LoggerStorageSpec 结构体:
// StorageSpec defines a spec for an object in an object store
type StorageSpec struct {
// The path to the object in the storage. Note that this path is relative to the storage URI.
// +optional
Path *string `json:"path,omitempty"`
// Parameters to override the default storage credentials and config.
// +optional
Parameters *map[string]string `json:"parameters,omitempty"`
// The Storage Key in the secret for this object.
// +optional
StorageKey *string `json:"key,omitempty"`
}
type LoggerStorageSpec struct {
StorageSpec `json:",inline"`
ServiceAccountName *string `json:"serviceAccountName,omitempty"`
}
从源码结构看,LoggerStorageSpec 通过内嵌 StorageSpec 复用了一套通用的"对象存储对象"描述(path、parameters、key 三字段),并额外增加了 ServiceAccountName 字段——这正是 Python 模型中四个属性的来源。其中 StorageSpec 是一个可复用的通用存储规格,在 KServe 中还被其他场景(如模型存储配置)引用,说明 path/parameters/key 是 KServe 存储描述的统一模式。
该结构体位于 LoggerSpec 中作为 Storage *LoggerStorageSpec 字段(JSON tag 为 storage),也就是说 V1beta1LoggerStorageSpec 是 logger.storage 配置块的类型。
各字段的实战语义
key:Secret 中的存储凭据键
key 指定对象存储凭据在 Secret 中的键名。在 agent 注入逻辑 pkg/webhook/admission/pod/agent_injector.go 中可以看到,当 Store 不为空时会使用默认常量:
LoggerDefaultStorageKey = "credentials"
(定义于 pkg/constants/constants.go)。也就是说,如果不在 YAML 中显式指定 key,默认从 Secret 的 credentials 键读取存储凭据。这意味着 key 用于告诉系统"去哪个 Secret 键里找访问对象存储的认证信息"。
parameters:覆盖默认存储凭据与配置
parameters 是一个 dict(str, str),用于覆盖默认的存储凭据和配置项。在注入逻辑中,parameters 里至少有一个被显式消费的键——存储格式。相关常量:
LoggerFormatKey = "format"
agent 注入器在拼接 logger 容器参数时,会从 Store.Parameters 中读取 format 键的值,作为 --log-store-format 参数传入(见 pkg/webhook/admission/pod/agent_injector.go):
format, ok := (*ag.loggerConfig.Store.Parameters)[constants.LoggerFormatKey]
if ok {
storageFormat = format
}
例如测试用例 pkg/webhook/admission/pod/agent_injector_test.go 中展示了 --log-store-format json 的注入结果。因此 parameters 中的 format 键用于指定日志在对象存储中的落盘格式(如 JSON)。
path:相对存储 URI 的对象路径
path 指定日志对象在存储中的位置,且该路径相对于存储 URI(即相对 bucket 根目录或存储前缀)。注入器会将其映射为 agent 的 --log-store-path 参数:
if storagePath != "" {
loggerArgs = append(loggerArgs, LoggerArgumentStorePath)
loggerArgs = append(loggerArgs, storagePath)
}
在 pkg/logger/store.go 的 BlobStore 中,storePath 被保存在存储实现中,用于计算日志写入的最终对象键(bucket + configPrefix + storePath),参见 NewBlobStore(logStorePath string, ...) 与 parseBlobStoreURL。
service_account_name:访问存储的 ServiceAccount
service_account_name 指定用于访问对象存储的 Kubernetes ServiceAccount。注入逻辑中,当配置了 Store 时会使用默认值:
LoggerDefaultServiceAccountName = "logger-sa"
该默认值定义在 pkg/constants/constants.go。也就是说,如果用户未指定,日志代理默认使用名为 logger-sa 的 ServiceAccount 来获取存储凭据;用户可以通过 serviceAccountName 显式覆盖,以便使用自定义的 RBAC 权限访问存储桶。
Python SDK 中的使用方式
V1beta1LoggerStorageSpec 作为 V1beta1LoggerSpec.storage 字段的类型被引用(见 python/kserve/kserve/models/v1beta1_logger_spec.py),而 V1beta1LoggerSpec 又挂在 predictor/transformer/explainer 的 logger 字段上(见 python/kserve/kserve/models/v1beta1_predictor_spec.py 等模型类,其构造函数均接受 logger 参数)。
在 Python SDK 中构造日志存储配置的典型写法:
from kserve.models import V1beta1LoggerStorageSpec, V1beta1LoggerSpec
storage_spec = V1beta1LoggerStorageSpec(
key="credentials", # Secret 中的存储凭据键
parameters={"format": "json"}, # 覆盖默认存储配置(如日志格式)
path="inference-logs/sklearn-iris", # 相对存储 URI 的对象路径
service_account_name="logger-sa", # 访问存储的 ServiceAccount
)
logger_spec = V1beta1LoggerSpec(
mode="all", # all / request / response
url="http://message-dumper.default/",
storage=storage_spec,
)
对应的 YAML 形式(serviceAccountName 使用驼峰命名):
apiVersion: serving.kserve.io/v1beta1
kind: InferenceService
metadata:
name: sklearn-iris
spec:
predictor:
logger:
mode: all
url: http://message-dumper.default/
storage:
key: credentials
parameters:
format: json
path: inference-logs/sklearn-iris
serviceAccountName: logger-sa
sklearn:
storageUri: gs://kfserving-examples/models/sklearn/1.0/model
单元测试验证
仓库中为 V1beta1LoggerStorageSpec 提供了单元测试 python/kserve/test/test_v1beta1_logger_storage_spec.py,测试覆盖了"仅必填字段"与"全部可选字段"两种构造场景:
def make_instance(self, include_optional):
if include_optional:
return V1beta1LoggerStorageSpec(
key="0", parameters={"key": "0"}, path="0", service_account_name="0"
)
else:
return V1beta1LoggerStorageSpec()
这印证了四个字段全部为 optional——即使不传任何参数,也能构造出一个合法的 V1beta1LoggerStorageSpec 实例,序列化时未设置的字段会以 None 呈现。
在日志链路中的位置
从整体数据流看,V1beta1LoggerStorageSpec 描述的存储配置最终会通过以下链路生效:
- 用户配置:在 InferenceService 的
spec.<component>.logger.storage中填写存储信息(或通过 Python SDK 构造)。 - agent 注入:KServe 的 Pod 注入 Webhook(pkg/webhook/admission/pod/agent_injector.go)读取
Logger.Storage,把path转为--log-store-path、把parameters["format"]转为--log-store-format,并注入 logger agent 容器。 - 存储写入:
pkg/logger/store.go中的NewStoreForScheme根据日志 URL 的 scheme(s3://、gs://、azure://)创建对应的BlobStore,把 marshal 后的日志记录批量写入storePath指定的对象路径。
pkg/logger/store.go 中 NewStoreForScheme 仅支持 AZURE、GCS、S3 三种协议,超出会返回 "unsupported protocol" 错误——这意味着 V1beta1LoggerStorageSpec 描述的存储对象主要面向三大主流云对象存储。
小结
V1beta1LoggerStorageSpec 是 KServe 推理日志功能中描述"日志写到哪里"的四个字段的载体:
key:Secret 中存储凭据的键(默认credentials);parameters:覆盖默认存储配置的键值对(如format键控制日志格式);path:相对于存储 URI 的对象路径,决定日志文件落盘位置;service_account_name:访问存储的 ServiceAccount(默认logger-sa)。
理解该模型,即可在 KServe Python SDK 与 InferenceService YAML 中自如配置推理日志的对象存储落盘,结合 docs/samples/logger/basic/README.md 中的端到端 demo(message-dumper + sklearn 日志示例)可进一步验证完整链路。