实时口罩检测-通用开源可部署实践GitHub Actions自动化CI/CD你有没有想过如何将一个实用的AI模型比如实时口罩检测变成一个随时可用、稳定可靠的服务传统的手动部署方式不仅繁琐而且难以维护和更新。今天我们就来聊聊如何利用GitHub Actions为基于ModelScope和Gradio的“实时口罩检测-通用”模型搭建一套自动化CI/CD流水线实现从代码提交到服务部署的“一键式”管理。简单来说这篇文章会带你走通一条路如何让一个AI模型自己“跑”起来并且能持续“进化”。我们将使用一个开源的实时口罩检测模型作为例子它基于DAMO-YOLO框架能准确识别图片中的人脸是否佩戴口罩。我们的目标不是仅仅部署它而是构建一套自动化系统确保每次代码改进或模型更新都能自动完成测试、构建和部署。1. 项目概述与核心价值1.1 为什么需要自动化CI/CD想象一下这个场景你发现了一个可以提升模型检测精度的参数或者修复了一个前端界面的小bug。在传统模式下你需要在本地修改代码。手动运行测试可能还会忘记。登录服务器停止旧服务。上传新代码重新安装依赖。启动新服务并祈祷一切正常。这个过程不仅容易出错而且重复劳动。CI/CD持续集成/持续部署就是为了解决这个问题而生的。它就像给你的项目请了一个不知疲倦的“机器人管家”持续集成 (CI)每当你提交代码到GitHub机器人会自动运行测试确保新代码不会“搞坏”原有功能。持续部署 (CD)当测试通过后机器人会自动将新版本部署到服务器上让用户立刻用上最新的服务。对于我们的“实时口罩检测”服务自动化CI/CD意味着更高的可靠性、更快的迭代速度和更低的运维成本。1.2 核心组件介绍我们的项目主要基于三个核心工具ModelScope魔搭社区一个开放的AI模型社区。我们的“实时口罩检测-通用”模型就托管在这里。它提供了便捷的模型加载和推理接口。Gradio一个超级好用的Python库可以快速为机器学习模型构建美观的Web界面。用户通过网页上传图片就能看到检测结果非常适合演示和轻量级服务。GitHub ActionsGitHub内置的自动化工具。我们可以编写一个“工作流”配置文件YAML格式告诉GitHub在特定事件如代码推送发生时自动执行一系列命令如安装依赖、运行测试、部署服务。把它们串起来整个流程就是代码托管在GitHub - GitHub Actions 自动构建 - 部署包含 ModelScope 模型和 Gradio 界面的服务。2. 项目结构与核心代码解析在搭建自动化流水线之前我们先要理解这个口罩检测服务本身是如何工作的。以下是经过简化和整理后的核心项目结构。2.1 核心应用文件 (app.py)这是服务的主入口使用Gradio创建Web界面。import gradio as gr from modelscope.pipelines import pipeline from modelscope.utils.constant import Tasks import cv2 import numpy as np # 1. 从ModelScope加载口罩检测模型 # ‘damo/cv_tinynas_object-detection_damoyolo_facemask’ 是模型ID mask_detection_pipeline pipeline( taskTasks.image_object_detection, modeldamo/cv_tinynas_object-detection_damoyolo_facemask ) def detect_mask(image): 核心检测函数 参数: image (numpy数组) - 输入图片 返回: image (numpy数组) - 带有检测框的图片 # 2. 执行模型推理 result mask_detection_pipeline(image) # 3. 处理结果在图片上绘制检测框 output_img image.copy() if boxes in result: for box_info in result[boxes]: # box: [x1, y1, x2, y2] box box_info[:4].astype(int) label int(box_info[4]) # 类别ID score box_info[5] # 置信度 # 类别ID与名称映射 class_names {1: facemask, 2: no facemask} label_name class_names.get(label, unknown) color (0, 255, 0) if label 1 else (0, 0, 255) # 绿色戴口罩红色未戴 # 绘制矩形框和标签 cv2.rectangle(output_img, (box[0], box[1]), (box[2], box[3]), color, 2) label_text f{label_name}: {score:.2f} cv2.putText(output_img, label_text, (box[0], box[1]-10), cv2.FONT_HERSHEY_SIMPLEX, 0.5, color, 2) return output_img # 4. 创建Gradio界面 demo gr.Interface( fndetect_mask, # 关联处理函数 inputsgr.Image(label上传图片, typenumpy), # 输入组件 outputsgr.Image(label检测结果), # 输出组件 title实时口罩检测-通用, description上传一张包含人脸的图片模型将检测是否佩戴口罩。绿色框表示已佩戴红色框表示未佩戴。, examples[[example_mask.jpg], [example_no_mask.jpg]] # 示例图片 ) # 5. 启动服务当直接运行此脚本时 if __name__ __main__: demo.launch(server_name0.0.0.0, server_port7860) # 允许外部访问2.2 依赖文件 (requirements.txt)这个文件列出了项目运行所需的所有Python库是自动化构建的关键。modelscope1.11.0 gradio4.0.0 opencv-python-headless4.8.0 numpy1.21.02.3 测试文件 (test_app.py)简单的单元测试用于验证核心功能是否正常这是CI流程中保证质量的重要一环。import pytest import numpy as np from app import detect_mask import cv2 def test_detect_mask_function_exists(): 测试检测函数是否存在且可调用 assert callable(detect_mask) def test_detect_mask_with_dummy_image(): 测试函数处理虚拟图片不崩溃即可 # 创建一个纯黑色的虚拟图片 dummy_image np.zeros((100, 100, 3), dtypenp.uint8) try: result detect_mask(dummy_image) # 确保返回的也是图片numpy数组 assert isinstance(result, np.ndarray) assert result.shape dummy_image.shape except Exception as e: pytest.fail(fdetect_mask function crashed with dummy image: {e})3. 构建GitHub Actions自动化CI/CD流水线现在进入最核心的部分编写GitHub Actions工作流配置文件。我们将创建一个.github/workflows/deploy.yml文件。3.1 工作流配置文件详解这个文件定义了自动化流水线的每一个步骤。name: Deploy Mask Detection App # 工作流名称 on: push: branches: [ main ] # 仅当代码推送到main分支时触发 pull_request: branches: [ main ] # 针对main分支的PR也会触发通常只运行CI测试 jobs: test-and-deploy: runs-on: ubuntu-latest # 在最新的Ubuntu系统环境中运行 steps: # 步骤1获取项目代码 - name: Checkout code uses: actions/checkoutv4 # 步骤2设置Python环境 - name: Set up Python uses: actions/setup-pythonv5 with: python-version: 3.9 # 指定Python版本 # 步骤3安装项目依赖 - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt # 步骤4运行单元测试CI部分 - name: Run tests run: | pip install pytest # 安装测试框架 pytest test_app.py -v # 运行测试并显示详细信息 # 步骤5部署到服务器CD部分 # 此步骤仅在推送到main分支而非PR且测试通过后执行 - name: Deploy to Server via SSH if: github.event_name push # 只在push事件时部署 uses: appleboy/ssh-actionv1.0.0 # 使用SSH连接服务器的Action with: host: ${{ secrets.SERVER_HOST }} # 服务器地址从GitHub Secrets读取 username: ${{ secrets.SERVER_USER }} # 服务器用户名 key: ${{ secrets.SSH_PRIVATE_KEY }} # SSH私钥 port: ${{ secrets.SERVER_PORT }} # SSH端口默认22 script: | # 1. 进入项目目录 cd /path/to/your/mask_detection_project # 2. 从GitHub拉取最新代码 git pull origin main # 3. 激活Python虚拟环境如果使用 # source venv/bin/activate # 4. 安装/更新依赖 pip install -r requirements.txt # 5. 重启应用服务 # 这里假设使用systemd管理进程服务名为mask-detection sudo systemctl restart mask-detection.service # 或者如果使用nohup/pm2等替换为相应的重启命令 # pkill -f python app.py # nohup python app.py app.log 21 echo Deployment completed successfully!3.2 关键配置与安全实践触发条件 (on): 我们设置为push到main分支时触发完整流程测试部署针对main的pull_request只触发测试确保合并前的代码质量。GitHub Secrets: 注意${{ secrets.XXX }}的用法。绝对不要将服务器密码、私钥等敏感信息直接写在代码里。你需要到GitHub仓库的Settings - Secrets and variables - Actions页面添加以下SecretsSERVER_HOST: 你的服务器IP或域名。SERVER_USER: 登录用户名如ubuntu。SSH_PRIVATE_KEY: 用于认证的SSH私钥内容对应服务器公钥已加入authorized_keys。SERVER_PORT: SSH端口可选默认22。服务器端准备确保服务器上已经克隆了你的Git仓库。安装了Python和项目依赖。设置了服务自启动如使用systemd、supervisor或pm2。工作流脚本中的systemctl restart命令就是基于这种假设。4. 本地开发与调试建议在将一切交给自动化之前良好的本地开发习惯能让你事半功倍。4.1 搭建本地开发环境创建虚拟环境隔离项目依赖避免冲突。python -m venv venv source venv/bin/activate # Linux/Mac # venv\Scripts\activate # Windows安装依赖pip install -r requirements.txt本地运行测试pytest test_app.py -v启动本地Gradio服务python app.py然后在浏览器中打开http://localhost:7860即可测试功能。4.2 模拟GitHub Actions环境你可以在本地使用act这个工具来运行GitHub Actions工作流提前发现配置问题。# 安装 act (需要Docker) # 参考https://github.com/nektos/act # 在项目根目录运行模拟push到main分支 act push -W .github/workflows/deploy.yml5. 总结通过本文的实践我们完成了一个从模型到自动化服务的完整闭环模型应用化我们利用ModelScope和Gradio将“实时口罩检测-通用”这个AI模型快速封装成了一个有界面的Web应用。流程自动化我们通过GitHub Actions构建了一套CI/CD流水线。现在每次你向main分支提交代码都会自动触发以下流程自动测试运行单元测试确保核心功能完好。自动部署通过SSH连接到远程服务器拉取最新代码更新依赖并重启服务。这套方案的最大优势在于“一劳永逸”。一旦配置完成后续所有的更新、优化、bug修复都只需要完成“提交代码”这一个动作剩下的繁琐工作全部由自动化流水线默默完成。这不仅极大提升了个人或小团队的开发效率也使得服务更加稳定和可靠。你可以将这套方法论轻松复用到其他基于ModelScope和Gradio的AI模型上快速构建属于你自己的自动化AI应用工厂。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。