KV 缓存事件同步

KV 缓存事件同步#

概述#

KV 缓存事件同步是一项功能，它允许多个 vLLM 实例通过基于 ZMQ 的事件发布来共享键值缓存状态。这通过允许 AIBrix 网关根据实时缓存状态做出智能路由决策，从而提高前缀缓存命中率并减少冗余计算。

架构#

KV 事件同步系统由以下部分组成：

  1. vLLM 实例：通过 ZMQ 发布/订阅模式发布 KV 缓存事件

  2. AIBrix 缓存：管理订阅和处理事件

  3. 同步前缀缓存索引器：维护全局前缀缓存状态

  4. 网关路由器：使用缓存状态进行智能路由决策

事件流#

vLLM Pod 1 ─────┐
                 ├─── ZMQ Events ───► KV Event Manager ───► Sync Indexer ───► Gateway Router
vLLM Pod N ─────┘                         (in Cache)

该系统使用两阶段初始化

  1. 缓存初始化：使用 InitWithOptions 模式，其中 EnableKVSync=true

  2. KV 事件管理器：在满足条件时自动创建

要求#

  • vLLM 版本 0.7.0 或更高版本，支持 KV 缓存事件

  • AIBrix 网关插件内置 ZMQ 支持 (-tags="zmq")

  • 网关节点上安装了 ZMQ 库 (libzmq3-dev)

  • 启用了远程分词器（严格先决条件）

  • 配置了 Redis 客户端（用于生产部署）

重要

KV 事件同步严格依赖于远程分词器，以确保网关和 vLLM 实例之间分词一致。如果远程分词器被禁用，系统将无法初始化。

配置#

环境变量#

变量

默认

描述

AIBRIX_PREFIX_CACHE_KV_EVENT_SYNC_ENABLED

false

启用 KV 事件同步

AIBRIX_PREFIX_CACHE_USE_REMOTE_TOKENIZER

false

对于 KV 同步必须为 true

AIBRIX_PREFIX_CACHE_REMOTE_TOKENIZER_ENDPOINT

vLLM 服务端点

AIBRIX_PREFIX_CACHE_LOCAL_ROUTER_METRICS_ENABLED

false

启用前缀缓存指标

Pod 标签#

标签

值

描述

model.aibrix.ai/kv-events-enabled

true

为此 Pod 启用 KV 事件

model.aibrix.ai/lora-id

string

LoRA 适配器 ID（可选）

vLLM 配置#

将这些参数添加到您的 vLLM 容器中

args:
  - --enable-kv-cache-events
  - --kv-events-publisher=zmq
  - --kv-events-endpoint=tcp://*:5557
  - --kv-events-replay-endpoint=tcp://*:5558
  - --kv-events-buffer-steps=10000

添加相应的端口

ports:
  - name: kv-events
    containerPort: 5557
    protocol: TCP
  - name: kv-replay
    containerPort: 5558
    protocol: TCP

部署#

快速入门#

  1. 启用远程分词器（强制性先决条件）

    kubectl set env deployment/aibrix-gateway-plugins -n aibrix-system \
  AIBRIX_PREFIX_CACHE_USE_REMOTE_TOKENIZER=true \
  AIBRIX_PREFIX_CACHE_REMOTE_TOKENIZER_ENDPOINT=http://vllm-service:8000

  2. 启用 KV 事件同步:

    kubectl set env deployment/aibrix-gateway-plugins -n aibrix-system \
  AIBRIX_PREFIX_CACHE_KV_EVENT_SYNC_ENABLED=true

  3. 启用前缀缓存指标（可选但推荐）

    kubectl set env deployment/aibrix-gateway-plugins -n aibrix-system \
  AIBRIX_PREFIX_CACHE_LOCAL_ROUTER_METRICS_ENABLED=true

  1. 使用 KV 事件部署 vLLM:

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-model
spec:
  template:
    metadata:
      labels:
        model.aibrix.ai/name: "llama-7b"
        model.aibrix.ai/kv-events-enabled: "true"
    spec:
      containers:
      - name: vllm
        args:
        - --enable-kv-cache-events
        - --kv-events-publisher=zmq
        - --kv-events-endpoint=tcp://*:5557
        - --kv-events-replay-endpoint=tcp://*:5558

构建注意事项#

AIBrix 使用条件编译来管理 ZMQ 依赖项

