KServe V1beta1LoggerStorageSpec 详解:推理日志对象存储配置的完整指南

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

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 描述的存储配置最终会通过以下链路生效:

  1. 用户配置:在 InferenceService 的 spec.<component>.logger.storage 中填写存储信息(或通过 Python SDK 构造)。
  2. agent 注入:KServe 的 Pod 注入 Webhook(pkg/webhook/admission/pod/agent_injector.go)读取 Logger.Storage,把 path 转为 --log-store-path、把 parameters["format"] 转为 --log-store-format,并注入 logger agent 容器。
  3. 存储写入: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 日志示例)可进一步验证完整链路。

登录后查看全文
kserve