目录
master
分支1
标签0
+ 疑修
Web IDE
Jinying Xiao
更新演示PPT
1个月前17次提交
README.md

面向高效可靠的分离式大模型推理系统

基于 SGLang 的增强分支,围绕 Prefill/Decode(PD)分离部署 做了系统增强。

目录结构

sglang-src/
├── src/
│   ├── python/sglang/srt/             # sglang 推理引擎(可编辑安装)
│   │   ├── disaggregation/
│   │   │   ├── kvpact/                # ★ KVPact 压缩传输后端(conn/transport/compression)
│   │   │   ├── local_kv/              # ★ 本地 KV 后端
│   │   │   └── ...                    # 上游 mooncake/nixl 等后端
│   │   ├── managers/                  # ★ DP worker 故障检测/恢复/请求迁移
│   │   ├── security/tenant_kv_sentry.py  # ★ 多租户 KV 缓存隔离
│   │   └── utils/process_teardown.py  # ★ 快速关闭
│   └── sgl-model-gateway/             # router(Rust) + Python bindings(mini-lb/SLOWeaver)
├── demo/
│   ├── kvpact/                        # ★ KVPact PD 栈一键启动脚本(4 种拓扑)
│   └── recovery/                      # ★ 故障恢复演示启停脚本
├── tests/                             # 实验数据汇总(KVPact 带宽扫描/故障恢复/SLOWeaver 消融)

环境部署

前提

  • NPU:昇腾 910B 64GB NPU ×8 ;支持 HCCL 或 RDMA
  • CANN 9.00,Python 3.10+,Conda(推荐)
  • 模型权重放在本地(示例用 /data2/llms/),已验证:Qwen2.5-7B/32B/72B、Qwen3-30B-A3B、Qwen3.5-27B(需 --disable-custom-all-reduce)、Llama-3.1-8B

安装

# 1. 创建环境
conda create -n sglang-dev python=3.10 -y
conda activate sglang-dev

# 2. 安装 sglang(可编辑安装,本仓库即源码)
cd sglang-src/src/python
pip install -e ".[all]"

# 3. router Python bindings(PD 负载均衡用,加入 PYTHONPATH)
export GATEWAY_SRC=$PWD/../sgl-model-gateway/bindings/python/src
export PYTHONPATH=$GATEWAY_SRC:$PYTHONPATH

启动方式一:Demo 脚本一键启动(推荐)

demo/ 下的脚本会自动完成 Prefill/Decode/LB 的启动、健康检查和日志管理,验证过可直接运行。

KVPact PD 栈(demo/kvpact/)

脚本 拓扑 默认 GPU LB 端口 默认模型 用途
start_kvpact_stack.sh 1P1D TP=1 D=3, P=4 33000 Qwen2.5-7B 快速验证,单双卡即可
start_kvpact_stack_72b.sh 1P1D TP=4 P=0-3, D=4-7 34000 Qwen2.5-72B 大模型 8 卡验证
start_kvpact_stack_6p2d_tp1.sh 6P2D TP=1 P=0-5, D=6-7 26000 需 MODEL_PATH 8 卡聚合带宽压测
start_kvpact_stack_qwen3_30b_3p1d.sh 3P1D TP=2 P=0-5, D=6-7 35000 Qwen3-30B-A3B MoE 模型带宽压测

最简启动(1P1D,2 张卡):

cd sglang-src/demo/kvpact

# 原始 KV 直传(基线)
bash start_kvpact_stack.sh

# 启用 KVPact 压缩(quantizer + codec)
COMPRESSION=default bash start_kvpact_stack.sh

脚本输出 栈已启动: LB=http://127.0.0.1:33000 即就绪。常用环境变量:

变量 默认 说明
COMPRESSION none none 直传 / default 内置压缩 / <config.json> 自定义压缩配置
MODEL_PATH 各脚本默认值 模型权重路径(6p2d 脚本必填)
PREFILL_GPU / DECODE_GPU 4 / 3 1P1D 脚本的卡号(其他脚本用 PREFILL_GPUS/DECODE_GPUS)
LOG_DIR demo/kvpact/logs_<tag> 日志目录(6p2d/30b 脚本必填)
PY conda sglang-dev 环境 Python 解释器路径

停止服务:日志目录下有 *.pid 文件,逐个 kill $(cat xxx.pid) 即可——SIGTERM 触发优雅关闭,子进程和显存会完整回收。

故障恢复演示(demo/recovery/)

# 启动 DP=2 服务(GPU 2,3,端口 30910,日志 recover_test/server.log)
bash demo/recovery/start_server.sh

# 对照组(原始未改动版本,需 sglang-pd conda 环境)
bash demo/recovery/start_server_baseline.sh

# PD 分离恢复演示(1P2D + mini-lb,GPU 2/3/4,端口 30000)
bash demo/recovery/start_pd_test.sh
bash demo/recovery/stop_pd_test.sh

服务就绪后,kill 掉任意一个 DP worker 的 scheduler 进程即可观察:控制器 <1s 检测故障、在途请求自动迁移重放、客户端无报错。

启动方式二:手动命令

