一、操作概述

本文档详细介绍 libllama.cpp（llama.cpp 核心库）的 CPU 版本编译、本地推理验证，以及消除软连接、打包集成到自有程序的完整步骤，适用于 Ubuntu 及 Debian 系 Linux 系统，确保操作可复现、打包后可正常使用。

二、前置准备

2.1 环境要求

• 系统：Ubuntu 18.04 及以上、Debian 10 及以上（其他 Linux 发行版可适配依赖安装命令）

• 权限：需具备 sudo 权限（用于安装依赖、执行系统级操作）

• 网络：可访问 GitHub 仓库（用于克隆 llama.cpp 源码）

2.2 关键说明

• 本文仅编译 CPU 版本，禁用 CUDA 加速，适配无 NVIDIA 显卡的环境；若需 GPU 版本，可修改编译参数（见注意事项）。

• 编译后会生成软连接文件，直接移动或打包会导致程序无法运行，需按步骤消除软连接、替换为实际文件。

• 文中涉及的库文件版本（如 libggml-base.so.0.9.7、libllama.so.0.0.8369）需根据实际编译结果替换，具体以编译后生成的文件版本为准。

三、详细操作步骤

3.1 安装依赖

执行以下命令，安装编译所需的基础工具（build-essential、cmake）、版本控制工具（git）及文件下载工具（wget）：

bash sudo apt install -y build-essential cmake git wget

3.2 克隆 llama.cpp 仓库

克隆 llama.cpp 官方仓库到本地（默认克隆到当前目录的 llama.cpp 文件夹）：

bash git clone https://github.com/ggerganov/llama.cpp.git

3.3 编译 libllama.cpp（CPU 版本）

进入仓库目录，执行基础编译流程，禁用 CUDA 加速，仅编译 CPU 版本，gcc版本必须大于等于9.**：

bash # 进入 llama.cpp 目录 cd llama.cpp # 创建 build 目录（用于存放编译产物）并进入 mkdir build && cd build # 配置 cmake，禁用 CUDA（CPU 版本核心配置） cmake .. -DLLAMA_CUBLAS=off # 并行编译，使用所有 CPU 核心（-j$(nproc) 自动获取核心数） make -j$(nproc)

3.4 查看编译产物

编译完成后，所有可执行文件和库文件均存储在以下路径：

bash ./llama.cpp/build/bin

核心产物说明：

• 可执行文件：llama-cli（本地推理测试工具）、llama-server（API 服务）、llama-perplexity（模型性能测试）等。

• 库文件：libggml 系列、libllama.so 系列、libmtmd.so 系列（核心依赖库，后续需处理软连接）。

3.5 消除软连接（关键步骤）

编译后生成的库文件存在软连接（如 libggml-base.so 是 libggml-base.so.0.9.7 的软连接），直接移动或打包会导致依赖缺失，需删除软连接并复制实际文件替换，步骤如下：

bash # 进入编译产物的 bin 目录（若当前在 build 目录，执行 cd bin） cd bin # 1. 处理 libggml-base.so 系列（版本需替换为实际编译版本） rm -f libggml-base.so && cp -p libggml-base.so.0.9.7 libggml-base.so rm -f libggml-base.so.0 && cp -p libggml-base.so.0.9.7 libggml-base.so.0 # 2. 处理 libggml-cpu.so 系列（版本需替换为实际编译版本） rm -f libggml-cpu.so && cp -p libggml-cpu.so.0.9.7 libggml-cpu.so rm -f libggml-cpu.so.0 && cp -p libggml-cpu.so.0.9.7 libggml-cpu.so.0 # 3. 处理 libggml.so 系列（版本需替换为实际编译版本） rm -f libggml.so && cp -p libggml.so.0.9.7 libggml.so rm -f libggml.so.0 && cp -p libggml.so.0.9.7 libggml.so.0 # 4. 处理 libllama.so 系列（版本需替换为实际编译版本） rm -f libllama.so && cp -p libllama.so.0.0.8369 libllama.so rm -f libllama.so.0 && cp -p libllama.so.0.0.8369 libllama.so.0 # 5. 处理 libmtmd.so 系列（版本需替换为实际编译版本） rm -f libmtmd.so && cp -p libmtmd.so.0.0.8369 libmtmd.so rm -f libmtmd.so.0 && cp -p libmtmd.so.0.0.8369 libmtmd.so.0 # 6. 修复可执行文件的动态链接路径（确保打包后可正常加载依赖） patchelf --set-rpath '$ORIGIN' llama-server

注意：上述命令中的版本号（如 0.9.7、0.0.8369）需替换为实际编译后生成的库文件版本，可通过 ls -l 命令查看 bin 目录下的库文件版本。

3.6 本地推理测试（验证编译成果）

使用编译后的 llama-cli 工具，加载本地模型（需提前准备 GGUF 格式模型）进行本地推理测试，确认编译正常：

bash # 进入 bin 目录（若未在该目录） cd ./llama.cpp/build/bin # 本地推理测试（替换 my_model.gguf 为你的本地 GGUF 模型路径） ./llama-cli -m /path/to/your/my_model.gguf -p "Hello, llama.cpp!"

若正常输出模型生成的文本，说明编译及本地推理功能正常。

3.7 打包集成到自有程序

消除软连接并验证正常后，即可将 build/bin 目录下的所有文件打包，集成到自有程序中，步骤如下：

1. 将 build/bin 目录复制到自有程序的依赖目录（如 ./your_project/deps/llama/）。

1. 在自有程序中配置动态链接路径，确保程序能正确加载 libllama.so 等核心库（可参考 patchelf 命令配置，或在程序运行时指定 LD_LIBRARY_PATH）。

1. 打包自有程序时，需将 llama.cpp 的 bin 目录一同打包，确保依赖完整。

四、注意事项

• 版本替换：文中所有库文件版本号（如 libggml-base.so.0.9.7）均为示例，实际需以 ls ./llama.cpp/build/bin 查看的版本为准，否则会出现文件找不到错误。

• GPU 版本编译：若需启用 CUDA 加速（NVIDIA 显卡），将 cmake 命令改为 cmake .. -DLLAMA_CUBLAS=on，需提前安装 NVIDIA 驱动和 CUDA 工具包。

• 模型要求：llama.cpp 仅支持 GGUF 格式模型，其他格式（如 PyTorch 模型）需使用 llama.cpp 仓库中的 convert_*.py 脚本转换为 GGUF 格式。

• 权限问题：若执行 patchelf 命令提示“command not found”，需安装 patchelf 工具：sudo apt install -y patchelf。

• 打包后异常：若打包后程序无法运行，检查是否遗漏库文件、软连接是否已完全消除，或动态链接路径是否配置正确。

五、常见问题排查

5.1 编译失败

原因：依赖未安装完整、cmake 版本过低、网络问题导致仓库克隆不完整。

解决：重新执行依赖安装命令，升级 cmake（sudo apt upgrade cmake），重新克隆仓库。

5.2 本地推理提示“模型文件不存在”

原因：模型路径错误、模型格式不是 GGUF。

解决：确认模型路径正确，使用 llama.cpp 提供的转换脚本将模型转换为 GGUF 格式。

5.3 打包后程序无法加载库文件

原因：软连接未消除、动态链接路径配置错误、库文件版本不匹配。

解决：重新执行软连接处理步骤，检查 patchelf 命令是否执行成功，确认库文件版本与命令中的版本一致。