SGLang 面试题

Client Request → Tokenizer → Radix Tree 前缀匹配 → KV Cache 复用
→ Prefill（仅计算增量部分） → Decode（Continuous Batching） → Detokenizer → Response

Root
├── "You are a helpful assistant."  [KV Block: 0x1A]
│   ├── "What is Kubernetes?"        [KV Block: 0x2B]
│   │   ├── "Explain in detail."     [KV Block: 0x3C]
│   │   └── "Give a short answer."   [KV Block: 0x4D]
│   └── "What is Docker?"            [KV Block: 0x5E]
└── "Summarize the following text:"  [KV Block: 0x6F]

首轮：[System Prompt: 1024 tokens] + [User: 128 tokens] → 计算 1152 tokens
二轮：[System Prompt: 1024 tokens] + [User: 256 tokens] → 复用 1024 tokens，仅计算 256 tokens
三轮：[System Prompt: 1024 tokens] + [User: 64 tokens]  → 复用 1024 tokens，仅计算 64 tokens

GPU 显存总览：
├── Model Weights（模型权重固定占用）
├── KV Cache Pool（可调大小）
│   ├── Active Blocks（正在被使用，ref > 0）
│   └── Cached Blocks（可淘汰，ref = 0，按 LRU 顺序）
└── Workspace（临时计算缓冲区）

# KV Cache 池大小（GPU 显存占比）
--mem-fraction-static 0.85        # 模型权重 + KV Cache 静态占比
--max-total-tokens 65536          # KV Cache 池最大 token 数
--eviction-policy lru             # 淘汰策略

import sglang as sgl

@sgl.function
def multi_turn_agent(s, query):
    # System prompt 作为初始状态
    s += sgl.system("You are a helpful coding assistant.")
    s += sgl.user(query)

    # 选择意图
    s += sgl.assistant("Intent: ")
    s += sgl.gen("intent", max_tokens=16, stop="\n")

    # 根据意图分支
    intent = s["intent"]
    if "code" in intent:
        s += sgl.assistant("Code:\n```python\n")
        s += sgl.gen("code", max_tokens=512, stop="\n```")
    else:
        s += sgl.assistant(sgl.gen("response", max_tokens=256))

    return s

# 执行
state = multi_turn_agent.run("Write a function to sort a list.")
print(state["code"])  # 提取指定字段

# SGLang Native（默认，推荐）
python -m sglang.launch_server \
    --model-path meta-llama/Llama-3-70B \
    --backend sglang

# vLLM 后端
python -m sglang.launch_server \
    --model-path meta-llama/Llama-3-70B \
    --backend vllm

graph TD
    Frontend["SGLang Frontend（DSL / OpenAI API）"]
    Runtime["SGLang Runtime（RadixAttention / Scheduler）"]
    Interface["Backend Interface（--backend 抽象）"]
    Sglang["sglang (Native)"]
    Vllm["vllm"]
    Lightllm["lightllm"]
    Tgi["tgi"]

    Frontend --> Runtime --> Interface
    Interface --> Sglang
    Interface --> Vllm
    Interface --> Lightllm
    Interface --> Tgi

JSON Schema 定义 → 编译为 token-level FSM
    → Decode 阶段每步采样
        → FSM 给出合法 token 集合
            → Logits Mask（非法 token → -inf）
                → 从合法 token 集合中采样
                    → 推进 FSM 状态
                        → 循环直至终止

# Regex 约束
@sgl.function
def phone_extract(s, text):
    s += sgl.user(f"Extract phone number from: {text}")
    s += sgl.assistant(sgl.gen(
        "phone",
        regex=r"\d{3}-\d{3}-\d{4}",
        max_tokens=20
    ))

# JSON Schema 约束
@sgl.function
def json_api_call(s, prompt):
    s += sgl.user(prompt)
    s += sgl.assistant(sgl.gen(
        "api_params",
        max_tokens=256,
        json_schema={
            "type": "object",
            "properties": {
                "method": {"type": "string", "enum": ["GET", "POST", "PUT"]},
                "url": {"type": "string"},
                "headers": {"type": "object"}
            },
            "required": ["method", "url"]
        }
    ))

sgl.gen(
    name="output",
    max_tokens=512,
    regex=r"...",              # Regex 约束
    json_schema={...},         # JSON Schema 约束
    stop=["\n---", "END"],    # 停止标记
    temperature=0.0,           # 建议 temperature=0 确保确定性
    top_p=0.95
)

