ColoMaaS 决赛提交 1.0

参赛队伍：导师说的都队。本目录为决赛提交材料根目录，包含源码、项目文档、测试证据、部署入口、演示 PPT、视频及原创承诺书。正式实验数据更新至 2026-10-07。

项目简介与主要功能

ColoMaaS 面向单机双 NVIDIA A10 的异构多模型推理服务，混部 Qwen3.5-0.8B、Phi-4-mini-instruct、InternVL3.5-2B，以四个独立 Worker 支持通用问答、代码推理、视觉文档分析和多租户服务。

OpenAI-compatible API、SSE、图像输入、会话及 Web 控制台。
HeteroMARS-X 请求级调度、阶段观测、高负载干扰感知、GPU 准入及公平槽位。
差异化模型精度、自研融合接入、原生回退、Worker 管理及故障转移。
多租户鉴权、RBAC、请求与 Token 配额和安全审计。

材料目录

路径	内容
`src/ColoMaas/`	完整工程、运行配置、模型重建脚本及源码内校验清单
`docs/项目说明书.pdf`	系统设计、实现、最新矩阵及七阶段消融结果
`docs/项目创新说明.pdf`	三项创新、实现位置、实验支撑及适用范围
`docs/项目创新说明.md`	创新说明的可编辑文本源文件
`docs/成员分工及主要贡献说明.pdf`	三名成员的分工与主要贡献
`docs/人工智能及第三方工具使用说明.pdf`	人工智能工具、第三方组件及使用范围
`tests/unit/`、`tests/deployment/`	单元测试和部署验证材料
`tests/results/formal-matrix-20261007/`	最新正式矩阵，36 个运行单元及原始记录
`tests/results/ablation/`	最新七阶段消融，28 个运行单元及重算分析
`demo/`	空白 Linux 服务器部署、启动、验证和停止入口
`presentation/决赛现场演示PPT.pptx`	可编辑决赛演示文稿，含最新矩阵、消融及演示视频
`presentation/决赛演示视频.mp4`	决赛演示视频
`作品原创承诺书.pdf`	作品原创承诺材料

评审实验数据以根目录 tests/results/ 中的最新矩阵和消融为准。源码内部 tests/、configs/、results/ 保留工程相对路径和历史复现材料；历史结果不替代本次正式数据。

正式实验结果

完整系统矩阵对比 BF16/native 完整功能 FIFO 与 W4-down8/fused HeteroMARS-X，覆盖 QPS 1、2、4、8、12、16，每种配置各重复 3 次，共 36 个单元。消融覆盖 7 阶段、QPS 4 和 12、各 2 次重复，共 28 个单元，数据选择以包内 selection.json 为准。每个单元预热 60 秒、正式测量 300 秒。

下表为同 Trace、同 Repeat 配对相对变化的中位数；P99 正值表示时延降低。

实验	QPS	请求吞吐增加	Token 吞吐增加	Goodput 增加	P99 降低
完整系统矩阵	8	6.8%	17.4%	69.4%	54.5%
完整系统矩阵	12	15.6%	25.1%	148.6%	59.8%
完整系统矩阵	16	22.4%	31.1%	224.3%	59.5%
消融 S1 到 S7	4	12.0%	8.0%	25.2%	17.0%
消融 S1 到 S7	12	9.2%	25.1%	129.3%	55.5%

矩阵记录 77,400 个输入请求，消融记录 67,200 个；合计成功 60,323 个、主动 Shed 84,276 个、失败 1 个。失败为消融中的一次 HTTP 500，二者是同一请求；超时与 SSE 终止帧缺失均为 0。消融另有一次健康探针异常，详情见 tests/results/ablation/README.md。

两组实验的源码快照 SHA-256 相同：33d53cf46ecd7a42dcbb6dea75d39e5c3d8340eb6343f7728b77ed9855298aad。全部负载数据、相邻阶段变化及指标定义见 docs/项目说明书.pdf。

环境与依赖

真实推理需要 Linux、双 NVIDIA A10、兼容 NVIDIA Driver、CUDA、PyTorch、vLLM、Redis 和模型权重。自动部署的发行版和资源要求见 demo/README.md：每卡至少 22,000 MiB 可见显存，约 64 GB 主存，初始至少 80 GiB 空闲空间。

原工程依赖见 src/ColoMaas/requirements*.txt 和 requirements*.lock；空白服务器部署使用 demo/ 中分离的 Gateway、模型重建及 Worker 环境。模型权重和虚拟环境不随仓库提交；脚本按固定 revision 下载和重建，需要相应网络、磁盘空间及模型访问授权。

空白服务器部署

以下命令从本提交根目录执行。无 GPU 功能联调：

sudo sh demo/deploy.sh --mode mock --install-system

双 A10 且已安装兼容驱动的真实推理部署：

sudo sh demo/deploy.sh --mode optimized --install-system

空白 Ubuntu 服务器安装 NVIDIA 驱动：

sudo sh demo/deploy.sh --mode optimized --install-system --install-driver

驱动安装阶段返回退出码 3 时，管理员重启服务器，确认 nvidia-smi 正常后重新执行真实推理部署命令。Debian、openEuler 的驱动按厂商及发行版流程安装。

部署器完成依赖安装、隔离环境、模型下载及量化、CUDA 扩展构建、启动和实际推理检查。默认数据目录 /os，监听 127.0.0.1:8000，认证令牌自动生成并保存于私有部署目录。自定义目录使用 --data-dir，后续命令保持相同参数。

完成首次部署后，启动、验证和停止：

sh demo/run_optimized.sh
sh demo/verify.sh --mode optimized
sh demo/stop.sh --mode optimized

mock 模式使用 run_mock.sh 和 --mode mock。mock 验证接口功能；真实模式验证模型加载及实际推理，性能评估使用正式实验流程。完整部署、分阶段重试及认证说明见 demo/README.md。

原工程构建与测试

原工程环境安装和模型重建入口：

cd src/ColoMaas
bash scripts/install_server.sh
bash scripts/setup_rebuild_env.sh
bash scripts/rebuild_optimized_models.sh all

上述脚本分别承担工程安装和模型重建；首次完整部署使用 demo/deploy.sh。重建细节见 src/ColoMaas/MODEL_REBUILD_GUIDE.md，API、配置与原实验方法见 src/ColoMaas/USAGE_GUIDE.md。

工程目录内安装测试依赖后执行：

python -m pytest -q

部署入口测试从提交根目录执行：

python3 -m unittest discover -s tests/deployment -v

部署验证记录及覆盖范围见 tests/deployment/验证说明.md，材料索引见 tests/README.md。源码内 MANIFEST.sha256 用于对应快照的文件完整性核对，不代表根目录全部文档的校验清单。

技术范围与结果解释

正式候选启用请求级 HeteroMARS、StageLens 和高负载干扰感知；阶段资源拆账、Pool Budget、KV Lease 与 MPS 默认关闭，不计入本次性能贡献。
矩阵同时比较执行栈和调度策略，系统收益不能全部归因于单一模块或融合算子；消融相邻阶段百分比不可相加。
负载和指标间存在取舍，例如 QPS 2 的 TTFT P95 上升 10.2%。主动 Shed 为过载准入策略的显式拒绝，与执行错误分开统计。
既有独立领域质量结果为 30/32，不等同于本次源码快照的独立质量复测。新消融覆盖 24 个 W4 配置运行单元，未提供对应融合内核命中计数。
CUDA 扩展及优化权重受硬件、工具链和后端版本影响，目标环境按部署流程重建与验证；材料整理及数据重算不替代目标服务器实际运行。