CoServe-MaaS

CoServe-MaaS 是一个面向 MaaS(Model as a Service)平台多模型混部的资源编排与性能优化原型系统。系统基于 vLLM OpenAI API Server 扩展，在不修改 vLLM 内核的前提下，通过 MaaS Gateway、SLO 感知调度、Token-Memory Co-Scheduling、Fast Handover、可解释治理与容灾防护机制，提升多模型并发服务下的有效吞吐、成功率、SLO 达成率和资源利用效率。

本项目面向“研究创新-MaaS 平台中模型混部的资源编排与性能优化”赛题构建，重点覆盖：

1. 多模型部署、卸载、并发服务与监控统计；
2. 基于 vLLM 的真实 LLM 推理服务接入；
3. baseline / optimized / balanced / real-balanced / slo-balanced / adaptive 策略切换；
4. 请求级调度、Token Budget、显存水位与快速资源交接；
5. 可解释调度、模型健康检查、熔断恢复、请求资源防护；
6. 本地模拟、Mock HTTP、真实 vLLM、消融实验的一体化复现实验闭环。
7. API Key、RBAC、租户级请求/Token/并发限流、SSRF 防护与审计日志；
8. 无外部依赖的交互式 Web 控制台与闭环 Adaptive Controller。

安全模式下，监控与解释接口仍执行 API Key 和 RBAC 校验，但只读 GET/HEAD 请求不消耗租户业务配额；推理请求和模型、策略等写操作才计入 请求、Token 与并发限流。该边界避免 Web 控制台的周期观测挤占真实推理额度。

评审快速入口

本提交包以“真实系统、真实 GPU、统一负载、可复现证据”为主线。正式性能结论来自 华为云 openEuler 24.03 LTS-SP1 + Tesla V100S 32GB 环境：两个 Qwen2.5 模型通过 两个 vLLM 实例同时驻留于同一 GPU，并由 CoServe-MaaS 网关统一调度。

评分维度	本项目对应能力	核心证据
功能完整性（40 分）	双模型部署/卸载、并发推理、策略切换、监控统计、健康检查、熔断与 Web 控制台	tests/、coserve/、技术报告第 4、5 章
性能优化（50 分）	SLO-Guard-TB、Token Reserve、Aging Fairness、Deadline Token Shaping、Adaptive Controller	正式 V100S 运行中 slo-balanced 综合增益 +33.22%，adaptive 综合增益 +26.16%
文档质量（10 分）	安装、使用、架构、算法、实验、消融、边界和参考文献齐全	report/研究创新-MaaS平台中模型混部的资源编排与性能优化-何诗雨-技术报告.pdf、docs/
研究创新性	Token-Memory 联合调度、可解释闭环控制、资源交接状态机、安全与容灾一体化	技术报告第 3、6 章及 /explain/scheduler、/security、/adaptive

正式 V100S 主结果

统一设置为每种策略 180 个计入统计的请求、4 个预热请求（不计入统计）、相同随机种子 和请求序列，三种策略成功率均为 100%。相对 FIFO baseline：

指标	baseline	slo-balanced	相对提升	adaptive	相对提升
Wall Throughput (req/s)	4.2729	5.2206	+22.18%	4.8625	+13.80%
Goodput (req/s)	3.2521	4.8436	+48.94%	4.5383	+39.55%
SLO 达成率	76.11%	92.78%	+16.67 pct	93.33%	+17.22 pct
P95 Service Latency (ms)	2420.51	1752.00	-27.62%	2050.65	-15.28%
高优先级 Goodput	1.9228	3.2194	+67.43%	3.0255	+57.35%
高优先级 P95 (ms)	2424.14	1236.38	-49.00%	1375.91	-43.24%
综合性能增益	0%	+33.22%	达到挑战目标	+26.16%	达到挑战目标

完整口径、公式和分析见 技术报告与正式结果索引。

快速启动的脚本

python -m py_compile coserve/resource/handover.py coserve/scheduler/sadcs.py coserve/runtime/service.py coserve/gateway/app.py
python -m unittest discover -s tests -p "test_*.py"
cat evidence/verification/report_check.txt
python scripts/run_all_experiments.py --quick --http-count 20 --http-workers 4

