XGBoost 项目中的自动化测试

本文档收集了使用 XGBoost 项目持续集成 (CI) 服务的技巧。

目录

GitHub Actions

配置文件位于目录 .github/workflows 下。

配置文件中列出的大多数测试对于每个传入的拉取请求和分支的每次更新都会自动运行。然而，少数测试需要手动激活：

  • 使用 noLD 选项的 R 测试：使用自定义构建的 R 运行 R 测试，编译标志为 --disable-long-double。有关 noLD 的更多详细信息，请参阅 此页面。这是保持 XGBoost 在 CRAN（R 包索引）上的要求。要为特定拉取请求调用此测试套件，只需添加一个审查评论 /gha run r-nold-test。（普通评论不起作用。它需要是一个审查评论。）

GitHub Actions 也被用于构建针对 MacOS Intel 和 Apple Silicon 的 Python 轮子。参见 .github/workflows/python_wheels.yml。python_wheels 流水线设置以 CIBW_* 为前缀的环境变量来指示目标操作系统和处理器。然后，流水线调用脚本 build_python_wheels.sh，该脚本反过来调用 cibuildwheel 来构建轮子。cibuildwheel 是一个库，它为每个操作系统和处理器目标设置合适的 Python 环境。由于我们在 GitHub Actions 中没有 Apple Silicon 机器，因此需要交叉编译；cibuildwheel 负责交叉编译 Python 轮子的复杂任务。（注意，cibuildwheel 将调用 pip wheel。由于 XGBoost 有一个本地库组件，我们创建了一个自定义的构建后端，该后端挂钩到 pip。自定义后端包含即时编译本地库的粘合代码。）

使用 Docker 容器重现 CI 测试环境

在我们的CI管道中，我们广泛使用Docker容器来打包许多软件包。您可以通过在本地运行Docker来重现与CI管道相同的测试环境。

先决条件

  1. 安装 Docker: https://docs.docker.com/engine/install/ubuntu/

  2. 安装 NVIDIA Docker 运行时: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#installing-on-ubuntu-and-debian 该运行时允许你在 Docker 容器内访问 NVIDIA GPU。

本地构建和运行 Docker 容器

为了方便您，我们提供了包装脚本 tests/ci_build/ci_build.sh。您可以如下使用它：

tests/ci_build/ci_build.sh <CONTAINER_TYPE> --use-gpus --build-arg <BUILD_ARG> \
  <COMMAND> ...

哪里：

  • <CONTAINER_TYPE> 是容器的标识符。包装脚本将使用位于 tests/ci_build/Dockerfile.<CONTAINER_TYPE> 的容器定义（Dockerfile）。例如，将容器类型设置为 gpu 将导致脚本加载 Dockerfile tests/ci_build/Dockerfile.gpu。

  • 指定 --use-gpus 以运行任何GPU代码。此标志将授予容器访问基础机器上所有NVIDIA GPU的权限。如果不需要访问GPU，则省略此标志。

  • <BUILD_ARG> 是一个传递给 Docker 的构建参数。必须为 VAR=VALUE 形式。例如：--build-arg CUDA_VERSION_ARG=11.0。你可以传递多个 --build-arg。

  • <COMMAND> 是在 Docker 容器内运行的命令。这可以包含多个参数。例如：tests/ci_build/build_via_cmake.sh -DUSE_CUDA=ON -DUSE_NCCL=ON。

可选地，您可以设置环境变量 CI_DOCKER_EXTRA_PARAMS_INIT 以传递额外的参数给 Docker。例如：

# Allocate extra space in /dev/shm to enable NCCL
export CI_DOCKER_EXTRA_PARAMS_INIT='--shm-size=4g'
# Run multi-GPU test suite
tests/ci_build/ci_build.sh gpu --use-gpus --build-arg CUDA_VERSION_ARG=11.0 \
  tests/ci_build/test_python.sh mgpu

要传递多个额外参数：

export CI_DOCKER_EXTRA_PARAMS_INIT='-e VAR1=VAL1 -e VAR2=VAL2 -e VAR3=VAL3'

