KServe 详细笔记

墨尘484

999人浏览 · 2026-05-26 19:30:48

墨尘484 · 2026-05-26 19:30:48 发布

KServe 详细笔记：从 0 理解 Kubernetes 上的大模型服务部署

1. KServe 到底是干嘛的？
2. 先理解几个基础概念
- 2.1 什么是模型？
- 2.2 什么是推理？
- 2.3 什么是模型服务？
- 2.4 什么是 KServe？
3. 用一个贴近你的例子理解 KServe
4. KServe 和 Kubernetes 的关系
5. CRD 是什么？
6. KServe 的核心资源：InferenceService
- 6.1 InferenceService 是什么？
- 6.2 InferenceService 和 Deployment 有什么区别？
7. KServe 的核心资源：ServingRuntime
- 7.1 ServingRuntime 是什么？
- 7.2 ServingRuntime 和 ClusterServingRuntime 的区别
8. KServe、vLLM、Qwen 三者到底是什么关系？
9. 用 Docker 跑 vLLM 和用 KServe 跑模型有什么区别？
10. 入门：做一个简单的 KServe 例子
- 10.1 创建 namespace
- 10.2 创建 Qwen InferenceService
11. 请求是怎么打到 Qwen 模型里的？
12. KServe 的 Standard 模式和 Knative 模式
- 12.1 Standard 模式
- 12.2 Knative 模式
13. storageUri 是什么？
14. 为什么大模型需要 LocalModelCache？
15. KServe 入门阶段到底应该学什么？

1. KServe 到底是干嘛的？

KServe 是 Kubernetes 上的模型服务平台。

打个比方：

Kubernetes 负责管理容器；
vLLM 负责高效运行大模型；
KServe 负责把“大模型服务”这件事变成标准化、可管理、可扩缩容的 Kubernetes 资源。

比如我们现在想部署一个国内大模型，Qwen2.5-0.5B-Instruct

如果你不用 KServe，你可能需要自己写：

Deployment
Service
Ingress / Gateway
HPA
GPU 资源声明
模型下载逻辑
模型启动命令
健康检查
日志监控
服务暴露
灰度发布

如果用了 KServe，就可以把这些东西抽象成一个更高层的 YAML：

我要部署哪个模型
模型文件在哪里
用什么运行时跑
需要多少 CPU / 内存 / GPU
怎么对外提供 API

所以说，KServe 是运行在 Kubernetes 上的 AI 模型推理平台，用于部署、管理和扩展生成式 AI 与传统预测模型服务。

2. 先理解几个基础概念

刚开始学 KServe，最易遇到的问题是：概念太多。

比如你会看到：

InferenceService
ServingRuntime
ClusterServingRuntime
Predictor
Transformer
Explainer
StorageUri
Runtime
Gateway
Knative
Standard Mode
OpenAI-compatible API

不过别急，我会带着你，从最底层一点一点理解。

2.1 什么是模型？

模型可以先粗暴理解成：

一个经过训练的“大文件”。

比如：Qwen2.5-0.5B-Instruct 或 DeepSeek-R1-Distill-Qwen-1.5B

它们本质上是一堆权重文件和配置文件。

比如一个大模型目录里，可能有：

config.json
tokenizer.json
model.safetensors
generation_config.json

简单来说：模型 = 权重文件 + 配置文件 + tokenizer

模型本身不会自动对外提供服务。它只是文件。

2.2 什么是推理？

推理就是：把输入喂给模型，模型输出结果。

比如你问：

Kubernetes 里的 Service 是干嘛的？

模型返回：

Service 是 Kubernetes 中用于为一组 Pod 提供稳定访问入口的资源。

这整个过程就叫推理。

对于大模型来说，推理就是：

输入 prompt
        ↓
模型逐 token 生成内容
        ↓
返回回答

2.3 什么是模型服务？

模型服务就是：把模型包装成一个可以被 HTTP API 调用的服务。

比如你现在本地用 vLLM 跑 Qwen：

vllm serve Qwen/Qwen2.5-0.5B-Instruct --host 0.0.0.0 --port 8000