真实 vLLM 复现需先按 openEuler 部署说明安装 CUDA 12.4 兼容环境，再执行 真实 vLLM 实验闭环。评审材料入口见 提交指南。

文档导航

• 技术报告
• 系统设计
• 比赛规范对照
• openEuler 部署说明
• 真实 vLLM 实验闭环
• 实验记录
• 参考资料
• 安全治理与自适应控制

系统架构

Client / Benchmark
        |
        v
FastAPI MaaS Gateway
        |
        v
CoServe Runtime
        |
        +-- Model Runtime Manager
        +-- Scheduler: FIFO / SLO-Guard-TB
        +-- Resource Handover Manager
        +-- Metrics Collector
        +-- Request Guardrails
        |
        v
Backend Adapter
        |
        +-- MockBackend
        +-- VLLMHTTPBackend

目录结构：

coserve/
  gateway/          # FastAPI API 入口、模型生命周期接口、OpenAI 兼容入口
  runtime/          # CoServe Runtime，组合调度器、模型管理、后端执行
  scheduler/        # FIFO baseline 与 SLO-Guard-TB 调度器
  resource/         # Token-Memory Co-Scheduling 与 Fast Handover
  model_manager/    # 模型状态、健康检查、熔断恢复、vLLM 后端适配
  metrics/          # 延迟、SLO、模型完成数、GPU 指标采集
  simulation/       # 离散时间排队模拟
configs/            # 模型与调度器配置样例
scripts/            # benchmark、真实 vLLM 实验、消融实验与烟测脚本
tests/              # handover、guardrails、scheduler、explain 等单元测试
docs/               # 系统设计、实验、部署与参考文献

核心算法

核心算法为 SLO-Guard-TB：

SLO-Guard-TB
  = SLO-aware request scoring
  + Per-Priority Token Reserve
  + Aging Fairness
  + Model Fair Slot
  + Deadline-Aware Token Shaping
  + Token-Memory Co-Scheduling
  + Fast GPU Memory Handover
  + Explainable Scheduling

1. SLO 感知评分

调度器对每个等待请求计算综合得分：

score =
  alpha * priority_score
+ beta  * slo_risk
+ gamma * wait_score
+ aging_bonus
- delta * length_penalty

含义：

priority_score:
  high-priority 在线请求获得更高基础权重。

slo_risk:
  根据请求已经等待的时间和 deadline_ms 估计违约风险。

wait_score:
  请求等待越久，得分越高，避免长期排队。

aging_bonus:
  low-priority 请求等待超过 starvation_ms 后获得补偿，避免饥饿。

length_penalty:
  长 prompt / 大输出请求占用更多 token budget，会被适度惩罚。

2. Per-Priority Token Reserve

系统维护全局 token budget，并按优先级拆分：

global_token_budget:
  当前允许同时在系统内运行的 token 预算。

high reserve:
  面向 high-priority 在线请求的保留预算。

low / elastic pool:
  low-priority 与 batch 请求使用的弹性预算。

borrow:
  当 high reserve 未被用满时，balanced 类策略允许 low 请求借用部分预算。

该机制避免低优先级长请求占满 GPU 池，也避免热点模型长期挤压长尾模型。

3. Deadline-Aware Token Shaping

slo-balanced 策略额外启用 deadline-aware token shaping。系统会在请求进入调度器前，根据请求优先级和 deadline_ms 对 max_tokens 做轻量收敛：

high-priority + tight deadline:
  将输出 token 上限收敛到更适合在线 SLO 的范围，降低 decode 尾延迟。

low-priority + normal deadline:
  保留更宽松的输出预算，避免过度牺牲普通请求质量。

long prompt:
  对超长 prompt 进一步收紧输出上限，减少 prefill + decode 叠加造成的
  service P95/P99 长尾。

该机制不是全局截断，而是只在 slo-balanced 中启用，并会在响应的 coserve.guardrails 中记录：

deadline_token_shaping
original_max_tokens
shaped_max_tokens
prompt_tokens_for_shaping