Request → Prefill（System + User Prompt）
    → Radix Tree 锚定前缀节点
        → fork(3)
            ├── Branch 0: decode → "temperature=0 的确定性回答"
            ├── Branch 1: decode → "temperature=0.7 的创造性回答"
            └── Branch 2: decode → "temperature=1.0 的高随机回答"
        → join → 返回 3 个结果

@sgl.function
def multi_branch_generation(s, prompt):
    s += sgl.system("You are a helpful assistant.")
    s += sgl.user(prompt)

    # 并行生成多个版本
    forks = s.fork(5)
    forks += sgl.assistant(sgl.gen(
        "response",
        max_tokens=256,
        temperature=0.8,
        top_p=0.95
    ))
    forks.join()

    return s

# Best-of-N 投票
@sgl.function
def best_of_n(s, prompt, n=5):
    s += sgl.user(prompt)
    forks = s.fork(n)
    forks += sgl.assistant(sgl.gen("candidate", max_tokens=100))
    forks.join()

    # 二次评估每个候选
    s += sgl.user(f"Rate each candidate from 1-10:\n" +
                  "\n".join([f"{i}: {s[f'candidate_{i}']}" for i in range(n)]))
    s += sgl.assistant(sgl.gen("best_index", regex=r"\d+", max_tokens=5))
    return s

时间线（单卡 GPU）：
t0: [Req1 Prefill] |                    | [Req1 Decode]
t1:                  | [Req2 Prefill]   | [Req1 Decode] [Req2 Decode]
t2:                                     | [Req1 Done]   [Req2 Decode] [Req3 Prefill]
t3:                                     |                [Req2 Done]   [Req3 Decode] [Req4 Prefill]

t0: [Req1 Prefill: Full System Prompt 1024t]  |
t1: [Req2 Prefill: Reuse 1024t + Δ 128t]      |  [Req1 Decode] [Req2 Decode]
t2: [Req3 Prefill: Reuse 1024t + Δ 64t]       |  [Req1 Decode] [Req2 Decode] [Req3 Decode]

python -m sglang.launch_server \
    --max-total-tokens 65536 \      # KV Cache 池大小
    --max-running-requests 256 \    # 最大并发请求数
    --max-prefill-tokens 16384 \    # 单批次 Prefill 最大 token 数
    --schedule-policy lpm           # 调度策略：lpm (longest prefix match)

Target Model（大模型，验证者）
     ↑
     │ 并行验证 K 个候选 token
     │
Draft Model（小模型，推测者）
     ↑
     │ 快速自回归生成 K 个候选 token
     │
共享前缀（RadixAttention KV Cache 复用）

# 启动 Server 端配置
python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-70B-Instruct \
    --speculative-algorithm eagle \
    --speculative-draft-model-path meta-llama/Llama-3.1-8B-Instruct \
    --speculative-num-steps 5 \
    --speculative-eagle-topk 1 \
    --speculative-num-draft-tokens 5

# 单机 4 卡 Tensor Parallelism
python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-70B-Instruct \
    --tp-size 4

# 单机 8 卡 Tensor Parallelism + Pipeline Parallelism
python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-405B-Instruct \
    --tp-size 4 \
    --pp-size 2

# 指定 GPU 设备
CUDA_VISIBLE_DEVICES=0,1,2,3 python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-70B-Instruct \
    --tp-size 4

# Data Parallel 多实例（多组 TP）
python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-70B-Instruct \
    --tp-size 4 \
    --dp-size 2 \
    --node-rank 0

# NCCL 通信后端
export NCCL_SOCKET_IFNAME=eth0
export NCCL_IB_DISABLE=0
export NCCL_NET_GDR_LEVEL=2

# 多节点场景
export MASTER_ADDR=<master-ip>
export MASTER_PORT=29500

python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-8B-Instruct \
    --host 0.0.0.0 \
    --port 30000

# OpenAI Python SDK 调用
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:30000/v1",
    api_key="not-needed"
)

response = client.chat.completions.create(
    model="meta-llama/Llama-3.1-8B-Instruct",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain Kubernetes in 3 sentences."}
    ],
    temperature=0.7,
    max_tokens=256,
    stream=True
)

for chunk in response:
    print(chunk.choices[0].delta.content, end="")

