Rectifiers × GPUStack 集成方案

GPUStack 架构概要

GPUStack 是一个开源的 GPU 集群管理器，采用 Server-Worker 架构：

┌─────────────────────────────────────────────────────────┐
│                   GPUStack Server                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────────┐  │
│  │ API      │  │Scheduler │  │ Controllers (state)   │  │
│  │ (FastAPI)│  │          │  │ + embedded PostgreSQL │  │
│  └──────────┘  └──────────┘  └──────────────────────┘  │
│                                                         │
│  ┌──────────────────────────────────────────────────┐  │
│  │  AI Gateway (Higress/Envoy + WasmPlugin)          │  │
│  │  - OpenAI-compatible routing                      │  │
│  │  - Load balancing                                 │  │
│  │  - Authentication                                 │  │
│  └──────────────────┬───────────────────────────────┘  │
└─────────────────────┼──────────────────────────────────┘
                      │ routes to workers
                      ▼
┌─────────────────────────────────────────────────────────┐
│                   GPUStack Workers                       │
│  ┌──────────────────┐  ┌──────────────────┐             │
│  │ Worker Node 0    │  │ Worker Node 1    │  ...        │
│  │ ┌──────────────┐ │  │ ┌──────────────┐ │             │
│  │ │vLLM container│ │  │ │vLLM container│ │             │
│  │ │(LMCache)     │ │  │ │(LMCache)     │ │             │
│  │ └──────────────┘ │  │ └──────────────┘ │             │
│  └──────────────────┘  └──────────────────┘             │
└─────────────────────────────────────────────────────────┘

关键发现：

GPUStack 能力	与 Rectifiers 的关系
AI Gateway	简单的负载均衡 + OpenAI 兼容路由。无缓存感知路由，无 P:D 分离调度
Custom Backend	支持自定义 Docker 镜像 + `run_command` 模板。可用但不适合 Rectifiers（Rectifiers 是路由层，不是推理引擎）
LMCache 支持	已内置。Rectifiers Connector 可直接作为 LMCache 的 `native_plugin` 后端
Higress WasmPlugin	网关扩展点。可以编写 WasmPlugin 查询 Director 做路由，但复杂
Worker 生命周期	GPUStack 管理 worker 的启动/停止/健康检查。Rectifiers 不越界

推荐方案：Rectifiers 作为独立路由层

最简集成，零侵入 GPUStack 源码。

                          外部 Client
                              │
                              ▼
┌──────────────────────────────────────────────────────────┐
│                    GPUStack Server                         │
│  ┌────────────────────────────────────────────────────┐  │
│  │  AI Gateway (Higress)                               │  │
│  │  upstream → Rectifiers Router (:8080)               │  │
│  │  而非直接 → vLLM workers                             │  │
│  └────────────────────────────────────────────────────┘  │
│                                                          │
│  Scheduler → 管理 worker 生命周期 (P0, P1, D0, D1...)     │
│  Controllers → 监控 GPU/worker 状态                      │
└──────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────┐
│                 Rectifiers 协调层 (独立部署)                │
│                                                          │
│  ┌──────────────────┐  ┌──────────────────────────────┐ │
│  │  Router (:8080)  │  │  Orchestrator (:9201)        │ │
│  │  tokenize → hash │  │  auto-tune P:D ratio         │ │
│  │  → Director.query│  │  → K8s scale vllm-prefill/   │ │
│  │  → dispatch best │  │    vllm-decode deployments   │ │
│  │  worker          │  │                              │ │
│  └────────┬─────────┘  └──────────────┬───────────────┘ │
│           │                           │                  │
│  ┌────────┴───────────────────────────┴───────────────┐ │
│  │  Director (:9200)                                   │ │
│  │  PrefixIndex + InstanceRegistry                     │ │
│  └────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘
           │                              │
           │ gRPC                         │ RDMA
           ▼                              ▼