需要 ZMQ 支持的组件

  • gateway-plugins：KV 事件同步的主要组件

  • kvcache-watcher：用于缓存监控的可选组件

构建命令

# Build with ZMQ support
go build -tags="zmq" ./cmd/plugins/main.go

# Docker build with ZMQ
make docker-build-gateway-plugins  # Automatically includes ZMQ

不需要 ZMQ 的组件

  • controller-manager：使用默认构建

  • metadata-service：使用默认构建

  • runtime：Python 组件，不需要 ZMQ

事件类型#

BlockStoredEvent（块存储事件）#

当新的 KV 缓存块被存储时发布

type BlockStoredEvent struct {
    BlockHashes     []int64    // Hash values of stored blocks
    TokenIDs        [][]byte   // Token IDs for each block (each token is a big-endian uint32)
    ModelName       string     // Model identifier
    LoraID          int64      // LoRA adapter ID (-1 if none)
    SourcePod       string     // Source pod name
    ParentBlockHash *int64     // Hash value of the parent block or nil
}

BlockRemovedEvent（块移除事件）#

当块从缓存中移除时发布

type BlockRemovedEvent struct {
    BlockHashes  []int64    // Hash values of removed blocks
    ModelName    string     // Model identifier
    LoraID       int64      // LoRA adapter ID
    SourcePod    string     // Source pod name
}

故障排除#

初始化失败#

  1. 检查初始化日志:

    kubectl logs deployment/aibrix-gateway-plugins -n aibrix-system | grep -E "KV event|initialize cache"

  2. 验证远程分词器:

    # Must see both enabled
kubectl get deployment/aibrix-gateway-plugins -n aibrix-system -o yaml | grep -A2 "REMOTE_TOKENIZER\|KV_EVENT_SYNC"

事件未发布#

  1. 检查 vLLM 日志:

    kubectl logs deployment/vllm-model | grep "KV cache events"

  2. 验证 ZMQ 连接:

    kubectl exec -it <gateway-pod> -n aibrix-system -- nc -zv <vllm-pod-ip> 5557

  3. 检查 ZMQ 构建支持:

    kubectl exec <gateway-pod> -n aibrix-system -- ldd /app/gateway-plugin | grep zmq

连接问题#

  1. 验证 Pod 标签:

    kubectl get pods -l model.aibrix.ai/kv-events-enabled=true

  2. 检查网络策略:

    • 确保端口 5557-5558 可访问

    • 无阻塞网络策略

  3. 验证分词器:

    kubectl exec <gateway-pod> -- curl http://tokenizer:8080/health

性能调优#

  • 高内存使用率：减少 vLLM 中的缓冲区步骤

  • 事件处理延迟：调整批处理大小和轮询超时

  • 网络开销：高负载下每个 Pod 约 1MB/s

从现有部署迁移#

在现有 vLLM 上启用#

  1. 添加标签

    kubectl label deployment vllm-model model.aibrix.ai/kv-events-enabled=true

  2. 使用 KV 事件参数更新部署（参见配置部分）

  3. 重启 Pod

    kubectl rollout restart deployment vllm-model

回滚#

禁用 KV 事件同步

# Disable in gateway
kubectl set env deployment/aibrix-gateway-plugins -n aibrix-system \
  AIBRIX_PREFIX_CACHE_KV_EVENT_SYNC_ENABLED=false

# Remove from vLLM deployments
kubectl label deployment vllm-model model.aibrix.ai/kv-events-enabled-

最佳实践#

  1. 部署顺序:

    • 首先启用远程分词器并验证其是否正常工作

    • 部署配置有 KV 事件的 vLLM

    • 最后在网关中启用 KV 同步

  2. 监控:

    • 启用前缀缓存指标以提高可见性

    • 监控日志中的 ZMQ 连接状态

    • 跟踪 Grafana 中的前缀缓存命中率

  3. 资源规划:

    • ZMQ 流量：高负载下每个 vLLM Pod 约 1MB/s

    • 内存：同步索引器每个前缀条目使用约 64 字节

    • CPU：最小开销（每个 Pod <1%）

  4. 生产注意事项:

    • 如果可能，为 ZMQ 流量使用专用网络

    • 根据网络延迟配置适当的超时

    • 如果 KV 同步失败，请规划优雅降级