开发基础设施

概述

Transformers 库使用全面的开发基础架构来确保代码质量、跨框架兼容性以及所有组件的正常运行。该基础架构包括：

构建系统：包配置、依赖管理和发布流程
测试框架：测试结构、实用工具和执行
持续集成：在各种环境上自动运行测试
Docker 镜像：用于测试和开发的容器化环境

下图说明了开发基础架构的总体概览：

来源

构建系统

构建系统负责依赖管理、包配置和发布准备。

依赖管理

依赖项在 setup.py 中进行管理，其中定义了基础依赖项和针对不同用例的可选附加项。

依赖项系统旨在允许灵活的安装配置，同时保持跨框架的兼容性。setup.py 中的 _deps 列表定义了所有带有版本约束的依赖项，然后这些依赖项会被处理成依赖项表。

来源

依赖项表使用以下工具自动更新：

make deps_table_update

来源

包配置

包配置在 setup.py 和 pyproject.toml 中均有定义。

setup.py：包元数据、依赖项、入口点
pyproject.toml：开发工具（ruff、pytest）的配置

来源

发布流程

发布流程由 Makefile 目标管理，并在 setup.py 中进行文档化。

# Pre-release steps
make pre-release  # For major/minor releases
make pre-patch    # For patch releases

# Post-release steps
make post-release # For major/minor releases
make post-patch   # For patch releases

# Build distribution
make build-release

来源

测试框架

测试框架由按组件类型组织的测试、用于识别相关测试的测试获取器系统以及用于运行测试的实用工具组成。

测试组织

测试按不同目录组织：

目录	描述
`tests/models/`	特定模型的测试
`tests/pipelines/`	管道测试
`tests/tokenization/`	分词器测试
`tests/extended/`	扩展测试（例如，deepspeed）
`tests/utils/`	实用工具测试
`examples/`	示例用法测试

来源

测试获取器

测试获取器系统（utils/tests_fetcher.py）根据代码更改来识别要运行的测试。这是实现高效 CI 的关键组件，因为它只运行受更改影响的测试。

测试获取器的工作原理如下：

识别分支或提交之间的修改文件
从 Python 模块中提取导入依赖项
构建反向依赖图以查找受影响的模块
根据依赖树推断需要运行哪些测试
根据重要性过滤测试（核心模型始终进行测试）

来源

测试配置

测试配置在 conftest.py 和 pyproject.toml 中进行管理。

来源

在本地运行测试

可以使用以下命令在本地运行测试：

来源

Makefile89-96

持续集成

Transformers 库使用多种 CI 系统来确保在不同环境下的全面测试。

CI 系统

使用的主要 CI 系统有：

GitHub Actions：用于 GPU 测试、Docker 镜像构建的自托管运行器
CircleCI：并行运行测试、管理测试工件

来源

GitHub Actions 工作流

主要的 GitHub Actions 工作流有：

工作流	目的
`self-push.yml`	推送至 main 分支时运行测试
`self-scheduled.yml`	运行计划测试（夜间）
`self-scheduled-amd-mi250-caller.yml`	运行 AMD GPU 测试
`doctests.yml`	运行文档测试
`slack-report.yml`	发送测试报告到 Slack
`check_failed_tests.yml`	处理和报告失败的测试

自托管运行器配置为使用特定的 GPU 资源。

来源

CircleCI 配置

CircleCI 配置处理：

测试获取，以确定要运行的测试
并行运行测试
收集和报告测试结果

CircleCI 管道是根据 PR 或提交中的更改文件动态生成的。create_circleci_config.py 脚本根据 tests_fetcher.py 的输出创建具有特定测试作业的配置。

来源

测试报告

测试结果通过多种方式报告：

测试工件上传到 GitHub Actions/CircleCI
Slack 通知和测试摘要
存储在 Hugging Face Hub 数据集上的报告，用于与未来运行进行比较

通知系统处理测试结果以：

识别与先前运行相比的新失败
按模型/组件分组失败
跟踪失败是出现在单 GPU 还是多 GPU 设置上
通知相关团队成员其代码中的失败
存储完整的调试报告

来源

Docker 镜像

Docker 镜像应用程序是开发基础设施的关键部分，为测试和开发提供了一致的环境。

镜像变体

主要的 Docker 镜像变体包括

