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

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

一、安装 llama.cpp

1.1 方案对比

方案	难度	GPU 加速	适用场景
conda 直接安装（推荐）	⭐	✅	快速上手，大多数情况够用
源码编译	⭐⭐⭐	✅	需要最新特性、自定义编译选项
预编译二进制包	⭐⭐	⚠️ 可能无法调用 GPU	临时使用，环境受限时

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

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

bash 复制代码

# 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 方案二：源码编译

① 准备编译工具链

bash 复制代码

# 创建 Conda 环境
conda create -n llama python=3.12
conda activate llama

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

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

② 克隆并编译

bash 复制代码

# 克隆仓库
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：

bash 复制代码

# 确认 nvcc 版本
nvcc --version

# 启用 CUDA 编译（需 CUDA 12.x 以上）
cmake .. -DLLAMA_BUILD_UI=OFF -DGGML_CUDA=ON

make -j$(nproc)

AMD ROCm：

bash 复制代码

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

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

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

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

bash 复制代码

# 在 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 报错：

bash 复制代码

# 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 量化版本选择建议

硬件条件	推荐量化	说明
低配 / 内存紧张	`Q4_K_S`	最小内存占用
常规推荐	`Q4_K_M`	平衡质量与性能，首选
追求精度	`Q5_K_M` / `Q8_0`	文件更大，效果更好

2.2 下载方式

方式一：wget 直接下载

bash 复制代码

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 下载

bash 复制代码

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 下载（国内推荐）

bash 复制代码

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）

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

bash 复制代码

# 源码编译的路径
./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

常用参数说明：

参数	说明	示例
`-m`	模型文件路径	`-m ~/models/model.gguf`
`-p`	输入提示词	`-p "你好"`
`-n`	最大生成 token 数	`-n 512`
`-ngl`	卸载到 GPU 的层数（999 = 全卸载）	`-ngl 999`
`-c`	上下文窗口大小	`-c 4096`
`--temp`	温度（越低越确定性）	`--temp 0.7`
`-i`	交互模式（持续对话）	`-i`

3.2 启动 API 服务（llama-server）

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

基础启动

bash 复制代码

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

常用模型启动示例

bash 复制代码

# 纯文本模型（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

关键参数说明：

参数	说明
`--mmproj`	多模态投影文件路径，加了才能处理图片
`-ngl 999`	尽量把模型所有层塞进显存，放不下的自动走内存
`-c` / `--ctx-size`	上下文长度，显存小时适当调小
`-n` / `--n-predict` (或 `-n` / `--n-predict`)	最大预测 Token 数，即模型针对每一次请求，最多能生成多少个新的 Token 作为回复
`--jinja`	Qwen3.x 系列必须加，不加会出现回复异常或无限重复
`--timeout 0`	禁用请求超时，长任务时避免连接中断
`--host 0.0.0.0`	允许局域网内其他机器访问（默认仅本机）
--port	端口

3.3 验证服务状态

bash 复制代码

# 健康检查
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 完全一致：

python 复制代码

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 重跑：

bash 复制代码

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

开启后可以看到：

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

4.2 精细日志控制

参数	作用	适用场景
`--verbose` / `-v`	最高级别详细日志（一次性开关）	通用问题排查
`--verbosity N`	数字控制日志详细程度（0=默认，越高越详细）	需要更多信息但不想被海量日志淹没
`--verbose-prompt`	生成前打印完整处理后的提示词	提示词调试、检查特殊 token 是否正确解析

组合使用示例：

bash 复制代码

# 仅调试提示词
./llama-server -m model.gguf --verbose-prompt

# 全面深度排查
./llama-server -m model.gguf --verbose --verbose-prompt

五、后台常驻

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

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

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

bash 复制代码

# 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，可靠性有限）：

bash 复制代码

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 用户实例可用

bash 复制代码

systemctl --user status

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

bash 复制代码

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

② 创建服务文件

bash 复制代码

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

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

