# 基于K3s的自托管LLM平台：GPU推理、多模型切换与云原生Agent工具链

> 一个完整的概念验证项目，展示如何在单节点K3s集群上搭建生产级LLM推理平台，支持vLLM后端、LiteLLM网关、多模型动态切换和完整的可观测性体系。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-06-15T14:13:20.000Z
- 最近活动: 2026-06-15T14:22:32.931Z
- 热度: 161.8
- 关键词: LLM平台, K3s, vLLM, LiteLLM, GPU推理, 云原生, Kubernetes, 多模型切换, 自托管AI
- 页面链接: https://www.zingnex.cn/forum/thread/k3sllm-gpuagent
- Canonical: https://www.zingnex.cn/forum/thread/k3sllm-gpuagent
- Markdown 来源: ingested_event

---

## 原作者与来源

- **原作者/维护者**: bitnik
- **来源平台**: GitHub
- **原始标题**: llm-platform
- **原始链接**: https://github.com/bitnik/llm-platform
- **发布时间**: 2026年6月15日

---

## 项目背景与目标

随着大语言模型（LLM）在开发工作流中的渗透加深，越来越多的团队开始探索如何在私有基础设施上部署和管理这些模型。与直接使用OpenAI或Anthropic的API相比，自托管方案带来了数据隐私、成本控制、模型选择灵活性等多重优势，但同时也引入了架构复杂性、运维门槛和资源管理的新挑战。

bitnik/llm-platform 项目正是针对这一需求而生的概念验证（POC）方案。它展示如何在单节点K3s集群上搭建一套完整的生产级LLM推理平台，涵盖从GPU驱动安装到多模型动态切换的全流程。这个项目的价值不仅在于"能让模型跑起来"，更在于它验证了整个生产部署模式——包括GPU调度、Operator管理、Kubernetes清单编排等关键环节。

---

## 整体架构概览

该平台的架构设计遵循云原生最佳实践，采用分层解耦的思路，将不同职责的组件清晰分离：

### 外部客户端层

开发者可以通过多种工具与平台交互：
- **Claude Code**：Anthropic的AI编程助手，通过HTTPS接入
- **kubectl-ai**：Kubernetes命令行AI助手
- **k8sgpt CLI**：Kubernetes诊断AI工具

### 网关层

**LiteLLM Proxy** 作为统一的API网关，承担以下职责：
- 按模型名称路由请求到不同的后端
- 实现用户级API密钥管理、预算控制和速率限制
- 提供统一的日志记录和监控能力
- 支持Anthropic与OpenAI协议之间的自动转换

### 推理层

**vLLM** 作为核心推理引擎，部署在单张物理GPU上。平台支持多模型部署，但在任意时刻只有一个模型处于活跃状态（ACTIVE），其他模型处于休眠状态（SLEEPING）。

### 存储与可观测性层

- **local-path PVC**：基于NVMe本地存储持久化模型权重文件
- **Prometheus + Grafana + OTel**：完整的监控、告警和链路追踪体系

---

## 多模型动态切换机制

这是该平台最具特色的设计之一。面对单GPU多模型的需求，项目采用了一种创新的"休眠-唤醒"策略：

### 状态定义

| 状态 | 描述 | 显存占用 |
|-----|------|---------|
| ACTIVE | 模型已加载到GPU显存，可立即响应推理请求 | ~20GB VRAM |
| SLEEPING (L1) | 模型权重从显存卸载到系统内存，保持内存映射 | 0 VRAM |
| COLD | 模型权重仅存在于磁盘存储，需完全重新加载 | 0 VRAM, 0 RAM |

### 切换控制器

平台内置一个切换控制器（switch controller），通过HTTP端点 `POST /sleep` 和 `POST /wake_up` 管理模型状态转换：

- 当需要切换模型时，当前活跃模型执行Level-1休眠，将权重从显存迁移到系统内存
- 目标模型从内存或磁盘加载到显存，成为新的活跃模型
- 这种设计使得在64GB系统内存的支持下，单张20GB显存的GPU可以托管多个大模型

### 实际价值

这种机制特别适合以下场景：
- **代码助手与聊天机器人混用**：白天使用代码生成模型，夜间切换为通用对话模型
- **多租户环境**：不同团队使用不同模型，按需切换而非为每个模型预留独立GPU
- **成本敏感场景**：最大化单GPU利用率，避免多卡部署的资本支出

---

## 部署流程详解

项目提供了一套完整的从零到一的部署指南，以下是关键步骤的技术 rationale：

### 1. 基础环境准备

**选择Ubuntu 24.04 LTS**：这是目前对NVIDIA驱动和CUDA支持最完善的发行版。Hetzner等裸金属服务器供应商通常只提供基础OS，需要自行安装GPU软件栈。

**安装NVIDIA驱动**：容器虽然自带CUDA运行时，但仍需宿主机内核驱动作为基础。通过 `nvidia-smi` 验证GPU可见性是继续后续步骤的必要前提。

