MixMaaS

MixMaaS 是面向「MaaS 平台中模型混部的资源编排与性能优化」的原型系统，基于开源推理引擎 vLLM 构建统一控制面（Manager）与节点执行面（Node Agent），在不修改 vLLM 内部推理逻辑的前提下，解决多模型并发服务中的显存预算、部署位置选择、运行状态观测、请求路由与异常回收问题，并提供 Web 门户与 Grafana 监控形成「观测—决策—执行」闭环。

项目简介

在普通 vLLM 部署方式下，每个模型服务通常由人工选择 GPU、端口和显存比例。多个模型同时部署时，即使是很小的模型也会按默认 gpu_memory_utilization=0.9 预留几乎整卡的 KV Cache 空间，导致同一张 GPU 无法继续加载其他模型（实验中第二个实例在 KV Cache 分配阶段直接 CUDA OOM）。

MixMaaS 将模型实例、节点、GPU、显存预算和 endpoint 纳入统一元数据管理：部署前根据模型资源画像计算显存预算并自动折算 gpu_memory_utilization，由全局调度器按逻辑显存账本选择节点和 GPU，通过异步部署、健康检查与状态回调保证只有就绪实例被路由，卸载时以进程组为单位彻底回收。

系统采用 Manager + Node Agent + vLLM Replica 三层架构：

Manager：维护全局资源视图（节点/GPU/模型/副本）与逻辑显存账本，负责调度决策、状态机管理与 OpenAI 兼容推理代理；
Node Agent：运行在每个 GPU 节点，负责本地端口池、vLLM 进程组管理、健康检查、GPU 指标采集与状态回调；
vLLM Replica：实际推理服务，以子进程方式被拉起，完全复用其 OpenAI 兼容接口。

实验结果：Qwen2.5-0.5B-Instruct 与 Qwen2.5-1.5B-Instruct 在同一张 32GB V100 上稳定混部（逻辑已分配 10240 MB）；在主服务模型满足 streaming SLO（TTFT P99 1.060 s、TPOT P99 10.18 ms、Latency P99 3.219 s）的前提下，单 GPU 综合输出吞吐从 1496.47 tokens/s 提升到 4537.92 tokens/s（+203.2%），1200/1200 请求全部成功。

应用场景

MaaS 平台多模型并发服务：大模型、小模型与领域模型共享同一 GPU 池，负载与 SLO 差异明显，需要统一编排与观测；
中小规模 GPU 集群降本：单个中小尺寸模型吃不满整卡时，通过显存预算与同卡混部摊薄单位吞吐的硬件成本；
多 vLLM 实例的统一管理：替代人工指定 GPU/端口/显存比例的分散部署，避免「部署中即被路由」「卸载后残留进程占显存」等事故；
混部调度研究与教学原型：逻辑显存账本、优先级放置、状态机闭环等机制均可独立配置与替换，适合作为平台层调度策略的实验载体。

主要功能

节点注册与心跳：Node Agent 启动即向 Manager 注册节点与 GPU，周期心跳上报，超时自动标记失联；
GPU 监控：基于 NVML 采集显存占用、利用率与型号，逻辑账本（allocated/available_memory_mb）与物理观测并列暴露；
多模型部署与卸载：REST API / Web 门户一键部署，异步执行立即返回 202；卸载按进程组整组终止，重复卸载幂等；
显存感知同卡混部：按模型资源画像自动计算显存预算与 gpu_memory_utilization，解决默认预算下的同卡 OOM；
优先级与放置策略：部署优先级 high/normal/low（high 分散、low 填充碎片）与放置策略 free_memory/least_replicas/binpack 正交组合；
状态感知路由与 OpenAI 兼容代理：/v1/chat/completions、/v1/models 与 vLLM 接口一致，仅路由 RUNNING 副本，支持 round_robin/first；
异步部署闭环：部署 → 端口原子分配 → vLLM 子进程 → 健康检查轮询 → 状态回调 → 路由就绪，启动超时自动回滚清理；
Web 门户（前端）：零构建原生 HTML/CSS/JS，含「监控」与「管理」两个视图，详见下文 Web 门户；
集群监控：Manager 与 Node Agent 各自暴露 /metrics，Prometheus 抓取，Grafana「MixMaaS 集群总览」仪表盘展示；
压测工具：自带 OpenAI 兼容 streaming 压测脚本，统计 TTFT/TPOT/Latency 分位、吞吐与成功率。

系统环境

项目	要求
操作系统	Linux（开发与部署验证于 Ubuntu；容器使用 host 网络模式）
GPU	NVIDIA GPU（实验环境：32GB V100 与 16GB V100 双节点）+ 可用驱动
容器部署	Docker Engine、Docker Compose v2、NVIDIA Container Toolkit
源码部署	Python 3.10+（容器内使用 vLLM 0.8.5 基础镜像自带 Python）
推理引擎	vLLM 0.8.5（OpenAI 兼容接口）
模型权重	Qwen2.5-Instruct 系列（0.5B/1.5B/3B/7B/14B/32B 已预置资源画像）

