KubeAI：AI 推理运算符

在 Kubernetes 上部署和扩展机器学习模型。

专为大型语言模型、嵌入、重排序以及语音转文本设计。

亮点

它用来做什么？

🚀 LLM 推理 - 运行 vLLM 和 Ollama 服务器
🎙️ 语音处理 - 使用 FasterWhisper 转录音频
🔢 向量嵌入 - 使用 Infinity 生成嵌入
📚 重排序 - 使用交叉编码器模型重新排列搜索结果

你能得到什么？

⚡️ 智能扩展 - 根据需求从零扩展到所需规模
📊 优化路由 - 大幅提升大规模性能（参见论文）
💾 模型缓存 - 自动下载并挂载（EFS 等）
🧩 动态适配器 - 协调跨副本的 LoRA 适配器
📨 事件流 - 与 Kafka、PubSub 等集成

我们致力于提供“开箱即用”的体验：

🔗 OpenAI 兼容 - 可与 OpenAI 客户端库配合使用
🛠️ 零依赖 - 不需要 Istio、Knative 等
🖥 硬件灵活 - 支持 CPU、GPU 或 TPU

社区评价：

可复用、高度抽象的 LLM 运行解决方案 - Mike Ensor, Google

为什么选择 KubeAI？

更好的大规模性能

当运行多个 vLLM 副本时，Kubernetes 标准服务背后 kube-proxy 内置的随机负载均衡策略表现不佳（TTFT 和吞吐量）。这是因为 vLLM 并非无状态，其性能受 KV 缓存状态的显著影响。

KubeAI 代理包含一种前缀感知的负载均衡策略，可优化 KV 缓存利用率，从而大幅提高系统整体性能。

更多详情请参阅 完整论文。

简单易用

KubeAI 不依赖其他系统，如 Istio 和 Knative（用于从零扩展），也不依赖 Prometheus 指标适配器（用于自动缩放）。这使得 KubeAI 几乎可以在任何 Kubernetes 集群中开箱即用。日常运维也大大简化——无需担心不同项目之间的版本和配置不匹配问题。

该项目附带一个常用模型目录，已针对常见 GPU 类型预配置。这意味着您可以减少调整 vLLM 特定参数的时间。随着项目的扩展，我们计划构建一个全面的模型优化流水线，以确保您充分利用硬件资源。

OpenAI API 兼容性

无需更改您的客户端库，KubeAI 支持以下端点：

/v1/chat/completions
/v1/completions
/v1/embeddings
/v1/rerank
/v1/models
/v1/audio/transcriptions

架构

KubeAI 由两个主要子组件组成：

1. 模型代理： KubeAI 代理提供与 OpenAI 兼容的 API。在此 API 后面，代理实施了一种前缀感知的负载均衡策略，以优化后端服务引擎（即 vLLM）的 KV 缓存利用率。代理还实现了请求排队（在系统从零副本扩展时）和请求重试（以无缝处理不良后端）。

2. 模型运算符： KubeAI 模型运算符直接管理后端服务器 Pod。它通过 KubeAI Model CRD 自动执行常见操作，例如下载模型、挂载卷以及加载动态 LoRA 适配器。

这两个组件位于同一部署中，但也可以独立部署。

采用者

已知采用者列表：

如果您正在使用 KubeAI 并希望被列入采用者名单，请提交 PR。

本地快速入门

使用 kind 或 minikube 创建本地集群。

# 您可能需要停止并删除现有虚拟机：
podman machine stop
podman machine rm

# 初始化并启动一台新虚拟机：
podman machine init --memory 6144 --disk-size 120
podman machine start

kind create cluster # 或者：minikube start

添加 KubeAI 的 Helm 仓库。

helm repo add kubeai https://www.kubeai.org
helm repo update

安装 KubeAI，并等待所有组件就绪（可能需要一分钟）。

helm install kubeai kubeai/kubeai --wait --timeout 10m

安装一些预定义的模型。

cat <<EOF > kubeai-models.yaml
catalog:
  deepseek-r1-1.5b-cpu:
    enabled: true
    features: [TextGeneration]
    url: 'ollama://deepseek-r1:1.5b'
    engine: OLlama
    minReplicas: 1
    resourceProfile: 'cpu:1'
  qwen2-500m-cpu:
    enabled: true
  nomic-embed-text-cpu:
    enabled: true
EOF

helm install kubeai-models kubeai/models \
    -f ./kubeai-models.yaml

在继续下一步之前，请在一个独立的终端中开启对 Pod 的监听，以观察 KubeAI 如何部署模型。

kubectl get pods --watch

与 Deepseek R1 1.5b 交互

由于我们为 Deepseek 模型设置了 minReplicas: 1，你应该会看到一个模型 Pod 已经启动并运行。

启动本地端口转发，连接到内置的聊天界面。

