在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

huggingface/transformers

菜单

测试框架

相关源文件

本文档描述了Hugging Face Transformers库中使用的测试基础设施。它涵盖了测试组织、CI/CD管道、测试执行环境和报告机制。有关模型特定测试的编写信息，请参阅模型开发指南；有关文档测试的信息，请参阅文档贡献指南。

概述

Transformers库拥有一个全面的测试框架，用于确保代码质量并防止回归。该框架围绕在持续集成（CI）环境中运行的自动化测试构建，主要使用GitHub Actions和自托管运行器进行GPU测试。

来源

测试组织

Transformers库中的测试按模型架构和功能区域进行组织

  1. 模型测试: 位于 tests/models/，按模型架构组织（例如，tests/models/bert/，tests/models/gpt2/）
  2. 功能测试: 位于 tests/ 目录的根目录下，涵盖跨模型功能
  3. 特殊测试类别:
    • tests/pipelines/: 对流水线功能的测试
    • tests/trainer/: 对训练功能的测试
    • tests/quantization/: 对模型量化的测试
    • tests/extended/: 对扩展功能（如deepspeed集成）的测试

来源

CI/CD 流水线

CI/CD管道主要通过GitHub Actions工作流进行编排，使用GitHub托管的运行器和自托管的GPU运行器。

工作流类型

  1. 定时CI: 每天对主分支进行检查

    • 定义于 .github/workflows/self-scheduled.yml 并由 .github/workflows/self-scheduled-caller.yml 触发
    • 在NVIDIA GPU上运行全面的模型和功能测试
    • AMD GPU变体定义于 .github/workflows/self-scheduled-amd-mi250-caller.yml

  2. 推送CI: 当代码被推送到特定分支时触发

    • 定义于 .github/workflows/self-push.yml 并由 .github/workflows/self-push-caller.yml 触发
    • 使用测试选择算法，仅运行与更改文件相关的测试
    • AMD GPU变体定义于 .github/workflows/self-push-amd.yml

  3. 文档测试: 验证文档示例是否正常工作

    • 定义于 .github/workflows/doctests.yml
    • 定期运行以确保文档准确性

  4. 特殊情况CI: 针对特定模型或功能

    • 示例: .github/workflows/push-important-models.yml 用于测试关键模型
    • 包括使用 utils/check_copies.py 进行代码一致性检查

来源

Docker 容器

CI系统使用Docker容器提供隔离、可复现的测试环境。针对不同的测试场景使用不同的容器

  1. 通用: huggingface/transformers-all-latest-gpu
  2. PyTorch专用: huggingface/transformers-pytorch-gpu
  3. TensorFlow专用: huggingface/transformers-tensorflow-gpu
  4. DeepSpeed和CUDA扩展测试: huggingface/transformers-pytorch-deepspeed-latest-gpu
  5. 量化: huggingface/transformers-quantization-latest-gpu
  6. 推送CI: huggingface/transformers-all-latest-gpu-push-ci
  7. AMD GPU: huggingface/transformers-pytorch-amd-gpu 和 huggingface/transformers-pytorch-amd-gpu-push-ci

这些容器在工作流文件中被引用，并独立构建和维护。每个容器都包含其特定测试场景所需的依赖项。

来源

测试执行

测试分发

为了高效执行，测试被分发到多个运行器上

  1. 模型测试: 使用 utils/split_model_tests.py 分割成子集
  2. 矩阵策略: 使用GitHub Actions的矩阵策略并行运行测试切片
  3. GPU配置: 测试在单GPU（aws-g4dn-4xlarge-cache）和多GPU（aws-g4dn-12xlarge-cache）机器上运行
  4. AMD GPU配置: 测试也在AMD MI210/MI250 GPU上运行，以实现硬件多样性

来源

运行测试

测试使用pytest执行，并采用特定配置

  1. 环境变量:

    • TRANSFORMERS_IS_CI: 表示测试正在CI中运行
    • HF_HOME: 下载模型的缓存目录
    • RUN_SLOW: 启用慢速测试
    • CUDA_VISIBLE_DEVICES: 控制GPU可见性

  2. Pytest命令:

  3. 测试报告: 生成于 reports/ 目录中，并采用特定命名约定

