llama.cpp在Linux上安装使用指南

本文面向无 sudo 权限但已安装 Conda 的 Linux 环境（如服务器/集群），讲解如何通过 Conda 完成 llama.cpp 的安装、模型下载、运行服务、后台常驻和多模型管理。

一、安装 llama.cpp

1.1 方案对比

1.2 方案一：conda 直接安装（推荐）

核心思路：用 Conda 创建独立虚拟环境，无需任何系统权限，一键安装所有内容。

# 1. 创建 Conda 环境（Python 版本自选）conda create -n llama python=3.12# 2. 激活环境conda activate llama# 3. 直接安装 llama.cpp（包含所有可执行文件）conda install -c conda-forge llama.cpp

注意：conda-forge 的包版本可能略滞后官方几个版本。若需要最新特性（如路由模式），请改用源码编译。

1.3 方案二：源码编译

① 准备编译工具链

# 创建 Conda 环境conda create -n llama python=3.12conda activate llama# 安装编译依赖：cmake 和 g++conda install -c conda-forge cmake gxx

conda install 会自动处理依赖，所有安装限制在用户目录，无需 sudo。

② 克隆并编译

# 克隆仓库git clone https://github.com/ggerganov/llama.cpp.gitcd llama.cpp# 创建构建目录mkdir build && cd build# 纯 CPU 编译（关闭 WebUI 以简化流程）cmake .. -DLLAMA_BUILD_UI=OFF# 并行编译（使用全部 CPU 核心）make -j$(nproc)

编译产物在 llama.cpp/build/bin/ 下（llama-server、llama-cli 等）。

③ GPU 加速编译（可选）

NVIDIA CUDA：

# 确认 nvcc 版本nvcc --version# 启用 CUDA 编译（需 CUDA 12.x 以上）cmake .. -DLLAMA_BUILD_UI=OFF -DGGML_CUDA=ONmake -j$(nproc)

AMD ROCm：

cmake .. -DGGML_HIPBLAS=ON -DAMDGPU_TARGETS="gfx1100"# 按显卡型号调整make -j$(nproc)

提示：加了 GPU 编译后，启动时 -ngl 999 才真正有效，能将模型层尽量卸载到显存。

1.4 方案三：预编译二进制包

当编译环境受限时，可直接下载官方发布的预编译包：

# 在 GitHub Releases 页面找到对应 Ubuntu 版本的包，替换版本号wget https://github.com/ggerganov/llama.cpp/releases/download/b9192/llama-b9192-bin-ubuntu-x64.tar.gztar -zxvf llama-b9192-bin-ubuntu-x64.tar.gz

缺点：预编译包可能无法调用 GPU（因编译时未链接系统 CUDA），且可能遇到 GLIBCXX 版本不兼容问题。

解决 GLIBCXX_3.4.30 not found 报错：

# 1. 在 conda 环境中安装高版本标准库conda activate llamaconda install -c conda-forge libstdcxx-ng=12# 2. 确认版本可用strings $(find $CONDA_PREFIX -name "libstdc++.so.6" 2>/dev/null) | grep GLIBCXX_3.4.30# 3. 设置库路径环境变量conda env config vars set LD_LIBRARY_PATH="$CONDA_PREFIX/lib:$CONDA_PREFIX/lib64"conda deactivate && conda activate llama

二、下载模型

llama.cpp 使用 .gguf 格式的量化模型文件。

2.1 量化版本选择建议

2.2 下载方式

方式一：wget 直接下载

mkdir -p ~/models && cd ~/models# 以 Llama-3.2-1B 的 Q4_K_M 量化为例wget https://huggingface.co/bartowski/Llama-3.2-1B-Instruct-GGUF/resolve/main/Llama-3.2-1B-Instruct-Q4_K_M.gguf

方式二：huggingface-cli 下载

pip install huggingface_hub# 下载单个文件huggingface-cli download bartowski/Llama-3.2-1B-Instruct-GGUF \  Llama-3.2-1B-Instruct-Q4_K_M.gguf \  --local-dir ~/models

方式三：modelscope CLI 下载（国内推荐）

pip install modelscope# 下载单个 GGUF 文件modelscope download --model Qwen/Qwen2.5-7B-Instruct-GGUF \  qwen2.5-7b-instruct-q4_k_m.gguf \  --local_dir ~/models

三、运行模型

3.1 命令行对话（llama-cli）

适合快速测试，直接在终端与模型交互：

# 源码编译的路径./build/bin/llama-cli -m ~/models/Llama-3.2-1B-Instruct-Q4_K_M.gguf \  -p "Hello, who are you?" \  -n 128# conda 安装后直接调用llama-cli -m ~/models/Llama-3.2-1B-Instruct-Q4_K_M.gguf \  -p "你好，请介绍一下自己" \  -n 256

常用参数说明：

3.2 启动 API 服务（llama-server）

这是最重要的使用方式，启动后可通过标准 HTTP API 调用模型，兼容 OpenAI 接口协议。

