llama.cpp 部署大模型到 Ubuntu 台式机 SOP

## 0. 先确认机器情况

```bash
# 查看显示设备
lspci | grep -Ei 'vga|3d|display'

# NVIDIA 显卡
nvidia-smi

# AMD 显卡
rocm-smi

• 有 NVIDIA：编译时用 -DGGML_CUDA=ON
• 有 AMD：编译时用 -DGGML_HIPBLAS=ON
• 无 GPU 或不想折腾：只编译 CPU 版

GLM-4.7-Flash 4bit 量化约需 18GB 左右内存/显存。不够就换更小量化，如 Q4_K_M、Q3_K_M。

---

1. 安装基础依赖

sudo apt update
sudo apt install -y git cmake build-essential libssl-dev curl

libssl-dev 必须安装，否则会报：

error: HTTPS is not supported

如果使用 NVIDIA GPU，请确保 CUDA Toolkit 已安装：

nvcc --version

没有 nvcc 请先安装 CUDA Toolkit 12.x。

---

2. 设置 Hugging Face 镜像（国内必须）

临时生效（当前终端）：

export HF_ENDPOINT=https://hf-mirror.com

永久生效（推荐）：

echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc
source ~/.bashrc

不设置此步骤，后面使用 -hf 下载模型大概率失败。

---

3. 下载并编译 llama.cpp

cd ~
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp

CPU 版

cmake -B build -DLLAMA_OPENSSL=ON
cmake --build build --config Release -j $(nproc)

NVIDIA GPU 版

cmake -B build -DGGML_CUDA=ON -DLLAMA_OPENSSL=ON
cmake --build build --config Release -j $(nproc)

AMD GPU 版

cmake -B build -DGGML_HIPBLAS=ON -DLLAMA_OPENSSL=ON
cmake --build build --config Release -j $(nproc)

编译完成后检查：

./build/bin/llama-cli --version

如果报找不到 libllama-cli-impl.so：

export LD_LIBRARY_PATH=$HOME/llama.cpp/build/bin:$LD_LIBRARY_PATH

---

4. 快速测试模型：llama-cli

确保已设置镜像：

export HF_ENDPOINT=https://hf-mirror.com

运行 GLM-4.7-Flash：

cd ~/llama.cpp
./build/bin/llama-cli \
  -hf unsloth/GLM-4.7-Flash-GGUF:UD-Q4_K_XL \
  -ngl 99 \
  --temp 1.0 --top-p 0.95 --min-p 0.01 --repeat-penalty 1.0

参数说明：

• -ngl 99：尽量把模型层放到 GPU；CPU 版请删掉。
• --min-p 0.01：GLM 推荐值，llama.cpp 默认是 0.05，需显式覆盖。
• --repeat-penalty 1.0：官方建议禁用重复惩罚。
• 显存不足时，去掉 -ngl 99，或换更小量化。

---

5. 启动 API 服务：llama-server

cd ~/llama.cpp
./build/bin/llama-server \
  -hf unsloth/GLM-4.7-Flash-GGUF:UD-Q4_K_XL \
  -ngl 99 \
  --host 0.0.0.0 --port 8080 \
  --ctx-size 32768 \
  --temp 1.0 --top-p 0.95 --min-p 0.01 --repeat-penalty 1.0

后台运行：

nohup ./build/bin/llama-server \
  -hf unsloth/GLM-4.7-Flash-GGUF:UD-Q4_K_XL \
  -ngl 99 \
  --host 0.0.0.0 --port 8080 \
  --ctx-size 32768 \
  --temp 1.0 --top-p 0.95 --min-p 0.01 --repeat-penalty 1.0 \
  > llama-server.log 2>&1 &

访问地址：

• Web UI：http://localhost:8080
• 局域网：http://你的Ubuntu机器IP:8080

---

6. 测试服务是否正常

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-4.7-flash",
    "messages": [{"role": "user", "content": "你好"}]
  }'

返回 JSON 即表示部署成功。

---

7. 常用参数速查

参数	作用
-hf 仓库:量化	自动从 Hugging Face 下载模型
--model /path/model.gguf	手动指定本地 GGUF 文件
-ngl 99	GPU 层数，99 表示尽量全放 GPU
--ctx-size 32768	上下文长度
--host 0.0.0.0	允许局域网访问
--port 8080	服务端口
--temp 1.0 --top-p 0.95 --min-p 0.01	GLM 推荐采样参数
--repeat-penalty 1.0	禁用重复惩罚
--cache-type-k q4_0 --cache-type-v q4_0	KV 缓存量化，省显存，不稳定则去掉

---

8. 常见问题

1）--model is required

通常是 -hf 下载失败。先确认：

echo $HF_ENDPOINT

应输出 https://hf-mirror.com。没有则重新 export。

2）HTTPS is not supported

未安装 libssl-dev 或编译未启用 OpenSSL：

sudo apt install -y libssl-dev
cd ~/llama.cpp
cmake -B build -DLLAMA_OPENSSL=ON -DGGML_CUDA=ON   # AMD 换 HIPBLAS，CPU 去掉 CUDA
cmake --build build --config Release -j $(nproc)

3）libllama-cli-impl.so: cannot open shared object file

临时解决：

export LD_LIBRARY_PATH=$HOME/llama.cpp/build/bin:$LD_LIBRARY_PATH

或重新安装：

cd ~/llama.cpp
sudo cmake --install build --config Release

4）显存不足

• 换更小量化：Q4_K_M、Q3_K_M、Q2_K
• 降低 -ngl
• 加 KV 量化：--cache-type-k q4_0 --cache-type-v q4_0
• 直接 CPU 推理，去掉 -ngl 99

5）速度慢

确认是否真的用了 GPU：

nvidia-smi

如果显存没占用，说明 -ngl 没生效或编译时没开 CUDA。

---

9. 最小命令汇总

# 1. 安装依赖
sudo apt update
sudo apt install -y git cmake build-essential libssl-dev curl

# 2. 设置 Hugging Face 镜像（国内必须）
export HF_ENDPOINT=https://hf-mirror.com

# 3. 编译
cd ~
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build -DGGML_CUDA=ON -DLLAMA_OPENSSL=ON
cmake --build build --config Release -j $(nproc)

# 4. 命令行测试
./build/bin/llama-cli -hf unsloth/GLM-4.7-Flash-GGUF:UD-Q4_K_XL -ngl 99 \
  --temp 1.0 --top-p 0.95 --min-p 0.01 --repeat-penalty 1.0

# 5. 启动 API 服务
./build/bin/llama-server -hf unsloth/GLM-4.7-Flash-GGUF:UD-Q4_K_XL -ngl 99 \
  --host 0.0.0.0 --port 8080 --ctx-size 32768 \
  --temp 1.0 --top-p 0.95 --min-p 0.01 --repeat-penalty 1.0