来源

测试报告

一个复杂的报告系统收集测试结果并提供测试失败通知

结果收集

  1. 构件上传: 测试结果作为GitHub Actions构件上传
  2. 分类: 故障按模型/组件和环境（单GPU与多GPU）进行分类
  3. 构件存储: 完整的报告被存储以供进一步分析

来源

Slack通知和报告

测试结果以详细的消息格式报告到Slack频道，并存储在HuggingFace Hub中以供历史分析

  1. 通知服务: 实现在 utils/notification_service.py 中

  2. 消息格式:

    • 测试结果摘要（通过/失败/总计）
    • 按模型和功能分类的故障
    • 详细GitHub Actions日志链接
    • 与先前运行相比发现的新故障
    • 从测试运行中收集的警告

  3. 频道: 不同测试类型的不同Slack频道

    • 模型测试: #transformers-ci-daily-models
    • 流水线测试: #transformers-ci-daily-pipeline-torch 和 #transformers-ci-daily-pipeline-tf
    • 训练测试: #transformers-ci-daily-training
    • 量化测试: #transformers-ci-daily-quantization
    • AMD GPU测试: #transformers-ci-daily-amd
    • 文档测试: #transformers-ci-daily-docs

  4. HuggingFace Hub存储:

    • 完整的测试结果上传到Hub数据集
    • 故障分析和历史比较
    • 识别不良提交以进行回归跟踪

来源

测试实现细节

推送事件的测试选择

当代码被推送时，仅执行相关测试以优化CI资源

  1. 测试获取器: utils/tests_fetcher.py 识别哪些文件已更改
  2. 测试映射: 根据更改创建应运行的测试映射
  3. 矩阵生成: 为GitHub Actions动态创建测试矩阵
  4. 分支处理: 对CI特定分支（例如，ci_*, ci-*）进行特殊处理

来源

特殊测试类别

模型测试

  • 按模型架构组织（tests/models/{model_name}/）
  • 包括建模测试、分词测试和集成测试
  • 分发到多个运行器上进行并行执行

文档测试

  • 验证文档示例是否正常工作
  • 使用 doctests.yml 工作流运行
  • 报告到专用Slack频道

CUDA扩展测试

  • 测试deepspeed集成和其他CUDA扩展
  • 使用具有特定CUDA配置的专用Docker镜像
  • 在单GPU和多GPU环境中运行

来源

测试工具

多个实用脚本支持测试框架

  1. 分割模型测试: utils/split_model_tests.py 将测试分割成可管理的块
  2. 通知服务: utils/notification_service.py 格式化并发送测试报告
  3. 检查自托管运行器: utils/check_self_hosted_runner.py 验证运行器可用性
  4. 提取警告: utils/extract_warnings.py 从测试运行中收集警告
  5. 先前CI结果: utils/get_previous_daily_ci.py 检索先前运行的结果
  6. 不良提交识别: utils/check_bad_commit.py 识别引入故障的提交

一致性检查

其他实用程序确保仓库一致性

  1. 检查复制: utils/check_copies.py 验证复制的代码是否保持同步

    • 跟踪带有 # Copied from 评论标记的代码块
    • 确保README模型列表在不同语言间保持一致
    • 保持完整文件副本同步

  2. 检查导入: utils/check_inits.py 确保导入结构正确定义

    • 验证模块导出是否正确
    • 检查循环导入

  3. 更新元数据: utils/update_metadata.py 保持模型元数据最新

    • 更新流水线标签和自动类映射
    • 维护框架兼容性信息
    • 与 transformers-metadata 仓库同步

来源

结论

Transformers测试框架通过自动化CI/CD管道、专业测试类别和详细报告的结合，提供了全面的测试覆盖。该系统旨在捕获回归错误并确保代码质量，同时通过Slack通知和构件存储向开发人员提供有用的反馈。

使用支持GPU的自托管运行器可以对性能关键型代码路径进行全面测试，而测试选择机制则通过仅在代码更改时运行相关测试来确保CI资源的有效利用。