# 1. NVIDIA 驱动 + CUDA Toolkit（推荐 CUDA 12.x）
nvidia-smi                                # 确认驱动正常
nvcc --version                            # 确认 CUDA 已装

# 2. Docker + nvidia-container-toolkit
docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

# 3. Python 3.10+ + pip（AI Infra 几乎全是 Python 生态）
python --version                          # 最好是 3.10 或 3.11
pip install vllm transformers torch       # 核心依赖

# 4. Kubernetes 集群（本地用 kind 或 minikube）
brew install kind                         # macOS
kind create cluster --name ai-infra

# 5. Go / Java（你有基础，直接用你顺手的语言做 Gateway 开发）
go version

flowchart TB
    App[Application] --> Agent[Agent / MCP]
    Agent --> GW[Model Gateway]
    GW --> GPT[GPT]
    GW --> Claude[Claude]
    GW --> Gemini[Gemini]
    GPT --> INF
    Claude --> INF
    Gemini --> INF
    INF[Inference Layer<br/>vLLM / SGLang<br/>TensorRT-LLM / Triton / LMDeploy]
    INF --> SCHED[GPU Scheduler<br/>Kubernetes<br/>Volcano / Kueue / Ray]
    SCHED --> CLUSTER[GPU Cluster<br/>H100 / B200 / MI300]

pip install transformers torch
python3 << 'EOF'
from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

model_name = "Qwen/Qwen2-0.5B-Instruct"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype=torch.float16,
    device_map="auto"
)

prompt = "解释一下什么是 API Gateway："
inputs = tokenizer(prompt, return_tensors="pt").to(model.device)

# 观察：prompt 长度不同，第一次推理时间的变化
import time
start = time.time()
outputs = model.generate(**inputs, max_new_tokens=100)
print(f"耗时: {time.time() - start:.2f}s")
print(tokenizer.decode(outputs[0], skip_special_tokens=True))
EOF

python3 -c "
from transformers import AutoTokenizer
tok = AutoTokenizer.from_pretrained('Qwen/Qwen2-0.5B-Instruct')
text = '什么是 KV Cache？'
tokens = tok.tokenize(text)
ids = tok.encode(text)
print('分词结果:', tokens)
print('Token IDs:', ids)
print('Token 数量:', len(ids))
# 试试中英文混合：中文的 token 效率远低于英文
print('中文:', len(tok.encode('你好世界')))
print('英文:', len(tok.encode('Hello world')))
"

# 启动一个 vLLM 服务并观察显存
pip install vllm
python3 -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2-0.5B-Instruct \
  --gpu-memory-utilization 0.9 &

# 另一个终端观察显存
watch -n 1 nvidia-smi
# 记下启动前和启动后的显存变化——这就是模型权重 + KV Cache 预留的显存

# 启动 vLLM 服务
pip install vllm
python3 -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2-7B-Instruct \
  --gpu-memory-utilization 0.9 \
  --max-model-len 4096 \
  --port 8000 &

# 等加载完，用 curl 测试
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2-7B-Instruct",
    "messages": [{"role": "user", "content": "你好"}],
    "max_tokens": 100
  }' | python3 -m json.tool

# 压测：对比不同并发下吞吐和延迟
pip install vllm-benchmarks locust
# 用 locust 写一个并发测试脚本，对比 1/4/16/32 并发下的 p50/p99 延迟

# 先跑一次带 continuous batching 的（默认开启）
python3 -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2-7B-Instruct \
  --enable-chunked-prefill \
  --port 8001 &

# 用 vLLM 自带的 benchmark 工具压测
python3 -m vllm.benchmarks.serve \
  --model Qwen/Qwen2-7B-Instruct \
  --dataset-name sharegpt \
  --num-prompts 100 \
  --endpoint /v1/chat/completions

# 观察日志中的 "Running:" 和 "Waiting:" 数量变化——这就是 continuous batching 在起作用

# 场景：50 个请求共享同一个 system prompt（典型的 RAG/Agent 场景）
# 启动时开启 prefix caching
python3 -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2-7B-Instruct \
  --enable-prefix-caching \
  --port 8002 &

# 构造 50 个请求，它们共享一段 1000 token 的 system prompt
# 观察开启 prefix cache 后 TTFT (Time To First Token) 的变化
# 预期：TTFT 降低 50%+，因为 prefix 的 KV Cache 被复用

# 安装并启动 SGLang
pip install sglang[all]
python3 -m sglang.launch_server \
  --model Qwen/Qwen2-7B-Instruct \
  --port 30000 &

