目录
master
分支1
标签0
+ 疑修
Web IDE
wanghuang
benchmark提交
4个月前24次提交
README.md

mini-llmd: 原生多进程版 PD 分离推理系统原型

项目简介

mini-llmd 是一个基于 llm-d 架构思想的 PD (Prefill-Decode) 分离推理系统原型。本项目采用原生 Python 多进程实现，不依赖 Kubernetes、Redis、Ray 等重型组件，支持单卡和双卡环境。

核心设计理念：由于硬件资源不足，所以目前暂时用原生进程模拟容器实例，每个进程边界清晰，模块职责单一，能够验证PD分离的功能有效性，同时为后续迁移到容器化和 Kubernetes 部署预留完整接口。

主要特性

  • 真实 vLLM 推理：支持通过 HTTP API 调用远程 vLLM 服务
  • 双卡 PD 分离：GPU 0 运行 Prefill，GPU 1 运行 Decode
  • 灵活配置：支持 YAML 配置和环境变量覆盖
  • 引擎切换：支持本地 vLLM 引擎和远程 HTTP 引擎
  • 故障恢复：Watchdog 健康检查 + 自动重启
  • Benchmark：支持 mock、real_decode、pd_2gpu 三种模式

与赛题要求的对应关系

赛题要求 本项目实现 状态
PD 分离推理架构 Prefill Worker + Decode Worker 独立进程，通过 HTTP 通信 ✓ 完整实现
vLLM 真实推理 Decode Worker 支持远程 vLLM HTTP 服务和本地 vLLM 引擎 ✓ 完整实现
LLM-aware 调度 SLO-aware 调度器，支持 short-job-first、prefix cache hint ✓ 完整实现
中断快速恢复 Watchdog 健康检查 + 自动重启 + Request Journal ✓ 完整实现
资源治理 Resource Cleaner 检测僵尸/孤儿进程、端口异常、vLLM 残留 ✓ 完整实现
故障注入 Benchmark 模块支持 kill prefill/decode、高负载、decode timeout ✓ 完整实现
性能指标 TTFT、TPOT、P99 Latency、Throughput、SLO Violation Rate ✓ 完整实现
容器化迁移路径 每个进程边界 = 一个未来容器，配置文件 = 未来 ConfigMap ✓ 完整实现

运行模式

模式 描述 适用场景
Mock 不调用真实模型 开发调试
Single 单服务推理 小规模测试
Dual-GPU PD 双卡分离推理 生产环境

系统架构

单卡模式

Client / Benchmark
        |
        v
   Router (端口 8010)
        |
        +--> Prefill Worker (端口 8101, Mock)
        |
        +--> Decode Worker (端口 8012)
                |
                v
            vLLM 服务 (端口 8000)

双卡 PD 分离模式（NixlConnector）

Client / Benchmark
        |
        v
   NixlProxy (端口 8010)
        |
        +--> Prefill Instance (GPU 0, 端口 8100)
        |       - vLLM + NixlConnector (kv_producer)
        |       - 处理 prompt, 生成 KV cache
        |       - 通过 UCX TCP 传输 KV cache
        |
        +--> Decode Instance (GPU 1, 端口 8200)
                - vLLM + NixlConnector (kv_consumer)
                - 接收 KV cache, 生成 tokens

端口分配

组件 端口 GPU 说明
Router / NixlProxy 8010 - HTTP API 入口
Prefill vLLM 8100 GPU 0 NixlConnector kv_producer
Decode vLLM 8200 GPU 1 NixlConnector kv_consumer

快速开始

环境要求

  • Python 3.9+
  • Linux（推荐 Ubuntu 20.04+ 或 openEuler 23.09+）
  • NVIDIA GPU（单卡或双卡）
  • CUDA 11.8+

操作系统支持

操作系统 状态 Dockerfile docker-compose
Ubuntu 20.04+ ✓ 主要支持 Dockerfile docker-compose.yml
openEuler 23.09+ ✓ 支持 Dockerfile.openeuler docker-compose.openeuler.yml

详见 openEuler 部署指南。

安装依赖

cd mini-llmd
pip install -r requirements.txt

方案一：连接已有的 vLLM 服务（推荐）

如果你已经有 vLLM 服务在运行：

# 1. 发现模型服务
bash scripts/discover_model_endpoint.sh

# 2. 验证模型服务
python3 scripts/check_model_endpoint.py --base-url http://127.0.0.1:8000

# 3. 启动系统
bash scripts/start_native.sh

