AI/LLM on Kubernetes 基础设施¶

这套文档讨论的不是“怎样把一个带 GPU 的 Pod 跑起来”，而是怎样把 Kubernetes 建设成一套可持续演进的 AI/LLM 基础设施：设备能被发现和隔离，作业能公平排队，数据能跟上算力，训练能够恢复，推理能够满足延迟目标，模型和依赖能够追溯，平台能够升级、观测和审计。

内容覆盖从硬件到应用的完整链路，并尽量回答四类问题：组件负责什么、什么时候需要、怎样验证、出问题从哪里排查。

按主题浏览查看参考架构运行 GPU 平台实验进入实战与排障

基础设施全景¶

用户、SDK、应用与工作流
        │
        ├─ 大数据 / RAG / Agent / 在线推理 / 训练任务
        │
Gateway、Serving、Trainer、Pipeline、Queue
        │
Kubernetes API、控制器、调度器、准入与策略
        │
Device Plugin / CDI / DRA / CNI / CSI / CRI
        │
GPU、TPU、NPU、CPU、RDMA、NVMe、对象存储
        │
供电、散热、机架、故障域与数据中心网络

任何一层都可能成为瓶颈。GPU 利用率低不一定是 GPU 问题，也可能是排队策略、CPU 解码、模型下载、存储吞吐、网络拥塞、请求路由或批处理参数造成的。阅读和排障时，应沿着完整请求或作业链路逐层验证。

从哪里开始¶

你的目标	建议路径
从零理解 AI 如何运行在 Kubernetes 上	Kubernetes 如何承载 AI → 集群架构设计 → 术语表
建设或接管 GPU 集群	GPU 节点软件栈 → 设备管理 → GPU 调度 → 平台运维
选择开源集群管理平台	开源集群管理工具与方式 → 平台运维 → 跨集群与大规模 GPU
选择国内外云厂商 Kubernetes	云厂商托管 Kubernetes → 集群架构设计 → 异构加速器
建设 GPU Notebook 开发平台	GPU Notebook 平台与存储 → GPU 调度 → 数据与缓存 → MLOps
建设大数据与 AI 数据平台	大数据 on Kubernetes → 数据与缓存 → 模型制品 → MLOps
建设多租户训练平台	队列与多租户 → 分布式训练 → RDMA 网络 → 可靠性
建设 Ray 大模型平台	Ray 训练与推理 → 分布式训练 → 大数据 on Kubernetes → 可靠性
建设在线 LLM 推理服务	本地运行与测试 → 推理平台总览 → 推理引擎 → Serving 框架 → API 中转与网关选型 → 网关与路由 → Higress 实战
规划多地域或多 GPU 集群	集群架构设计 → 跨集群与大规模 GPU → 生产参考架构
建设 RAG 或 Agent 平台	Agent 现状与趋势 → Agent Harness → HarnessRouter → DeepSeek Harness 容器化 → Kubernetes 实战 → Agent Sandbox 选型 → 安全治理
负责 SRE、成本或容量	可观测性 → 性能基准 → 成本与容量 → 落地路线图

完整主题地图¶

基础与架构¶

Kubernetes 如何承载 AI：从 API、控制器、调度器到 CRI、CNI、CSI 和设备接口。
AI 集群架构设计：工作负载画像、节点池、故障域、单集群与多集群边界。
Kubernetes 流控与服务限流：APF、公平排队、客户端限速、GPU 任务准入与模型接口流量治理。
开源 Kubernetes 集群管理工具与方式：从 kubectl、Headlamp 和 GitOps，到 Rancher、Cluster API、Gardener、Karmada 与 OCM 的分层选型。
国内外主流云厂商 Kubernetes：对比 ACK、TKE、CCE、EKS、GKE 和 AKS 的托管边界、网络存储生态与 AI/GPU 能力。
Kubernetes 跨集群与大规模 GPU：Federation 历史、Karmada/MultiKueue 等当前能力，以及训练整 Job 放置和区域级推理架构。
Karmada 与 Virtual Kubelet 对比：集群级编排与虚拟节点适配的架构边界、副本语义、故障恢复、网络存储及 GPU 选型。
AI on Kubernetes 十年发展史：从 GPU Pod、Operator 和批调度，到 DRA、推理网关与分离式推理。
术语表：统一 Kubernetes、GPU、训练、推理、网络、RAG 和可靠性术语。

集群、节点与加速器¶

GPU 节点软件栈：固件、内核、驱动、容器运行时、CDI、Operator 与节点验收。
多厂商异构加速器：NVIDIA、AMD、Intel、TPU、Trainium/Inferentia 与 CPU/NPU。
Device Plugin、CDI 与 DRA：三者的职责、迁移路径和生产选型。
GPU 与异构资源调度：整卡、MIG、共享、拓扑、亲和性与碎片治理。

队列、弹性与容量¶

队列、公平共享与多租户：Kueue、ClusterQueue、Flavor、Cohort、优先级与抢占。
AI 工作负载弹性伸缩：HPA、KEDA、Cluster Autoscaler、Karpenter 与队列协同。
GPU 成本与容量规划：单位经济性、需求预测、利用率、Spot 和 FinOps。