curl http://localhost:30000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/Llama-3.1-8B-Instruct",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ],
    "temperature": 0.7,
    "max_tokens": 128
  }'

# 启用 API Key 验证
python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-8B-Instruct \
    --api-key my-secret-key

apiVersion: v1
kind: ConfigMap
metadata:
  name: sglang-config
data:
  model-path: "meta-llama/Llama-3.1-8B-Instruct"
  tp-size: "1"
  port: "30000"
apiVersion: apps/v1
kind: Deployment
metadata:
  name: sglang-server
spec:
  replicas: 1
  selector:
    matchLabels:
      app: sglang
  template:
    metadata:
      labels:
        app: sglang
    spec:
      containers:
      - name: sglang
        image: lmsysorg/sglang:latest
        command: ["python", "-m", "sglang.launch_server"]
        args:
        - "--model-path"
        - "$(MODEL_PATH)"
        - "--tp-size"
        - "$(TP_SIZE)"
        - "--host"
        - "0.0.0.0"
        - "--port"
        - "$(PORT)"
        env:
        - name: MODEL_PATH
          valueFrom:
            configMapKeyRef:
              name: sglang-config
              key: model-path
        - name: TP_SIZE
          valueFrom:
            configMapKeyRef:
              name: sglang-config
              key: tp-size
        - name: PORT
          valueFrom:
            configMapKeyRef:
              name: sglang-config
              key: port
        - name: CUDA_VISIBLE_DEVICES
          value: "0"
        ports:
        - containerPort: 30000
          name: http
        resources:
          limits:
            nvidia.com/gpu: 1
            memory: "64Gi"
          requests:
            nvidia.com/gpu: 1
            memory: "32Gi"
        readinessProbe:
          httpGet:
            path: /health
            port: 30000
          initialDelaySeconds: 60
          periodSeconds: 10
        livenessProbe:
          httpGet:
            path: /health
            port: 30000
          initialDelaySeconds: 120
          periodSeconds: 30
        volumeMounts:
        - name: model-cache
          mountPath: /root/.cache/huggingface
      volumes:
      - name: model-cache
        persistentVolumeClaim:
          claimName: model-cache-pvc
apiVersion: v1
kind: Service
metadata:
  name: sglang-svc
spec:
  selector:
    app: sglang
  ports:
  - port: 30000
    targetPort: 30000
  type: ClusterIP

# 单 Pod 多卡
env:
- name: CUDA_VISIBLE_DEVICES
  value: "0,1,2,3"
resources:
  limits:
    nvidia.com/gpu: 4
args:
- "--model-path"
- "meta-llama/Llama-3.1-70B-Instruct"
- "--tp-size"
- "4"
- "--host"
- "0.0.0.0"
- "--port"
- "30000"

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: sglang-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: sglang-server
  minReplicas: 1
  maxReplicas: 5
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70

# 模型缓存 PVC
--model-path /models/Llama-3.1-8B-Instruct  # 本地路径优于远程下载

# 合理设置资源预留
--mem-fraction-static 0.85                    # GPU 显存静态分配比例
--max-total-tokens 65536                      # KV Cache 池大小

# 日志配置
--log-level info                              # 日志级别
--log-requests True                           # 记录请求日志

graph LR
    subgraph PagedAttention
        BT["Block Table"]
        B0["Block 0 → GPU Addr"]
        B1["Block 1 → GPU Addr"]
        B2["Block 2 → GPU Addr"]
        BT --- B0
        BT --- B1
        BT --- B2
    end
    PagedAttention -.->|"需哈希匹配完整 Prompt"| Fixed["固定粒度"]

    subgraph RadixAttention
        RT["Radix Tree"]
        Root["Root"]
        Sys["System:"]
        KV["KV[0:1024]"]
        RT --- Root --> Sys --> KV
    end
    RadixAttention -.->|"任意 token 序列匹配"| Any["任意粒度"]

每步调度决策：
1. 计算当前 KV Cache 池剩余容量
2. 计算正在进行 Decode 的请求数
3. 计算等待 Prefill 的请求数及其 token 数
4. 决策：
   if 剩余 KV Cache > threshold_dec:
       优先完成 Prefill（快速释放 KV Cache 压力）
   elif 等待队列中 Prefill ≥ 2:
       混合 1 个 Prefill + N 个 Decode
   else:
       全部 Decode
5. Batched 执行，进入下一步

