面向开源操作系统的大语言模型 PD 分离容器化推理系统设计与优化

简介

本项目面向开源 Linux，以 vLLM 和 Docker 构建 PD 分离原型。Prefill 与 Decode 使用独立 GPU，通过 NCCL 或 NIXL 传输 KV Cache；PD-Guardian 提供 OpenAI 兼容入口，集成故障恢复和指标采集。

针对远程 KV 加载等待，项目实现逐层流水线，将 KV 接收由请求粒度细化到层粒度。第 0 层 KV 到达后即可启动 Decode，计算本层时预取下一层，实现传输与计算重叠。

针对故障与资源残留，单端故障触发 P/D 成对重建，通过恢复代次校验隔离旧 KV 数据，清理残留资源并重新执行 Prefill，同时修复 P2P NCCL 与 chunked prefill 的兼容问题。

面向端到端 SLO，项目统一请求准入、Prefill 排队与 Decode 背压，结合吞吐估算、短请求优先、并发槽位和容量水位控制协调负载，采集时延指标。项目提供部署、GPU 验收、故障注入、逐层传输分析和 Benchmark 脚本，以 Qwen3 为验证模型。

提交内容

项目根目录/
├── README.md
├── src/                         # 项目源代码、配置与镜像构建文件
│   ├── pyproject.toml、uv.lock、.dockerignore
│   ├── pd_guardian/              # 服务、实例治理、恢复与 SLO
│   ├── vllm_extensions/          # NCCL 与 逐层流水线 KV 恢复 扩展
│   ├── docker/                  # NIXL、逐层流水线 KV 恢复、Guardian 镜像
│   └── scripts/                 # 运行配置、启动与停止
├── docs/                        # 项目文档与技术说明
│   ├── 项目说明书.pdf
│   ├── 项目创新说明.pdf
│   ├── 成员分工及主要贡献说明.pdf
│   ├── 人工智能及第三方工具使用说明.pdf
│   └── deployment/              # 环境、镜像、运行与调度指南
├── tests/                       # 测试及验证材料
│   ├── unit/、integration/      # CPU 回归
│   ├── gpu/、scripts/           # 推理与故障验收
│   └── performance/、tools/     # 压测与 trace 分析
├── demo/                        # 可验证交付物与演示入口
│   ├── run.sh
│   └── README.md
├── presentation/                # 决赛现场演示 PPT 与视频
└── 作品原创承诺书.pdf

所有代码和项目配置位于 src/，测试及验证材料位于 tests/，演示入口位于 demo/。说明书编辑源文件保存在 docs/；提交 PDF、PPT 和视频按上图位置补充。详见目录说明和代码实现。

环境要求

Linux 发行版 (OpenEuler、OpenKylin 等国产开源发行版, 也支持 Ubuntu 等发行版)、Python 3.12、uv、NVIDIA 驱动 (CUDA 12.8)、Docker 和 NVIDIA Container Toolkit
至少两个可用 GPU
本地 Qwen3-8B 与 Qwen3-0.6B 模型文件
vLLM 0.10.2、torch 2.8.0/cu128；Python 依赖由 src/pyproject.toml 和 src/uv.lock 管理。

从仓库根目录安装环境：

uv sync --project src --frozen --extra inference --extra test

模型、GPU、端口和预算可通过环境变量覆盖，默认配置位于 src/scripts/config.sh。详细说明见环境准备。

快速运行：容器化 PD 分离

从官方 vLLM 镜像构建 NIXL 基础环境，再安装逐层流水线恢复实现：

docker build -f src/docker/Dockerfile.nixl \
  -t local/vllm-openai:v0.10.2-nixl-rebuilt src
docker build -f src/docker/Dockerfile.plan-e \
  --build-arg VLLM_BASE_IMAGE=local/vllm-openai:v0.10.2-nixl-rebuilt \
  -t local/vllm-openai:v0.10.2-nixl-plan-e-verified src