┌──────────────────────┐    ┌──────────────────────────────┐
│  GPUStack Workers     │    │  RDMAS Storage Cluster       │
│  ┌──────────────────┐ │    │  Node 0  Node 1  Node N     │
│  │ P0 (vLLM+LMCache)│ │    │  HugePage KV cache          │
│  │ P1 (vLLM+LMCache)│ │    └──────────────────────────────┘
│  │ D0 (vLLM+LMCache)│ │
│  │ D1 (vLLM+LMCache)│ │
│  │                   │ │
│  │ Connector (PyO3)  │─┼─── report_store/remove → Director
│  │ 内嵌 Director 上报 │ │
│  └──────────────────┘ │
└──────────────────────┘

集成步骤

Step 1: 部署 Rectifiers 组件

# 1. 部署 Director
kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: rectifiers-director
spec:
  replicas: 1
  selector:
    matchLabels:
      app: rectifiers-director
  template:
    spec:
      containers:
      - name: director
        image: rectifiers-director:latest
        ports:
        - containerPort: 9200
---
apiVersion: v1
kind: Service
metadata:
  name: rectifiers-director
spec:
  selector:
    app: rectifiers-director
  ports:
  - port: 9200
EOF

# 2. 部署 Router
kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: rectifiers-router
spec:
  replicas: 2
  selector:
    matchLabels:
      app: rectifiers-router
  template:
    spec:
      containers:
      - name: router
        image: rectifiers-router:latest
        ports:
        - containerPort: 8080
        env:
        - name: DIRECTOR_ADDR
          value: "http://rectifiers-director:9200"
---
apiVersion: v1
kind: Service
metadata:
  name: rectifiers-router
spec:
  selector:
    app: rectifiers-router
  ports:
  - port: 8080
EOF

# 3. 部署 Orchestrator（需要 K8s RBAC）
kubectl apply -f orchestrator-rbac.yaml
kubectl apply -f orchestrator-deployment.yaml

Step 2: 配置 GPUStack AI Gateway 指向 Rectifiers Router

GPUStack 的 AI Gateway 基于 Higress。修改 Higress 配置，将 upstream 从直接指向 vLLM workers 改为指向 Rectifiers Router：

# GPUStack Gateway 配置（Higress McpBridge）
apiVersion: networking.higress.io/v1
kind: McpBridge
metadata:
  name: gpustack-gateway
spec:
  registries:
  - name: rectifiers
    type: static
    domain: rectifiers-router.rectifiers.svc.cluster.local
    port: 8080

或者，如果 GPUStack 不支持直接修改 Gateway upstream，可以在 GPUStack 部署模型的 run_command 中配置 worker 注册到 Rectifiers Director：

Step 3: 配置 GPUStack Worker 使用 Rectifiers Connector

GPUStack 已经内置 LMCache 支持。在部署模型时添加 LMCache 配置，指向 Rectifiers Connector 和 Director：

通过 GPUStack UI 或 API 部署模型时添加 backend parameters：

# GPUStack 部署 vLLM 模型时的 backend_parameters
{
  "backend_parameters": [
    "--lmcache-config",
    "{\"type\":\"native_plugin\",\"module_path\":\"lmcache_rdma_connector\",\"class_name\":\"RDMANativeConnector\",\"adapter_params\":{\"device\":\"mlx5_0\",\"server\":\"10.0.0.1:9400\",\"num_workers\":4,\"director_addr\":\"rectifiers-director:9200\",\"node_id\":\"rdmas-0\",\"tenant_id\":\"default\",\"model_name\":\"llama-70b\",\"block_size\":16},\"eviction\":{\"eviction_policy\":\"LRU\"}}"
  ]
}

通过 GPUStack Custom Backend YAML 方式：

