llamafile 发布全流程指南从版本号更新、GPU 共享库构建到发布 Zip 与二进制打包【免费下载链接】llamafileDistribute and run LLMs with a single file.项目地址: https://gitcode.com/GitHub_Trending/ll/llamafile本指南完整讲解 llamafile 项目的发布Release流程覆盖版本号更新、依赖初始化make setup、GPU 共享库ggml-cuda.so / ggml-rocm.so构建、make install安装以及发布 Zip 与五种发布二进制的生成与打包细节。读完本文你将掌握在当前仓库中从源码产出llamafile-version.zip与全套发布二进制的可复现步骤并能理解每条命令背后的 Makefile 与脚本实现。发布产物总览每次 llamafile 发布产生两类核心产物见 RELEASE.mdllamafile-version.zip一个完整的安装包包含五个二进制与 man 手册页发布二进制release binaries以llamafile-version等命名方式发布的独立可执行文件供用户直接下载运行。其中第五个二进制zipalign承担了发布流程中的关键职责——把 GPU 共享库以 ZIP 对齐方式「打包」进 llamafile 主程序这正是 llamafile「单文件分发」能力的来源llamafile/llamafile.c 中甚至对直接使用zip创建 llamafile 的行为给出警告提示应使用zipalign。发布流程概览完整发布路径如下更新 llamafile/version.h 中的版本号在 Linux 上构建ggml-cuda.so与ggml-rocm.so共享库仅当改动 CUDA 相关代码或 API 时需要否则可直接复用上一版本的共享库以make -j8构建整个项目以sudo make install PREFIX/usr/local将产物安装到系统目录生成llamafile-version.zip调用 llamafile/release.sh 生成命名规范的发布二进制。下面逐一展开每个环节。构建环境准备make setup任何构建开始前必须先执行make setup该命令完成两件事见 Makefile 中setup目标的实现初始化 git 子模块依次拉取whisper.cpp、stable-diffusion.cpp、llama.cpp含其嵌套子模块、transcribe.cpp与third_party/zipalign应用 llamafile 补丁分别执行各模块的apply-patches.sh如 llama.cpp.patches/apply-patches.sh、whisper.cpp.patches/apply-patches.sh 等将上游依赖与 llamafile 的构建系统整合并注入 llamafile 特有的功能。补丁清单与说明见 llama.cpp.patches/README.md。setup目标的末尾还会调用$(MAKE) cosmocc准备 cosmocc 工具链Makefile。如果你需要把子模块还原到未打补丁的原始状态可以使用make reset-repoMakefile它会删除并恢复全部相关子模块目录。更新版本号version.h发布的第一步是修改 llamafile/version.h 中的版本宏#define LLAMAFILE_MAJOR 0 #define LLAMAFILE_MINOR 10 #define LLAMAFILE_PATCH 5 #define LLAMAFILE_VERSION \ (100000000 * LLAMAFILE_MAJOR 1000000 * LLAMAFILE_MINOR LLAMAFILE_PATCH) #define MKVERSION__(x, y, z) #x . #y . #z #define MKVERSION_(x, y, z) MKVERSION__(x, y, z) #define LLAMAFILE_VERSION_STRING MKVERSION_(LLAMAFILE_MAJOR, LLAMAFILE_MINOR, LLAMAFILE_PATCH)其中LLAMAFILE_VERSION是数值化版本号用于程序内比较LLAMAFILE_VERSION_STRING是0.10.5形式的字符串。该字符串会在运行时被打印出来例如llamafile v0.10.5 - run LLMs locally见 llamafile/main.cpp以及 llamafile/chatbot_main.cpp 中的software: llamafile 0.10.5输出。发布时务必保证该版本号与最终归档名、二进制名一致。构建 GPU 共享库可选步骤注意此步骤仅在你修改了 CUDA 代码或其周边 API时才需要。ggml-cuda.so与ggml-rocm.so是随 llamafile 二进制一起分发的运行时加载共享库未改动时可继续使用上一版本的共享库。构建入口分别是 llamafile/cuda.sh 与 llamafile/rocm.shMakefile 中对应的封装目标是make cuda、make rocm见 Makefile。构建产物默认输出到用户主目录CUDA~/ggml-cuda.soROCm~/ggml-rocm.soCUDA 共享库TinyBLAS 与 cuBLAS默认情况下 llamafile 使用TinyBLAS作为 CUDA 后端实现即便部分模型家族如 Qwen3.5 在 CUDA 上默认使用 cuBLAS。cuda.sh的核心行为如下见 llamafile/cuda.sh./llamafile/cuda.sh # 使用 TinyBLAS默认 ./llamafile/cuda.sh --cublas # 改用 NVIDIA cuBLAS运行时需要 libcublas.so ./llamafile/cuda.sh -j16 # 16 个并行编译任务 ./llamafile/cuda.sh --clean # 清理后重建 ./llamafile/cuda.sh --output /path/to/output.so关键编译细节默认目标 NVIDIA 架构为 sm_75Turing/ sm_80 / sm_86Ampere/ sm_89Ada Lovelace/ sm_90Hopper见脚本中的ARCH_FLAGS当宿主机为 aarch64 且 CUDA 13 时切换为 sm_110f/sm_121aCUDA 13 还会追加 sm_120fRTX 5000 系列。TinyBLAS 模式会把 llamafile/tinyblas.h、llamafile/tinyblas.cu、llamafile/tinyblas-compat.h 复制到构建目录参与编译。脚本要求nvcc位于${CUDA_PATH:-/usr/local/cuda}/bin/nvcc可用CUDA_PATH环境变量覆盖。还提供体积优化选项--minimize-size等价于开启--minimal-archs --no-iq-quants --strip --compress、--minimal-archssm_75/sm_90 仅保留虚拟 PTX 以缩短编译时间、--no-iq-quants、--strip、--compress要求 CUDA ≥ 12.8传递--compress-modesize以及--fa-all-quants用于编译全部 flash-attention 向量量化组合。ROCm 共享库AMD GPUllamafile/rocm.sh 通过 HIP 编译 GGML CUDA 后端同样默认使用 TinyBLAS./llamafile/rocm.sh # 自动检测并行度 ./llamafile/rocm.sh -j16 # 16 个并行任务 ./llamafile/rocm.sh --clean ./llamafile/rocm.sh --output /path/to/output.so要求hipcc位于${ROCM_PATH:-/opt/rocm}/bin/hipcc可用ROCM_PATH覆盖。默认覆盖 gfx906Vega 20/ gfx1030-1032RDNA2/ gfx1100-1103RDNA3/ gfx942MI300 系列等多代 AMD 架构通过环境变量可快速构建单一架构OFFLOAD_ARCH--offload-archgfx942 ./llamafile/rocm.sh。编译标志包含-DGGML_USE_HIP1 -DGGML_USE_TINYBLAS1与--offload-compress。两个脚本都依赖共享的 llamafile/build-functions.sh含parse_build_args、get_ggml_version、compile_gpu_sources_parallel、link_shared_library等公共函数并以-DGGML_VERSION/-DGGML_COMMIT记录所构建的 GGML 版本信息。编译与安装主项目完成共享库构建后编译整个项目make -j8make顶层目标会构建 llamafile、llama.cpp、whisper.cpp、stable-diffusion.cpp、whisperfile、transcribe.cpp、transcribefile、diffusionfile 以及 third_party/zipalign 等全部子包见 Makefile。安装到系统目录sudo make install PREFIX/usr/localinstall目标Makefile会安装二进制llamafile、whisperfile、diffusionfile、transcribefile、zipalign到$(PREFIX)/binman 手册whisperfile.1、whisper-server.1、zipalign.1到$(PREFIX)/share/man/man1。注意install目标安装的是「薄」二进制thin binaries即尚未内嵌 GPU 共享库的版本GPU 库的打包发生在后续 zipalign 步骤。制作发布 Zip生成安装目录最简单的方式是直接把项目安装到带版本号的目录中make install PREFIXpreferred_dir/llamafile-version目录创建完成后需要把构建好的共享库打包进发布二进制目前仅 llamafile 需要。对每个需要内嵌 GPU 库的二进制执行zipalign -j0 llamafile ggml-cuda.so ggml-rocm.sozipalign是 llamafile 自带的 ZIP 对齐工具由 third_party/zipalign 子模块提供-j0表示以 0 字节对齐方式把附加文件加入 ZIP。llamafile 运行时会按需从自身 ZIP 中加载这些.so共享库从而保持「单文件即完整程序」的形态。注意 llamafile/llamafile.c 明确提示应使用zipalign而非普通zip来创建 llamafile。发布 Zip 目录结构打包后的目录结构如下源自 RELEASE.mdllamafile-version |-- README.md |-- bin | |-- diffusionfile | |-- llamafile | |-- transcribefile | |-- whisperfile | -- zipalign -- share -- man -- man1 |-- whisperfile.1 -- zipalign.1打包 Zip压缩前务必从目录中移除共享库文件如果存在rm *.so *.dll然后打包zip -r llamafile-version.zip llamafile-version生成发布二进制Zip 构建完成后接下来为发布生成命名规范的独立二进制。发布包含以下五个二进制llamafilezipalignwhisperfilediffusionfiletranscribefile直接调用 llamafile/release.sh 脚本即可一次性完成全部命名、复制与打包工作./llamafile/release.sh -v version -s source_dir -d dest_dir最后把llamafile-version.zip一并移动到dest_dir完成测试后即可发布。release.sh 内部流程从 llamafile/release.sh 源码看该脚本实际执行了比RELEASE.md描述更完整的流水线通过make install PREFIX${ZIP_DIR}把二进制与 man 页装入llamafile-version目录并复制README.md在打包 GPU 库前复制一份「薄」llamafile 副本llamafile-thin该副本不内嵌 GPU 共享库另存为llamafile-version-thin发布用zipalign -j0把ggml-cuda.so、ggml-cuda.dll、ggml-vulkan.so、ggml-vulkan.dll依次内嵌进bin/llamafileGPU 库目录由脚本头部的GPU_LIBS_DIR变量指定默认形如~/gpulibs/version将五个二进制以binary-version命名复制到release/目录对llamafile-version目录执行zip -r产出llamafile-version.zip。可见脚本中的-v version会驱动所有产物命名因此发布时务必保证脚本传入的版本号与 llamafile/version.h 保持一致脚本头部示例版本为0.10.4与当前version.h中的0.10.5之间的差异正是每次发布需要同步更新的点。发布前检查清单结合上述流程整理一份可复现的发布清单版本同步更新 llamafile/version.h 的LLAMAFILE_MAJOR/MINOR/PATCH并确保 llamafile/release.sh 头部的LLAMAFILE_VERSION一致环境初始化在干净工作区执行make setup确认子模块与补丁全部就绪GPU 库按需若改动 CUDA/ROCm 相关代码在 Linux 上运行./llamafile/cuda.sh与./llamafile/rocm.sh产物位于~/否则复用上一版本构建make -j8全量编译通过安装测试sudo make install PREFIX/usr/local验证命令行可启动、llamafile --version输出新版本号生成 Zipmake install PREFIXdir/llamafile-version→zipalign -j0内嵌 GPU 库 → 清理.so/.dll→zip -r llamafile-version.zip ...生成发布二进制./llamafile/release.sh -v version -s source_dir -d dest_dir并移入 Zip回归测试对llamafile、zipalign、whisperfile、diffusionfile、transcribefile五个二进制逐一验证基本功能仓库提供了集成测试入口如 tests/run_integration_tests.sh 与make check确认无误后发布。结语llamafile 的发布流程是一条「版本号 → 依赖准备 → GPU 库构建 → 全量编译 → 安装 → ZIP 归档 → 命名二进制」的完整流水线其中zipalign是贯穿始终的关键工具它既决定了 llamafile 单文件可分发的能力也是发布 Zip 结构bin/share/man/与内嵌 GPU 库行为的实现基础。理解 Makefile、llamafile/release.sh、llamafile/cuda.sh 与 llamafile/rocm.sh 之间的协作关系后维护者即可稳定、可复现地完成每次版本发布。【免费下载链接】llamafileDistribute and run LLMs with a single file.项目地址: https://gitcode.com/GitHub_Trending/ll/llamafile创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考