CloudEco：一个基于环境机器学习的云端容器编排应用（30%）

截止日期：2026年4月29日（星期三，第8周）23:55

1. 概述与背景

环境监测日益依赖边缘到云端的计算机视觉架构，用于检测和追踪生态事件，例如森林火灾、海洋塑料污染、城市垃圾堆积以及野生动物活动。这些复杂系统利用深度神经网络——特别是单阶段目标检测器，例如 YOLO（You Only Look Once）——以实时方式识别、分类并定位图像中的对象。

本项目名为 CloudEco，要求开发一个高度可扩展的、部署在公有云上的基于 Web 的机器学习推理系统。终端用户（由自动化测试脚本模拟）将通过 HTTP POST 请求向你的 RESTful Web 服务提交图像。系统将使用预训练的环境机器学习模型处理这些图像，并返回一个结构化负载，其中包含检测到的对象详情以及一张带标注的图像。

该 Web 服务必须使用 Python 的 FastAPI 框架开发。应用程序必须使用 Docker 进行容器化，并使用 Kubernetes 集群进行编排。为了符合现代 DevOps 实践，强烈鼓励你使用 基础设施即代码（IaC） 工具（例如 Terraform 或 Ansible）来配置你的网络和集群基础设施。

最后，系统性能将被严格测试。你将使用负载生成工具 Locust，在集群中通过调整活动 Kubernetes Pod 的数量，在不同并发需求和资源可用性条件下对你的服务进行基准测试。

2. 作业目标

本作业旨在评估你在云原生开发、分布式系统和性能工程方面的能力，涵盖以下核心目标：

1. API 开发： 使用 FastAPI 构建一个基于 Python 的 RESTful API，以处理图像负载，安全地执行阻塞式或异步式机器学习推理，并返回结构化 JSON 以及 base64 编码的标注图像。
2. 容器化： 将 Python 应用程序、模型权重和系统依赖打包为一个经过优化的、轻量级的 Docker 镜像。
3. 基础设施即代码（IaC）： 使用 Terraform、Ansible 或 Chef 自动化云资源及资源分配策略的配置。
4. 容器编排： 部署容器化应用，配置 Kubernetes Deployments 和 Services（LoadBalancer），并管理严格的 Pod 资源请求与限制。
5. 性能基准测试： 使用 Locust 模拟高并发流量，并在考虑硬件限制的前提下测量系统延迟、吞吐量（每秒查询数）和失败率。
6. 实证报告（500 字）： 以简洁、数据驱动的基准测试报告分析系统瓶颈、处理效率以及水平扩展特性。

3. 模型分配策略

为了确保系统测试的多样性并防止大量代码重复，你将根据你的 Monash 学号最后一位数字 被分配四种环境 YOLO 模型中的一种。你将获得对应模型的预训练权重和源代码。你不需要训练或微调模型；你的任务完全聚焦于云端部署、推理集成和架构扩展。

模型分配依据如下表：

4. Web 服务架构

你必须使用 FastAPI 框架开发一个 RESTful API。服务器必须能够高效处理多个并发客户端。Web 服务需要为每个传入请求创建异步任务处理，使用 YOLO 引擎检测图像中的对象。

4.1 推理 JSON API（/api/predict）

客户端将发送一个 HTTP POST 请求，其中包含一个 JSON 对象，该对象具有唯一标识符（例如 UUID）和一个 base64 编码的图像。由于标准 JSON 中无法直接传输二进制图像数据，因此需要进行这种编码转换。

Web 服务必须将 base64 字符串解码为 NumPy 数组或 OpenCV 图像，将其传入分配给你的 YOLO 模型中，并返回一个 JSON 对象，其中包含所有检测对象的边界框、置信度分数和类别标签。

用于发送图像的 JSON 请求示例如下：

要求的响应负载格式：

说明：

1. uuid 是客户端连同图像一起发送的相同 ID。它用于在客户端将异步响应与请求对应起来。
2. count 的值 n 表示在图像中检测到的对象数量。
3. boxes 表示围绕检测对象的 n 个矩形框列表，其中包含 (x,y) 坐标、宽度、高度，以及该矩形区域包含检测对象的概率信息。当 count 为 0 时，这里应为空数组。
4. 延迟指标（speed_preprocess_ms 等）由 Ultralytics YOLO 推理引擎在预测时自动生成，必须被动态提取并返回在负载中。

4.2 标注图像 API（/api/annotate）

第二个端点必须接受完全相同的请求负载结构，但返回的 JSON 对象中应包含叠加了边界框和标签的原始图像。Ultralytics 库提供了绘图工具，可以自动渲染这些标注。生成后的标注图像必须重新编码为 base64 格式并返回给客户端。

5. 容器化与基础设施即代码

5.1 Dockerfile 设计

Docker 通过读取 Dockerfile 中的指令来构建镜像。你必须创建一个经过优化的 Dockerfile 来打包你的 Web 服务。对于云部署而言，优化至关重要。请避免安装不必要的软件包（例如文本编辑器或图形界面库），以尽量减小最终镜像大小并缩短从镜像仓库拉取的时间。你必须使用合适的 Python 基础镜像，并确保像 PyTorch 这样的重量级机器学习库使用 仅 CPU 的索引标志 安装，以减少数 GB 的容器体积膨胀。

5.2 基础设施即代码（IaC）

为了体现现代 DevOps 实践，作业总分中有一部分分数用于评价你是否使用 Terraform、Ansible 或 Chef 来自动化基础设施配置。你必须提交脚本，以自动创建所需的云资源和资源分配策略。允许你通过图形化 OCI Web 控制台手动创建这些资源以完成作业，但这样做将失去分配给 IaC 的分数。

6. Kubernetes 集群配置