网络、数据与模型制品¶

RDMA 与 AI 高速网络：InfiniBand、RoCE、GPUDirect、NCCL 和逐层排障。
AI 数据、存储与缓存：对象存储、共享文件、本地 NVMe、数据加载与缓存层级。
大数据 on Kubernetes：Spark、Flink、Kafka、Trino、Lakehouse、Operator、队列调度，以及训练与 RAG 数据链路。
模型制品、分发与缓存：格式、版本、OCI Modelcar、跨地域复制、P2P、节点缓存、流式加载和冷启动。

分布式训练¶

分布式训练平台：Kubeflow Trainer、KubeRay、JobSet 与训练生命周期。
大模型 SFT 入门：从一条问答样本开始，解释 Loss、LoRA、Batch、Epoch、Checkpoint、Dense、MoE 与各种并行方式。
Kubernetes 领域 SFT 社区实践：分析 KubeFix、K8s Distill、KubeBench 和 ITBench，说明领域数据、工具调用、安全边界与可执行评测应该怎样设计。
SFT 训练实战：从单卡 LoRA 到 DeepSeek V4：单卡闭环、多卡 MoE、DeepSeek V4 与多机网络实测。
DeepSeek V4 双机 RDMA 训练实测：用三轮 TCP/RDMA A/B、NCCL AllReduce/All-to-All 和负对照解释哪些训练能真正受益。
SwanLab 自托管与 SFT 指标：官方 Helm 部署、PoC/生产边界、ms-swift 接入、真实曲线和版本兼容性。
从 W&B Local 到 SwanLab：结合两年团队化 W&B Local 运维记录与当前 SwanLab 实测，比较功能、生产复杂度、迁移和授权边界。
Ray 在大模型训练与推理中的角色：Ray Core、Data、Train、Tune、Serve、Serve LLM 与 KubeRay 的端到端边界。
可靠性、Checkpoint 与故障恢复：RPO/RTO、Spot、优雅退出和故障演练。

LLM 推理¶

本地运行与测试大模型：用 Ollama、llama.cpp、LM Studio、LocalAI、MLX-LM 和 vLLM/SGLang 验证模型与应用契约。
LLM 推理平台总览：服务抽象、运行时、请求链路和容量模型。
推理引擎选型：vLLM、SGLang、TensorRT-LLM、Triton、llama.cpp 等运行时的边界。
LLM Serving 与 AI 微服务框架：vLLM、KServe、AIBrix、Ray Serve、BentoML、NVIDIA NIM 与应用层框架。
LLM 推理性能优化：TTFT、TPOT、批处理、KV Cache、量化、并行和推测解码。
KV Cache 原理、应用与 Kubernetes：Attention 原理、显存算例、前缀复用、分层缓存，以及请求路由、NUMA 和扩缩容。
大模型 API 中转器与 LLM Gateway 综述：模型聚合、自建统一 API、企业 AI Gateway、推理路由、语义路由、安全风险与选型。
AI Gateway 与智能路由：Gateway API Inference Extension、前缀感知、负载感知和流控。
Higress AI Gateway 实战：隔离安装、AI Proxy、Token 治理、可观测性，以及与 AIBrix 同集群和跨集群接入。
分布式与 Prefill/Decode 分离推理：模型并行、LeaderWorkerSet、llm-d、Dynamo 和 KV 传输。

RAG、Agent 与边缘¶

2026 年 AI Agent 现状、实现原理与趋势：主流编程、浏览器与企业 Agent 的产品格局、实现原理、框架、风险和演进方向。
Agent Harness 技术综述：Agent Loop、上下文、工具、状态恢复、沙箱、权限、验证与 Kubernetes 生产架构。
Agent 评估方法综述：任务成功、工具轨迹、故障恢复、安全、成本和人工介入的评分方法。
Harbor Agent 评测框架综述：Task、Agent Adapter、隔离环境、Verifier、Rollout 及 Kubernetes 生产化。
Jev System One 决策模型综述：不生成文本的概率决策接口、置信度、Agent 路由、社区争议、生产架构与评估方法。
HarnessRouter 综述：UHP、统一 Harness API、Cloud 与 Community Edition、安全边界、成本及与模型网关的关系。
DeepSeek Harness GitHub 仓库深度解析：源码目录、Cordis 插件树、Profile 与 Bundle、Agent Loop、事件溯源会话和能力 seam。
DeepSeek Harness Docker、Compose 与 Helm 部署实战：多架构镜像、EROFS 修复、状态持久化、StatefulSet、Helm 与安全暴露边界。
从 Docker 到 Kubernetes：DeepSeek Harness、内置 Chromium 与 DSH Plugin 实战：all-in-one 浏览器桌面、自研 DSH Plugin、Tailscale 远程入口、状态卷、Cilium 探针冲突和安全边界。
RAG 基础设施：采集、切分、Embedding、向量数据库、检索、重排和权限过滤。
Agent Sandbox 选型与架构分析：威胁模型、Kubernetes Agent Sandbox、gVisor、Kata、微虚机和托管平台决策。
CubeSandbox Kubernetes 部署条件与生产评估：60ms 基准口径、KVM/PVM、XFS、eBPF、Helm 与生产上线边界。
CubeSandbox Agent Adapter v0.3 实测：OpenClaw、DSH、Hermes 与 Codex 四客户端验收，以及持久租约、异步 Job、PTY、Checkpoint、Redis HA、多租户身份和迁移 Gate。
OpenClaw 作为企业 Agent 平台底座：可复用能力、企业控制面缺口、安全风险、二次开发边界和推荐架构。
OpenClaw 2.0 实测：与 1.x 的架构、功能、性能和迁移风险对比：隔离安装、Control UI、Workboard、无头 Agent、实测指标、doctor 迁移与回滚 Gate。
企业内部 AI 应用如何快速发布与共享：面向商务、法务和运营等非研发用户的搭建、试运行、审批、权限、运行时和应用目录设计。
AI Agent、沙箱与工具执行：RuntimeClass、网络边界、凭据、工具权限和审计。
边缘 AI 与云边协同：K3s、弱网自治、设备管理、模型 OTA 和边缘可观测性。