python -m sglang.launch_server \
    --schedule-policy lpm \                  # 最长前缀匹配调度
    --max-prefill-tokens 16384 \             # 单批次最大 Prefill token 数
    --schedule-conservativeness 0.5 \        # 调度保守度（0=激进, 1=保守）
    --max-running-requests 256               # 最大并发请求数

# 使用 AWQ 量化模型
python -m sglang.launch_server \
    --model-path TheBloke/Llama-2-70B-Chat-AWQ \
    --quantization awq \
    --dtype float16 \
    --tp-size 4

# 使用 GPTQ 量化模型
python -m sglang.launch_server \
    --model-path TheBloke/Llama-2-70B-Chat-GPTQ \
    --quantization gptq \
    --dtype float16 \
    --tp-size 4

# 使用 FP8 量化
python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-70B-Instruct \
    --quantization fp8 \
    --dtype float8_e4m3fn \
    --tp-size 2

# 运行时动态转换为 FP8
python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-70B-Instruct \
    --quantization fp8 \
    --kv-cache-dtype fp8_e5m2 \           # KV Cache 单独指定 FP8
    --dtype float16                        # 权重数据类型

# LLaVA-1.6 部署
python -m sglang.launch_server \
    --model-path liuhaotian/llava-v1.6-vicuna-7b \
    --tokenizer-path liuhaotian/llava-v1.6-vicuna-7b \
    --chat-template llava \
    --tp-size 1

# Qwen2-VL 部署
python -m sglang.launch_server \
    --model-path Qwen/Qwen2-VL-7B-Instruct \
    --tp-size 2

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:30000/v1",
    api_key="not-needed"
)

response = client.chat.completions.create(
    model="liuhaotian/llava-v1.6-vicuna-7b",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {"type": "image_url", "image_url": {
                "url": "https://example.com/image.jpg"
            }}
        ]
    }],
    max_tokens=256
)

@sgl.function
def visual_qa(s, image_path, question):
    s += sgl.user(sgl.image(image_path) + question)
    s += sgl.assistant(sgl.gen("answer", max_tokens=256))
    return s

result = visual_qa.run(
    image_path="/path/to/image.jpg",
    question="Describe this image in detail."
)

Base Model Weight: W ∈ R^(d×k)
LoRA Adapter:       ΔW = A·B,   A ∈ R^(d×r), B ∈ R^(r×k), r ≪ min(d,k)
Effective Weight:   W' = W + ΔW

请求侧指定 adapter_id → Runtime 动态加载对应的 A,B 矩阵

# 启动时指定 LoRA 适配器目录
python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-8B-Instruct \
    --lora-paths \
        math=path/to/math-lora,\
        code=path/to/code-lora,\
        medical=path/to/medical-lora \
    --max-lora-rank 64 \
    --lora-backend triton \
    --tp-size 1

# 指定 LoRA 适配器
response = client.chat.completions.create(
    model="math",  # 对应 --lora-paths 中定义的 math 适配器
    messages=[{"role": "user", "content": "Solve integral of x^2 dx"}],
    max_tokens=256
)

# 不指定 LoRA：使用基础模型
response = client.chat.completions.create(
    model="meta-llama/Llama-3.1-8B-Instruct",
    messages=[{"role": "user", "content": "Hello!"}],
    max_tokens=256
)

python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-8B-Instruct \
    --cuda-graph-max-bs 256 \           # CUDA Graph 最大 batch size
    --cuda-graph-bs "[1,2,4,8,16,32]"  # 预编译的 batch size 列表

python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-8B-Instruct \
    --attention-backend flashinfer      # 使用 FlashInfer 作为 Attention 后端

python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-8B-Instruct \
    --enable-torch-compile              # 启用 Torch Inductor 编译

python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-8B-Instruct \
    --kv-cache-dtype fp8_e5m2           # KV Cache 使用 FP8 存储

python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-70B-Instruct \
    --tp-size 4 \
    --attention-backend flashinfer \
    --kv-cache-dtype fp8_e5m2 \
    --cuda-graph-max-bs 256 \
    --enable-torch-compile \
    --mem-fraction-static 0.85 \
    --max-total-tokens 131072

# 单机 8 卡，Data Parallel：2 组 TP=4
python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-70B-Instruct \
    --tp-size 4 \
    --dp-size 2

# GPU 映射：GPU0-3 → TP Group 0（实例 0）
#          GPU4-7 → TP Group 1（实例 1）

