Ultralytics YOLO27：

CI/测试工作流 🧪#

持续集成 (CI) 对于通过及早发现问题来维护高质量代码至关重要。本指南介绍 Ultralytics 项目的 CI 测试和质量检查。

CI 操作 🔄#

所有 PR 在合并前都必须通过自动化 CI 检查。我们的 CI 流水线包括：

CI 测试#

主要的 CI 测试，运行单元测试、代码检查和综合测试。

Docker 部署#

使用 Docker 验证部署，确保 Dockerfile 和相关脚本正常运行。

失效链接#

扫描代码库，在 Markdown 和 HTML 文件中查找失效或无效链接。

CodeQL 分析#

GitHub 用于发现潜在安全漏洞并维护代码质量的语义分析工具。

PyPI 发布#

验证项目能否无错误地打包并发布到 PyPI。

平台测试 🖥️#

测试在多个环境中运行：

  • 操作系统：Ubuntu、Windows、macOS
  • Python：主矩阵使用 3.13，外加 3.8-3.12 的兼容性作业

代码覆盖率 📊#

我们使用 Codecov 来测量和可视化代码覆盖率，了解测试对代码库的覆盖程度。

覆盖率集成#

Codecov 集成提供：

  • 详细的覆盖率分析
  • 提交之间的覆盖率比较
  • 在代码上以可视化叠加层显示已覆盖的代码行
  • ultralytics 软件包的覆盖率百分比

在 codecov.io/github/ultralytics/ultralytics 查看完整的覆盖率详情。

理解覆盖率#

代码覆盖率表示测试期间执行的代码占全部代码的百分比。较高的覆盖率表明代码经过充分测试，但不能保证不存在错误。覆盖率有助于识别可能容易出错但尚未经过测试的区域。

在本地运行测试 🖥️#

安装开发依赖#

pip install -e ".[dev]"

运行所有测试#

pytest tests/

运行特定测试#

# Single file
pytest tests/test_engine.py

# Single test function
pytest tests/test_engine.py::test_export

# Tests matching pattern
pytest -k "export"

# Slow tests only
pytest --slow -m slow

运行覆盖率测试#

pytest --cov=ultralytics tests/

并行测试#

# Install pytest-xdist
pip install pytest-xdist

# Run tests in parallel
pytest -n auto

编写测试 ✍️#

测试结构#

from pathlib import Path

from ultralytics import YOLO

def test_model_export():
    """Test ONNX model export."""
    model = YOLO("yolo26n.pt")
    model.export(format="onnx")
    assert Path("yolo26n.onnx").exists()

最佳实践#

  • 描述性名称：使用 test_export_onnx_format()，而不是 test_1()
  • 单一断言：每个函数只测试一项内容
  • 快速测试：使用小型模型/数据集
  • 测试固件：使用 pytest 测试固件进行设置/清理
  • 标记：对长时间运行的测试使用 @pytest.mark.slow

测试组织#

查看上游tests directory以了解当前的测试组织方式。

测试标记#

import pytest

@pytest.mark.slow
def test_full_training():
    """Test full training run (slow)."""
    model = YOLO("yolo26n.pt")
    model.train(data="coco128.yaml", epochs=1)

代码质量检查 🎯#

使用 Ruff 进行格式化#

# Check formatting
ruff check ultralytics/

# Auto-fix issues
ruff check --fix ultralytics/

# Format code
ruff format ultralytics/

在我们的开发工作流中了解更多代码规范。

类型检查#

# Run mypy (where configured)
mypy ultralytics/

文档字符串格式化#

pip install ultralytics-actions
# Auto-fix
ultralytics-actions-format-python-docstrings .

CI 故障排除 🔧#

测试在本地通过，但在 CI 中失败#

常见原因：

  • 平台特定问题：在目标操作系统上测试
  • Python 版本差异：检查版本兼容性
  • 缺少依赖：检查 CI 配置
  • 时序/并发问题：添加重试或延长超时时间

CI 运行缓慢#

解决方案：

  • 对耗时测试使用 @pytest.mark.slow
  • 模拟外部依赖
  • 减小测试数据集规模
  • 使用 pytest-xdist 实现并行化

不稳定测试#

修复方法：

  • 为依赖网络的测试添加重试
  • 为缓慢操作延长超时时间
  • 修复异步代码中的竞态条件
  • 使用确定性的随机种子

性能基准 📈#

CI 跟踪关键指标：

  • 推理速度 (FPS)
  • 内存使用量
  • 模型大小
  • 导出时间

显著的性能回归会阻止合并。如果指标发生变化：

  1. 确认变更符合预期
  2. 在 PR 中说明原因
  3. 获得维护者批准

CI 状态 📋#

在 docs.ultralytics.com/help/CI 查看所有 Ultralytics 代码库的 CI 状态。

主代码库徽章#

CI Docker 链接 PyPI codecov

跳过 CI 检查 ⚠️#

在提交消息中添加 [skip ci] 以跳过 CI（请谨慎使用）：

git commit -m "Update README [skip ci]"

仅适用于：

  • 仅涉及文档的变更
  • 非代码文件更新
  • 紧急热修复（需获得批准）

资源 📚#

贡献者
GLglenn-jocher6LAlaodouya1PDpderrenger1FCfcakyon1BOBorda1