它的目标是优化 p95_service_ms / p99_service_ms，弥补单纯提升并发时可能带来的服务尾延迟压力。slo-balanced 同时采用比 real-balanced 更低的全局并发与更严格的 token budget，以降低真实 vLLM 后端的并发干扰。

4. Token-Memory Co-Scheduling

在请求 admit 前，调度器同时检查：

1. token budget 是否允许该请求进入；
2. memory budget 是否允许该请求占用显存租约；
3. 低优先级 batch 是否超过在线推理保留水位；
4. 是否需要触发 batch shrink / pause / resume。

这使系统不仅能做请求级调度，还能表达模型混部中的显存竞争和快速资源交接。

5. Fast Handover

ResourceHandoverManager 管理显存租约：

admit_batch:
  batch 请求只能使用 inference reserve watermark 之外的剩余显存。

handover:
  high-priority 在线请求到来时，可从 low-priority batch 中 reclaim 显存。

shrink:
  优先缩小 batch lease。

pause:
  shrink 不足时暂停 batch lease。

resume:
  在线请求释放资源后，batch lease 可恢复。

/explain/scheduler 会展示最近一次 handover 决策，包括 action、batch_action、reclaimed_mb、handover_cost_ms 等。

运行策略

系统支持六种策略，均可通过 /policy/switch 动态切换：

baseline:
  FIFO 基线。用于比赛要求的固定部署 + FIFO Routing 对照。

optimized:
  SLO-first 策略。强保护 high-priority 在线请求，适合展示 SLO 风险评分、
  Token Budget 和 Fast Handover 的机制收益。

balanced:
  模拟与本地负载下的综合策略。相比 optimized 更重视公平性和整体 P95。

real-balanced:
  真实 vLLM 承载能力优先策略。放宽 token budget 与全局并发，
  目标是提升真实 GPU 环境中的成功率、goodput 和端到端完成能力。

slo-balanced:
  真实 vLLM 综合指标优先策略。相比 real-balanced 降低全局并发，
  high-priority 请求也必须进入 token budget，并启用 Deadline-Aware Token Shaping，
  用于改善 SLO、P95/P99 和“保证服务质量的约束”。

具体表述：

real-balanced 用于展示承载能力上限和请求完成能力；
slo-balanced 用于展示更稳的服务质量约束；
optimized / balanced 用于解释算法组件在模拟和消融中的独立贡献。

功能接口

GET  /health
GET  /models
POST /models/load
POST /models/unload
POST /v1/chat/completions
GET  /stats
GET  /metrics
GET  /policy
POST /policy/switch
GET  /explain/scheduler
GET  /health/models
POST /models/recover
POST /adaptive/tick
GET  /security
GET  /audit

Web 控制台

服务启动后访问 http://127.0.0.1:8080/。控制台提供 Overview、Models、Scheduler、Resilience 四个工作视图，可操作策略切换、模型注册/卸载/恢复和 Adaptive control tick，并展示 SLO/P95、GPU/队列、Token Budget、调度解释、handover、熔断状态与审计事件。

$env:COSERVE_MODE="adaptive"
python -m uvicorn coserve.gateway.app:app --host 0.0.0.0 --port 8080

控制台静态资源随项目交付，不依赖 CDN，适合 openEuler 离线环境。

安全生产模式

默认不开启强制鉴权，以兼容已有 benchmark。正式部署必须设置：

export COSERVE_SECURITY_ENABLED=true
export COSERVE_API_KEYS='{"admin-secret":{"tenant":"platform","role":"admin","key_id":"admin-1"},"user-secret":{"tenant":"team-a","role":"user","key_id":"user-1"}}'
export COSERVE_ALLOWED_MODEL_HOSTS='127.0.0.1,localhost,vllm-a.internal,vllm-b.internal'
export COSERVE_AUDIT_LOG='/var/log/coserve/audit.jsonl'
export COSERVE_RATE_REQUESTS_PER_MINUTE=120
export COSERVE_RATE_TOKENS_PER_MINUTE=100000
export COSERVE_RATE_MAX_CONCURRENT=16

客户端使用 X-API-Key 或 Authorization: Bearer <key>。角色权限为：