默认占用端口（host 网络模式下即宿主机端口，启动前请确认未被占用）：

端口	服务	建议访问范围
8000	Manager API（控制面 + 推理代理，已开启 CORS）	仅内网
18000	Node Agent 本地控制端口	仅本机/内网
18001–18099	vLLM 实例端口池	仅本机
4173	Web 门户（前端静态页面）	用户浏览器
19090	Prometheus	仅本机/内网
13000	Grafana	按需开放

依赖要求

Python 依赖（src/MixMaaS/requirements.txt）：fastapi、uvicorn、PyYAML、httpx、nvidia-ml-py、pydantic。

Node Agent 与测试依赖（src/MixMaaS/node_agent/requirements.txt）：在上述基础上增加 pytest、pytest-asyncio、pytest-mock。

容器镜像：

后端基础镜像：vllm/vllm-openai（vLLM 0.8.5，可通过构建参数 BASE_IMAGE 替换镜像源）；
quay.io/prometheus/prometheus:v2.54.1；
Grafana 镜像（可选，grafana profile，镜像地址经 monitoring/.env 的 GRAFANA_IMAGE 配置）。

前端：零依赖——原生 HTML/CSS/JavaScript，无 Node、无打包构建，任意现代浏览器可直接运行。

模型权重：不随仓库分发。将 Qwen2.5-Instruct 系列模型目录放置于 src/MixMaaS/models/（容器内以只读方式挂载到 /models），模型名与路径、显存预算的对应关系见 src/MixMaaS/configs/base.yml 的 MODEL_RESOURCES。

目录结构

mptzmxhbdzybpyxnyh/
├── README.md                     # 本文档（项目根目录）
├── docs/                         # 决赛提交文档（PDF）
│   ├── 项目说明书.pdf             #   决赛项目说明书
│   ├── 项目创新说明.pdf           #   三项创新与已有工作对照、代码位置与验证依据
│   ├── 成员分工及主要贡献说明.pdf #   匿名化（A/B/C）成员分工与主要贡献
│   └── 人工智能及第三方工具使用说明.pdf # AI 与第三方工具使用声明及人工验证责任
├── presentation/                 # 决赛答辩 PPT 与演示视频
├── tests/                        # 实验证据
│   ├── images/                   # exp1–exp4 实验截图与 charts 曲线图
│   └── results/exp3/             # 实验三 benchmark 原始 JSON
├── demo/                         # 决赛演示：可运行/可复现/可部署三层证明
│   ├── quickstart/               #   ① mock 模式全链路演示（无需 GPU/权重/Docker）
│   ├── reproduce/                #   ② GPU 实验分阶段复现 + 结论图重绘
│   ├── deploy/                   #   ③ 生产部署自检/验证与离线内网方案
│   └── evidence/                 #   说明书论断 ↔ 证据映射表
└── src/MixMaaS/                  # 系统源代码
    ├── configs/base.yml          # 默认配置：端口、调度策略、vLLM 参数、模型资源画像
    ├── mixmass/                  # Manager 控制面
    │   ├── entrypoints/vllm/api_server.py   # 统一入口（注册/部署/卸载/路由/代理，含 CORS）
    │   ├── llm_engine_manager.py            # 核心编排器（预算计算、生命周期、路由）
    │   ├── global_scheduler/                # 放置与路由策略
    │   ├── metadata/                        # NodeInfo/GPUInfo/ModelInfo/Replica 与逻辑显存账本
    │   ├── agent/                           # 调用 Node Agent 的 HTTP 客户端
    │   ├── config/                          # YAML 配置与命令行覆盖
    │   └── metrics.py                       # Manager /metrics 指标
    ├── node_agent/               # 节点执行面
    │   ├── main.py / server.py              # 启动入口与本地控制 API
    │   ├── deployer.py                      # 部署编排：端口分配、启动、回调、回滚
    │   ├── state.py                         # 线程安全实例表与端口池
    │   ├── process_manager.py               # CUDA_VISIBLE_DEVICES 绑定、进程组隔离、killpg 清理
    │   ├── health_checker.py                # 轮询本地 /v1/models 判定就绪
    │   ├── monitor.py / metrics.py          # NVML 采集与 Agent /metrics
    │   ├── http_client.py                   # 注册、心跳、状态回调客户端
    │   ├── mock_vllm.py                     # 无 GPU 环境测试用 mock 服务
    │   └── tests/                           # 单元测试（28 例）
    ├── frontend/                 # Web 门户（零构建静态前端）
    │   ├── index.html / styles.css
    │   ├── app.js                           # 监控视图 + 视图切换
    │   └── manage.js                        # 管理视图（查询/部署/卸载/自动刷新）
    ├── benchmarks/benchmark_openai_stream.py  # streaming 压测脚本
    ├── docker/Dockerfile         # 后端镜像（基于 vllm-openai）
    ├── monitoring/               # Docker Compose 监控栈（manager/node-agent/frontend/prometheus/grafana）
    ├── docs/                     # API、实验、决赛文档与架构图
    ├── DEPLOYMENT.md             # 服务器部署手册
    └── requirements.txt