# 配置请求路由均衡策略
python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-70B-Instruct \
    --tp-size 4 \
    --dp-size 2 \
    --load-balance-method round-robin   # 轮询（默认）或 shortest-queue

# DeepSeek-V2 / Mixtral 8x7B 等 MoE 模型
python -m sglang.launch_server \
    --model-path deepseek-ai/DeepSeek-V2 \
    --tp-size 4 \
    --ep-size 8 \
    --enable-ep-moe                     # 启用 Expert Parallel + MoE 优化

# 节点 0（Master）
python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-405B-Instruct \
    --tp-size 8 \
    --nnodes 2 \
    --node-rank 0 \
    --master-addr 192.168.1.100 \
    --master-port 29500

# 节点 1（Worker）
python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-405B-Instruct \
    --tp-size 8 \
    --nnodes 2 \
    --node-rank 1 \
    --master-addr 192.168.1.100 \
    --master-port 29500

export NCCL_SOCKET_IFNAME=eth0          # 指定 NCCL 通信网卡
export NCCL_IB_DISABLE=0               # 启用 InfiniBand
export NCCL_NET_GDR_LEVEL=2            # GPUDirect RDMA
export NCCL_DEBUG=INFO                 # NCCL 调试日志
export GLOO_SOCKET_IFNAME=eth0         # Gloo 通信网卡

python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-8B-Instruct \
    --log-level info \
    --log-requests True \
    --log-requests-level 2 \
    --show-time-cost True

[2024-01-15 10:23:45] Finish request: rid=abc123, 
  input_tokens=2048, output_tokens=512,
  prefill_time=0.32s, decode_time=2.15s,
  ttft=0.35s, latency=2.47s, 
  kv_cache_hit_rate=0.85

# 访问 http://localhost:30000/metrics

sglang:num_running_reqs          # 当前正在处理的请求数
sglang:num_queue_reqs            # 队列中等待的请求数
sglang:num_used_tokens           # KV Cache 池已使用 token 数
sglang:token_usage               # KV Cache 使用率
sglang:gen_throughput            # Token 生成吞吐（tokens/s）
sglang:time_to_first_token       # 首 token 延迟统计
sglang:time_per_output_token     # 每 token 生成延迟
sglang:e2e_request_latency       # 端到端请求延迟
sglang:cache_hit_rate            # KV Cache 命中率

# Prometheus ServiceMonitor
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: sglang-monitor
spec:
  selector:
    matchLabels:
      app: sglang
  endpoints:
  - port: http
    path: /metrics
    interval: 15s

# 单 API Key
python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-8B-Instruct \
    --api-key sk-secret-key-12345

# 多 API Key（文件方式）
python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-8B-Instruct \
    --api-key-file /etc/sglang/api_keys.txt

# 客户端携带 API Key
client = OpenAI(
    base_url="http://localhost:30000/v1",
    api_key="sk-secret-key-12345"
)

python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-8B-Instruct \
    --max-running-requests 64 \           # 最大并发请求数
    --max-total-tokens 65536 \            # KV Cache 池大小（隐式限流）
    --max-prefill-tokens 16384 \          # 单请求最大 Prefill token
    --context-length 8192                 # 上下文长度限制

# 仅监听内网
python -m sglang.launch_server \
    --host 127.0.0.1 \                    # 仅本机访问
    --port 30000

# 反向代理 + HTTPS
# Nginx 配置示例
location /v1/ {
    proxy_pass http://127.0.0.1:30000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_read_timeout 600s;
    # 限流
    limit_req zone=sglang burst=20 nodelay;
}

# 生产环境安全配置组合
python -m sglang.launch_server \
    --model-path /models/Llama-3.1-8B-Instruct \
    --host 127.0.0.1 \                    # 仅监听 localhost
    --port 30000 \
    --api-key $(cat /etc/sglang/api_key) \ # 环境变量或文件传入
    --max-running-requests 128 \
    --context-length 8192 \
    --trust-remote-code False             # 禁止执行远程代码

# 大部分 HuggingFace 模型无需额外适配，直接加载
python -m sglang.launch_server \
    --model-path my-org/my-custom-model \
    --trust-remote-code True

# model_config.py 覆盖默认配置
from sglang.srt.models.llama import LlamaForCausalLM

class CustomLlamaForCausalLM(LlamaForCausalLM):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        # 覆盖 attention 或 FFN 实现

