GGML 同步

相关源文件

• ggml/cmake/GitVars.cmake
• ggml/cmake/ggml-config.cmake.in
• scripts/sync-ggml-am.sh
• scripts/sync-ggml.last
• scripts/sync-ggml.sh

本文档介绍了 llama.cpp 仓库与上游 GGML 库之间的同步过程，包括自动补丁管理、文件路径转换和集成工作流。此过程可确保 llama.cpp 及时获取 GGML 核心的改进，同时维护其自身的目录结构和定制化设置。

有关 GGML 张量库本身的信息，请参阅 GGML 张量库。有关构建系统配置，请参阅 构建系统。

同步概述

llama.cpp 仓库在 ggml/ 目录中维护着 GGML 库的副本，并定期与上游 GGML 仓库进行同步。此同步过程主要有两种方法：基于自动补丁的同步和手动文件复制。

同步系统通过存储在 scripts/sync-ggml.last 中的哈希值来跟踪最后同步的提交，并以补丁的形式应用新提交，同时转换文件路径以匹配 llama.cpp 的目录结构。

同步工作流

来源： scripts/sync-ggml-am.sh1-202 scripts/sync-ggml.sh1-36 scripts/sync-ggml.last1-2

自动同步脚本

主要的同步工具是 sync-ggml-am.sh，它提供了一种自动化的基于补丁的方法来保持 llama.cpp 与上游 GGML 更改的同步。

脚本用法与参数

脚本支持以下参数

• -skip: 在同步过程中要跳过的提交哈希列表，用逗号分隔
• -C: Git 补丁的上下文行数（默认为 8 行）

同步过程流程

来源： scripts/sync-ggml-am.sh24-49 scripts/sync-ggml-am.sh61-102 scripts/sync-ggml-am.sh191-198

文件路径转换

同步过程包含一个全面的文件路径转换系统，用于将上游 GGML 路径映射到 llama.cpp 的目录结构。

跟踪的文件和目录

同步过程处理以下文件类别

上游 GGML 路径	llama.cpp 路径	描述
CMakeLists.txt	ggml/CMakeLists.txt	主构建配置
src/CMakeLists.txt	ggml/src/CMakeLists.txt	源文件构建配置
cmake/*	ggml/cmake/*	CMake 模块和配置
src/ggml*.{c,cpp,h}	ggml/src/ggml*	核心 GGML 源文件
src/gguf*.cpp	ggml/src/gguf*	GGUF 格式实现
src/ggml-*/	ggml/src/ggml-*/	特定后端实现
include/ggml*.h	ggml/include/ggml*.h	公共头文件
tests/test-*.cpp	tests/test-*.cpp	测试文件

路径转换实现

脚本执行广泛的 sed 路径转换，以重新映射生成补丁中的文件路径

来源： scripts/sync-ggml-am.sh69-100 scripts/sync-ggml-am.sh160-189

手动同步替代方案

sync-ggml.sh 脚本提供了一种更简单的手动同步方法，通过直接从上游 GGML 仓库复制文件。

手动同步过程

此方法需要手动执行 Git 操作来提交同步的更改，并且不保留上游提交历史或消息。

来源： scripts/sync-ggml.sh3-35

提交跟踪和状态管理

最后提交跟踪

同步状态通过 scripts/sync-ggml.last 文件进行维护，该文件包含来自上游 GGML 仓库最后一次成功同步的提交的 SHA-1 哈希值。

提交过滤

自动同步脚本会过滤提交，以避免重新应用源自 llama.cpp 的更改

• 排除提交消息中带有 (llama/[0-9]*) 模式的提交
• 将 PR 引用从 (#1234) 转换为 (ggml/1234) 格式
• 维护上游更改的正确归属

来源： scripts/sync-ggml-am.sh49 scripts/sync-ggml-am.sh114-122 scripts/sync-ggml.last1

集成注意事项

构建系统集成

同步的 GGML 组件通过 CMake 配置文件与 llama.cpp 的构建系统集成，这些文件也从上游同步

• ggml/cmake/ggml-config.cmake.in: CMake 包配置模板
• ggml/cmake/GitVars.cmake: 用于构建元数据的 Git 信息提取
• ggml/cmake/common.cmake: 通用构建工具

后端同步

所有 GGML 后端实现都已同步，包括

• ggml-cpu: 具有 SIMD 优化的 CPU 后端
• ggml-cuda: NVIDIA CUDA 后端
• ggml-metal: Apple Metal 后端
• ggml-vulkan: Vulkan 计算后端
• ggml-sycl: Intel SYCL 后端
• 其他专用后端（HIP、MUSA、OpenCL、CANN）

测试同步

关键测试文件已同步，以确保后端兼容性

• test-backend-ops.cpp: 跨后端操作验证
• test-quantize-fns.cpp: 量化函数测试
• test-opt.cpp: 优化测试

来源： ggml/cmake/ggml-config.cmake.in1-153 ggml/cmake/GitVars.cmake1-23 scripts/sync-ggml-am.sh95-98