# 用相同的请求分别打 vLLM 和 SGLang
# 重点对比：Agent 多轮对话场景下，SGLang 的 Radix Cache 优势

# 用 PyTorch 观察内存分配
python3 << 'EOF'
import torch
import time

# 观察 HBM 分配
print(f"总显存: {torch.cuda.get_device_properties(0).total_mem / 1024**3:.1f} GB")
x = torch.randn(10000, 10000, device="cuda")
print(f"10000x10000 float32 占用: {x.element_size() * x.nelement() / 1024**2:.1f} MB")
torch.cuda.synchronize()
print(f"已分配: {torch.cuda.memory_allocated() / 1024**2:.1f} MB")
print(f"已缓存: {torch.cuda.memory_reserved() / 1024**2:.1f} MB")

# GPU 利用率 vs 显存利用率 —— 这是两个概念
# nvidia-smi 里的 "Volatile GPU-Util" 只代表 GPU 核有没有活跃
# 不代表显存带宽有没有打满
EOF

# 安装并使用 NVIDIA 官方 benchmark 工具
# DCGM (Data Center GPU Manager)
docker run --rm --gpus all nvcr.io/nvidia/k8s/dcgm-exporter:latest

# 或者直接用简单的 PyTorch benchmark
python3 << 'EOF'
import torch
import time

size = 1024 * 1024 * 100  # 100M 元素
x = torch.randn(size, device="cuda")

# 测试显存读取带宽（实际上是在测 HBM bandwidth）
torch.cuda.synchronize()
start = time.time()
for _ in range(100):
    y = x * 2
torch.cuda.synchronize()
elapsed = time.time() - start
data_moved = size * 4 * 3 * 100  # 读 x + 读 2(标量) + 写 y，100 次
bandwidth_gb_s = data_moved / elapsed / 1024**3
print(f"实测带宽: {bandwidth_gb_s:.1f} GB/s")
print(f"A100 理论带宽: ~1555 GB/s")
print(f"利用率: {bandwidth_gb_s / 1555 * 100:.1f}%")
EOF

# 启动 vLLM 并监控显存分布
python3 -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2-7B-Instruct \
  --gpu-memory-utilization 0.9 &

# 用 nvidia-smi 或 py-spy 观察
pip install py-spy
# 看看到底多少显存给了 KV Cache，多少给了模型权重
# 思考：为什么 "gpu-memory-utilization 0.9" 不等于显存真的用了 90%？

# 如果你的机器有 GPU
# 1. 安装 K3s（轻量 K8s）
curl -sfL https://get.k3s.io | sh -

# 2. 安装 NVIDIA GPU Operator
helm repo add nvidia https://helm.ngc.nvidia.com/nvidia
helm repo update
helm install --wait --generate-name \
  -n gpu-operator --create-namespace \
  nvidia/gpu-operator

# 3. 验证 GPU 可用
kubectl describe nodes | grep nvidia.com/gpu
# 应该看到类似 nvidia.com/gpu: 1 的输出

# 1. 安装 KServe
kubectl apply -f https://github.com/kserve/kserve/releases/latest/download/kserve.yaml

# 2. 创建一个 InferenceService
cat << 'EOF' | kubectl apply -f -
apiVersion: serving.kserve.io/v1beta1
kind: InferenceService
metadata:
  name: qwen2-7b
spec:
  predictor:
    containers:
    - name: kserve-container
      image: vllm/vllm-openai:latest
      args:
      - --model
      - Qwen/Qwen2-7B-Instruct
      - --gpu-memory-utilization
      - "0.9"
      resources:
        limits:
          nvidia.com/gpu: 1
EOF

# 3. 等 pod Ready 后测试
kubectl get inferenceservice qwen2-7b
# 拿到 URL 后用 curl 调用

# 安装 Volcano
kubectl apply -f https://raw.githubusercontent.com/volcano-sh/volcano/master/installer/volcano-development.yaml

# 创建 Queue 和两个 vLLM Job，观察优先级调度
# 一个高优推理服务 + 一个低优批处理推理，看 Volcano 怎么排队和抢占

# 7B 模型 + tensor parallel = 2 卡
python3 -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2-7B-Instruct \
  --tensor-parallel-size 2 \
  --gpu-memory-utilization 0.9 &

# 观察 nvidia-smi：两张卡都在做计算
# 思考：通信开销（all-reduce）占了总耗时的多少？