user:      推理与只读监控
operator:  user + 模型注册、卸载、恢复
admin:     operator + 策略切换、Adaptive tick、安全状态与审计

/models/load 只接受 COSERVE_ALLOWED_MODEL_HOSTS 白名单中的 HTTP(S) 端点；本地 Mock 模式允许 mock://。云元数据地址、含凭据 URL、未授权私网端点会被拒绝。

Adaptive 策略

adaptive 使用独立的 quality-guarded profile：以 slo-balanced 的 SLO 约束为基础，额外提高低优先级借用能力与 aging 强度，避免在真实 vLLM 高压负载下只提升 high-priority goodput、却牺牲低优先级尾延迟。控制器周期性计算多目标风险：

risk = 0.45 * SLO violation EWMA
     + 0.15 * queue pressure EWMA
     + 0.15 * GPU interference pressure
     + 0.15 * failure rate EWMA
     + 0.10 * P95/P99 tail pressure EWMA

控制动作包括：

protect_slo:
  SLO 或失败风险过高时降低全局并发和 Token Budget，提高 high-priority reserve。

protect_tail_latency:
  P95/P99 尾延迟风险过高时限制保护态并发，增强 low-priority borrowing 与 aging。

protect_fairness:
  模型间 SLO/P95 偏斜变大时降低 starvation_ms，提高 aging_factor，避免长尾模型或低优先级请求被持续推迟。

expand_capacity:
  风险较低且存在队列或 GPU 余量时释放并发和 Token 容量。

所有动作、信号、调整前后参数和原因均进入 /explain/scheduler，并在 Web 控制台的“闭环控制时间线”和“调度智能”区域可视化。

关键能力：

/v1/chat/completions:
  OpenAI 兼容请求入口，可转发到 MockBackend 或 vLLM OpenAI API Server。

/policy/switch:
  运行时切换 baseline / optimized / balanced / real-balanced / slo-balanced / adaptive。

/explain/scheduler:
  展示最近调度决策、token budget、priority budget、handover 状态。

/health/models:
  展示模型健康状态、失败计数和熔断状态。

/models/recover:
  恢复 failed 模型实例。

运行环境要求

本地 Mock / 模拟实验

OS: Windows / Linux / WSL 均可
Python: 3.10+
依赖: fastapi, uvicorn
GPU: 不需要
用途: 代码功能验证、调度器单测、离散模拟、HTTP 控制面验证

安装：

python -m pip install -U pip
python -m pip install -e .

真实 vLLM / GPU 实验

OS: 推荐 openEuler 22.03 LTS / openEuler 24.03 LTS，或比赛统一 GPU 环境
Python: 3.10+
GPU: 32GB Tesla V100S 为正式评测环境；15GB Tesla T4 完成兼容性预检
CUDA: 与 vLLM 版本匹配
推理引擎: vLLM
模型:
  Qwen/Qwen2.5-0.5B-Instruct
  Qwen/Qwen2.5-1.5B-Instruct

安装：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e .
python -m pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu124
python -m pip install -r requirements-vllm-cu124.txt

openEuler + V100 32GB 双模型闭环

当前推荐验证机规格为 openEuler 24.03 LTS-SP1、x86_64、Tesla V100 32GB、 8 vCPU、64 GiB 内存和 200 GiB 系统盘。V100 的计算能力为 7.0， vLLM 0.8.5.post1 会自动使用 V0 engine，这是预期兼容路径。

先执行只读预检。该步骤会在启动模型前检查 nvidia-smi、PyTorch CUDA、 pip check、模型 config.json、磁盘空间、端口和上下文预算：

python scripts/real_vllm_experiment.py \
  --start-vllm \
  --model-a /root/models/Qwen2.5-0.5B-Instruct \
  --model-b /root/models/Qwen2.5-1.5B-Instruct \
  --gpu-memory-utilization-a 0.38 \
  --gpu-memory-utilization-b 0.38 \
  --max-model-len 1024 \
  --workload v100-dual \
  --max-prompt-tokens 512 \
  --max-output-tokens 128 \
  --warmup-count 8 \
  --count 120 \
  --workers 4 \
  --preflight-only \
  --require-gpu