基础启动

# 监听本地 8080 端口，启用 GPU 加速，不设超时./build/bin/llama-server \  -m ~/models/Llama-3.2-1B-Instruct-Q4_K_M.gguf \  --port 8080 \  -ngl 999 \  --timeout 0

常用模型启动示例

# 纯文本模型（Qwen3.5-35B 示例）./build/bin/llama-server \  -m "models/Qwen3.6-35B-A3B-Q4_K_M.gguf" \  -ngl 999 -c 32768 -n 8192 \  --jinja --port 8080# 多模态模型（需额外加载视觉投影文件）./build/bin/llama-server \  -m "models/Qwen3.6-35B-A3B-Q4_K_M.gguf" \  --mmproj "models/mmproj-Qwen3.6-35B-A3B-f16.gguf" \  -ngl 999 -c 32768 -n 8192 \  --jinja --port 8080

关键参数说明：

3.3 验证服务状态

# 健康检查curl http://localhost:8080/health# 查看已注册模型curl http://127.0.0.1:8080/v1/models# 测试对话（OpenAI 兼容接口）curl http://localhost:8080/v1/chat/completions \  -H "Content-Type: application/json" \  -d '{    "model": "my-model",    "messages": [{"role": "user", "content": "你好"}]  }'# 查看端口占用lsof -i:8080# 监控 GPU 使用率watch -n 1 nvidia-smi

3.4 在应用中调用

服务启动后，将 base_url 指向本地即可，与调用云端 API 完全一致：