kubectl port-forward svc/open-webui 8000:80

现在打开浏览器访问 localhost:8000，选择 Deepseek 模型开始聊天。

将 Qwen2 从零扩展到多副本

如果你回到浏览器并与 Qwen2 开始对话，会发现它一开始响应较慢。这是因为我们为该模型设置了 minReplicas: 0，KubeAI 需要启动一个新的 Pod（可以通过 kubectl get models -oyaml qwen2-500m-cpu 来验证）。

加入社区

在 kubeai.org 上阅读相关概念、指南和 API 文档。

🌟 别忘了在 GitHub 上给项目点个赞，并关注仓库以获取最新动态！

如果你有感兴趣的特性建议或遇到问题，欢迎随时联系我们。

你也可以通过以下方式联系本项目的维护者：

• Slack 频道
• Discord 频道（已归档）

或者直接在 LinkedIn 上联系他们：

• Nick Stogner
• Sam Stoelinga

维护者：

• ffais
• m4oc
• Davide Rutigliano

KubeAI 快速上手指南

KubeAI 是一个专为 Kubernetes 设计的 AI 推理运算符（Operator），支持大语言模型（LLM）、语音处理、向量嵌入和重排序任务。它具备智能扩缩容、前缀感知负载均衡和 OpenAI API 兼容等特性，无需依赖 Istio 或 Knative 即可运行。

环境准备

在开始之前，请确保您的环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows (配合 WSL2)
• Kubernetes 集群: 本地开发推荐使用 kind 或 minikube。
  • 注意: 若使用 Podman 运行 kind，建议将机器内存限制提升至至少 6GB（默认通常为 2G）：

    podman machine stop
    podman machine rm
    podman machine init --memory 6144 --disk-size 120
    podman machine start
    

• 命令行工具:
  • kubectl: 用于管理 Kubernetes 资源。
  • helm: 用于安装 KubeAI (需 v3+ 版本)。
• 硬件资源: 支持 CPU、GPU 或 TPU。本地测试建议使用至少 4 核 CPU 和 8GB 内存的节点。

安装步骤

1. 创建本地集群

使用 kind 或 minikube 启动一个本地 Kubernetes 集群：

kind create cluster
# 或者
# minikube start

2. 添加 Helm 仓库

添加 KubeAI 的官方 Helm 仓库并更新索引：

helm repo add kubeai https://www.kubeai.org
helm repo update

3. 安装 KubeAI

执行安装命令并等待所有组件就绪（首次安装可能需要几分钟下载镜像）：

helm install kubeai kubeai/kubeai --wait --timeout 10m

4. 部署示例模型

创建一个名为 kubeai-models.yaml 的配置文件，定义要部署的模型（此处以 CPU 运行的 DeepSeek R1 和 Qwen2 为例）：

catalog:
  deepseek-r1-1.5b-cpu:
    enabled: true
    features: [TextGeneration]
    url: 'ollama://deepseek-r1:1.5b'
    engine: OLlama
    minReplicas: 1
    resourceProfile: 'cpu:1'
  qwen2-500m-cpu:
    enabled: true
  nomic-embed-text-cpu:
    enabled: true

使用 Helm 应用该配置：

helm install kubeai-models kubeai/models \
    -f ./kubeai-models.yaml

提示: 您可以新开一个终端窗口运行 kubectl get pods --watch 来观察 Pod 的启动过程。

基本使用

方式一：通过 Web UI 交互

对于设置了 minReplicas: 1 的模型（如本例中的 DeepSeek R1），Pod 启动后即可直接访问内置的聊天界面。

1. 端口转发：将服务映射到本地端口。

   kubectl port-forward svc/open-webui 8000:80
   

2. 访问界面：打开浏览器访问 http://localhost:8000。
3. 开始对话：在界面中选择 deepseek-r1-1.5b-cpu 模型即可开始聊天。

方式二：体验从零扩缩容 (Scale from Zero)

对于未设置最小副本数的模型（如本例中的 qwen2-500m-cpu，默认为 0），KubeAI 会在收到请求时自动拉起实例。

1. 在 Web UI 中选择 qwen2-500m-cpu 模型发送第一条消息。
2. 观察现象：首次响应会有短暂延迟，因为系统正在动态创建 Pod。
3. 验证状态：您可以在终端查看模型资源状态确认扩缩容行为：

   kubectl get models -oyaml qwen2-500m-cpu
   

方式三：通过 API 调用

KubeAI 完全兼容 OpenAI API 格式，您可以直接使用现有的 OpenAI 客户端库连接 http://localhost:8000/v1 (需先进行端口转发或配置 Ingress)。

支持的端点包括：

• /v1/chat/completions
• /v1/embeddings
• /v1/audio/transcriptions
• /v1/rerank

更多详细概念、高级指南及 API 文档，请访问 kubeai.org。