你将在公有云平台（GCP、Oracle 或 Azure）上使用三台虚拟机（每台 4 核 CPU、8 GB RAM）部署你的容器化应用。你需要在这些虚拟机上设置一个 K8s 集群，其中 1 台为主节点（master node），2 台为工作节点（worker nodes）。你必须配置一个基础 K8s 集群并在其上托管你的应用。

你必须创建标准的 Kubernetes 清单文件（YAML）来编排你的应用。

• Deployments： 创建一个 Kubernetes Deployment，从可访问的镜像仓库中拉取你的 Docker 镜像。
• 资源限制： 你必须将每个 Pod 限制为最多 1 个 vCPU（CPU limit: "1.0"）以及指定大小的内存（更多细节见 rubric）。这个硬件限制对于性能基准测试阶段的有效性在数学上至关重要。
• 服务暴露： 使用 Kubernetes Service 的 NodePort、LoadBalancer 或 ingress controller 来暴露你的 Deployment；也允许在 master 节点上使用独立的负载均衡器。你需要将外部互联网流量路由到集群中的 Pod。

7. 负载生成与性能指标

使用 Locust，你将编写一个 Python 负载生成脚本，以模拟对你的 API 的并发用户访问。该脚本必须持续地将本地环境测试图像编码为 base64，将其嵌入要求的 JSON 结构中，并向你的 /api/predict 和 /api/annotate 端点执行 HTTP POST 请求。

提示： 由于机器学习推理是高度 CPU 密集型任务，因此在 Python 中实现高并发需要谨慎的架构管理。如果你只是简单地在标准异步 FastAPI 路由内部执行同步的 YOLO 预测，那么你会阻塞主事件循环，导致所有并发请求出现灾难性的延迟飙升。

8. 实验与基准测试报告

你将测试系统在不同资源条件下的可扩展性。你必须针对你的 K8s 集群运行 Locust 脚本，同时调整 Deployment 的副本数，以改变活动 Pod 的数量：1、2、4 和 8 个 Pod。

对于每一种特定的 Pod 配置，你将逐步增加 Locust 的并发用户数，直到系统达到其崩溃点——定义为响应时间呈指数级恶化，或开始出现 HTTP 500/503 错误的阈值。记录在该阈值下的最大稳定并发用户数以及平均响应时间。

报告要求：

你必须提交一份简洁、数据驱动的基准测试报告（最多 500 字），内容包括以下部分：

1. 结果表格： 记录在 1、2、4 和 8 个 Pod 配置下的最大用户数和平均响应时间。
2. 图形绘图： 两张不同的图，用于展示在不同扩展配置下，并发用户数与平均延迟之间的相关关系。
3. 性能分析： 从技术角度解释扩展效率。根据排队论和 Little 定律，解释系统达到饱和时观察到的延迟尖峰。识别你的 FastAPI/YOLO 架构中的主要瓶颈，并论证水平 Pod 自动扩展如何缓解这些问题。

9. 面试 / 演示

现在你已经完成了项目，是时候向利益相关者演示它了。

为了验证你提交内容的真实性并确保你具备相应的技术理解，你必须参加一次由教学团队组织的 20 分钟现场技术面试。这是本作业的一个严格门槛要求。如果你未参加面试，或无法展示对你自己的项目有足够理解，那么你最终可获得的最高分数将是 45 分（满分 100 分）。

在面试过程中，你将需要：

1. 共享你的屏幕，并使用 kubectl 命令现场展示你的集群。
2. 实时执行 Locust 脚本，以展示应用功能和负载均衡效果。
3. 在面试官提问时，解释你应用中的部分源代码。
4. 解释你的优化策略，并演示你的 IaC 脚本（如果有）。

如果你无法充分解释你自己的代码，或表现出对你的云基础设施缺乏理解，将导致整个作业自动不及格（NH），你的分数将被封顶为 45%，无论系统本身是否能够运行。

10. 提交要求

你需要通过 Moodle 提交 3 个文件：

• 一份按要求撰写的 PDF 格式报告（文件名：firstname_lastname_studentid.pdf）。
• 一份 PDF 文件，其中包含你使用过的生成式 AI 提示词及其输出。
• 一个 .ZIP 文件（不是 .RAR 或其他格式），其中包含以下内容：

1. 你的 Dockerfile。
2. 你的 Web 服务源代码。
3. 你的 Kubernetes 部署和服务配置（YAML 文件）。
4. 你的 Locust 客户端脚本。
5. 任何用于自动化运行实验的脚本（如果你有）。
6. 你的 IaC 脚本。
7. 一个 readme.md 文件，简要说明如何运行你的应用程序。此外，还要包含你已部署应用的、可通过互联网访问的 URL。

这个 zip 文件本质上就是你的交付工件（deliverable artefact）（当你完成一个软件项目时，你需要向客户交付一个可构建 / 可部署的软件包）。

11. 生成式 AI 声明

根据学校关于生成式 AI 使用指南与实践的政策：

本次评估中，允许公开使用生成式 AI 工具。

如果使用了 AI，必须负责任地使用，清晰记录，并进行适当致谢（见 Learn HQ）。

任何用于评分的提交作品都必须：

1. 体现出你本人在人类努力、技能和学科知识方面的真实投入，而这些内容你需要为之负责。
2. 遵守本评估任务规定的 AI 使用指南。
3. 体现学校对学术诚信和道德行为的承诺。
4. 不恰当使用 AI 和 / 或未对 AI 使用进行说明，将被视为违反学术诚信。

教学团队鼓励学生在使用生成式 AI 助手完成评估任务时，运用自己的批判性思维和推理能力。

生成式 AI 工具可能会产生不准确的内容，这可能会对学生对大数据主题的理解产生负面影响。

你使用过的所有提示词及其输出都必须作为参考附在你的提交内容中。