构建方法

方式 A：Docker 构建（推荐）

后端镜像 mixmaas-backend:local 基于 vLLM 官方镜像叠加本项目代码构建，前端与 Node Agent 复用同一镜像（前端由镜像内 Python HTTP Server 托管），无需单独构建前端：

cd src/MixMaaS/monitoring
sudo docker compose build          # 或 docker compose up -d --build 一步构建并启动

基础镜像可通过构建参数替换（如使用华为云镜像源）：docker compose build --build-arg BASE_IMAGE=<镜像地址>。

方式 B：源码环境准备（无编译步骤）

cd src/MixMaaS
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt -r node_agent/requirements.txt

源码方式需自行准备 vLLM 0.8.5 环境（pip install vllm==0.8.5）与 NVIDIA 驱动；仅运行单元测试时不需要 GPU 与 vLLM。

运行方法

Docker Compose 启动（推荐）

cd src/MixMaaS
mkdir -p models                    # 将模型权重放入该目录
cd monitoring
printf 'GRAFANA_IMAGE=<grafana 镜像地址>\n' > .env   # 可选，需要 Grafana 时配置
sudo docker compose up -d --build                    # Manager + Node Agent + 前端 + Prometheus
sudo docker compose --profile grafana up -d grafana  # Grafana（镜像可用时）

启动顺序由 Compose 依赖关系保证（Manager 健康后才启动 Node Agent）。多 Node Agent 场景需为额外节点分配不同宿主机端口并在 prometheus.yml 登记；若 Agent 地址需被外部客户端访问，修改 docker-compose.yml 中 MAAS_AGENT_ADVERTISE_HOST 为内网 IP。

源码直接运行

cd src/MixMaaS
# 1. Manager
python3 -m mixmass.entrypoints.vllm.api_server --config-file configs/base.yml --port 8000
# 2. Node Agent（另开终端；启动后自动向 Manager 注册）
python3 -m node_agent.main --manager-url http://127.0.0.1:8000 --node-id node-1
# 3. Web 门户（另开终端）
cd frontend && python3 -m http.server 4173

访问地址与验证

Web 门户：http://<服务器IP>:4173；Manager API：http://<服务器IP>:8000（接口文档见 src/MixMaaS/docs/API.md）
Grafana：http://<服务器IP>:13000（初始账号 admin / 密码 mixmaas）；Prometheus：http://<服务器IP>:19090
快速验证：curl http://127.0.0.1:8000/health、curl http://127.0.0.1:8000/v1/nodes（应看到节点 ready）

完整的服务器部署流程（环境检查、镜像准备、端口检查、分阶段启动、防火墙与日常运维）见部署手册。

Web 门户

前端为零构建纯静态门户（src/MixMaaS/frontend/），顶部页签切换两个视图：

监控视图：以 iframe 嵌入 Grafana「MixMaaS 集群总览」仪表盘，展示节点、GPU、模型副本与资源趋势；Grafana 不可用时保留入口并提示降级，管理功能不受影响；
管理视图：浏览器 fetch 直连 Manager 控制面 API（Manager 已开启 CORS），提供：
- KPI 卡片：在线节点数、GPU 总数、运行中副本数、模型数；
- 四张数据表：节点、GPU 资源（显存已用/分配/总量、利用率、运行副本）、模型（含卸载按钮）、副本明细（状态、节点/GPU、优先级、显存、Endpoint，含卸载按钮）；
- 部署表单：模型名称（候选来自 configs/base.yml，支持自由输入）、优先级、显存 MB、副本 ID、Tensor Parallel Size、Max Model Len、Dtype；
- 交互反馈：toast 提示、卸载前确认对话框、默认 5 秒自动刷新（可开关）；
- 地址配置：Grafana 与 Manager 地址可在页面修改并保存于浏览器 localStorage。

详细说明见前端门户文档。

测试方法

单元测试（无需 GPU 与真实 vLLM，NVML 与子进程均被 mock）：