然后你可以请求：

curl http://localhost:8000/v1/chat/completions

这时候，vLLM 就把模型变成了一个 API 服务。

所以你可以这样理解：

模型文件：Qwen2.5-0.5B-Instruct
模型服务引擎：vLLM
模型服务 API：/v1/chat/completions

2.4 什么是 KServe？

KServe 不是模型本身，也不是 vLLM 本身。

KServe 是更上一层的管理平台。

它更像是：

vLLM：负责把 Qwen 跑起来
Kubernetes：负责把 vLLM 容器调度起来
KServe：负责用统一方式描述、创建、暴露、管理这个模型服务

如果不用 KServe，你可能要写：

Deployment
Service
Ingress
HPA
ConfigMap
Secret

如果用 KServe，你主要写：

InferenceService

KServe 会根据这个 InferenceService 自动生成底层 Kubernetes 资源。
KServe 官方文档说，它通过 Kubernetes CRD 来服务预测式和生成式模型，并封装自动扩缩容、网络、健康检查和服务配置等复杂性。

3. 用一个贴近你的例子理解 KServe

假设你现在是一个智算云后端开发实习生，你的 leader 让你做一个功能：

在 Kubernetes 集群里部署一个 Qwen 模型服务，
以后公司控制台可以调用它，
用于回答用户关于云主机、容器、GPU、K8s 的问题。

这个服务可以叫：

qwen-cloud-assistant

它要实现的效果是：

用户在页面输入：
“GPU 云服务器和裸金属服务器有什么区别？”

后端请求模型服务：
POST /v1/chat/completions

模型返回：
“GPU 云服务器通常是虚拟化资源，裸金属服务器是独占物理机……”

这个时候，整体链路是：

前端页面
  ↓
后端业务服务
  ↓
KServe 暴露的大模型 API
  ↓
vLLM Runtime
  ↓
Qwen 模型
  ↓
返回答案

你要注意：KServe 不负责“回答问题”，真正回答问题的是 Qwen。

KServe 负责的是：

怎么把 Qwen 服务稳定地部署到 Kubernetes 上
怎么给它分配 GPU
怎么暴露 HTTP API
怎么让它可以扩缩容
怎么让它可以被统一管理

4. KServe 和 Kubernetes 的关系

这里很好理解。

Kubernetes 原生资源有：

Pod
Deployment
Service
ConfigMap
Secret
Ingress
HPA

但是 Kubernetes 原生并不知道什么叫“大模型”。

也就是说，Kubernetes 不理解：

Qwen 是什么
DeepSeek 是什么
模型权重在哪里
用 vLLM 还是 Triton
推理 API 怎么写

所以 KServe 做了一件事：

给 Kubernetes 增加一批专门用于模型服务的 CRD。

最重要的是：

InferenceService
ServingRuntime
ClusterServingRuntime
InferenceGraph

KServe 官方资源文档也把 InferenceService、ServingRuntime、ClusterServingRuntime、InferenceGraph 等作为核心资源来介绍。

你可以这样记：

Kubernetes 原生不懂模型；
KServe 通过 CRD 让 Kubernetes “看懂”模型服务。

5. CRD 是什么？

CRD 全称是： Custom Resource Definition

中文：自定义资源定义

Kubernetes 默认知道这些资源：

Pod
Deployment
Service
Namespace
ConfigMap
Secret

但是如果你安装了 KServe，它会往 Kubernetes 里注册新的资源类型：

InferenceService
ServingRuntime
ClusterServingRuntime
InferenceGraph

于是你就可以执行：

kubectl get inferenceservice
kubectl get isvc
kubectl get clusterservingruntime

这就像 Kubernetes 被“扩展”了。

你可以这样理解：

CRD = 给 Kubernetes 增加新的资源类型
Controller = 负责监听这些资源，并创建真正的底层资源

6. KServe 的核心资源：InferenceService

6.1 InferenceService 是什么？

InferenceService 是 KServe 最核心的资源。

可以把它理解成：一个模型服务的声明文件。

