使用 KServe Modelcar 存储模型

概述

KServe Modelcar,也称为基于 OCI 容器的模型存储,是一种在云原生环境中部署模型的强大方式。将模型打包为 OCI 容器映像后,您可以利用容器运行时的功能,实现更快的启动速度和更高效的资源利用。

使用 OCI 容器存储模型的优势

  • 缩短启动时间:避免多次下载相同的模型
  • 降低磁盘空间占用:减少本地下载的模型数量
  • 提升模型性能:允许预先获取映像,从而加快加载速度
  • 支持离线环境:非常适合互联网访问受限的环境
  • 简化模型分发:使用 Quay 或 Harbor 等企业内部镜像仓库

前提条件

  • 已安装并运行 Alauda AI Platform
  • 已准备好要打包的模型文件
  • 具有容器镜像仓库(例如 Harbor、Quay)的写入/推送权限
  • 本地计算机已安装 Podman 或 nerdctl

将模型打包为 OCI 映像

选项 1:使用 Busybox 基础映像(Alauda AI Platform 推荐)

创建一个包含以下内容的 Containerfile:

# Use lightweight busybox as base image
FROM busybox
 
# Create directory for model and set permissions
RUN mkdir -p /models && chmod 775 /models
 
# Note: Harbor has a file size limit per image layer. 
# It is recommended to copy large files (e.g. 4GB .safetensors) in chunks of 2 files per layer.
# The last layer should copy the remaining model configuration files.
# Example:
# COPY models/model-00001-of-00004.safetensors models/model-00002-of-00004.safetensors /models/
# COPY models/model-00003-of-00004.safetensors models/model-00004-of-00004.safetensors /models/
# COPY models/*.json models/*.md models/*.txt /models/

# If size is not an issue, you can simply copy everything:
COPY models/ /models/
 
# According to KServe convention, model loader usually only needs image layers
# No need to keep running, but can add CMD if debugging is needed

选项 2:使用 UBI Micro 基础映像(Red Hat 推荐)

创建一个包含以下内容的 Containerfile:

FROM registry.access.redhat.com/ubi9/ubi-micro:latest
COPY --chown=0:0 models /models
RUN chmod -R a=rX /models

# nobody user
USER 65534

构建并推送模型映像

  1. 创建一个临时目录,用于存储模型和支持文件:

    cd $(mktemp -d)
  2. 创建一个 models 文件夹(也可以选择为 OpenVINO 等框架创建版本子目录):

    mkdir -p models/1
  3. 将模型文件复制到相应目录:

    • 对于大多数框架:cp -r your-model-folder/* models/
    • 对于 OpenVINO:cp -r your-model-folder/* models/1/
  4. 构建 OCI 容器映像:

    # Using Podman
    podman build --format=oci -t <registry>/<repository>:<tag> .
    
    # Using nerdctl
    nerdctl build -t <registry>/<repository>:<tag> .
  5. 将映像推送到容器镜像仓库:

    # Using Podman
    podman push <registry>/<repository>:<tag>
    
    # Using nerdctl
    nerdctl push <registry>/<repository>:<tag>

    注意 如果您的仓库是私有的,请确保在上传容器映像之前已通过身份验证并登录镜像仓库。

从 OCI 映像部署模型

部署前提条件

除上述常规前提条件外,无需其他前提条件。

创建 InferenceService

创建一个包含以下内容的 InferenceService YAML 文件:

kind: InferenceService
apiVersion: serving.kserve.io/v1beta1
metadata:
  annotations:
    aml-model-repo: Qwen2.5-0.5B-Instruct
    aml-pipeline-tag: text-generation
    serving.kserve.io/deploymentMode: Standard
  labels:
    aml-pipeline-tag: text-generation
    aml.cpaas.io/runtime-type: vllm
  name: oci-demo
  namespace: demo-space
spec:
  predictor:
    maxReplicas: 1
    minReplicas: 1
    model:
      modelFormat:
        name: transformers
      protocolVersion: v2
      resources:
        limits:
          cpu: '2'
          ephemeral-storage: 10Gi
          memory: 8Gi
        requests:
          cpu: '2'
          memory: 4Gi
      runtime: aml-vllm-0.11.2-cpu
      storageUri: oci://<registry>/<repository>:<tag>
    securityContext:
      seccompProfile:
        type: RuntimeDefault
  1. 将 Qwen2.5-0.5B-Instruct 替换为实际的模型名称。
  2. aml.cpaas.io/runtime-type: vllm 指定代码运行时类型。有关自定义推理运行时的更多信息,请参阅扩展推理运行时。
  3. 将 demo-space 替换为现有命名空间,或先使用 kubectl create namespace demo-space 创建命名空间。
  4. 将 aml-vllm-0.11.2-cpu 替换为平台中已安装的运行时名称(对应于 ClusterServingRuntime CRD 实例)。
  5. storageUri 指定存储模型的 OCI 映像 URI 及标签。请使用完全限定的镜像仓库 URL。例如:storageUri: oci://docker.io/alaudapublic/models-qwen2.5:v1

应用 InferenceService

使用 kubectl 应用 InferenceService 配置:

kubectl apply -f oci-inference-service.yaml

验证部署

检查 InferenceService 的状态:

kubectl get inferenceservices -n demo-space

部署成功后,您应看到服务处于 Ready 状态。

如果服务启动失败或一直处于未就绪状态,可以通过以下方式进行故障排除:

  1. 检查 InferenceService 事件以获取详细错误信息:
    kubectl describe inferenceservice oci-demo -n demo-space
  2. 检查 predictor pod 日志:
    kubectl logs -n demo-space -l serving.kserve.io/inferenceservice=oci-demo
  3. 验证集群是否可以在本地成功拉取模型映像:
    # On a node in the cluster
    crictl pull <registry>/<repository>:<tag>

最佳实践

  1. 模型版本管理:使用容器映像中的标签为模型进行版本管理
  2. 映像大小优化:使用轻量级基础映像,并仅包含必要的模型文件
  3. 镜像仓库管理:使用具有适当访问控制的私有镜像仓库
  4. 安全性:遵循容器安全最佳实践,包括定期进行漏洞扫描
  5. 缓存:利用容器镜像仓库缓存来缩短拉取时间

故障排除

常见问题

  1. 权限错误:确保映像中的模型文件具有适当的权限
  2. Ascend 910 vLLM-ascend 权限模式:对于 Huawei Ascend 910 vLLM-ascend 部署,尤其是单节点多卡服务,请参阅 Ascend 910 的 Modelcar 权限模式。
  3. 镜像仓库身份验证:验证集群是否可以访问容器镜像仓库

结论

使用 KServe Modelcar(基于 OCI 容器的模型存储)可以在 Alauda AI Platform 中高效地部署模型。按照本指南中介绍的步骤操作,您可以将模型打包为 OCI 映像,并以更快的启动时间和更高的资源利用率进行部署。