更新 BuildKite CI 的管道定义

BuildKite 是一个 SaaS（软件即服务）平台，它协调云机器来托管 CI 管道。BuildKite 平台允许我们以声明性的 YAML 文件定义 CI 管道。

管道定义位于 tests/buildkite/ 中：

  • tests/buildkite/pipeline-win64.yml: 此流水线为 Windows 平台构建并测试 XGBoost。

  • tests/buildkite/pipeline-mgpu.yml: 此流水线构建并测试可访问多个 NVIDIA GPU 的 XGBoost。

  • tests/buildkite/pipeline.yml: 此流水线使用单个 NVIDIA GPU 构建并测试 XGBoost。大多数测试位于此处。

使用 BuildKite 管理弹性 CI 栈

BuildKite 允许我们以声明式的方式定义云资源。每个配置步骤现在都明确地作为代码文档化。

前提条件：你应该对 CloudFormation 有一定的了解。CloudFormation 允许我们使用一个 YAML 文件定义一组云资源（如 EC2 机器、Lambda 函数、S3 等）。

前提条件：获取 XGBoost 项目的 AWS 账户访问权限 (admin@xgboost-ci.net)，然后设置凭证对以便在 AWS 上配置资源。参见 在您的 AWS 账户中创建 IAM 用户。

  • 选项 1. 授予您的 IAM 用户完全的管理员权限。这是最简单的选项。

  • 选项 2. 为您的 IAM 用户授予有限的权限集，以减少搞乱其他资源的可能性。为此，请使用脚本 tests/buildkite/infrastructure/service-user/create_service_user.py。

工作镜像管道

为工作机器构建镜像曾经是一件繁琐的事情：你需要配置一个EC2机器，通过SSH连接到它，并手动安装必要的软件包。这个过程不仅费力，而且容易出错。你可能会忘记安装某个软件包或更改系统配置。

不再需要手动操作。现在我们有了一个自动化的流水线，用于为工作机构建镜像。

  • 运行 tests/buildkite/infrastructure/worker-image-pipeline/create_worker_image_pipelines.py 以配置名为 buildkite-linux-amd64-gpu-worker 和 buildkite-windows-gpu-worker 的 CloudFormation 堆栈。它们分别是用于创建 Linux 和 Windows 工作者的 AMI（Amazon 机器映像）的管道。

  • 导航到 CloudFormation 网页控制台，以验证镜像构建管道是否已配置。这可能需要一些时间。

  • 一旦管道完全配置好，运行脚本 tests/buildkite/infrastructure/worker-image-pipeline/run_pipelines.py 来执行管道。新的 AMI 将被上传到 EC2 服务。你可以在 EC2 控制台中找到它们。

  • 确保修改 tests/buildkite/infrastructure/aws-stack-creator/metadata.py 以使用正确的 AMI ID。（对于 linux-amd64-cpu 和 linux-arm64-cpu，使用 BuildKite 提供的 AMI。请参考 https://s3.amazonaws.com/buildkite-aws-stack/latest/aws-stack.yml 中的 AWSRegion2AMI 部分。）

EC2 自动扩展组

在EC2中，您可以创建自动扩展组，根据工作负载动态调整工作实例的数量。当提交拉取请求时，将执行以下步骤：

  1. GitHub 向已注册的 webhook 发送信号，该 webhook 连接到 BuildKite 服务器。

  2. BuildKite 向名为 Autoscaling 的 Lambda 函数发送一个信号。

  3. Lambda 函数向自动扩展组发送信号。该组扩展并添加额外的 worker 实例。

  4. 新的工作实例运行测试任务。测试结果会报告回 BuildKite。

  5. 当测试作业完成时，BuildKite 向 Autoscaling 发送一个信号，后者随后请求自动扩展组进行缩减。空闲的工作实例将被关闭。

要设置自动扩展组，请运行脚本 tests/buildkite/infrastructure/aws-stack-creator/create_stack.py。检查 CloudFormation 网页控制台以验证自动扩展组的配置是否成功。