**安装NVIDIA Container Toolkit**：这是容器访问GPU的桥梁。在K3s之前安装它，可以让K3s自动检测到nvidia容器运行时并创建相应的RuntimeClass。

### 2. Kubernetes集群搭建

**单节点K3s**：选择K3s而非标准K8s是因为其轻量级特性，特别适合POC场景。K3s内置了Traefik（Ingress控制器）和local-path（存储类），减少了额外配置工作。

**NVIDIA GPU Operator**：这是将"盒子里的GPU"转化为"Pod可申请的GPU资源"的关键组件。配置中禁用驱动和工具包安装（因为宿主机已具备），保留设备插件、节点特征发现和DCGM导出器功能。

### 3. 模型服务部署

**vLLM配置要点**：
- 请求 `nvidia.com/gpu: 1` 资源确保独占GPU访问
- 调整 `--gpu-memory-utilization` 参数优化显存使用
- 启用 `--enable-sleep-mode` 支持动态休眠功能

**持久化存储**：通过local-path PVC将模型权重存储在NVMe盘上，避免Pod重启时的重复下载（17GB+的模型文件）。

### 4. 网关与入口配置

**LiteLLM部署**：作为唯一的前向入口，所有客户端都通过它访问后端模型。vLLM本身不直接暴露，这种设计提供了：
- 统一的认证和授权层
- 灵活的模型别名和路由规则
- 详细的调用日志和用量统计

**Traefik Ingress + TLS**：通过cert-manager自动管理HTTPS证书，为外部开发工具提供安全接入点。集群内Agent则绕过Ingress，直接使用ClusterIP服务地址以获得更低延迟。

### 5. 客户端接入配置

不同工具的配置方式略有差异：

| 工具 | 配置方式 | 说明 |
|-----|---------|------|
| kagent | ModelConfig中设置provider: OpenAI，baseUrl指向LiteLLM | 集群内Agent |
| kubectl-ai/k8sgpt | 配置OpenAI base URL为LiteLLM地址 | CLI工具 |
| Claude Code | 设置ANTHROPIC_BASE_URL环境变量指向LiteLLM的Anthropic端点 | 需要协议转换 |

---

## 可观测性体系

平台内置了完整的监控栈，这是验证POC并发能力的关键仪器：

### 核心指标

- **GPU利用率**：通过DCGM导出器采集，反映GPU计算饱和程度
- **KV缓存压力**：vLLM特有的指标，显示注意力键值缓存的使用情况
- **抢占率（Preemptions）**：当显存不足时请求被中断的频率
- **P95延迟**：端到端推理延迟的百分位统计

### 链路追踪

可选集成OpenTelemetry，实现从客户端请求到模型推理的全链路追踪，帮助定位延迟瓶颈。

---

## 技术选型思考

### 为什么选择vLLM？

vLLM作为推理后端有多个显著优势：
- **PagedAttention算法**：显著提高显存利用率和吞吐率
- **连续批处理**：支持多用户并发请求的流水线处理
- **OpenAI兼容API**：降低客户端迁移成本
- **活跃的社区**：快速迭代和新模型支持

### 为什么选择LiteLLM？

LiteLLM作为网关层解决了多个实际问题：
- **多后端统一**：可以同时对接vLLM、OpenAI、Azure OpenAI等多种后端
- **预算管控**：细粒度的用量限制和成本控制
- **协议转换**：自动处理不同厂商API的差异

### 为什么选择K3s？

在单节点场景下，K3s的优势尤为明显：
- **资源占用低**：适合资源受限的边缘/POC环境
- **内置组件齐全**：默认包含存储、Ingress、DNS等基础能力
- **与标准K8s兼容**：POC验证的模式可以直接迁移到生产K8s集群

---

## 局限性与扩展方向

### 当前局限

- **单节点架构**：虽然简化了部署，但不具备高可用能力
- **手动模型切换**：需要显式调用API切换模型，尚未实现自动负载驱动的切换
- **存储限制**：local-path存储不具备跨节点迁移能力

### 可能的扩展

- **多节点扩展**：引入Kubernetes原生调度，支持多GPU分布式推理
- **自动扩缩容**：基于请求队列长度自动扩缩vLLM副本
- **模型缓存优化**：引入共享存储或模型仓库，加速冷启动
- **多租户隔离**：通过Namespace和NetworkPolicy实现更强的租户隔离

---

## 总结与启示

bitnik/llm-platform 项目为希望自建LLM基础设施的团队提供了一个扎实的起点。它的价值不仅在于代码本身，更在于其背后的设计思想：

1. **云原生优先**：充分利用Kubernetes的编排能力，而非自建调度逻辑
2. **分层解耦**：网关、推理、存储各司其职，便于独立升级和替换
3. **资源效率**：通过休眠机制最大化单GPU利用率，降低硬件成本
4. **可观测性内置**：将监控视为一等公民，而非事后补丁

对于正在评估自托管LLM方案的团队，这个项目提供了一个可运行的参考实现，帮助理解从裸机到可用服务的完整路径，以及其中涉及的技术权衡。