from openai import OpenAIclient = OpenAI(    base_url="http://127.0.0.1:8080/v1",    api_key="sk-no-key-required"# 本地服务不校验，可任意填)response = client.chat.completions.create(    model="my-model",    messages=[{"role": "user", "content": "你好，请介绍一下量子计算"}])print(response.choices[0].message.content)

四、调试技巧

4.1 --verbose 全量日志

当服务跑起来但结果不对或速度慢时，加上 --verbose 重跑：

./llama-server -m model.gguf --verbose

开启后可以看到：

• Build Info & System Info：编译版本和系统配置，确认与环境匹配
• GPU 卸载情况：-ngl 是否真正生效，实际卸载了多少层
• KV Cache 使用：内存/显存使用情况
• Prompt 处理进度：slot 分配与释放，定位慢在哪里

4.2 精细日志控制

组合使用示例：

# 仅调试提示词./llama-server -m model.gguf --verbose-prompt# 全面深度排查./llama-server -m model.gguf --verbose --verbose-prompt

五、后台常驻

有两种可靠方案让 llama-server 持续在后台运行。

5.1 方案一：tmux（简单灵活）

适合快速部署和临时运行，可随时 attach 查看日志。

# 1. 安装 tmux（若系统无 sudo 权限）conda install -c conda-forge tmux# 2. 创建新会话并启动服务tmux new -s llamaserverconda activate llamallama-server -m /path/to/model.gguf --host 0.0.0.0 --port 8080 -ngl 999 --timeout 0# 3. 分离会话（服务继续后台运行）# 按 Ctrl+B，然后 D# 常用管理命令tmux ls# 列出所有会话tmux attach -t llamaserver        # 重新进入会话tmux kill-session -t llamaserver  # 停止服务# 在会话内滚动查看历史：Ctrl+B 然后 [（按 q 退出）

开机自动启动（cron，可靠性有限）：

crontab -e# 添加以下行（替换路径和环境名）@reboot tmux new-session -d -s llamaserver 'conda activate llama && llama-server -m /path/to/model.gguf --host 0.0.0.0 --port 8080 -ngl 999 --timeout 0'

@reboot 在用户登录前可能不生效，更可靠的方案见下文 systemd。

5.2 方案二：用户级 systemd（推荐，更健壮）

支持自动重启、开机自启，无需 sudo。

① 确认 systemd 用户实例可用

systemctl --user status

若提示 Failed to connect to bus，执行：

export XDG_RUNTIME_DIR="/run/user/$(id -u)"

② 创建服务文件

mkdir -p ~/.config/systemd/usernano ~/.config/systemd/user/llamaserver.service

填入以下内容（替换路径和用户名）：

[Unit]Description=llama.cpp serverAfter=network.target[Service]Type=simpleEnvironment="PATH=/home/你的用户名/miniconda3/envs/llama/bin:/usr/local/bin:/usr/bin:/bin"ExecStart=/home/你的用户名/miniconda3/envs/llama/bin/llama-server \    -m /path/to/model.gguf \    --host 0.0.0.0 --port 8080 \    -ngl 999 --timeout 0WorkingDirectory=/home/你的用户名Restart=alwaysRestartSec=10StandardOutput=journalStandardError=journal[Install]WantedBy=default.target

关键：Environment 中必须包含 conda 环境的 bin 路径；推荐直接写绝对路径而非 conda activate 命令。

③ 启动与管理

systemctl --user daemon-reload             # 重新加载配置systemctl --user start llamaserver         # 启动服务systemctl --user enable llamaserver        # 设置登录后自启systemctl --user status llamaserver        # 查看状态journalctl --user -u llamaserver -f        # 实时查看日志journalctl --user -u llamaserver -n 100 --no-pager   # 查看近 100 行日志systemctl --user stop llamaserver          # 停止systemctl --user restart llamaserver       # 重启

④ 开机自启（未登录也能运行）

# 允许用户进程在未登录时也保持运行loginctl enable-linger 你的用户名

5.3 tmux vs systemd 对比

推荐原则：长期稳定运行 → systemd --user；临时测试 → tmux 足够。

六、多模型管理（路由模式）

llama.cpp 官方提供 Router Mode（路由模式），用一个端口、一个进程管理多个模型，按需加载，空闲自动卸载（LRU 算法）。

⚠️ 注意：conda-forge 的 llama.cpp 版本可能偏旧，路由模式存在 bug（如返回 proxy error: Failed to read connection(tools)）。确认使用源码编译的最新版本再开启路由模式。

6.1 启动路由模式

方式一：自动扫描目录（简单推荐）

llama-server --models-dir /path/to/models --port 8080 -ngl 999 --timeout 0

方式二：手动指定模型和别名

llama-server \  --model /path/to/model1.gguf --alias"chat-7b" \  --model /path/to/model2.gguf --alias"code-3b" \  --port 8080 -ngl 999 --timeout 0# 多模态模型llama-server \  --model /path/to/qwen-vl.gguf \  --mmproj /path/to/mmproj.gguf \  --alias"qwen-vl" \  --port 8080 -ngl 999 --timeout 0

方式三：.ini 配置文件（精细管理）

适合为不同模型设置独立参数（上下文长度、量化等）：

# models.ini[global]ngl = 99[model:qwen-chat:9b]model = ./models/Qwen3.5-9B-Q4_K_M.ggufalias = qwen-chatctx-size = 131072[model:qwen-vl:7b]model = ./models/Qwen2.5-VL-7B-Q6_K.ggufalias = qwen-vlctx-size = 131072

llama-server --models-preset /path/to/models.ini --port 8080 --timeout 0

6.2 路由模式资源控制

6.3 API 调用

与标准 OpenAI API 完全一致，在 model 字段指定别名：

# 查看已注册模型列表curl http://127.0.0.1:8080/v1/models# 手动加载指定模型curl -X POST http://127.0.0.1:8080/models/load \  -H "Content-Type: application/json" \  -d '{"model": "chat-7b"}'# 手动卸载模型curl -X POST http://127.0.0.1:8080/models/unload \  -H "Content-Type: application/json" \  -d '{"model": "chat-7b"}'

from openai import OpenAIclient = OpenAI(base_url="http://127.0.0.1:8080/v1", api_key="sk-no-key-required")# 按需切换模型r = client.chat.completions.create(    model="chat-7b",    messages=[{"role": "user", "content": "你好"}])

6.4 路由模式后台常驻

将启动命令换成路由模式命令即可，配置方式与"单模型常驻"完全一样：

tmux：

tmux new -s llamaserver-routerconda activate llamallama-server --models-dir /path/to/models --port 8080 --timeout 0# Ctrl+B D 分离会话

systemd（服务文件 llamaserver-router.service）：

[Unit]Description=llama.cpp Router Mode ServerAfter=network.target[Service]Type=simpleEnvironment="PATH=/home/你的用户名/miniconda3/envs/llama/bin:/usr/local/bin:/usr/bin:/bin"ExecStart=/home/你的用户名/miniconda3/envs/llama/bin/llama-server \    --models-dir /path/to/models \    --port 8080 --timeout 0WorkingDirectory=/home/你的用户名Restart=alwaysRestartSec=10StandardOutput=journalStandardError=journal[Install]WantedBy=default.target

systemctl --user daemon-reloadsystemctl --user start llamaserver-routersystemctl --user enable llamaserver-routerloginctl enable-linger 你的用户名   # 开机自启

6.5 路由模式 vs 多进程模式

七、常见问题

八、性能参考与对比

与 Ollama 的差异

llama.cpp 相比 Ollama 的核心优势：

• 工具调用（tool_call）更稳定：Ollama 在 Qwen3 / Qwen3.5 系列模型上容易踩坑，llama.cpp 基本无此问题
• 生成速度更快：下方是一次真实测试数据（Qwen3.5 9B Q4_K_M）

真实性能测试日志

prompt eval time =    41.64 ms /   32 tokens  (  1.30 ms/token,  768.51 tok/s)       eval time =  1069.30 ms /  200 tokens  (  5.35 ms/token,  187.04 tok/s)      total time =  1110.94 ms /  232 tokens

Ollama 预热后 Prompt 处理速度相近，但生成速度有明显差距，llama.cpp 领先。

总结