平台工程与生产运维¶

大模型时代的 GPU Notebook 平台与存储选型：JupyterHub、Kubeflow、托管 Workbench、GPU 共享、用户 Home、对象存储和本地缓存。
MLOps 与平台工程：流水线、实验、模型注册、GitOps 和平台 API。
GPU、训练与推理可观测性：DCGM、作业指标、TTFT/TPOT、Trace、SLO 和告警。
AI 平台安全与治理：身份、Pod Security、镜像与模型供应链、租户隔离。
性能基准、压测与回归：硬件、NCCL、存储、训练、推理和发布门禁。
平台运维、升级与多集群：版本矩阵、Canary、CRD、备份、灾备和事故响应。
AI on K8s 落地路线图：从现状评估到 30/60/90 天实施计划。

参考架构与实验¶

实战、排障与选型：GPU Pending、低利用率、推理引擎实测、成本计算、模型分发、Spot 恢复和安全攻防。
生产参考架构：小型 GPU 平台、多租户训练、高可用推理、分离式推理和 Agent 沙箱。
GPU 平台最小闭环实验：资源发现、GPU 冒烟、vLLM 服务、网络策略、冷启动和优雅下线。
AI/LLM 集群组件清单：按目标场景列出组件、必要性、引入理由和验收条件。

工具不等于架构¶

同一层通常有多个项目可选，项目之间也可能重叠。选择工具前先写清输入、输出、所有者和验收指标。

能力	常见实现	先回答的问题
设备接入	Device Plugin、CDI、DRA、厂商 Operator	需要整卡、分片、拓扑还是动态声明？
批调度	kube-scheduler、Kueue、Volcano	需要准入队列、公平共享还是 Gang Scheduling？
大数据计算	Spark、Flink、Trino、Ray Data	是批处理、流状态、交互 SQL 还是 AI 数据准备？
训练控制	Kubeflow Trainer、JobSet、KubeRay	训练框架、容错和弹性边界是什么？
模型服务	KServe、Seldon、自建控制器	需要标准模型 API、多模型还是 LLM 专用能力？
推理运行时	vLLM、SGLang、TensorRT-LLM、Triton	目标模型、硬件、延迟和吞吐是什么？
请求入口	Gateway API、Inference Extension、服务网格	路由需要理解模型、KV Cache 和队列状态吗？
Agent 执行	Agent Sandbox、gVisor、Kata、托管 Sandbox API	生命周期、隔离运行时和工具授权是否已经分层？
可观测性	Prometheus、OpenTelemetry、DCGM Exporter	能否从用户请求追到 Pod、GPU、网络和模型版本？

内容状态和更新规则¶

stable：原理和生产方法相对稳定，仍需结合目标 Kubernetes 和组件版本验证。
evolving：上游 API、项目边界或最佳实践仍在快速变化，上线前应检查官方版本说明。
lab：用于复现和学习的最小实验，不应不经评审直接复制到生产。
last_reviewed：最近一次按一手资料复核的日期，不代表所有依赖都固定在该日期。
示例优先表达结构和验证方法；生产配置还必须补齐镜像固定、容量、身份、密钥、备份、SLO 和变更流程。

建议的建设顺序¶

先建立节点、驱动、网络、存储和 GPU 的可重复验收基线。
再统一资源模型、队列、租户、镜像、模型制品和可观测性。
分别为训练、在线推理、离线推理、RAG 和 Agent 建立黄金路径。
用性能基准、故障演练、成本指标和升级矩阵形成持续交付门禁。
最后再根据规模引入 DRA、高级拓扑、分离式推理、多集群和复杂调度策略。

如果正在规划第一版平台，可以从生产参考架构选一个最接近的起点，再用落地路线图拆成阶段目标。