从零搭建你的Flash Attention轮子工厂flash-attention-prebuild-wheels自托管Runner部署实战指南【免费下载链接】flash-attention-prebuild-wheelsProvide with pre-build flash-attention 2 and 3 package wheels on Linux and Windows using GitHub Actions项目地址: https://gitcode.com/gh_mirrors/fl/flash-attention-prebuild-wheelsflash-attention-prebuild-wheels是一个专注提供 Flash Attention 2 / 3 预编译 wheel轮子包的开源项目覆盖 Linuxx86_64、ARM64、ROCm与 Windows 平台总计 1000 个预构建包覆盖率 100%。编译 Flash Attention 极其耗时且消耗资源而这个项目的核心秘诀之一就是用自托管 Runnerself-hosted runner搭建了一座轮子工厂。本文将带你从零部署这套自托管 Runner理解整座工厂的运转逻辑。为什么你需要一个轮子工厂编译 Flash Attention 是什么体验一句话等一直等。单次构建动辄数小时且对 CPU、内存、CUDA 环境都有苛刻要求。更麻烦的是Python 版本3.10~3.14含 free-threaded 构建PyTorch 版本2.5 ~ 2.14CUDA / ROCm 版本平台Linux x86_64 / ARM64 / Windows / AMD ROCm这些维度交叉组合后官方并不提供全部 wheel。而 flash-attention-prebuild-wheels 把这些官方没有的组合统统替你编译好直接给你可下载的.whl文件flash_attn-2.6.3cu124torch2.5-cp312-cp312-linux_x86_64.whl flash_attn-2.8.4rocm7.2torch2.14git4a948e9-cp312-cp312-linux_x86_64.whl文件名即身份铭牌fa版本 CUDA/ROCm版本 PyTorch版本 Python版本 平台一眼就能挑出你要的那个。项目发布以来的下载量呈爆发式增长完整包列表可查阅 doc/packages.md发布历程见 doc/release_history.md。工厂运转原理构建矩阵与流水线 整座工厂的大脑是一个构建矩阵生成器create_matrix.py定义所有构建组合FA 版本 × Python × PyTorch × CUDA输出 JSON 矩阵按平台分组例如linux_self_hosted、windows_self_hosted、linux_rocmbuild_linux.sh / build_windows.ps1真正执行单个组合的编译scripts/coverage_matrix.py全仓库的版本兼容性单一事实来源定义哪些组合不兼容并自动排除触发方式非常简洁推送一个v*.*.*格式的版本 tagCI 流水线随即创建 Release、生成矩阵、在多台 Runner 上并行编译最后自动更新 Release 文档与包列表。平台Runner 类型说明Linux x86_64GitHub 托管 / 自托管自托管使用ubuntu:24.04容器Linux ARM64GitHub 托管 / 自托管ARM 构建需 QEMU 模拟Linux x86_64 (ROCm)自托管AMD GPU 专用编译极耗时Windows x86_64GitHub 托管 / 自托管Windows 环境托管 Runner 的瓶颈自托管 Runner 登场关键问题来了GitHub 托管 Runner 对单个任务有时间上限约 6 小时而某些版本组合尤其是 ROCm、10 个 GPU 架构打包编译在 32 线程机器上也要跑 9 个小时以上。这类超重活只能交给自托管 Runner 完成。项目把 Runner 做成了即开即用的 Docker 配置位于 self-hosted-runner/ 目录包含两个服务服务说明架构runner原生架构 Runner内置 Docker-in-DockerDinD可跑容器化任务宿主机原生runner-arm通过 QEMU 模拟 ARM64用于直接执行的非容器任务arm64核心文件一览self-hosted-runner/Dockerfile基于ubuntu:24.04预装编译工具链、Docker、GitHub Actions Runnerself-hosted-runner/compose.yml定义两个 Runner 服务及其环境变量self-hosted-runner/entrypoint.sh启动 Docker 守护进程 → 注册 Runner → 启动执行self-hosted-runner/env.template环境变量模板Token Runner 标签自托管 Runner 部署5 步完成一键搭建第 1 步准备前置条件一台 Linux 服务器建议 16~32 核装好# Docker Docker Compose必需 # ARM64 模拟仅 runner-arm 需要 sudo apt install qemu-user-static第 2 步克隆仓库git clone https://gitcode.com/gh_mirrors/fl/flash-attention-prebuild-wheels cd flash-attention-prebuild-wheels/self-hosted-runner 实际编译自己的 wheel 时建议先 Fork 一份到自己的账号下。第 3 步创建并配置环境变量从模板创建环境文件cp env.template .env # 原生 Runner cp env.template .env.arm # ARM64 QEMU Runner可选编辑.env填入认证信息二选一PERSONAL_ACCESS_TOKEN优先级更高# 方式一GitHub Personal Access Token推荐 PERSONAL_ACCESS_TOKENyour-token # 方式二一次性 Runner 注册 Token REGISTRY_TOKENyour-registry-token # 可选自定义 Runner 标签逗号分隔 RUNNER_LABELSLinux,self-hosted一次性注册 Token 的获取方式参考 self-hosted-runner/README.md 中的gh api命令。第 4 步修改仓库地址Fork 场景必做如果你是 Fork 后自建工厂需要把 self-hosted-runner/compose.yml 中runner和runner-arm两个服务的REPOSITORY_URL改为你的 Fork 地址否则 Runner 会注册到别人的仓库上。第 5 步构建并启动# 原生 Runner docker compose build runner docker compose up -d runner # ARM64 QEMU Runner可选 docker compose build runner-arm docker compose up -d runner-arm启动后可在仓库的 Actions → Runners 页面看到绿色在线的 Runner。 它的工作方式很简单启动容器内 DockerDinD→ 用 Token 向仓库注册 → 轮询并执行分配到的编译任务。Runner 上线后一个 Wheel 的诞生之旅Runner 就绪后你只需两个动作就能产出 wheel编辑矩阵修改 create_matrix.py 中对应平台的矩阵如LINUX_SELF_HOSTED_MATRIX取消注释你想要的版本组合打 tag 触发git tag v1.0.0 git push --tags流水线随后自动完成并行编译 → 导入测试import flash_attn→ 上传 →auditwheel repair打包 manylinux 版本。值得一提的是流水线还内置了可断点续传构建缓存机制——编译超时后自动保存 ninja 构建缓存重跑任务时恢复缓存跳过已完成的编译单元大幅摊薄超重活的总耗时。产出的 wheel 可直接安装pip install flash_attn-2.6.3cu124torch2.5-cp312-cp312-linux_x86_64.whl常见问题与最佳实践Token 怎么选长期使用选 Personal Access Token一次性/临时 Runner 用 Registry Token 更安全用后失效。ARM64 为什么单独一个服务QEMU 模拟性能有限不适合 DinD 容器任务因此runner-arm只跑直接在 Runner 上执行的非容器任务且需安装qemu-user-static。安全提醒两个服务都使用privileged: trueDinD 所必需请部署在可信机器上Token 权限遵循最小化原则。编译失败怎么办某些版本组合本身不可构建上游不兼容流水线会给出明确日志也可用 scripts/tools/check_missing_packages.py 检查各平台覆盖缺口。想深入了解构建细节推荐阅读根目录的 CLAUDE.md项目架构全景与 doc/scripts.md脚本参考以及 FA3 补丁 patches/fa3/。总结flash-attention-prebuild-wheels 的价值在于把编译数小时的 Flash Attention 变成了pip install 一条命令。而它背后的自托管 Runner 方案——Docker 化、Compose 编排、双架构服务、矩阵驱动——是一套非常值得借鉴的 CI 基建模板。照着本文的 5 个步骤你也可以为自己的大编译项目搭建一座专属轮子工厂。资源路径自托管 Runner 部署文档self-hosted-runner/README.md完整 wheel 包列表doc/packages.md构建矩阵生成器create_matrix.py版本兼容性定义scripts/coverage_matrix.py项目架构说明CLAUDE.md【免费下载链接】flash-attention-prebuild-wheelsProvide with pre-build flash-attention 2 and 3 package wheels on Linux and Windows using GitHub Actions项目地址: https://gitcode.com/gh_mirrors/fl/flash-attention-prebuild-wheels创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/10 5:18:58 · 阅读 1.2k 从零搭建你的Flash Attention轮子工厂：flash-attention-prebuild-wheels自托管Runner部署实战指南
从零搭建你的Flash Attention轮子工厂flash-attention-prebuild-wheels自托管Runner部署实战指南【免费下载链接】flash-attention-prebuild-wheelsProvide with pre-build flash-attention 2 and 3 package wheels on Linux and Windows using GitHub Actions项目地址: https://gitcode.com/gh_mirrors/fl/flash-attention-prebuild-wheelsflash-attention-prebuild-wheels是一个专注提供 Flash Attention 2 / 3 预编译 wheel轮子包的开源项目覆盖 Linuxx86_64、ARM64、ROCm与 Windows 平台总计 1000 个预构建包覆盖率 100%。编译 Flash Attention 极其耗时且消耗资源而这个项目的核心秘诀之一就是用自托管 Runnerself-hosted runner搭建了一座轮子工厂。本文将带你从零部署这套自托管 Runner理解整座工厂的运转逻辑。为什么你需要一个轮子工厂编译 Flash Attention 是什么体验一句话等一直等。单次构建动辄数小时且对 CPU、内存、CUDA 环境都有苛刻要求。更麻烦的是Python 版本3.10~3.14含 free-threaded 构建PyTorch 版本2.5 ~ 2.14CUDA / ROCm 版本平台Linux x86_64 / ARM64 / Windows / AMD ROCm这些维度交叉组合后官方并不提供全部 wheel。而 flash-attention-prebuild-wheels 把这些官方没有的组合统统替你编译好直接给你可下载的.whl文件flash_attn-2.6.3cu124torch2.5-cp312-cp312-linux_x86_64.whl flash_attn-2.8.4rocm7.2torch2.14git4a948e9-cp312-cp312-linux_x86_64.whl文件名即身份铭牌fa版本 CUDA/ROCm版本 PyTorch版本 Python版本 平台一眼就能挑出你要的那个。项目发布以来的下载量呈爆发式增长完整包列表可查阅 doc/packages.md发布历程见 doc/release_history.md。工厂运转原理构建矩阵与流水线 整座工厂的大脑是一个构建矩阵生成器create_matrix.py定义所有构建组合FA 版本 × Python × PyTorch × CUDA输出 JSON 矩阵按平台分组例如linux_self_hosted、windows_self_hosted、linux_rocmbuild_linux.sh / build_windows.ps1真正执行单个组合的编译scripts/coverage_matrix.py全仓库的版本兼容性单一事实来源定义哪些组合不兼容并自动排除触发方式非常简洁推送一个v*.*.*格式的版本 tagCI 流水线随即创建 Release、生成矩阵、在多台 Runner 上并行编译最后自动更新 Release 文档与包列表。平台Runner 类型说明Linux x86_64GitHub 托管 / 自托管自托管使用ubuntu:24.04容器Linux ARM64GitHub 托管 / 自托管ARM 构建需 QEMU 模拟Linux x86_64 (ROCm)自托管AMD GPU 专用编译极耗时Windows x86_64GitHub 托管 / 自托管Windows 环境托管 Runner 的瓶颈自托管 Runner 登场关键问题来了GitHub 托管 Runner 对单个任务有时间上限约 6 小时而某些版本组合尤其是 ROCm、10 个 GPU 架构打包编译在 32 线程机器上也要跑 9 个小时以上。这类超重活只能交给自托管 Runner 完成。项目把 Runner 做成了即开即用的 Docker 配置位于 self-hosted-runner/ 目录包含两个服务服务说明架构runner原生架构 Runner内置 Docker-in-DockerDinD可跑容器化任务宿主机原生runner-arm通过 QEMU 模拟 ARM64用于直接执行的非容器任务arm64核心文件一览self-hosted-runner/Dockerfile基于ubuntu:24.04预装编译工具链、Docker、GitHub Actions Runnerself-hosted-runner/compose.yml定义两个 Runner 服务及其环境变量self-hosted-runner/entrypoint.sh启动 Docker 守护进程 → 注册 Runner → 启动执行self-hosted-runner/env.template环境变量模板Token Runner 标签自托管 Runner 部署5 步完成一键搭建第 1 步准备前置条件一台 Linux 服务器建议 16~32 核装好# Docker Docker Compose必需 # ARM64 模拟仅 runner-arm 需要 sudo apt install qemu-user-static第 2 步克隆仓库git clone https://gitcode.com/gh_mirrors/fl/flash-attention-prebuild-wheels cd flash-attention-prebuild-wheels/self-hosted-runner 实际编译自己的 wheel 时建议先 Fork 一份到自己的账号下。第 3 步创建并配置环境变量从模板创建环境文件cp env.template .env # 原生 Runner cp env.template .env.arm # ARM64 QEMU Runner可选编辑.env填入认证信息二选一PERSONAL_ACCESS_TOKEN优先级更高# 方式一GitHub Personal Access Token推荐 PERSONAL_ACCESS_TOKENyour-token # 方式二一次性 Runner 注册 Token REGISTRY_TOKENyour-registry-token # 可选自定义 Runner 标签逗号分隔 RUNNER_LABELSLinux,self-hosted一次性注册 Token 的获取方式参考 self-hosted-runner/README.md 中的gh api命令。第 4 步修改仓库地址Fork 场景必做如果你是 Fork 后自建工厂需要把 self-hosted-runner/compose.yml 中runner和runner-arm两个服务的REPOSITORY_URL改为你的 Fork 地址否则 Runner 会注册到别人的仓库上。第 5 步构建并启动# 原生 Runner docker compose build runner docker compose up -d runner # ARM64 QEMU Runner可选 docker compose build runner-arm docker compose up -d runner-arm启动后可在仓库的 Actions → Runners 页面看到绿色在线的 Runner。 它的工作方式很简单启动容器内 DockerDinD→ 用 Token 向仓库注册 → 轮询并执行分配到的编译任务。Runner 上线后一个 Wheel 的诞生之旅Runner 就绪后你只需两个动作就能产出 wheel编辑矩阵修改 create_matrix.py 中对应平台的矩阵如LINUX_SELF_HOSTED_MATRIX取消注释你想要的版本组合打 tag 触发git tag v1.0.0 git push --tags流水线随后自动完成并行编译 → 导入测试import flash_attn→ 上传 →auditwheel repair打包 manylinux 版本。值得一提的是流水线还内置了可断点续传构建缓存机制——编译超时后自动保存 ninja 构建缓存重跑任务时恢复缓存跳过已完成的编译单元大幅摊薄超重活的总耗时。产出的 wheel 可直接安装pip install flash_attn-2.6.3cu124torch2.5-cp312-cp312-linux_x86_64.whl常见问题与最佳实践Token 怎么选长期使用选 Personal Access Token一次性/临时 Runner 用 Registry Token 更安全用后失效。ARM64 为什么单独一个服务QEMU 模拟性能有限不适合 DinD 容器任务因此runner-arm只跑直接在 Runner 上执行的非容器任务且需安装qemu-user-static。安全提醒两个服务都使用privileged: trueDinD 所必需请部署在可信机器上Token 权限遵循最小化原则。编译失败怎么办某些版本组合本身不可构建上游不兼容流水线会给出明确日志也可用 scripts/tools/check_missing_packages.py 检查各平台覆盖缺口。想深入了解构建细节推荐阅读根目录的 CLAUDE.md项目架构全景与 doc/scripts.md脚本参考以及 FA3 补丁 patches/fa3/。总结flash-attention-prebuild-wheels 的价值在于把编译数小时的 Flash Attention 变成了pip install 一条命令。而它背后的自托管 Runner 方案——Docker 化、Compose 编排、双架构服务、矩阵驱动——是一套非常值得借鉴的 CI 基建模板。照着本文的 5 个步骤你也可以为自己的大编译项目搭建一座专属轮子工厂。资源路径自托管 Runner 部署文档self-hosted-runner/README.md完整 wheel 包列表doc/packages.md构建矩阵生成器create_matrix.py版本兼容性定义scripts/coverage_matrix.py项目架构说明CLAUDE.md【免费下载链接】flash-attention-prebuild-wheelsProvide with pre-build flash-attention 2 and 3 package wheels on Linux and Windows using GitHub Actions项目地址: https://gitcode.com/gh_mirrors/fl/flash-attention-prebuild-wheels创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考