llamafile 补丁再生成指南用 generate_patches 从子模块原地修改导出规范补丁集【免费下载链接】llamafileDistribute and run LLMs with a single file.项目地址: https://gitcode.com/GitHub_Trending/ll/llamafile本文是 llamafile 开发流程中「补丁生产」环节的操作指南聚焦 tools/generate_patches.sh 这一官方补丁生成工具。读完本文你将掌握如何在 llama.cpp以及其他子模块上做原地修改后用一条命令导出规范化补丁、为什么不能手工git diff造补丁、生成前的验证门槛与生成后的干净回环验证以及补丁生命周期中「分流—调和—生成—验证」四个工具各自的分工。补丁在 llamafile 中的角色llamafile 的核心思路是「用单个文件分发和运行大模型」其能力建立在多个上游子模块之上——最主要的是 llama.cpp推理引擎此外还有 whisper.cpp、stable-diffusion.cpp、transcribe.cpp。这些子模块不能原样使用必须经过两层适配打补丁对上游源码做定向修改例如GGML_CALL调用约定、Cosmopolitan libc 兼容、TinyBLAS 集成、文件读取接口等补丁文件统一存放在各子模块对应的.patches/patches/目录例如 llama.cpp.patches/patches/新增文件上游没有、但构建必需的新文件如BUILD.mk、common/license.cpp存放在.patches/llamafile-files/例如 llama.cpp.patches/llamafile-files/。这套补丁集是 llamafile 与上游之间的「契约」Makefile 的setup目标make setup会先拉取子模块再通过 llama.cpp.patches/apply-patches.sh 把patches/里的补丁逐个patch -p1应用并把llamafile-files/里的新文件复制进子模块。因此补丁集的质量直接决定每一次构建与升级bump的成败而generate_patches.sh正是这套补丁集的唯一合法生产者。generate-patches 命令一条命令导出整个补丁集原文档docs/commands/generate-patches.md给出的一句话定位是捕获子模块当前的原地修改把它们固化为补丁文件。它对应仓库里的llamafile:generate-patches任务底层实现是 tools/generate_patches.sh。以最常见场景——修改了llama.cpp子模块——为例标准用法是( cd llama.cpp echo y | ../tools/generate_patches.sh --output-dir ../llama.cpp.patches )这条命令有四个细节值得拆解子 shell 包裹( ... )无论脚本中途成功还是失败工作目录都能恢复不会污染外层 shell 的当前路径echo y管道脚本执行前会弹出确认提示Proceed with patch generation? [y/N]见 tools/generate_patches.sh 第 52 行echo y让它非交互地自动确认便于在 CI 或脚本链中调用--output-dir指定补丁输出目录不带该参数时默认输出到当前目录下的./candidate_patches必须在子模块目录内运行脚本通过basename $(pwd)识别仓库名并校验当前目录确实是 git 工作树不是则报错退出见脚本第 40–46 行。该工具是通用的不只限于llama.cpp。对 whisper.cpp、stable-diffusion.cpp、transcribe.cpp 等任何子模块只需替换目录与输出路径即可例如( cd whisper.cpp echo y | ../tools/generate_patches.sh --output-dir ../whisper.cpp.patches ) ( cd stable-diffusion.cpp echo y | ../tools/generate_patches.sh --output-dir ../stable-diffusion.cpp.patches )为什么「手工 git diff」是禁区原文档明确警告绝不手工用git diff造补丁——补丁生产是generate-patches的唯一职责。原因在于脚本对 diff 输出做了四件事对应 tools/generate_patches.sh 第 109–125 行的处理逻辑重写a/、b/路径为仓库根相对路径用sed把--- a/path和 b/path改写为--- a/REPO_NAME/path形式REPO_NAME即当前子模块目录名如llama.cpp。这样生成的补丁在apply-patches.sh以仓库根为基准patch -p1应用时路径才能对齐剔除易变的index行用awk NR 2 {next}丢弃 diff 的第二行即index hash..hash mode行因为它是哈希快照升级子模块后必然失效保留只会让git apply --check之类的校验产生噪音按约定命名补丁文件文件名 源码相对路径中/替换为_再加上.patch后缀tr / _。例如common/arg.cpp的修改会导出为common_arg.cpp.patchggml/src/ggml-cuda/ggml-cuda.cu的修改导出为ggml_src_ggml-cuda_ggml-cuda.cu.patch——这正是 llama.cpp.patches/patches/ 里那批命名规整的补丁文件的由来也与 llama.cpp.patches/README.md「Creating New Patches」一节所述一致把新增/未跟踪文件路由到llamafile-files/脚本用git status -s区分「已跟踪但被修改的文件」前缀M/M和「新增/未跟踪文件」前缀??/A。前者走 diff 流程生成.patch后者则整体复制到output-dir/llamafile-files/保留原目录结构见脚本第 155–161 行的mkdir -pcp。手工git diff在这四个方面全部会出错路径不是 repo-rooted、index行残留、文件名不按约定、新增文件例如BUILD.mk根本不会被带出。这正是原文档强调「rawgit diffgets all of that wrong」的底层原因。输出结构patches/ 与 llamafile-files/ 各司其职运行成功后输出目录被组织为两个子目录脚本第 66–68 行创建llama.cpp.patches/ ├── patches/ # 被修改文件 → .patch 补丁 └── llamafile-files/ # 新增文件原样复制含 BUILD.mk、common/license.cpp 等以 llama.cpp 为例脚本还会处理一个边界情况BUILD.mk在子模块中始终存在但在 macOS 这类大小写不敏感的文件系统上可能被 gitignore 掉导致git status探测不到。脚本对此做了兜底——若文件存在但未出现在新增文件列表里就强制把它加入NEW_FILES脚本第 80–84 行确保BUILD.mk永远被收集进llamafile-files/。llamafile-files/里的文件由 llama.cpp.patches/apply-patches.sh 在应用补丁前整体cp -r进子模块根目录随后执行 llama.cpp.patches/renames.sh 处理必要的文件搬移再删除上游多余的Makefile——这套「复制新文件 → 改名 → 打补丁」的次序就是make setup对每个子模块执行的标准化流程。只写不删被放弃的补丁必须手工清理脚本有一个重要且容易踩坑的特性只写入/覆盖从不删除脚本全程只有echo 、cp、mkdir -p没有任何清理逻辑。场景如下一次 llama.cpp 升级后某条补丁变得多余——例如上游已经合入了同样的修改。此时子模块里不再有对应的修改generate_patches.sh自然不会再生成本补丁但旧文件llama.cpp.patches/patches/dropped.patch仍静静躺在目录里。由于apply-patches.sh会对patches/*.patch全部遍历应用见其第 48–59 行这条「僵尸补丁」会在每次make setup时被继续应用轻则产生冲突重则破坏构建。正确的清理动作是对每条被放弃的补丁手工git rm llama.cpp.patches/patches/dropped.patch然后用计数做最终确认ls llama.cpp.patches/patches | wc -l该数字应与你的预期一致旧数量 − 放弃的 新增的。这一步也被收录在 docs/skills/llamafile/update_llamacpp.md 的 Step 5「Regenerate the patches」中作为 bump 流程的固定环节。生成前置门槛只有「已验证」的修改才有资格固化原文档对运行时机给出了硬性约束IMPORTANT: only run thisafterthe in-place edits are proven to work (a clean build succeeds and llamafile runs as expected). Generating patches from unproven edits bakes in breakage.即必须先在子模块的脏工作树上证明修改可用——干净构建通过、llamafile 按预期运行——之后才允许生成补丁。从未经证明的修改生成补丁等于把破坏固化进补丁集后续每次构建都会复现。这与 docs/skills/llamafile/update_llamacpp.md 中定义的 Step 4「Prove the reconciliation works (on the dirty tree)」完全对应那里要求先跑干净构建与llamafile:check再运行 llamafile理想情况是集成测试全绿后才进入 Step 5 的补丁再生成。构建日志不要写进o/目录——make clean会rm -rf o日志会被连带清掉而且看起来像构建失败。生成后验证verify-clean 干净回环补丁再生成之后原文档要求的验证手段是llamafile:verify-clean完整命令序列见 docs/commands/verify-clean.md# 确保工具链可用首次需下载 cosmocc if [ ! -d .cosmocc/4.0.2 ]; then build/download-cosmocc.sh .cosmocc/4.0.2 4.0.2 85b8c37a406d862e656ad4ec14be9f6ce474c1b436b9615e91a55208aced3f44 fi MAKE.cosmocc/4.0.2/bin/make $MAKE reset-repo # 干净起点丢弃所有本地修改重置子模块 $MAKE setup # 拉取子模块 应用补丁 抓取 UI 资源 $MAKE clean # 清除过期的构建产物 $MAKE -j$(nproc) # 干净构建mac 上用 -j$(sysctl -n hw.physicalcpu) $MAKE check # 单元测试这条回环之所以必要是因为补丁化修改不改变子模块文件的时间戳——reset-repo/setup之后增量make可能链接到陈旧的中间产物所以必须先make clean强制全量构建见 docs/commands/clean.md。make setup既拉子模块又打补丁而它无法在脏树上拉取子模块这正是reset-repo必须最先执行的原因。注意reset-repo具有破坏性会rm -rf子模块目录再恢复权限受限环境可能提示或拦截此时应使用$MAKE形式.cosmocc/4.0.2/bin/make reset-repo而非裸git clean/reset。一次成功的回环证明提交的补丁集内部自洽——新补丁能在干净树上重新应用并构建通过。需要清醒认识它的边界verify-clean不覆盖GPU 运行时后端、非宿主平台、Web UI 与长时运行稳定性这些需要按 docs/skills/llamafile/update_llamacpp.md 末尾的交接清单在真实硬件/平台上验证如 CUDA/ROCm 冒烟测试、Windows 冒烟测试、macOS Metal 运行时编译等。补丁生命周期的四个工具各司其职不要越权generate-patches不是孤立工具它与补丁生命周期中另外三个工具构成完整闭环分工表见 docs/skills/llamafile/update_llamacpp.md工具唯一职责运行位置tools/check_patches.sh分流triage对已存在的补丁做git apply --check干跑逐个标出哪些在升级后的子模块上仍能应用、哪些需要手工调和一次性列出全部冲突而非遇错即停仓库根目录apply-patches.sh --tolerant调和reconcilebump 期间应用所有能吻合的 hunk漂移的 hunk 留下*.rej文件而非中止并同步执行复制llamafile-files/、删 Makefile、抓 UI 等非补丁步骤仓库根目录llamafile:generate-patches生产produce从已验证的原地修改再生成全套补丁本文主题封装了cd的子模块调用llamafile:verify-clean验证verifyreset-repo → setup → 干净构建 → check的完整回环作为生成后的最终验证仓库根目录对照的「DO / DONT」红线也很清晰不要用git diff/git apply手工制造或编辑补丁生产归generate-patches分流归check_patches.sh回环验证归verify-clean不要手写for p in patches/*.patch; do git apply --check ...之类的循环那是前两个工具已做的事git diff $OLD_ID..$COMMIT_ID的唯一合法用途是「上游漂移侦察」——查看新上游改了哪些文件用来驱动BUILD.mk源列表的增删改。在完整 bump 流程docs/skills/llamafile/update_llamacpp.md中generate-patches位于 Step 5Step 2 用check_patches.sh分流 → Step 3 就地调和编辑子模块源码绝不编辑补丁文件→ Step 4 在脏树上证明构建与运行 → Step 5 运行generate-patches刷新全部补丁行号漂移会被自动修正这正是补丁再生成带来的韧性→ Step 6 用verify-clean收尾。升级中被判定「已被上游吸收」而放弃的补丁还要按上一节的方法手工git rm并同步更新 llama.cpp.patches/README.md 中新增/删除/实质重做的补丁条目。小结generate-patches是 llamafile 补丁集的唯一合法生产者它把「在子模块上的原地修改」转化为规整、可复现、路径正确的补丁文件与新增文件同时通过「只写不删」的语义把废弃补丁的清理决定权交还开发者。把「分流用check_patches.sh、调和用apply-patches.sh --tolerant、生产用generate-patches、验证用verify-clean」这条流水线记牢llama.cpp 等子模块的升级与维护就能始终保持可预测、可回滚的工程化状态。【免费下载链接】llamafileDistribute and run LLMs with a single file.项目地址: https://gitcode.com/GitHub_Trending/ll/llamafile创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考