1. 单机普通推理(基线)

python -m sglang.launch_server \
    --model-path /data2/llms/Qwen3-30B-A3B-Instruct-2507 \
    --host 0.0.0.0 --port 30000 \
    --mem-fraction-static 0.85 --trust-remote-code

2. PD 分离 + KVPact 压缩(1P1D,手动三步)

MODEL=/data2/llms/Qwen3-30B-A3B-Instruct-2507
BACKEND=kvpact                      # 可选: kvpact / local_kv / mooncake / nixl / fake
COMP=default                        # 可选: none / default / <config.json路径>

# [1/3] Decode(GPU 1)
CUDA_VISIBLE_DEVICES=1 python -m sglang.launch_server \
    --model-path $MODEL --host 127.0.0.1 --port 30200 \
    --disaggregation-mode decode \
    --disaggregation-transfer-backend $BACKEND \
    --disaggregation-kvpact-compression $COMP \
    --mem-fraction-static 0.85 --trust-remote-code &

# [2/3] Prefill(GPU 0)
CUDA_VISIBLE_DEVICES=0 python -m sglang.launch_server \
    --model-path $MODEL --host 127.0.0.1 --port 30100 \
    --disaggregation-mode prefill \
    --disaggregation-transfer-backend $BACKEND \
    --disaggregation-kvpact-compression $COMP \
    --disaggregation-bootstrap-port 8998 \
    --mem-fraction-static 0.85 --trust-remote-code &

# [3/3] Load Balancer
python -m sglang_router.launch_router \
    --pd-disaggregation --mini-lb \
    --prefill http://127.0.0.1:30100 8998 \
    --decode http://127.0.0.1:30200 \
    --host 127.0.0.1 --port 30000

3. 多 P 多 D + SLOWeaver

python -m sglang_router.launch_router \
    --pd-disaggregation --mini-lb \
    --sloweaver-policy slo \
    --sloweaver-openkylin-aware \
    --sloweaver-worker-numa-nodes \
      http://127.0.0.1:30100=0 http://127.0.0.1:30300=1 \
      http://127.0.0.1:30200=0 http://127.0.0.1:30400=1 \
    --prefill http://127.0.0.1:30100 8998 \
    --prefill http://127.0.0.1:30300 8999 \
    --decode http://127.0.0.1:30200 \
    --decode http://127.0.0.1:30400

运行时 GET /sloweaver/state 可查看 OS 检测结果、PSI、CPU 节流率与压力分数。

使用系统

健康检查与推理

curl http://127.0.0.1:30000/health

curl http://127.0.0.1:30000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "'$MODEL'", "messages": [{"role": "user", "content": "你好"}], "max_tokens": 64}'

压测

python -m sglang.bench_serving \
    --backend sglang --host 127.0.0.1 --port 30000 \
    --dataset-name random --num-prompts 800 \
    --random-input-len 1024 --random-output-len 128

链路带宽仿真(模拟跨机房低带宽)

# 固定限速: 10Gbps = 1.25e9 B/s
KVPACT_WIRE_BPS=1250000000 bash start_kvpact_stack.sh

# 动态换挡: 运行中改写文件即生效(压测换挡不重启栈)
echo 125000000 > /tmp/wire.txt
KVPACT_WIRE_BPS_FILE=/tmp/wire.txt bash start_kvpact_stack.sh

压缩模式选择建议(基于实测)

  • 单机 PD(带宽充足):压缩为负收益(量化 TTFT +110~150ms),用 none 或 local_kv
  • 10Gbps 链路:72B 模型压缩吞吐 +39%;≤3Gbps 链路:吞吐 +183%360%,交叉点约 45Gbps
  • 带宽越受限、模型越大,压缩收益越大

参数与环境变量参考

新增启动参数

参数 取值 说明
--disaggregation-transfer-backend kvpact / local_kv / mooncake / nixl / fake KV 传输后端,kvpact 与 local_kv 为本项目新增
--disaggregation-kvpact-compression none / default / <path>.json 压缩模式;JSON 配置文件启用自定义/在线控制器模式
--disaggregation-kvpact-quality-guard flag(默认关闭) Prefill 侧 KV 压缩重建质量抽检,越界自动回退 raw 传输
--disaggregation-kvpact-quality-sample-rate float(默认 0.01) 质量抽检比例;1.0 逐请求校验
--disaggregation-kvpact-quality-sample-elements int(默认 8192) 每次检查最多比较的均匀抽样 KV 元素数
--disaggregation-kvpact-quality-max-relative-l2 float(默认 0.20) 可接受的最大相对 L2 重建误差
--disaggregation-kvpact-quality-min-cosine float(默认 0.98) 可接受的最小原始/重建 KV 余弦相似度
--disaggregation-kvpact-quality-failure-threshold int(默认 3) 触发压缩熔断的连续质量失败次数
--disaggregation-kvpact-quality-cooldown-requests int(默认 100) 熔断后直接走 raw 传输的请求数
--disaggregation-localkv-slot-count int(默认 32) local_kv 环形缓冲槽位数
--disaggregation-localkv-chunk-tokens int(默认 512) local_kv 单块传输 token 预算
--enable-tenant-kv-sentry flag(默认关闭) 启用服务端认证的多租户 Prefix KV Cache 隔离
--tenant-kv-sentry-secret-file path HMAC 密钥文件,启用 TenantKV-Sentry 时必填且至少 32 字节
--tenant-kv-sentry-tenant-header string 租户身份 Header,默认 x-sglang-tenant-id
--tenant-kv-sentry-signature-header string 租户签名 Header,默认 x-sglang-tenant-signature
--tenant-kv-sentry-default-tenant string/空 可信单租户部署的固定租户
--sloweaver-openkylin-aware flag(默认关闭) 启用 openKylin PSI、cgroup v2 和 NUMA 感知预测
--sloweaver-worker-numa-nodes URL=NODE ... 声明 P/D worker 所在 NUMA 节点,规避跨插槽 KV 传输
--sloweaver-system-pressure-weight float(默认 0.35) PSI 与 cgroup CPU 节流对预测时延的权重
--sloweaver-cross-numa-penalty-ms float(默认 35) P/D 不同 NUMA 节点时增加的 TTFT 代价
--sloweaver-telemetry-interval-ms float(默认 250) 系统遥测最小采样间隔