预检通过后，先跑稳定档：

python scripts/real_vllm_experiment.py \
  --start-vllm \
  --start-coserve \
  --model-a /root/models/Qwen2.5-0.5B-Instruct \
  --model-b /root/models/Qwen2.5-1.5B-Instruct \
  --gpu-memory-utilization-a 0.38 \
  --gpu-memory-utilization-b 0.38 \
  --max-model-len 512 \
  --workload t4-dual \
  --max-prompt-tokens 256 \
  --max-output-tokens 96 \
  --warmup-count 6 \
  --count 60 \
  --workers 2 \
  --modes baseline slo-balanced adaptive \
  --min-success-rate 0.95 \
  --require-gpu

稳定档通过后，再使用 docs/real_vllm_experiment.md 中的 V100 压力档。 每种策略均先完成相同请求预热，并在正式计时前重置 CoServe 指标，以减少 冷启动和固定执行顺序造成的偏差。压测期间会持续写入 GPU 时间序列和逐请求记录。

验证环境：

python -c "import vllm; print(vllm.__version__)"
python -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available(), torch.cuda.get_device_name(0))"
nvidia-smi

本地快速验证

编译与单元测试：

python -m py_compile coserve/resource/handover.py coserve/scheduler/sadcs.py coserve/runtime/service.py scripts/benchmark.py scripts/handover_ablation.py scripts/http_compare.py scripts/real_vllm_experiment.py
python -m unittest discover -s tests -p test_*.py

一键 quick 实验：

python scripts/run_all_experiments.py --quick --http-count 20 --http-workers 4

完整本地实验：

python scripts/run_all_experiments.py

输出目录：