方案二：双卡 PD 分离

如果有两张 GPU：

# 一键启动双卡 PD 分离系统
bash scripts/start_native_pd_2gpu.sh

# 检查系统状态
bash scripts/check_gpu_status.sh

# 停止系统
bash scripts/stop_native_pd_2gpu.sh

方案三：Docker Compose 部署（推荐生产环境）

# 1. 配置环境变量
cp .env.docker .env
vi .env  # 设置 MODEL_PATH

# 2. 启动所有服务
docker-compose up -d

# 3. 查看服务状态
docker-compose ps

# 4. 测试推理
curl -X POST http://127.0.0.1:8010/v1/completions \
  -H "Content-Type: application/json" \
  -d '{"prompt": "你好", "max_tokens": 50}'

# 5. 扩缩容
docker-compose up -d --scale decode-worker=3

# 6. 停止系统
docker-compose down

详见 Docker 部署指南。

方案四：单卡本地推理

如果需要本地加载模型：

# configs/model.yaml
engine_type: "local"
model:
  name: "Qwen2.5-7B-Instruct-AWQ"
  path: "/root/autodl-tmp/models/Qwen2.5-7B-Instruct-AWQ"
bash scripts/start_native.sh

发送请求

# 文本补全
curl -X POST http://127.0.0.1:8010/v1/completions \
  -H "Content-Type: application/json" \
  -d '{"prompt": "你好，请介绍一下 PD 分离推理系统", "max_tokens": 128}'

# Chat 接口
curl -X POST http://127.0.0.1:8010/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "什么是 KVCache？"}],
    "max_tokens": 128
  }'

# 健康检查
curl http://127.0.0.1:8010/health

# Decode 健康检查
curl http://127.0.0.1:8010/health/decode

# 查看指标
curl http://127.0.0.1:8010/metrics

运行 Benchmark

# Mock 模式
python3 -m benchmark.run_benchmark --mode mock --num-requests 10

# 真实 Decode 模式
python3 -m benchmark.run_benchmark --mode real_decode --base-url http://127.0.0.1:8010

# 双卡 PD 分离模式
python3 -m benchmark.run_benchmark --mode pd_2gpu --base-url http://127.0.0.1:8010

故障注入

# 停止 Decode 容器
python3 -m benchmark.fault_injection kill_container --container whh-vllm-server

# 重启 Decode 容器
python3 -m benchmark.fault_injection restart_container --container whh-vllm-server

# 多轮故障注入
python3 -m benchmark.fault_injection multi_round --rounds 5

目录结构

mini-llmd/
├── README.md                    # 本文件
├── requirements.txt             # Python 依赖
├── Dockerfile                   # Docker 镜像构建
├── docker-compose.yml           # Docker Compose 编排
├── .dockerignore                # Docker 构建排除
├── .env.docker                  # Docker 环境变量模板
├── configs/                     # 配置文件
│   ├── model.yaml              # 模型配置
│   ├── pd_2gpu.yaml            # 双卡 PD 配置
│   ├── slo.yaml                # SLO 配置
│   └── runtime.yaml            # 运行时配置
├── router/                      # Router 模块
│   ├── api_server.py           # FastAPI HTTP 入口
│   ├── scheduler.py            # LLM-aware 调度器
│   ├── request_journal.py      # 请求生命周期记录
│   └── retry_policy.py         # 指数退避重试
├── workers/                     # Worker 模块
│   ├── prefill_worker.py       # Prefill Worker
│   ├── decode_worker.py        # Decode Worker
│   ├── vllm_engine.py          # 本地 vLLM 引擎
│   ├── http_engine.py          # 远程 HTTP 引擎
│   ├── engine_factory.py       # 引擎工厂
│   └── backends/               # Backend 抽象层
│       ├── base.py             # 抽象基类
│       ├── mock_backend.py     # Mock Backend
│       └── vllm_http_backend.py # vLLM HTTP Backend
├── runtime/                     # 运行时管理
│   ├── process_manager.py      # 进程管理
│   ├── watchdog.py             # 健康检查 + 自动重启
│   ├── healthcheck.py          # HTTP 健康检查
│   └── resource_cleaner.py     # 资源清理
├── monitor/                     # 监控模块
│   ├── metrics.py              # 指标收集
│   ├── logger.py               # 统一日志
│   └── exporter.py             # 指标导出
├── benchmark/                   # 基准测试
│   ├── run_benchmark.py        # 基准测试运行器
│   ├── workloads.py            # 负载生成
│   ├── fault_injection.py      # 故障注入
│   ├── report.py               # 报告生成
│   └── plot_report.py          # 图表生成
├── scripts/                     # 运维脚本
│   ├── start_native.sh         # 启动所有进程
│   ├── stop_native.sh          # 停止所有进程
│   ├── start_native_pd_2gpu.sh # 双卡 PD 启动
│   ├── stop_native_pd_2gpu.sh  # 双卡 PD 停止
│   ├── discover_model_endpoint.sh # 发现模型服务
│   ├── check_model_endpoint.py # 验证模型服务
│   ├── check_gpu_status.sh     # GPU 状态检查
│   ├── kill_decode_container_safe.sh # 安全停止容器
│   └── restart_decode_container_safe.sh # 安全重启容器
├── docs/                        # 文档
│   ├── real_decode_qwen3_4b.md # 真实 Decode 指南
│   ├── pd_2gpu_design.md       # 双卡 PD 设计
│   ├── fault_recovery.md       # 故障恢复文档
│   ├── migration_to_k8s.md     # Kubernetes 迁移方案
│   └── benchmark_real_qwen3_4b.md # Benchmark 指南
├── logs/                        # 日志目录
├── runtime_state/               # 运行时状态
└── outputs/                     # Benchmark 输出