环境变量

变量 说明
KVPACT_WIRE_BPS 链路带宽仿真(字节/秒),模拟跨机房低带宽链路,0 为关闭
KVPACT_WIRE_BPS_FILE 指向文件,运行时动态读取带宽值(压测换挡用)
KVPACT_LOG_LEVEL KVPact 后端日志级别
SGLANG_DISAGGREGATION_BOOTSTRAP_TIMEOUT PD .bootstrap 超时(秒),大模型建议 600+
SGLANG_DISAGGREGATION_WAITING_TIMEOUT PD 传输等待超时(秒)
SGLANG_INSTANCE_FAILURE_MAX_RETRIES 实例故障时请求迁移重试上限(默认 3)

TenantKV-Sentry

开启后,OpenAI 接口和原生 /generate 接口都会将租户身份、客户端 cache_salt 与 extra_key 编码为带类型边界的 HMAC 缓存键。租户身份必须由可信网关签名,客户端无法伪造租户名命中其他租户的 Radix Cache;LoRA 身份以独立类型维度加入缓存键。

# 密钥应通过 Kubernetes Secret 等安全方式挂载,不要放入命令行参数
python -c 'import secrets; open("tenant-kv.secret", "wb").write(secrets.token_bytes(32))'
chmod 600 tenant-kv.secret

python -m sglang.launch_server \
    --model-path "$MODEL" \
    --enable-tenant-kv-sentry \
    --tenant-kv-sentry-secret-file tenant-kv.secret

可信网关用 TenantKVSentry.sign_tenant(tenant_id) 生成 x-sglang-tenant-signature;完全可信的单租户部署可加 --tenant-kv-sentry-default-tenant <tenant> 免签名。当前实现是隔离 MVP,不含 PD Tenant Capsule 和 L2 AES-GCM 加密。

压缩管线组成(kvpact/compression/)

子模块 职责
transformer/ Hadamard 变换等预处理
quantizer/ 分层重要性量化(split_func,基于校准 scores)
codec/ nvCOMP 熵编码
controller/ 在线压缩比控制器(bandit + 解析模型 + profile 库)
config/duo_config/ 各模型校准 scores(Qwen2.5-7B/32B/72B、Qwen3-30B、Qwen3.5-27B、Llama-3.1-8B)
wire.py GPU 驻留线上传输格式(msgpack 元数据 + NCCL 张量)

运维行为

回收资源

直接 kill <pid>(SIGTERM)即可:服务以退出码 0 退出,完整回收所有子进程(GPU worker、detokenizer 等),不残留进程占用显存。

DP Worker 故障恢复

DP 部署下某个 worker 进程崩溃时:

  1. 控制器 <1s 内检测到故障
  2. 该 worker 的在途请求自动迁移到健康 worker 重放
  3. 请求级附加时延 0.65~3.55s,客户端无报错(24/24 全模型实测恢复成功)

实验数据

tests/ 下有三份整理好的实测数据 CSV,每行带 source 列指向原始数据:

文件 内容
kvpact_wire_sweep_1-10gbps.csv 4 模型(7B/14B/30B/72B)× 1-10Gbps 带宽扫描,none/quant 对比,100 行
fault_recovery_summary.csv 7 模型 DP worker 故障恢复 dev/pd 对照 + PD 分离故障注入 + TTFT 回放,20 行
sloweaver_admission_ablation.csv / _comparisons.csv SLOWeaver 五准入策略消融(960 请求/策略 × 10 trials,含 95% CI)
关于
README.md
331.3 MB
邀请码
    Gitlink（确实开源）
  • 加入我们
  • 官网邮箱：gitlink@ccf.org.cn
    • QQ群
  • QQ群
    • 公众号
  • 公众号

版权所有：中国计算机学会技术支持：开源发展技术委员会
京ICP备13000930号-9 京公网安备 11010802047560号