results/<timestamp>/summary.md
results/<timestamp>/*.txt
results/<timestamp>/*.csv
results/latest/summary.md

当前 quick 实验覆盖：

compile
unit-tests
chat-120 benchmark
handover-ablation
http-compare

启动服务

Mock 模式

PowerShell：

$env:COSERVE_MODE="slo-balanced"
$env:COSERVE_BACKEND="mock"
python -m uvicorn coserve.gateway.app:app --host 0.0.0.0 --port 8080

Bash：

export COSERVE_MODE=slo-balanced
export COSERVE_BACKEND=mock
python -m uvicorn coserve.gateway.app:app --host 0.0.0.0 --port 8080

切换策略：

curl -X POST http://127.0.0.1:8080/policy/switch \
  -H "Content-Type: application/json" \
  -d '{"mode":"real-balanced"}'

查看解释：

curl http://127.0.0.1:8080/explain/scheduler

真实 vLLM 模式

推荐使用统一实验器。它会先检查 CUDA、模型路径、端口和上下文预算，再顺序启动两个 vLLM，避免单卡并发初始化争抢显存：

python scripts/real_vllm_experiment.py \
  --start-vllm \
  --start-coserve \
  --model-a /root/models/Qwen2.5-0.5B-Instruct \
  --model-b /root/models/Qwen2.5-1.5B-Instruct \
  --gpu-memory-utilization-a 0.30 \
  --gpu-memory-utilization-b 0.30 \
  --max-model-len 512 \
  --workload t4-dual \
  --max-prompt-tokens 256 \
  --max-output-tokens 96 \
  --count 60 \
  --workers 2 \
  --modes baseline slo-balanced adaptive \
  --require-gpu

PASS 不再只表示脚本执行结束。每个模式必须生成完整请求记录，且成功率达到 --min-success-rate（默认 95%）；否则结果目录写入 failure.txt 并以失败退出。

脚本会自动生成：

results/real_vllm/<timestamp>/
  gpu_before.csv
  gpu_during.csv
  gpu_after.csv
  records/
  vllm_a.log
  vllm_b.log
  coserve.log
  http_compare.txt
  manifest.json
  summary.md

如果两个 vLLM 已经手动启动，只让实验器启动 CoServe 并完成真实对比：

python scripts/real_vllm_experiment.py \
  --no-start-vllm \
  --start-coserve \
  --endpoint-a http://127.0.0.1:8001/v1/chat/completions \
  --endpoint-b http://127.0.0.1:8002/v1/chat/completions \
  --max-model-len 512 \
  --workload t4-dual \
  --max-prompt-tokens 256 \
  --max-output-tokens 96 \
  --count 60 \
  --workers 2 \
  --modes baseline slo-balanced adaptive \
  --require-gpu

实验脚本

离散时间排队模拟

python scripts/benchmark.py --count 120 --seed 7 --mode compare-all
python scripts/benchmark.py --count 300 --seed 7 --mode compare-all

多类型模型融合负载

python scripts/benchmark.py --count 180 --seed 7 --mode compare-all --workload fusion

Fusion 负载包含：

LLM chat:  qwen2.5-0.5b / qwen2.5-1.5b
Embedding: bge-small
Rerank:    rerank-mini

Fast Handover 演示

python scripts/handover_smoke.py

典型输出：

batch_action: admit_batch
online_action: handover
reclaimed_mb: 3974
handover_cost_ms: 18.0
batch_status: shrunk

Fast Handover 消融

python scripts/handover_ablation.py --count 180 --seed 7

该脚本对比：

baseline
score-only
token-only
token+memory-no-handover
token+memory+handover
balanced-no-aging
balanced

输出指标包括：

goodput
p95 / p99
high_goodput
high_p95
batch_completed
batch_slo
fairness
handover_count
defer_batch_count
resume_batch_count
reclaimed_mb
handover_cost_ms
peak_memory_mb

HTTP 级策略对比

python scripts/http_compare.py --count 100 --seed 7 --workers 8

默认会在本地 127.0.0.1:8091 自启动 Mock Gateway，并依次切换：

baseline
optimized
balanced
real-balanced
slo-balanced

关键指标

实验报告重点记录：

success_rate:
  HTTP 请求成功率。

wall_throughput:
  客户端实际观察到的吞吐。

goodput:
  wall_throughput * SLO attainment。

SLO attainment:
  service_ms <= deadline_ms 的请求比例。

p95_service_ms / p99_service_ms:
  CoServe 排队时延 + 后端推理时延。

p95_wall_ms:
  客户端端到端 HTTP 时延，用于观察 timeout 与卡死问题。

high_goodput / high_p95_ms:
  高优先级在线请求指标。

GPU util / memory:
  来自 gpu_during.csv，用于说明资源利用率与显存占用。

records/*.csv:
  每条请求的 ok、wall_ms、service_ms、priority、model、deadline_ms、error。

实验结论与证据边界

正式结论采用单 V100S、双 vLLM、双 Qwen2.5 模型的统一负载实验。slo-balanced 取得 +33.22% 综合性能增益，adaptive 取得 +26.16% 综合性能增益，均超过赛题 “挑战目标为 25% 或更大”的门槛。详细原始口径与局限性见技术报告第 6 章。

补充实验承担不同的证明责任：

离散模拟：验证调度趋势、Token Reserve、Aging Fairness 与 handover 消融；
HTTP Mock：验证网关、策略切换、监控、解释接口和错误处理；
T4 预检：验证 openEuler/CUDA/vLLM 的较小显存兼容路径；
V100S 正式实验：支撑最终性能结论和 25% 挑战目标判断。

ResourceHandoverManager 当前实现为控制面的显存预算、批任务租约与 shrink/pause/resume 状态机；它不宣称完成 CUDA 页迁移或 vLLM KV Cache 的物理迁移。 该边界在报告中明确披露，避免把控制面机制误写为推理引擎内核能力。

提交内容

最终我的提交包仅保留一套权威源码、文档和证据，不包含 API Key、私钥、历史压缩包、模型权重 或缓存文件。评委建议按以下顺序阅读：

1. README.md：三分钟入口、运行方式与核心结果；
2. report/研究创新-MaaS平台中模型混部的资源编排与性能优化-何诗雨-技术报告.pdf：完整研究报告；
3. SUBMISSION_GUIDE.md：评分项映射、验收命令与材料清单；
4. evidence/formal_v100/：正式 V100S 指标与证据说明；
5. docs/competition_compliance.md：逐条赛题合规矩阵；
6. coserve/、scripts/、tests/：系统实现、实验脚本与自动化测试。