GPUStack 面试题库

Model 变更事件 → ModelController.sync_replicas()
                   ├── 期望副本 > 实际副本 → 创建 ModelInstance (PENDING)
                   └── 期望副本 < 实际副本 → 按 Scale-Down 评分移除实例

ModelInstance 变更事件 → ModelInstanceController
                          ├── INITIALIZING → 触发模型文件下载
                          └── DELETED → 重新触发调和

Worker 心跳事件 → WorkerController
                   └── 超时 → 标记实例 UNREACHABLE

Worker 启动 → GPU 设备检测（CUDA/ROCm/CANN）
           → 向 Server 注册（Worker ID + GPU 列表 + VRAM/RAM 容量）
           → Server 维护全局 GPU 资源视图（Worker → GPU  → 可用容量）
           → Scheduler 基于全局视图进行 Filter → Score → Select

graph LR
    P["PENDING"] --> A["ANALYZING"] --> S["SCHEDULED"] --> I["INITIALIZING"] --> D["DOWNLOADING"] --> ST["STARTING"] --> R["RUNNING"]
    R --> E["ERROR"]
    R --> U["UNREACHABLE"]

1. 单 Worker 单 GPU 满足需求 → 最优（单节点内延迟最低）
2. 单 Worker 多 GPU 满足需求 → 次优（单节点内张量并行）
3. 跨 Worker 分布式推理        → 仅当 Backend 支持（vLLM/SGLang）
4. 部分 Offload 或 CPU 执行    → 仅 GGUF / VoxBox / Custom Backend

Worker 启动 → Runtime 调用 GPU 驱动 API 枚举设备
           → 收集 GPU 属性：Index / Name / Vendor / VRAM Total / Framework / Labels
           → WorkerManager 构建注册请求（Worker ID + GPU 列表）
           → 向 Server /worker-auth 端点认证并注册
           → Server 创建或更新 Worker 记录，更新全局 GPU 资源表

export GPUSTACK_API_KEY=gpustack_abc123_def456
curl http://<gpustack-server>/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GPUSTACK_API_KEY" \
  -d '{
    "model": "qwen3-32b",
    "messages": [
      {"role": "system", "content": "你是一个AI助手"},
      {"role": "user", "content": "解释GPUStack的架构"}
    ],
    "temperature": 0.7,
    "max_tokens": 2048,
    "stream": true
  }'

Client → AI Gateway (Higress) → 路由表匹配 model → 负载均衡选择 ModelInstance → Worker → 推理引擎

model_sets:
  - name: Qwen3
    categories: [llm]
    capabilities: [context/128k, tools]
    sizes: [8, 32, 235]
    licenses: [apache-2.0]
    templates:
      - quantizations: [Q4_K_M, Q8_0, BF16]
        source: huggingface
        huggingface_repo_id: Qwen/Qwen3-{size}B-Instruct
        backend: vllm
        cpu_offloading: false
        distributed_inference_across_workers: true

templates:
  - quantizations: [Q4_K_M, Q8_0]
    source: huggingface
    huggingface_repo_id: bartowski/Llama-3.2-{size}B-Instruct-GGUF
    huggingface_filename: "*-{quantization}*.gguf"
    backend: llama-box
    cpu_offloading: true
    distributed_inference_across_workers: true

用户指定 Backend → 直接使用
未指定 + GGUF 模型 → llama-box
未指定 + HuggingFace 模型 + NVIDIA GPU → vLLM（默认）
未指定 + HuggingFace 模型 + Ascend NPU → MindIE

Client → AI Gateway
           ├── model: qwen3-32b → Worker-1 (vLLM instance 1) / Worker-2 (vLLM instance 2)
           ├── model: llama-8b   → Worker-1 (llama-box instance) / Worker-3 (llama-box instance)
           └── model: embedding  → Worker-2 (vLLM embedding instance)

graph TD
    subgraph K8s["Kubernetes Cluster"]
        subgraph Server["GPUStack Server (Deployment)"]
            API["API Server"]
            SCH["Scheduler"]
            CTRL["Controllers"]
            PG["PostgreSQL"]
        end

        subgraph Worker["GPUStack Worker (DaemonSet)"]
            RT["GPUStack Runtime"]
            SM["ServeManager"]
            ME["MetricExporter"]
            GPU["GPU devices"]
        end

        subgraph GW["AI Gateway (Higress)"]
            SVC["Service (LoadBalancer/NodePort)"]
            ROUTE["Request Routing"]
        end

        Server --> GW
        Worker --> GW
    end

gguf-parser-go 工具 → 解析 GGUF 模型的层数与每层大小
                    → ComputedResourceClaim { total_layers, vram_per_gpu, offload_layers }
                    → 调度器按 Waterfall 策略匹配：
                        1. 全量 GPU 加载（prefer_gpu）
                        2. 单 Worker 多 GPU 分片
                        3. 跨 Worker 分布式
                        4. 部分 Offload（GPU 层 + CPU 层）
                        5. 全 CPU 执行

Client Request → AI Gateway
                   ├── 请求认证（API Key / JWT）
                   ├── 模型名匹配 → 查询路由表（Model → ModelInstances）
                   ├── 负载均衡选择目标实例
                   └── 转发请求 → Worker → 推理引擎

ModelInstance.CREATED / RUNNING → 添加到路由表
ModelInstance.DELETED / ERROR / UNREACHABLE → 从路由表移除

export GPUSTACK_API_KEY=gpustack_abc123_def456789
curl http://<server>/v1/chat/completions \
  -H "Authorization: Bearer $GPUSTACK_API_KEY" \
  -d '{"model": "qwen3-32b", "messages": [{"role": "user", "content": "Hello"}]}'

