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.12
conda activate llama

# 安装编译依赖：cmake 和 g++
conda install -c conda-forge cmake gxx

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

② 克隆并编译

# 克隆仓库
git clone https://github.com/ggerganov/llama.cpp.git
cd 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=ON

make -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.gz
tar -zxvf llama-b9192-bin-ubuntu-x64.tar.gz

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

解决 GLIBCXX_3.4.30 not found 报错：

# 1. 在 conda 环境中安装高版本标准库
conda activate llama
conda 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-UD-Q4_K_M.gguf" \\
-ngl 999 -c 32768 -n 8192 \\
–jinja –port 8080

# 多模态模型（需额外加载视觉投影文件）
./build/bin/llama-server \\
-m "models/Qwen3.6-35B-A3B-UD-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 OpenAI

client = 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 llamaserver
conda activate llama
llama-server -m /path/to/model.gguf –host 0.0.0.0 –port 8080 -ngl 999 –timeout 0

# 以 Qwen3.6-35B-A3B-UD-Q4_K_M.gguf 模型为例
llama-server \\
-m Qwen3.6-35B-A3B-UD-Q4_K_M.gguf \\
–mmproj mmproj-Qwen3.6-35B-A3B-f16.gguf \\
-ngl 999 -c 98304 -n 8192 \\
–jinja –port 8080

# 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/user
nano ~/.config/systemd/user/llamaserver.service

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

[Unit]
Description=llama.cpp server
After=network.target

[Service]
Type=simple
Environment="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 0
WorkingDirectory=/home/你的用户名
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=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.gguf
alias = qwen-chat
ctx-size = 131072

[model:qwen-vl:7b]
model = ./models/Qwen2.5-VL-7B-Q6_K.gguf
alias = qwen-vl
ctx-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 OpenAI
client = 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-router
conda activate llama
llama-server –models-dir /path/to/models –port 8080 –timeout 0
# Ctrl+B D 分离会话

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

[Unit]
Description=llama.cpp Router Mode Server
After=network.target

[Service]
Type=simple
Environment="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 0
WorkingDirectory=/home/你的用户名
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=default.target

systemctl –user daemon-reload
systemctl –user start llamaserver-router
systemctl –user enable llamaserver-router
loginctl 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 领先。

总结