# 用 nccl-tests 实测卡间通信带宽
git clone https://github.com/NVIDIA/nccl-tests.git
cd nccl-tests && make
./build/all_reduce_perf -b 8 -e 128M -f 2 -g 2
# 对比 NVLink 和 PCIe 的带宽差异
# 这就是为什么 A100 用 NVLink 走的比 PCIe 快 5-10 倍

POST /v1/chat/completions
  ├── Auth           (JWT / API Key 鉴权)
  ├── Rate Limit     (按用户/API Key 限流)
  ├── Model Router   (根据请求路由到不同模型后端)
  │       ├── GPT-4  → Azure OpenAI
  │       ├── Claude → Anthropic API
  │       └── Qwen2  → 自建 vLLM 集群
  ├── Fallback       (主模型挂了切备用)
  └── Observability  (Prometheus metrics + OTEL tracing)

// 目录结构
// gateway/
//   main.go          -- HTTP server
//   auth.go          -- JWT/API Key middleware
//   ratelimit.go     -- token bucket / sliding window
//   router.go        -- model routing logic
//   proxy.go         -- reverse proxy to upstream
//   metrics.go       -- Prometheus instrumentation

// 核心路由逻辑伪代码
func (g *Gateway) Route(ctx context.Context, req *ChatRequest) (*Upstream, error) {
    // 1. 检查用户配额
    if err := g.rateLimiter.Allow(ctx, req.UserID); err != nil {
        return nil, ErrRateLimited
    }
    // 2. 根据 model 名选后端
    upstream := g.registry.Resolve(req.Model)
    // 3. 如果主后端不健康，走 fallback
    if !g.healthChecker.IsHealthy(upstream) {
        upstream = g.registry.GetFallback(req.Model)
    }
    return upstream, nil
}

# Prometheus 采集 vLLM 指标
# vLLM 自带 /metrics 端点
curl http://localhost:8000/metrics | grep vllm
# 关键指标：
#   vllm:num_requests_running      -- 当前正在处理的请求数
#   vllm:num_requests_waiting      -- 排队等待的请求数  
#   vllm:gpu_cache_usage_perc      -- KV Cache 使用率
#   vllm:time_to_first_token_seconds  -- TTFT
#   vllm:time_per_output_token_seconds -- TPOT

# Grafana dashboard 关注：
# - P50/P99 延迟曲线
# - 吞吐（tokens/s）
# - KV Cache 水位
# - 排队深度（waiting requests count）

# 让你的 Gateway 支持 MCP 协议（让 Agent 可以调用你的推理服务）
# 参考：https://modelcontextprotocol.io/
# 或者直接用一个现成的 MCP gateway，比如 LiteLLM
pip install litellm[proxy]
litellm --model ollama/qwen2 --port 4000
# LiteLLM 自带 OpenAI-compatible API + 多模型路由 + 成本追踪

@startmindmap
<style>
mindmapDiagram {
  node {
    BackgroundColor #F8F9FA
    RoundCorner 10
    Padding 10
    FontSize 13
  }
  :depth(0) {
    BackgroundColor #1E3A5F
    FontColor white
    FontSize 18
    FontStyle bold
  }
  :depth(1) {
    FontSize 15
    FontStyle bold
  }
  :depth(2) {
    FontSize 13
  }
}
</style>

* AI Infra 练级手册
** S0: 环境搭建
*** GPU 机器 + nvidia-smi
*** Docker + CUDA Toolkit
*** Python 3.10+ / vLLM
*** K8s 本地集群
** S1: LLM 基础 (1周)
*** Illustrated Transformer
*** 亲手跑一次推理
*** 理解 Tokenization
*** Prefill vs Decode
** S2: Inference (2周)
*** vLLM 部署 + 压测
*** PagedAttention 原理
*** Continuous Batching
*** SGLang Radix Cache
** S3: GPU (2~3周)
*** GPU 显存层级
*** Memory Bandwidth 瓶颈
*** nvidia-smi / nsys
*** 手算模型显存
** S4: Kubernetes AI (2周)
*** GPU Operator 安装
*** KServe 部署
*** Volcano / Kueue 调度
*** MIG / GPU Sharing
** S5: Distributed AI (2周)
*** Tensor/Pipeline Parallel
*** NCCL AllReduce
*** 手算多卡方案
*** DeepSpeed ZeRO
** S6: AI Platform (长期)
*** Model Gateway 开发
*** Observability 接入
*** MCP / Agent 集成
*** 开源社区贡献
@endmindmap