比如你想部署一个 Qwen 模型服务，你就写一个 InferenceService：

apiVersion: serving.kserve.io/v1beta1
kind: InferenceService
metadata:
  name: qwen-cloud-assistant
spec:
  predictor:
    model:
      modelFormat:
        name: huggingface
      storageUri: hf://Qwen/Qwen2.5-0.5B-Instruct

这段 YAML 的意思是：

我要创建一个模型服务
名字叫 qwen-cloud-assistant
模型格式是 HuggingFace
模型地址是 Qwen/Qwen2.5-0.5B-Instruct

6.2 InferenceService 和 Deployment 有什么区别？

可以这样说：
Deployment：描述我要跑一个普通容器
InferenceService：描述我要跑一个模型服务

Deployment 关心的是：

镜像是什么
副本数是多少
端口是多少
资源限制是多少

InferenceService 更关心：

模型是什么
模型格式是什么
模型文件在哪里
用什么 Runtime 跑
推理协议是什么
是否需要 GPU

不过，InferenceService 最终还是会转成底层 Kubernetes 资源。

也就是说：

我们写了 InferenceService；
KServe Controller 最后帮你转换创建成 Deployment、Service、Gateway 等资源。

7. KServe 的核心资源：ServingRuntime

7.1 ServingRuntime 是什么？

ServingRuntime 解决的问题是：这个模型到底用什么容器来跑？

比如：

Qwen2.5 用 vLLM 跑
sklearn 模型用 sklearn server 跑
TensorFlow 模型用 TensorFlow Serving 跑
ONNX 模型用 Triton 跑

所以你可以这样记：

InferenceService：我要部署哪个模型
ServingRuntime：用哪个服务引擎运行这个模型

KServe 官方文档说明，ServingRuntime 和 ClusterServingRuntime 用于定义模型服务环境；它们会声明 runtime 的容器镜像、支持的模型格式、启动参数等。

7.2 ServingRuntime 和 ClusterServingRuntime 的区别

这两个名字看起来吓人，其实区别很简单：

ServingRuntime：只在某个 namespace 内可用
ClusterServingRuntime：整个集群都可用

举个例子。

如果公司平台团队给整个集群安装了一个通用的 Qwen Runtime：

ClusterServingRuntime: kserve-huggingfaceserver

那所有业务 namespace 都能用。

如果你只想在自己的测试 namespace 里定义一个实验 Runtime：

ServingRuntime: my-qwen-runtime

那它只在你自己的 namespace 里生效。

你可以这样记：

ClusterServingRuntime = 公司统一模板
ServingRuntime = 个人 / 项目自定义模板

8. KServe、vLLM、Qwen 三者到底是什么关系？

这是你一定要讲清楚的地方。

假设我们部署：

Qwen2.5-0.5B-Instruct

那么三者关系是：

Qwen：模型本体
vLLM：让 Qwen 高效运行起来的推理引擎
KServe：把 vLLM + Qwen 部署到 Kubernetes 上，并对外提供统一服务

可以画成这样：

用户请求
  ↓
KServe 暴露的服务地址
  ↓
Kubernetes Service / Gateway
  ↓
vLLM 容器
  ↓
Qwen 模型权重
  ↓
返回回答

vLLM 官方文档明确说明，vLLM 可以和 KServe 一起部署在 Kubernetes 上，用于可扩展的分布式模型服务；可以通过 KServe 的 Hugging Face serving runtime 使用 vLLM。

KServe 的生成式推理文档也说明，它的 Hugging Face Runtime 默认启用 vLLM backend，用于更好的大模型推理性能。

所以你可以背下来：

Qwen 负责“会不会回答”；
vLLM 负责“回答得快不快、显存用得省不省”；
KServe 负责“这个模型服务怎么在 K8s 上部署、暴露、扩缩容、管理”。

9. 用 Docker 跑 vLLM 和用 KServe 跑模型有什么区别？

你之前已经接触过 vLLM 的 Docker 命令，比如：

docker run --gpus all -p 8000:8000 \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen2.5-0.5B-Instruct \
  --host 0.0.0.0 \
  --port 8000