图片	目的	应用场景
`transformers-all-latest-gpu`	所有支持 GPU 的框架	模型测试、示例
`transformers-pytorch-gpu`	支持 GPU 的 PyTorch 特定版本	PyTorch 管道测试
`transformers-tensorflow-gpu`	支持 GPU 的 TensorFlow 特定版本	TensorFlow 管道测试
`transformers-pytorch-deepspeed-latest-gpu`	支持 DeepSpeed 的 PyTorch	DeepSpeed/FSDP 测试
`transformers-quantization-latest-gpu`	量化库	量化测试
`transformers-pytorch-amd-gpu`	适用于 AMD GPU 的 PyTorch	AMD GPU 测试
`transformers-consistency`	代码质量工具	存储库一致性检查

Docker 镜像旨在为不同的测试场景提供具有特定依赖项的隔离环境。每个镜像都包含其特定用途所需的框架和库。

来源

Docker 镜像构建

Docker 镜像在几种情况下进行构建和推送

每日计划构建
在推送特定分支时（例如，build_ci_docker_image*）
在运行特定 CI 工作流之前

来源

CI 中使用 Docker 镜像

Docker 镜像用于 CI 工作流以提供一致的环境。自托管的运行器配置了特定的硬件资源，Docker 容器被配置为访问这些资源。

CI 系统为不同的测试场景使用不同的机器类型

机器类型	GPU 配置	用于
`aws-g4dn-4xlarge-cache`	单个 GPU	单 GPU 测试
`aws-g4dn-12xlarge-cache`	多个 GPU	多 GPU 测试
AMD MI210/MI250	AMD GPU	AMD 特定测试

挂载卷（-v /mnt/cache/.cache/huggingface:/mnt/cache/）为模型权重和其他工件提供了持久缓存，跨 CI 运行，显著提高了性能。

来源

开发工具

存储库包含各种用于辅助开发的工具

代码质量检查

代码质量通过以下方式维护

ruff 进行 linting 和格式化（取代了之前使用的 black 和 isort）
存储库一致性的自定义检查

Makefile 提供了几个代码质量目标

来源

存储库一致性检查

多项检查可确保存储库一致性

这会运行多项检查

副本一致性（确保重复代码同步）
模块化转换检查
虚拟模型检查
初始化文件一致性
配置 docstrings 和属性
文档测试列表维护

存储库包含每个检查的专用工具

实用工具	目的
`check_copies.py`	确保重复代码同步
`check_modular_conversion.py`	检查模块化转换函数
`check_dummies.py`	验证虚拟模型实现
`check_repo.py`	通用存储库结构检查
`check_inits.py`	验证初始化文件
`check_config_docstrings.py`	检查配置 docstrings
`check_config_attributes.py`	验证配置属性
`check_doctest_list.py`	维护文档测试列表
`update_metadata.py`	更新模型元数据

来源

与外部服务集成

开发基础架构集成了各种外部服务

Hugging Face Hub

与 Hugging Face Hub 集成，用于

在测试期间下载模型和数据集
报告和存储 CI 结果
缓存模型权重以提高 CI 性能
跟踪测试失败随时间的变化

CI 系统使用一个令牌（HF_HUB_READ_TOKEN）来访问受限存储库，以及一个单独的令牌（TRANSFORMERS_CI_RESULTS_UPLOAD_TOKEN）来将测试结果上传到专用数据集存储库。

来源

Slack 通知

全面的 Slack 通知，用于

测试结果及失败摘要
与之前运行相比的新测试失败
识别哪些作者的代码引入了失败
每日不同组件的测试报告

通知系统根据被测组件将报告发送到指定的 Slack 频道

渠道	目的
`#transformers-ci-daily-models`	模型测试结果
`#transformers-ci-daily-pipeline-torch`	PyTorch 管道测试结果
`#transformers-ci-daily-pipeline-tf`	TensorFlow 管道测试结果
`#transformers-ci-daily-training`	Trainer/FSDP/DeepSpeed 测试结果
`#transformers-ci-daily-quantization`	量化测试结果
`#transformers-ci-daily-amd`	AMD GPU 测试结果
`#transformers-ci-daily-docs`	文档测试结果

来源

结论

Transformers 库的开发基础架构旨在支持具有多个框架集成的庞大而复杂的代码库。它确保了代码质量、全面的测试和高效的开发工作流程。

基础架构将不断发展，以满足不断增长的库和社区的需求。