MORE-MaaS

1. 项目简介

MORE-MaaS 是一个面向资源受限端的多模型推理资源编排插件。项目以 llama.cpp / llama-server 作为模型推理后端，在其外部增加统一 API 网关、请求队列、动态并发服务能力分配、运行状态监测、后端路由和内存备用实例迁移等功能。

本项目不修改 llama.cpp 的推理内核、模型加载逻辑和 GGUF 模型文件。团队创新代码集中在 maas/ 目录，可作为独立插件部署，并能够针对不同模型设置不同的优先级、并发范围、请求完成时限和运行配置。

项目主要包含两个并列的优化点：

1. 动态分配并发服务能力
   根据各模型的排队长度、等待时间、请求到达速率和完成速率，动态调整不同模型可同时进入后端执行的请求数量。

2. 内存备用实例迁移
   提前加载并预热 CPU/系统内存备用实例。当 GPU 资源紧张时，仅切换网关内部的新请求路由，使原 GPU 实例完成在途请求后退出并释放显存。

---

2. 提交材料说明

本次提交材料主要包括以下三部分：

• MORE-MaaS/
  整体实验代码目录，包含 llama.cpp 推理后端、项目运行环境、团队开发的 maas 插件以及全部实验脚本。

• MORE-MaaS项目技术说明书.docx
  项目技术说明书，介绍项目背景、系统设计、两个优化点、代码实现、实验方法、实验结果和快速复现方式。

• 视频/
  本次比赛实验结果的完整复现视频，展示服务启动、动态并发分配、请求热点转移、内存备用实例迁移以及最终结果文件。

---

3. 代码目录

提交目录
├─ README.md
├─ MORE-MaaS项目技术说明书.docx
├─ 视频/
│  └─ 实验结果复现视频
└─ MORE-MaaS/
   ├─ llama.cpp 相关源码、编译文件和推理后端
   └─ maas/                            # 团队自主实现的创新插件代码
      ├─ app/                          # 统一 API 网关、请求接入和后端转发
      ├─ scheduler/                    # 每模型请求队列和请求调度
      ├─ orchestrator/                 # 动态并发分配、资源决策和实例迁移
      ├─ monitor/                      # 模型状态与 GPU 状态监测
      ├─ metrics/                      # 请求时延、吞吐量和运行指标记录
      ├─ benchmark/                    # 突发负载、热点转移和迁移实验
      ├─ scripts/                      # 服务启动、实例恢复和辅助脚本
      ├─ run_all_competition_tests_v2.ps1
      │                                # 三轮正式实验总脚本
      ├─ requirements.txt              # Python 依赖
      └─ README.md                     # 插件运行与开发说明

MORE-MaaS/ 是完整的实验工程目录；其中 maas/ 是本团队开发的核心插件代码。
llama.cpp 负责模型加载和实际推理，maas 负责多个模型之间的统一接入、请求排队、资源编排、路由切换和实验记录。

---

4. 核心代码模块

4.1 app/

提供统一 API 入口，负责：

• 接收客户端请求；
• 校验模型名称和生成参数；
• 将请求放入对应模型队列；
• 根据当前路由转发到 llama-server；
• 返回请求结果和异常信息。

客户端统一访问：

POST /v1/chat/completions

4.2 scheduler/

负责维护不同模型的独立请求队列，并管理请求的入队、出队和执行状态。

4.3 orchestrator/

项目的核心资源编排模块，主要负责：

• 根据实时负载调整各模型的并发服务能力；
• 检查总并发预算和模型并发上下限；
• 管理调整冷却时间；
• 管理 GPU 主实例和 CPU/内存备用实例；
• 执行后端路由切换和旧实例退出。

4.4 monitor/ 与 metrics/

负责采集和记录：

• 排队请求数量；
• 最老请求等待时间；
• 请求吞吐量；
• 平均时延、P95 和 P99；
• 当前并发执行名额；
• GPU 显存、利用率、功耗和温度；
• 实例迁移状态。

4.5 benchmark/

包含本次比赛使用的主要实验负载：

• 单模型短时请求突发实验；
• 请求热点转移实验；
• GPU 压力与内存备用实例迁移实验；
• 实验结果汇总和时间轨迹记录。

---

5. 运行说明

以下命令均在 maas/ 目录下执行。

5.1 启动模型服务和统一网关

打开第一个 CMD 窗口：

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\start_gateway.ps1

启动成功后，请保持该窗口运行。系统将启动两个 GPU 模型实例、CPU/内存备用实例和统一 API 网关。

5.2 运行三轮正式实验

打开第二个 CMD 窗口：

powershell -NoProfile -ExecutionPolicy Bypass -File .\run_all_competition_tests_v2.ps1 -Rounds 3

脚本会自动完成：

1. 单模型短时请求突发的固定分配与动态分配对比；
2. 请求热点转移的固定分配与动态分配对比；
3. 不迁移方案与内存备用实例迁移方案对比；
4. 模型状态恢复与短请求预热；
5. GPU 温度检查；
6. 三轮实验结果汇总。

---

6. 实验结果文件

正式实验结果默认保存在：

maas/benchmark/results/competition_all_in_one/

主要文件包括：

competition_summary.csv
all_results.json
r01_*.json
r02_*.json
r03_*.json

其中：

• competition_summary.csv：三轮实验的平均值、标准差和变化比例；
• all_results.json：全部实验的完整结果、调度事件、迁移记录和 GPU 时间轨迹；
• r01_*、r02_*、r03_*：每一轮单项实验的原始结果。

---

7. 复现视频说明

视频/ 目录中的视频用于完整展示本次比赛实验的复现过程，主要包括：

1. 项目目录和运行环境说明；
2. 两个 GPU 模型实例和内存备用实例启动；
3. 统一 API 网关健康状态检查；
4. 单模型短时请求突发实验；
5. 请求热点转移与并发服务能力双向调整；
6. 内存备用实例迁移和 GPU 显存释放；
7. 三轮正式实验结果文件查看。

建议按照“项目技术说明书 → 复现视频 → 代码目录”的顺序进行审阅。

---

8. 项目代码边界说明

• llama.cpp / llama-server：作为基础推理后端，负责模型加载、CPU/GPU 推理和文本生成；
• maas/：本团队自主实现的多模型资源编排插件；
• MORE-MaaS 不修改 llama.cpp 推理源码；
• 插件通过 HTTP 接口调用多个独立的 llama-server 实例；
• 更换模型或升级 llama.cpp 时，主要调整模型配置和启动参数，无需重新修改推理引擎代码。

---

9. 推荐审阅顺序

1. 阅读 MORE-MaaS项目技术说明书.docx，了解项目背景、设计和实验结果；
2. 观看 视频/ 中的实验复现视频；
3. 查看 MORE-MaaS/maas/ 中的团队创新代码；
4. 运行 run_all_competition_tests_v2.ps1 复现三轮正式实验；
5. 在 benchmark/results/competition_all_in_one/ 中核对实验结果。