backend_name: vllm-with-rectifiers-custom
default_entrypoint: vllm serve
default_execution_command: >
  {{model_path}}
  --host {{worker_ip}}
  --port {{port}}
  --served-model-name {{model_name}}
  --lmcache-config '{
    "type": "native_plugin",
    "module_path": "lmcache_rdma_connector",
    "class_name": "RDMANativeConnector",
    "adapter_params": {
      "device": "mlx5_0",
      "server": "10.0.0.1:9400",
      "num_workers": 4,
      "director_addr": "rectifiers-director:9200",
      "node_id": "rdmas-{{WORKER_ID}}",
      "tenant_id": "default",
      "model_name": "{{MODEL_NAME}}",
      "block_size": 16
    }
  }'
version_configs:
  v1:
    image_name: vllm/vllm-openai:v0.8.5
    custom_framework: cuda

Step 4: 配置 P:D 分离池

GPUStack 管理两组独立的 Deployment：

# Prefill Pool
kubectl scale deployment vllm-prefill --replicas=4

# Decode Pool  
kubectl scale deployment vllm-decode --replicas=4

# Rectifiers Orchestrator 自动调优
# 在 rectifiers_config.json 中:
{
  "orchestrator": {
    "auto_tune": {
      "prefill_deployment": "vllm-prefill",
      "decode_deployment": "vllm-decode",
      "min_prefill": 2, "max_prefill": 6,
      "dry_run": false
    }
  }
}

验证集成

# 1. 验证 Director 健康
grpcurl -plaintext rectifiers-director:9200 grpc.health.v1.Health/Check

# 2. 验证 Router 健康
curl http://rectifiers-router:8080/health

# 3. 发送推理请求（经过 Rectifiers 缓存感知路由）
curl -X POST http://rectifiers-router:8080/v1/completions \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Explain quantum computing", "model": "llama-70b", "stream": true}'

# 4. 查看 Director 索引状态
grpcurl -plaintext rectifiers-director:9200 \
  rectifiers.director.Director/GetStats \
  -d '{"tenant_id":"default","model_name":"llama-70b"}'

# 5. 查看 Orchestrator 建议
grpcurl -plaintext rectifiers-orchestrator:9201 \
  rectifiers.orchestrator.Orchestrator/GetRecommendation \
  -d '{}'

备选方案：Rectifiers 作为 Higress WasmPlugin

如果希望更深度的网关层集成，可以将 Rectifiers 的 Director 查询逻辑编译为 Higress WasmPlugin：

AI Gateway (Higress)
   │
   ├── WasmPlugin: rectifiers-router
   │   Request → 解析 prompt → 调 Director gRPC → 选最佳 worker → 改写 upstream
   │
   ▼
vLLM worker (由 Higress 直接路由，无需独立 Router 进程)

优点：减少一跳网络延迟（不需要独立 Router 进程）缺点：WasmPlugin 中无法做 tokenizer（太重），block hash 计算受限；调试困难

不推荐，除非团队有 Higress Wasm 开发经验且对 Router 延迟有极致要求。

集成清单

步骤	内容	改动 GPUStack?	工作量
1	部署 Rectifiers Director + Router + Orchestrator	❌ 独立部署	低
2	AI Gateway upstream 指向 Rectifiers Router	✅ 最小改动	低
3	Worker 启动参数添加 `--lmcache-config`	✅ backend parameters	低
4	部署 `liblmcache_rdma_connector.so` 到 worker 镜像	✅ custom Docker image	中
5	配置 P:D 分离两组 Deployment	✅ 两组 Deployment	中
6	Orchestrator auto-tune K8s 扩缩	❌ 独立运行	中

总工作量估算：3-5 天完成首次集成（不含 RDMAS 存储集群部署）。

核心原则：Rectifiers 不修改 GPUStack 源码，通过配置集成。GPUStack 管理 worker 生命周期，Rectifiers 管理请求路由和缓存感知调度。各司其职。

FilesExpand file tree

gpustack-integration.md

Latest commit

History