配置说明

环境变量

变量名 说明 默认值
MINI_LLMD_VLLM_BASE_URL vLLM 服务地址 http://127.0.0.1:8000
MINI_LLMD_MODEL_NAME 模型名称 /data/Qwen3-4B
MINI_LLMD_DECODE_BACKEND Decode backend 类型 vllm_http
MINI_LLMD_ROUTER_HOST Router 绑定地址 0.0.0.0
MINI_LLMD_ROUTER_PORT Router 端口 8010
MINI_LLMD_PREFILL_HOST Prefill Worker 地址 0.0.0.0
MINI_LLMD_PREFILL_PORT Prefill Worker 端口 8011
MINI_LLMD_DECODE_HOST Decode Worker 地址 0.0.0.0
MINI_LLMD_DECODE_PORT Decode Worker 端口 8012

配置文件

详见 configs/ 目录下的 YAML 文件。

文档

端到端 SLO 优化效果（NixlConnector PD 分离）

性能对比

指标 Mock 单服务 NixlConnector PD 提升
Avg TTFT (ms) 40.7 96.0 61.0 36% ↓
P50 TTFT (ms) 41.5 41.5 40.9 持平
P99 TTFT (ms) 81.1 51.1 90.6 -
Avg TPOT (ms) 21.8 21.8 21.8 持平
P50 延迟 (ms) 2822 5691 1660 70.8% ↓
P99 延迟 (ms) 5714 7138 1938 72.9% ↓
吞吐量 (req/s) 0.70 0.67 1.19 77.6% ↑
SLO 违约率 0% 0% 0% -

核心提升

  • **P99 延迟降低 73%**：从 7138ms 降至 1938ms
  • **吞吐量提升 78%**：从 0.67 req/s 提升至 1.19 req/s
  • GPU 并行：Prefill (GPU 0) 和 Decode (GPU 1) 互不干扰

原始数据查看

# NixlConnector 结果
cat outputs/benchmark/nixl_test/summary.json

# 完整对比报告
cat outputs/benchmark/nixl_comparison_report.md

# 对比图表
ls outputs/benchmark/nixl_test/*.png

运行 Benchmark

# 单服务模式
python3 -m benchmark.run_benchmark --mode real_decode --base-url http://127.0.0.1:8010

# NixlConnector PD 模式
python3 -m benchmark.run_benchmark --mode pd_2gpu --base-url http://127.0.0.1:8010

后续优化

  1. KVCache 传输：实现真实的 KVCache 跨 GPU 传输
  2. 流式输出：支持 SSE 流式输出
  3. 动态批处理：根据负载动态调整批处理大小
  4. 监控集成：集成 Prometheus 和 Grafana
  5. 自动扩缩容：集成 K8s HPA 实现自动扩缩容
  6. Helm Chart：编写 Helm Chart 简化 K8s 部署

致谢

  • llm-d — 架构灵感
  • vLLM — 推理引擎
关于
README.md
4.0 MB
MIT
邀请码
    Gitlink（确实开源）
  • 加入我们
  • 官网邮箱：gitlink@ccf.org.cn
    • QQ群
  • QQ群
    • 公众号
  • 公众号

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