01
集群概览与报错总览
多节点vLLM推理集群架构简介、常见报错分类（网络、资源、配置、模型加载）、排错思维导图。
思维导图报错分类
02
K8s环境准备与检查
kubectl与集群连通性检查、节点状态与资源查看（kubectl get nodes）、kube-system核心组件健康检查。
kubectl节点状态
03
GPU节点驱动与容器运行时
NVIDIA驱动版本检查、nvidia-docker与containerd配置、nvidia-smi在Pod内的验证。
NVIDIAcontainerd
04
vLLM镜像拉取与版本兼容
镜像仓库认证（ImagePullSecret）、vLLM版本与CUDA版本对应关系、常见镜像拉取失败错误（ErrImagePull/ImagePullBackOff）。
镜像拉取版本兼容
05
Pod启动失败之资源配额
Resource Quota与LimitRange冲突、GPU资源请求格式（nvidia.com/gpu）、OOMKilled与内存限制调整。
ResourceQuotaOOM
06
Pod启动失败之调度问题
节点选择器（nodeSelector）与亲和性（affinity）、GPU节点污点（taint）与容忍（toleration）、Pending状态排查。
调度污点容忍
07
多节点通信之网络基础
K8s网络模型（CNI）、Pod IP与Service发现、跨节点通信延迟问题。
CNI跨节点
08
多节点通信之Headless Service
StatefulSet与Headless Service配置、vLLM分布式推理的gRPC通信、DNS解析失败（CoreDNS问题）。
HeadlessCoreDNS
09
多节点通信之端口冲突
vLLM默认端口（8000/8080）冲突、多副本Pod端口映射、hostPort与hostNetwork风险。
端口冲突hostNetwork
10
模型加载失败之存储挂载
PV/PVC配置错误、NFS挂载权限问题、ReadWriteMany与ReadWriteOnce选择。
PV/PVCNFS
11
模型加载失败之模型路径
模型路径配置错误、HuggingFace缓存目录、模型文件损坏检查。
模型路径HuggingFace
12
模型加载失败之显存不足
模型大小与GPU显存估算、vLLM的max-model-len与gpu-memory-utilization参数、显存碎片化处理。
显存碎片化
13
vLLM配置参数详解
tensor-parallel-size与pipeline-parallel-size、max-num-seqs与max-model-len、dtype与quantization。
并行量化
14
推理性能瓶颈之吞吐量
首token延迟（TTFT）与token生成速率、vLLM的调度策略、批处理大小（batch size）调优。
吞吐量TTFT
15
推理性能瓶颈之显存管理
KV Cache管理、PagedAttention原理、显存溢出（OOM）与自动回收。
KV CachePagedAttention
16
日志与监控体系
kubectl logs查看Pod日志、vLLM内置metrics（/metrics）、Prometheus与Grafana监控。
监控Prometheus
17
健康检查与自动恢复
Liveness Probe与Readiness Probe配置、Pod CrashLoopBackOff处理、自动重启策略。
探针CrashLoopBackOff
18
Ingress与外部访问
Ingress Controller配置、HTTPS证书挂载、负载均衡策略。
IngressHTTPS
19
ConfigMap与Secret管理
vLLM启动参数通过ConfigMap注入、API密钥通过Secret挂载、热更新配置。
ConfigMapSecret
20
多节点扩缩容问题
HPA（Horizontal Pod Autoscaler）配置、扩缩容时模型重加载、连接中断处理。
HPA扩缩容
21
节点故障与Pod迁移
节点宕机后Pod漂移、GPU显存残留清理、StatefulSet的Pod管理策略。
故障迁移StatefulSet
22
网络策略（NetworkPolicy）
限制Pod间非必要通信、gRPC端口白名单、默认拒绝策略。
NetworkPolicy白名单
23
安全与权限
RBAC配置、ServiceAccount权限最小化、Pod Security Policy（PSP）或Pod Security Admission。
RBACPSP
24
多租户隔离
Namespace隔离、ResourceQuota与LimitRange、不同模型部署隔离。
多租户Namespace
25
vLLM版本升级与回滚
滚动更新策略、vLLM API兼容性、回滚操作步骤。
滚动更新回滚
26
常见错误码与含义
HTTP 503 Service Unavailable、gRPC错误码（UNAVAILABLE/INTERNAL）、vLLM内部错误日志解读。
错误码gRPC
27
分布式推理的AllReduce问题
NCCL超时（NCCL_TIMEOUT）、NCCL拓扑感知、IB（InfiniBand）与RoCE配置。
NCCLInfiniBand
28
模型量化与精度问题
FP16/INT8/FP8量化配置、量化后精度损失排查、量化模型加载失败。
量化精度
29
自定义模型与分词器
自定义模型注册、分词器配置错误、tokenizer_config.json缺失。
自定义模型分词器
30
综合排障案例实战
端到端排障流程、从Pod Pending到推理成功的完整案例、排障Checklist与自动化脚本。
实战Checklist