cd src/MixMaaS
pip install -r requirements.txt -r node_agent/requirements.txt
python3 -m pytest node_agent/tests -q
# 预期：28 passed（覆盖 ProcessManager 进程组与清理、HealthChecker 就绪判定与超时、GPUMonitor 采集与降级）

全链路演示验证（无需 GPU/权重/vLLM/Docker，mock 模式，调度类步骤仍需 NVML）：

bash demo/quickstart/run_demo.sh                       # 启动 Manager + mock Agent + 前端门户
python3 demo/quickstart/walkthrough.py --with-benchmark # 11 步自动验证，全 PASS 退出码 0
bash demo/quickstart/stop_demo.sh

功能验证（需 GPU 环境）：

启动服务后确认 GET /v1/nodes 中节点为 ready、GET /v1/gpus 能识别 GPU；
通过门户管理视图或 POST /v1/models/deploy 部署 Qwen2.5-0.5B-Instruct 与 Qwen2.5-1.5B-Instruct，观察副本状态由 deploying 进入 running，同卡混部后 allocated_memory_mb=10240；
经 Manager POST /v1/chat/completions 对两个模型发起推理请求，确认返回内容与 token usage 正常；
POST /v1/models/undeploy 卸载（重复调用应幂等），确认副本清空且 allocated_memory_mb 归零；
前端 CORS 验证：curl -s -D - -o /dev/null -H "Origin: http://127.0.0.1:4173" http://127.0.0.1:8000/health 应返回 access-control-allow-origin: *。

性能压测（streaming 逐 token 计时）：

cd src/MixMaaS
python3 benchmarks/benchmark_openai_stream.py \
  --base-url http://127.0.0.1:8000 \
  --model Qwen2.5-1.5B-Instruct \
  --concurrency 8 --num-requests 200 --max-tokens 256 \
  --output-json result.json

脚本输出 TTFT/TPOT/Latency 的均值与 P99、输出吞吐与成功率。完整实验步骤、对照组设置与原始数据见实验说明；实验截图位于 tests/images/，实验三原始 JSON 位于 tests/results/exp3/。

已知限制

优先级作用范围：high/normal/low 只影响部署放置（分散/填充），不影响 vLLM 内部请求调度、batch 组织或 CUDA kernel 执行顺序；
元数据不持久化：当前 METADATA_STORE=memory，Manager 重启后全局视图丢失，需依赖 Node Agent 重新注册与心跳恢复，运行中副本的平台侧账本不会自动重建；
逻辑账本边界：显存账本只约束经 MixMaaS 部署的实例，不阻止其他进程直接占用 GPU 显存；账本与物理占用的偏差需通过监控人工关注；
无鉴权：Manager/Node Agent API 未提供认证授权，前端 CORS 为 allow_origins=["*"]，仅适合内网/实验环境，暴露公网前必须自行加访问控制；
前端实时性：管理视图以 5 秒轮询逼近实时，未使用 WebSocket 推送；
模型画像需手工配置：显存预算来自 configs/base.yml 的静态画像，尚不支持依据运行时占用自动标定；
单机 Compose 默认单 Agent：多节点需手动为每个节点配置不同端口、MAAS_NODE_ID 并更新 Prometheus 抓取目标；
实验结论适用范围：性能数据基于 V100 + Qwen2.5-0.5B/1.5B 组合与固定负载，其他硬件、模型或负载下提升幅度会变化；
Grafana 可选依赖：Grafana 镜像不可获取时监控视图降级为提示，不影响部署与管理功能。

文档导航

项目说明书 — 决赛项目说明书全文（系统设计、实验测试与结论）
项目创新说明 — 三项创新相对已有工作的新增贡献、代码位置与验证依据
成员分工及主要贡献说明 — 按匿名要求以 A/B/C 指代成员的分工与贡献说明
人工智能及第三方工具使用说明 — AI 及第三方工具的使用环节、涉及成果与人工检查验证声明
部署手册 — 服务器环境准备、构建、分阶段启动与日常运维
接口文档 — Manager 对外接口、Node Agent 对接契约与请求示例
实验说明 — 实验环境、复现命令、原始结果与分析
最终提交文档 — 系统设计、实验结果、优化方案与创新点
优先级基准说明 — 直接 vLLM + XSCHED 的独立优先级测试记录
架构图与流程图 — 系统架构图、部署与状态回调流程图
前端门户文档 — 监控/管理视图与配置说明
监控栈说明 — Docker Compose 监控栈与 Grafana 仪表盘
实验截图 / 原始结果 — 实验证据
演示与证明 — 可运行（mock 全链路）/可复现（GPU 实验）/可部署（Docker 栈）三层证明与论断↔证据映射

项目视频

决赛演示视频：presentation/决赛演示视频.mp4——真实 GPU 服务器上的完整录屏，展示系统核心功能与实际效果；随仓库直接分发，无需外链下载。