llama.cpp 团队如何用 Hugging Face 解决 GitHub Actions 瓶颈
llama.cpp 项目每月处理数千个 PR,原有的 GitHub Actions CI 流程因缓存限制和并发不足变得缓慢。团队通过分离 PR 与主分支工作流、将编译器缓存迁移至 Hugging Face Buckets,并利用 Hugging Face Jobs 运行 Linux x64 任务,显著提升了构建效率并降
为什么 llama.cpp 的 CI 跑不动了
llama.cpp 可能是目前 GitHub 上增长最快、社区最活跃的开源项目之一。这种热度带来的直接后果是巨大的维护压力。仅以 2026 年 8 月到 10 月这三个月为例,项目收到了 3181 个 Pull Request(PR),平均每天约 35 个,其中合并了 1802 个。
为了保证代码质量,每个 PR 都需要经过严格的测试。完整的 CI(持续集成)流程包含 100 多个任务,涵盖多种硬件后端和运行时环境。这些任务大多涉及繁重的计算和模型数据操作,单个任务耗时可达 30 分钟。此外,每当有代码合并到 master 分支,团队还会触发预发布构建,让用户能尽快体验最新功能。这些预发布任务更加耗时,部分甚至需要运行数小时。
年初时,团队的 CI 基础设施主要依赖 GitHub Actions 的原生能力,但很快遇到了瓶颈:
- 缓存命中率低:团队使用
ccache存储编译后的对象文件,以加速后续构建。这些数据原本存储在 GitHub Actions Cache 中。然而,GitHub 为免费公共仓库提供的缓存上限仅为 10GB。一旦填满,系统会自动删除最近最少使用的条目。这意味着许多任务不得不重新编译本可以复用的文件。 - 编译开销大:CUDA 后端大量使用 C++ 模板,针对 CUDA、HIP 和 MUSA 等不同后端及多种硬件架构进行构建时,如果没有缓存,编译时间极长。
- 并发资源不足:
ggml-org组织使用的是 GitHub 免费计划,全组织仅限 20 个并发作业(其中 macOS 作业最多 5 个)。面对每次超过 100 个任务的完整 CI 运行,大量任务只能排队等待空闲的运行器(Runner)。
优化策略:三步走
面对这些问题,团队没有选择盲目升级付费套餐,而是对工作流程进行了结构性调整。核心思路分为三点:分离 PR 与主分支的工作流、将编译器缓存迁移至 Hugging Face Buckets、以及利用 Hugging Face Jobs 承载大部分 Linux x64 任务。
1. 分离 PR 和 master 工作流
首先,团队减少了每个 PR 需要执行的任务量。以前,每个 PR 可能都会触发全套测试。现在,系统会根据代码差异(diff)智能选择必要的测试任务。只有当代码推送到 master 分支时,才会执行那套包含 100+ 任务的完整 CI 流程。这一改动直接减轻了日常开发中的等待时间。
2. 将编译器缓存移至 Hugging Face Buckets
虽然团队之前已经限制了缓存保存策略(仅在推送到 master 时保存,且每个任务只保留一个缓存条目),但总存储需求依然超过了 GitHub Actions 的 10GB 限额。
解决方案是将非发布构建的 ccache 数据迁移到 Hugging Face Buckets。这是一个类似 S3 的对象存储服务,底层由 Xet 技术支持,具备上传/下载层面的去重功能,因此在速度和成本上都更具优势。
具体工作流程如下:
- 写入缓存:当
master分支上的 eligible build(符合条件的构建)完成后,运行器会将最新的编译器缓存快照上传到 Hugging Face Bucket。 - 读取缓存:每个 PR 构建在开始编译前,会从 Bucket 下载对应的缓存快照。如果源文件和构建设置匹配,
ccache就能直接复用现有的对象文件,避免重复编译。 - 共享与清理:Bucket 充当了所有运行器的共享存储中心。新启动的运行器无需依赖前一个运行器的磁盘状态,直接拉取最新缓存即可。团队会保留每个构建键(build key)的最新缓存,并定期清理旧归档。
这一改动不仅解决了存储空间不足的问题,还让 GitHub Actions Cache 腾出了更多空间用于关键的发布构建。详细的迁移过程可以参考 PR #27699。
3. 使用 Hugging Face Jobs 运行 Linux x64 任务
解决了缓存问题后,团队接着处理并发资源瓶颈。他们将部分原本在自托管运行器上运行的任务,以及大量原本在 GitHub 托管运行器上运行的 Linux x64 任务,迁移到了 Hugging Face Jobs。
Hugging Face Jobs 提供按需计费的云 CPU 或 GPU 实例。团队通过 jobs-actions 工具将这些任务无缝集成到现有的 CI 工作流中。由于 Bucket 存储已经解决了缓存共享问题,新的运行器可以随时启动并获取所需数据,不再依赖持久化存储。
技术实现:jobs-actions 如何工作
jobs-actions 并不是要取代 GitHub Actions 作为主要的工作流编排器,而是作为一个轻量级的调度器和桥梁。它允许标准的 GitHub Actions 工作流步骤指向 Hugging Face 上的自定义计算环境(如 hf-jobs-cpu-upgrade 或 hf-jobs-t4-small)。
整个流程是这样的:
- 触发:PR 触发 GitHub Actions 工作流。
- 排队:如果某个任务的
runs-on标签指向 Hugging Face(例如hf-jobs-cpu-upgrade),GitHub 会将其排队,并通过 GitHub App 向调度器发送签名的 Webhook 事件。 - 调度:托管在 Hugging Face 上的 Dispatcher Space 收到 Webhook,验证权限,检查标签,并向 GitHub API 请求一个短期的运行器注册令牌。
- 启动:Dispatcher 根据硬件配置动态启动一个临时的 Hugging Face Job。该 Job 启动一个 ephemeral(临时)GitHub Actions 运行器,并使用一次性令牌注册到仓库。
- 执行与反馈:GitHub 将 pending 的任务分配给这个运行器。运行器执行 CI 步骤,并将状态、日志和输出实时流式传回 GitHub Actions 界面。
对开发者而言,这一切都是透明的。他们依然在 GitHub 的 PR 页面查看日志和状态,无需切换到其他控制台。这种架构既保留了 GitHub Actions 熟悉的用户体验,又利用了 Hugging Face 更灵活、更具性价比的计算资源。
总结
对于像 llama.cpp 这样规模的大型开源项目,传统的 CI 模式往往难以应对海量的构建需求。通过引入 Hugging Face Buckets 解决缓存存储瓶颈,并利用 Hugging Face Jobs 弹性扩展计算资源,团队成功在不牺牲开发体验的前提下,突破了 GitHub Actions 的限制。
这套方案的核心在于“解耦”:将存储与计算解耦,将任务调度与执行环境解耦。对于其他面临类似 CI/CD 瓶颈的团队来说,这种混合云架构提供了一个值得参考的思路。如果你想在自己的项目中尝试类似设置,可以查阅 Hugging Face 官方指南。