1. 更新 Model 的 huggingface_repo_id / revision
2. ModelController 触发 reconcile
3. 旧 ModelInstance 逐步删除
4. 新 ModelInstance 创建 → 下载新权重 → 启动新 Backend → 加入路由表
5. AI Gateway 路由切换至新实例

Scheduler 评估模型显存需求（ComputedResourceClaim.vram）
    ├── 单 Worker 单 GPU 满足 → 不使用分布式
    ├── 单 Worker 多 GPU 满足 → 使用 Ray 多 GPU（单节点内 NCCL）
    └── 单 Worker 不满足 → 启用 distributed_inference_across_workers
         └── 选择 N 个 Worker 上的 GPU 组成分布式推理组
              ├── 主节点（Rank 0）：启动推理引擎主进程
              └── 从节点（Rank 1..N-1）：配置分布式环境变量后启动

Ray Cluster 用于跨节点 GPU 通信协调

# Model 部署参数
replicas: 1
backend: vllm
distributed_inference_across_workers: true
# vLLM Backend 参数
backend_parameters:
  --tensor-parallel-size: 4
  --pipeline-parallel-size: 2

Worker 心跳超时（90 秒）
  → WorkerController 标记 Worker NOT_READY
  → 该 Worker 上所有 ModelInstance → UNREACHABLE
  → AI Gateway 从路由表移除 UNREACHABLE 实例
  → Scheduler 检测副本数不足
  → 在其他可用 Worker 上创建新 ModelInstance
  → 新实例达到 RUNNING 后加入路由表
  → 服务恢复

Model.replicas = N
  → ModelController.sync_replicas()
  → current_replicas < N → 创建新 ModelInstance（Scheduler 分配 Worker/GPU）
  → current_replicas > N → Scale-Down 评分，移除低分实例
  → current_replicas == N → 无操作

Client → AI Gateway
           ├── 速率限制检查（API Key / IP 级别）
           ├── 路由表匹配（model → instances）
           ├── 实例选择（负载均衡）
           ├── 请求转发队列（Gateway 层排队）
           └── 超时处理（Gateway 层超时返回 504）
         
         → Worker → 推理引擎
                      ├── Continuous Batching（vLLM）
                      ├── 内部请求队列（等待 GPU 资源）
                      ├── Prefix Caching
                      └── KV Cache 管理

1. 备份数据库（/var/lib/gpustack/database.db）
2. 拉取新版本 Docker 镜像
3. 停止旧版本容器
4. 启动新版本容器（挂载同一数据目录）
5. 自动执行数据库 Migration（Alembic）
6. 验证服务正常
7. 删除旧版本镜像（可选）

更新 Model 配置（如修改 Backend 参数）
  → ModelController 检测 spec 变更
  → 逐个创建新版本 ModelInstance
  → 新实例达到 RUNNING → AI Gateway 将路由切换到新实例
  → 逐个删除旧版本 ModelInstance
  → 所有副本升级完成

GPUStack Model Deployment
  ├── backend: vllm
  │     ├── GPUStack 调用 vLLM API Server（OpenAI 兼容模式）
  │     ├── 自动传递 --tensor-parallel-size / --gpu-memory-utilization 等参数
  │     ├── MetricExporter 抓取 vLLM /metrics 端点
  │     └── 归一化为 gpustack:* 命名空间
  │
  └── backend: sglang
        ├── GPUStack 调用 SGLang Runtime
        ├── 支持 RadixAttention、分层缓存
        ├── 支持扩散模型（Flux.1-dev, Qwen-Image）
        └── MetricExporter 抓取并归一化指标

vLLM  v0.6.3  → gpustack/vllm:v0.6.3
vLLM  v0.7.1  → gpustack/vllm:v0.7.1
SGLang v0.4.1 → gpustack/sglang:v0.4.1

backend: vllm
backend_version: v0.7.1
backend_parameters:
  --tensor-parallel-size: "2"
  --gpu-memory-utilization: "0.90"
  --max-model-len: "32768"

server {
    listen 443 ssl;
    server_name gpustack.example.com;

    ssl_certificate     /etc/ssl/certs/gpustack.crt;
    ssl_certificate_key /etc/ssl/private/gpustack.key;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;

    location / {
        proxy_pass http://gpustack-server:80;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }
}

# 检查 Worker 容器日志
docker logs gpustack-worker

# 检查 Worker 心跳
curl http://<server>:10161/metrics/targets

# 检查 GPU 设备
docker exec gpustack-worker nvidia-smi

docker run -d --name gpustack \
    --restart unless-stopped \
    -p 80:80 \
    -v gpustack-data:/var/lib/gpustack \
    gpustack/gpustack:latest

docker run -d --name gpustack-worker \
    --restart unless-stopped \
    --gpus all \
    -e GPUSTACK_SERVER_URL=http://<server-ip> \
    -e GPUSTACK_TOKEN=<token> \
    -e GPUSTACK_WORKER_LABELS='{"region":"cn-east","tier":"production"}' \
    gpustack/gpustack:latest

curl -X POST http://<server>/v2/models \
  -H "Authorization: Bearer $GPUSTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "qwen3-32b",
    "source": "huggingface",
    "huggingface_repo_id": "Qwen/Qwen3-32B-Instruct",
    "backend": "vllm",
    "backend_version": "v0.7.1",
    "replicas": 2,
    "placement_strategy": "spread",
    "backend_parameters": ["--tensor-parallel-size=2", "--max-model-len=32768"]
  }'

curl http://<server>/v1/chat/completions \
  -H "Authorization: Bearer $GPUSTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen3-32b", "messages": [{"role": "user", "content": "Hello"}], "stream": true}'