docker build -f src/docker/Dockerfile.guardian \
  -t local/pd-guardian:latest src

镜像关系与来源见镜像说明，完整启动和停止命令见 Guardian 部署。

启动 Guardian + 逐层流水线恢复实现：

export KV_BACKEND=nixl GUARDIAN_RUNTIME=docker
export MODEL=/data_ssd/Qwen3-8B
export PREFILL_GPU=0 DECODE_GPU=1
export LOG_DIR="$PWD/src/.runtime/joint"
export PREFILL_GPU_MEM_UTIL=0.72 DECODE_GPU_MEM_UTIL=0.72
export MAX_MODEL_LEN=2048 MAX_NUM_BATCHED_TOKENS=256 MAX_NUM_SEQS=4
bash src/scripts/start.sh
curl -f http://localhost:10001/health

就绪后请求统一入口：

curl http://localhost:10001/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"Qwen3-8B","messages":[{"role":"user","content":"你好"}],"max_tokens":32}'
# 沿用启动时的配置停止：
bash src/scripts/stop.sh

快速运行：PD-Guardian 与 SLO 调度

Guardian + NCCL 运行入口：

export KV_BACKEND=nccl GUARDIAN_RUNTIME=process
export MODEL=/data_ssd/Qwen3-8B
export PREFILL_GPU=0 DECODE_GPU=1
export LOG_DIR="$PWD/src/.runtime/nccl"
export PREFILL_GPU_MEM_UTIL=0.70 DECODE_GPU_MEM_UTIL=0.70
export MAX_MODEL_LEN=2048 MAX_NUM_BATCHED_TOKENS=256 MAX_NUM_SEQS=4
export ENABLE_SLO=1
bash src/scripts/start.sh
curl -f http://localhost:10001/health
curl http://localhost:10001/metrics
bash src/scripts/stop.sh

SLO 调度通过 ENABLE_SLO=1 启用，默认关闭。支持 FCFS、SJF、aging、短请求优先槽位、准入限制和 Decode 实时水位控制。拒绝返回 429，后端不可用或恢复中返回 503。设置与指标口径见 SLO 说明，NCCL 配置见运行指南。

服务接口包括 /v1/chat/completions、/v1/completions、/health、/instances 和 /metrics，支持 JSON 与 SSE 输出。

实验结果

CPU 回归入口：

src/.venv/bin/python -m unittest discover -s tests -t . -v

GPU 测试包括独立逐层流水线恢复实现、Guardian + NCCL、Guardian +逐层流水线恢复实现和 SLO。预算较小的联合验收：

PREFILL_GPU_MEM_UTIL=0.72 DECODE_GPU_MEM_UTIL=0.72 \
MAX_MODEL_LEN=2048 MAX_NUM_BATCHED_TOKENS=256 MAX_NUM_SEQS=4 \
bash tests/scripts/test_slo.sh nixl --skip-recovery

测试运行条件、输出及性能测量说明集中在 tests/README.md。

注意事项

命令从仓库根目录执行；模型路径、GPU、端口和 LOG_DIR 按运行环境设置。
模型加载后等待 /health 返回就绪；多个部署使用独立端口和运行目录。
文档入口见 docs/README.md。

可验证交付物

演示入口及验收依据见 demo/README.md。从仓库根目录执行：

bash demo/run.sh cpu
bash demo/run.sh joint --skip-recovery

demo/run.sh 还提供 Guardian + NCCL、独立逐层流水线 KV 恢复、故障恢复及 SLO 演示。默认报告和日志位于 demo/output/<模式>_<时间>/，GPU 报告通过时 status 为 passed。

演示视频及答辩幻灯片链接

由于 Gitlink 平台不支持 Git LFS, PPT 与演示视频已上传至百度网盘 (提取码: 5qjm), 请您移步查看.

链接: https://pan.baidu.com/s/1bd7Q9wPAnGWMMzKj5ihoUA?pwd=5qjm