这适合个人学习。

但是如果是在公司环境里，通常不会只用一个 Docker 命令裸跑。

公司更关心：

服务挂了能不能自动拉起？
能不能统一暴露域名？
能不能分配 GPU？
能不能监控？
能不能灰度？
能不能扩缩容？
能不能多租户隔离？
能不能统一管理多个模型？

所以公司一般会把它放到 Kubernetes 上。

再进一步，如果公司有很多模型服务，就会考虑 KServe。

对比一下：

方式	适合场景	你要自己处理什么
直接 Docker 跑 vLLM	本地学习、单机测试	容器启动、端口、模型路径
Kubernetes Deployment 跑 vLLM	公司内部普通部署	Deployment、Service、Ingress、GPU、探针
KServe 跑 vLLM + Qwen	模型平台、AI Infra、生产模型服务	主要写 InferenceService，KServe 帮你封装模型服务治理

一句话：

Docker 跑 vLLM 是“把模型跑起来”；
KServe 跑 vLLM 是“把模型服务平台化”。

10. 入门：做一个简单的 KServe 例子

注意：下面 YAML 是学习结构用的示例。实际能不能直接跑，需要结合自己的 KServe 版本、Runtime、GPU、网络、镜像源、模型下载方式。

10.1 创建 namespace

kubectl create namespace kserve-test

意思是：

创建一个专门测试 KServe 的命名空间。

以后你的模型服务都放这里，方便管理和删除。

10.2 创建 Qwen InferenceService

apiVersion: serving.kserve.io/v1beta1
kind: InferenceService
metadata:
  name: qwen-cloud-assistant
  namespace: kserve-test
spec:
  predictor:
    model:
      modelFormat:
        name: huggingface
      args:
        - --model_name=qwen-cloud-assistant
      storageUri: hf://Qwen/Qwen2.5-0.5B-Instruct
      resources:
        requests:
          cpu: "2"
          memory: 8Gi
          nvidia.com/gpu: "1"
        limits:
          cpu: "2"
          memory: 8Gi
          nvidia.com/gpu: "1"

逐行解释。

apiVersion: serving.kserve.io/v1beta1

说明这是 KServe 的 API，不是 Kubernetes 原生 API。

kind: InferenceService

说明你要创建一个模型服务。

metadata:
  name: qwen-cloud-assistant
  namespace: kserve-test

模型服务名字叫：

qwen-cloud-assistant

部署到：

kserve-test namespace

spec:
  predictor:

predictor 是真正负责推理的部分。

在 KServe 里，一个完整的推理服务可以有：

Transformer：前处理
Predictor：模型推理
Explainer：解释模型结果

但入门阶段你先只学：

Predictor

因为大模型问答最核心的就是模型推理。

model:
  modelFormat:
    name: huggingface

意思是：

这个模型是 HuggingFace 格式。

Qwen2.5 这类大模型通常就是 HuggingFace Transformer 模型格式。

storageUri: hf://Qwen/Qwen2.5-0.5B-Instruct

意思是：

模型文件从 HuggingFace Hub 上的 Qwen/Qwen2.5-0.5B-Instruct 获取。

如果在国内环境，可能需要换成：

ModelScope 模型地址
公司内部对象存储
PVC 本地挂载
提前下载好的模型目录

这是因为国内环境访问 HuggingFace 经常不稳定。ModelScope 上也提供了 Qwen2.5-0.5B-Instruct 模型页面。([ModelScope][10])

resources:
  requests:
    cpu: "2"
    memory: 8Gi
    nvidia.com/gpu: "1"

意思是：

这个模型服务至少需要 2 核 CPU、8Gi 内存、1 张 GPU。

你之前学 K8s 时应该知道：

requests：调度时的最低资源需求
limits：运行时的最大资源限制

这里写 GPU 是因为大模型推理通常需要 GPU。即使 Qwen2.5-0.5B 很小，生产环境仍然更常用 GPU 做推理。

11. 请求是怎么打到 Qwen 模型里的？