EntryClass = CustomLlamaForCausalLM

python -m sglang.launch_server \
    --model-path my-org/my-custom-model \
    --model-impl path/to/model_config.py \
    --trust-remote-code True

# custom_model.py
import torch
from sglang.srt.model_executor.model_runner import ModelRunner

class CustomModelRunner(ModelRunner):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

    def load_model(self):
        # 自定义模型加载逻辑
        pass

    def forward(self, input_ids, positions, ...):
        # 自定义前向传播
        pass

    def update_weights_from_disk(self, *args, **kwargs):
        # 自定义权重更新逻辑
        pass

# 指定独立的 Tokenizer 路径
python -m sglang.launch_server \
    --model-path my-org/my-custom-model \
    --tokenizer-path my-org/my-tokenizer \
    --trust-remote-code True

# 指定 Chat Template
python -m sglang.launch_server \
    --model-path my-org/my-custom-model \
    --chat-template my-custom-template

端到端延迟 = Queue Waiting + Prefill Time + TTFT + Decode Time
              ──────────   ────────────   ────   ───────────
              Scheduler      Attention   调度+   自回归生成
              与KV Cache     计算+       Tokenizer
              管理            网络传输

# 低延迟优先配置
python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-8B-Instruct \
    --tp-size 1 \
    --attention-backend flashinfer \
    --cuda-graph-max-bs 64 \
    --cuda-graph-bs "[1,2,4,8,16,32,64]" \
    --max-running-requests 32 \             # 限制并发，降低排队
    --max-prefill-tokens 8192 \             # 限制单次 Prefill 规模
    --schedule-conservativeness 1.0 \       # 保守调度，延迟优先
    --disable-radix-cache False

# 客户端 Streaming 调用
response = client.chat.completions.create(
    model="meta-llama/Llama-3.1-8B-Instruct",
    messages=[{"role": "user", "content": prompt}],
    max_tokens=256,
    stream=True,                # Streaming 降低 TTFT 感知
    temperature=0.0             # 贪婪采样减少延迟抖动
)

Throughput (tokens/s) = Batch_Size × Sequence_Length / Latency

优化方向：
1. 增大 Batch_Size：增加并发请求数、提高显存利用率
2. 减小 Latency：RadixAttention 前缀复用、FlashInfer 加速
3. 提高显存效率：FP8 KV Cache、量化权重

# 高吞吐优先配置
python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-8B-Instruct \
    --tp-size 1 \
    --attention-backend flashinfer \
    --kv-cache-dtype fp8_e5m2 \             # FP8 KV Cache 节省 50% 显存
    --cuda-graph-max-bs 512 \               # 大 batch CUDA Graph
    --max-total-tokens 131072 \             # 大型 KV Cache 池
    --max-running-requests 512 \            # 高并发
    --max-prefill-tokens 32768 \            # 大批量 Prefill
    --mem-fraction-static 0.92 \            # 最大化显存分配
    --schedule-conservativeness 0.0 \       # 激进调度，吞吐优先
    --enable-torch-compile                  # Torch Inductor 编译优化

# 逐步调大，监控 OOM
--max-total-tokens 8192   # 初始值
--max-total-tokens 16384  # 调大
--max-total-tokens 32768  # 继续调大
--max-total-tokens 65536  # 目标值
--max-total-tokens 131072 # 最大尝试

# 监控指标
curl http://localhost:30000/metrics | grep "token_usage"

前缀复用率 = 复用的 token 数 / 总 Prefill token 数

提升方法：
1. 统一 System Prompt（所有请求使用相同或相似前缀）
2. Few-shot 示例标准化（固定格式，减少变化）
3. Prompt 模板化（动态部分放在末尾）
4. 请求分组路由（相似 Prompt 路由到同一实例）

# SGLang 异常请求处理
python -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-8B-Instruct \
    --max-total-tokens 65536 \              # 防止 OOM
    --context-length 8192 \                 # 限制单请求上下文
    --max-running-requests 128              # 限制并发

# 客户端重试机制
from tenacity import retry, stop_after_attempt, wait_exponential

@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=2, max=30)
)
def inference_request(prompt):
    return client.chat.completions.create(
        model="meta-llama/Llama-3.1-8B-Instruct",
        messages=[{"role": "user", "content": prompt}],
        max_tokens=256
    )

apiVersion: apps/v1
kind: Deployment
metadata:
  name: sglang-server