ini 复制代码

[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 命令。

③ 启动与管理

bash 复制代码

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       # 重启

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

bash 复制代码

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

5.3 tmux vs systemd 对比

特性	tmux	systemd --user
部署难度	简单	稍复杂，一劳永逸
自动重启	❌ 需手动	✅ `Restart=always`
开机自启	⚠️ cron（不可靠）	✅ 原生支持（需 linger）
日志管理	查看会话输出	`journalctl` 统一管理
未登录运行	❌	✅（加 linger 后）

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

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

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

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

6.1 启动路由模式

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

bash 复制代码

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

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

bash 复制代码

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 配置文件（精细管理）

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

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

bash 复制代码

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

6.2 路由模式资源控制

参数	作用	默认值
`--models-max N`	最大同时加载模型数，超过时卸载最久未用的	4
`--models-dir`	模型目录路径	无

6.3 API 调用

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

bash 复制代码

# 查看已注册模型列表
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"}'

python 复制代码

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：

bash 复制代码

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）：

ini 复制代码

[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

bash 复制代码

systemctl --user daemon-reload
systemctl --user start llamaserver-router
systemctl --user enable llamaserver-router
loginctl enable-linger 你的用户名   # 开机自启

6.5 路由模式 vs 多进程模式

模式	优点	缺点	适用场景
路由模式	统一端口、按需加载、资源开销小	首次调用有加载延迟；conda 包版本可能有 bug	生产环境，多模型长期服务
多进程模式	配置简单、互相隔离	多端口、资源开销大、管理繁琐	快速测试，或两个模型都高频使用

七、常见问题

问题	原因	解决方案
`GLIBCXX_3.4.30 not found`	预编译包依赖的 C++ 标准库版本比系统高	见 §1.4 GLIBCXX 修复步骤
tmux 中找不到 `llama-server`	conda 环境未激活	`conda activate llama` 后再运行，或用绝对路径
systemd 启动失败 `Permission denied`	文件权限或路径错误	检查模型路径权限；确认端口未被占用 `netstat -tlnp
`-ngl 999` 但 GPU 未加载	编译时未开启 CUDA	源码编译时加 `-DGGML_CUDA=ON`
路由模式返回 `proxy error`	conda 包版本过旧	改用源码编译的最新版本
Qwen3.x 回复异常/无限重复	缺少 `--jinja` 参数	启动命令加上 `--jinja`

八、性能参考与对比

与 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

指标	数值
Prompt 处理速度	768.51 tok/s（1.30 ms/token）
生成速度	187.04 tok/s（5.35 ms/token）

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

总结

场景	推荐方案
快速上手	`conda install llama.cpp`
生产部署 / GPU 加速	源码编译 + `-DGGML_CUDA=ON`
单模型长期服务	`systemd --user` 常驻
多模型按需切换	路由模式（需最新源码版本）
工具调用 / Qwen3.x 模型	llama.cpp 优于 Ollama

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

一、安装 llama.cpp

1.1 方案对比

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

1.3 方案二：源码编译

① 准备编译工具链

② 克隆并编译

③ GPU 加速编译（可选）

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

二、下载模型

2.1 量化版本选择建议

2.2 下载方式

三、运行模型

3.1 命令行对话（llama-cli）

3.2 启动 API 服务（llama-server）

基础启动

常用模型启动示例

3.3 验证服务状态

3.4 在应用中调用

四、调试技巧

4.1 --verbose 全量日志

4.2 精细日志控制

五、后台常驻

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

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

① 确认 systemd 用户实例可用

② 创建服务文件

③ 启动与管理

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

5.3 tmux vs systemd 对比

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

6.1 启动路由模式

6.2 路由模式资源控制

6.3 API 调用

6.4 路由模式后台常驻

6.5 路由模式 vs 多进程模式

七、常见问题

八、性能参考与对比

与 Ollama 的差异

真实性能测试日志

总结

4.1 `--verbose` 全量日志