假设部署成功后，你的调用链路大概是：

用户
  ↓
curl / 前端 / 后端服务
  ↓
Gateway / Ingress
  ↓
KServe 创建的 Service
  ↓
qwen-cloud-assistant Pod
  ↓
vLLM backend
  ↓
Qwen2.5-0.5B-Instruct
  ↓
返回回答

如果你调用的是 OpenAI-compatible API，请求可能长这样：

curl -X POST "http://localhost:8080/openai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Host: qwen-cloud-assistant.kserve-test.example.com" \
  -d '{
    "model": "qwen-cloud-assistant",
    "messages": [
      {
        "role": "user",
        "content": "请用小白能听懂的话解释 Kubernetes 的 Service 是什么"
      }
    ]
  }'

KServe 官方文档说明，它面向生成式 AI 支持 OpenAI-compatible API，包括 chat completions、completions、streaming、embeddings 等能力。

所以你可以这样记：

以前你调用 OpenAI API；
现在你可以调用自己部署在 K8s 里的 Qwen API；
KServe 负责把这个 API 标准化、平台化。

12. KServe 的 Standard 模式和 Knative 模式

这是最容易懵的地方。

KServe 有两种常见部署思路：

Standard 模式
Knative / Serverless 模式

12.1 Standard 模式

Standard 模式更像普通 Kubernetes 部署。

底层主要是：

Deployment
Service
Gateway / Ingress
HPA

在进行安装前，要确定版本 Kubernetes 1.32+、Cert Manager 1.15.0+

如果可行，建议优先理解 Standard 模式。

12.2 Knative 模式

Knative 模式更偏 Serverless。

它强调：

有请求时自动扩容
没请求时缩容甚至缩到 0
更强的流量治理
Revision 管理
Canary 发布

你可以这样理解：

Standard 模式：更像长期运行的大模型服务
Knative 模式：更像按请求弹性启动的模型函数

入门建议：

先学 Standard
后学 Knative

13. storageUri 是什么？

storageUri 是 KServe 里非常重要的字段。

storageUri 指向训练好的模型文件位置。
KServe 会根据 storageUri 的协议和运行时配置，把模型文件下载、复制或挂载到推理 Pod 可访问的位置。

比如：

storageUri: hf://Qwen/Qwen2.5-0.5B-Instruct

意思是从 HuggingFace 下载。

但国内环境下，你要知道实际可能有几种方式：

1. hf://Qwen/Qwen2.5-0.5B-Instruct
2. modelscope://Qwen/Qwen2.5-0.5B-Instruct
3. pvc://qwen-model-pvc/Qwen2.5-0.5B-Instruct
4. s3://bucket/qwen-model
5. oss://bucket/qwen-model
6. 公司内部模型仓库地址

入门时你只要先理解：

storageUri 不是服务地址；
storageUri 是模型文件存放地址。

14. 为什么大模型需要 LocalModelCache？

你以后一定会遇到这个问题：为什么模型服务启动这么慢？

原因是：大模型太大了。

比如：

0.5B 模型还比较小
7B 模型已经明显变大
32B / 72B 模型就更大
DeepSeek-V3 这类 MoE 模型更夸张

如果每次 Pod 启动都重新下载模型，会非常慢。

核心就是： LocalModelCache = 把模型文件提前缓存到节点本地磁盘（提前下载/缓存，需要时直接用。）

换个小图：

没有缓存：
Pod 启动 → 下载几十 GB 模型 → 加载模型 → 提供服务

有缓存：
Pod 启动 → 直接读取节点本地已有模型 → 加载模型 → 提供服务

这对大模型服务非常重要。

15. KServe 入门阶段到底应该学什么？

不要一上来就学全部。

正确顺序是：

第一步：理解 KServe 是什么
第二步：理解 InferenceService
第三步：理解 ServingRuntime / ClusterServingRuntime
第四步：理解 Qwen + vLLM + KServe 的关系
第五步：跑通一个小模型服务
第六步：再学习 GPU、模型缓存、扩缩容、网关、灰度