spec:
  replicas: 2
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0              # 零停机更新
  template:
    spec:
      affinity:
        podAntiAffinity:             # 反亲和：分散到不同节点
          requiredDuringSchedulingIgnoredDuringExecution:
          - labelSelector:
              matchLabels:
                app: sglang
            topologyKey: kubernetes.io/hostname
      containers:
      - name: sglang
        livenessProbe:               # 存活探针
          httpGet:
            path: /health_generate
            port: 30000
          initialDelaySeconds: 120
          periodSeconds: 30
          failureThreshold: 3
        readinessProbe:              # 就绪探针
          httpGet:
            path: /health
            port: 30000
          initialDelaySeconds: 60
          periodSeconds: 10
          failureThreshold: 3

# 当前生产版本（Blue）
apiVersion: apps/v1
kind: Deployment
metadata:
  name: sglang-v1
  labels:
    version: v1
    active: "true"
spec:
  replicas: 2
  ...

# 新版本（Green）
apiVersion: apps/v1
kind: Deployment
metadata:
  name: sglang-v2
  labels:
    version: v2
    active: "false"
spec:
  replicas: 0                        # 初始 0 副本
  ...

# NCCL 超时与重试
export NCCL_ASYNC_ERROR_HANDLING=1
export NCCL_TIMEOUT=600               # NCCL 超时（秒）
export NCCL_NET_GDR_LEVEL=2
export NCCL_IB_TIMEOUT=22

# 检查当前版本
python -c "import sglang; print(sglang.__version__)"

# 升级到最新版本
pip install --upgrade sglang[all]

# 查看版本变更
# https://github.com/sgl-project/sglang/releases

# 1. 模型本地持久化存储
# 使用 PVC 或 HostPath 缓存模型，避免每次启动从 HuggingFace 下载
python -m sglang.launch_server \
    --model-path /models/Llama-3.1-8B-Instruct \    # 本地路径
    --model-loader-extra-config '{"ignore_patterns":["*.safetensors"]}'

# 2. 模型预热
# 启动后发送预热请求，编译 CUDA Graph 和 Torch Inductor
curl http://localhost:30000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"Llama-3.1-8B-Instruct","messages":[{"role":"user","content":"ping"}],"max_tokens":1}'

# 显存分配
--mem-fraction-static 0.85                   # 85% 用户资源分配（余 15% 缓冲）
--max-total-tokens <显存取 60–70% 的 token 数>  # KV Cache 池大小

# 计算公式（以 80GB A100 + Llama-3.1-8B 为例）
# 模型权重：~16GB（FP16）
# 可用显存：80 - 16 = 64GB
# KV Cache Pool：64GB × 70% = 44.8GB
# max-total-tokens ≈ 44.8GB / (每 token KV Cache 大小)

graph TD
    LB["Load Balancer (Nginx / Envoy / Traefik)"]
    PodA["Pod A: GPU 0, TP=1 (单卡实例)"]
    PodB["Pod B: GPU 0,1,2,3, TP=4 (多卡实例)"]
    PodC["Pod C: GPU 0, TP=1 (单卡实例)"]

    LB --> PodA
    LB --> PodB
    LB --> PodC

# Prometheus + Grafana 监控
# 关键指标面板：
#   1. 请求吞吐（tokens/s）
#   2. TTFT P50 / P99
#   3. TPOT P50 / P99
#   4. KV Cache 使用率
#   5. 队列长度
#   6. 请求错误率

# 告警规则示例（PromQL）
# KV Cache 使用率 > 85%
sglang:token_usage > 0.85

# 请求排队 > 10
sglang:num_queue_reqs > 10

# 错误率 > 1%
rate(sglang:request_errors[5m]) / rate(sglang:request_total[5m]) > 0.01

# 生产环境完整配置
python -m sglang.launch_server \
    --model-path /models/Llama-3.1-8B-Instruct \
    --host 127.0.0.1 \                        # 仅 localhost
    --port 30000 \
    --api-key $(cat /etc/secrets/sglang-key)  # API Key 认证
    --tp-size 1 \
    --mem-fraction-static 0.85 \
    --max-total-tokens 65536 \
    --max-running-requests 128 \
    --context-length 8192 \
    --log-level info \
    --log-requests True \
    --enable-metrics True \
    --trust-remote-code False \               # 禁止远程代码执行
    --served-model-name my-model-v1           # 模型别名