Hugging Face is way more fun with friends and colleagues!

下载：https://github.com/ggml-org/llama.cpp/releases

llama-cli 参数详解与部署推荐指南

基于 llama.cpp llama-cli -h 整理。

每个参数包含： - - 适用场景 - 推荐配置（CPU / RTX 4090 / 多
GPU）

1. 通用参数（common params）

-m, --model FNAME

指定加载的模型文件路径。

作用

告诉 llama-cli 使用哪个 GGUF 模型。

适用场景

• 本地运行 Llama、Qwen、DeepSeek 等 GGUF 模型。
• 多模型切换。

推荐值

CPU:

-m model.gguf

RTX 4090:

-m Qwen3-32B-Q4_K_M.gguf

多 GPU:

-m DeepSeek-R1-70B-Q4_K_M.gguf

-ngl, --gpu-layers N

设置放入 GPU 显存中的模型层数量。

作用

控制 GPU 加速比例。

适用场景

显存不足时降低； 显存充足时提高速度。

推荐值

CPU:

-ngl 0

RTX 4090 24GB:

-ngl auto

70B 多 GPU:

-ngl all

-c, --ctx-size N

设置上下文长度。

作用

决定模型一次能记忆多少 token。

适用场景

长文本分析、代码、大文档。

推荐值

普通聊天:

-c 4096

RTX 4090:

-c 32768

长文本:

-c 131072

注意： 上下文越大，KV Cache 占用越高。

-t, --threads N

CPU 推理线程数量。

适用场景

纯 CPU 推理。

推荐值

8核CPU:

-t 8

16核CPU:

-t 16

服务器: 设置为物理核心数。

-b, --batch-size N

批处理大小。

作用

影响 prompt 处理速度。

推荐值

CPU:

-b 256

RTX 4090:

-b 2048

大显存:

-b 4096

--flash-attn

启用 Flash Attention。

作用

降低显存占用，提高注意力计算速度。

推荐值

RTX 4090:

--flash-attn on

CPU:

--flash-attn off

多 GPU:

--flash-attn auto

2. 采样参数（sampling params）

--temperature

温度参数，控制随机性。

推荐值

严谨回答:

--temp 0.2

代码:

--temp 0.3

聊天创作:

--temp 0.8

--top-k

限制候选 token 数量。

推荐值

通用:

--top-k 40

代码:

--top-k 20

--top-p

核采样概率范围。

推荐值

通用:

--top-p 0.95

稳定输出:

--top-p 0.8

--repeat-penalty

重复惩罚。

推荐值

默认:

--repeat-penalty 1.1

长文本:

1.15

3. KV Cache 参数

--cache-type-k / --cache-type-v

设置 KV Cache 精度。

推荐值

RTX 4090:

节省显存:

--cache-type-k q8_0
--cache-type-v q8_0

高质量:

f16

4. 多 GPU 参数

--split-mode

多 GPU 模型切分方式。

类型

none: 单 GPU

layer: 按层切分（推荐）

row: 按权重切分

tensor: 张量并行（实验）

推荐

双 RTX 4090:

--split-mode layer

--tensor-split

指定 GPU 显存比例。

示例

两张 4090:

--tensor-split 1,1

48GB+24GB:

--tensor-split 2,1

5. 推测解码（Speculative Decoding）

--model-draft

指定草稿模型。

作用

使用小模型预测，大模型验证。

适用

例如:

主模型: 70B

Draft: 7B

可以明显提升速度。

6. 多模态参数

--mmproj

加载视觉投影模型。

用途

图片理解模型。

例如:

--mmproj mmproj-model.gguf

--image

输入图片。

示例

--image test.jpg

推荐配置模板

RTX 4090 24GB 单卡

llama-cli \
-m model.gguf \
-ngl auto \
--flash-attn on \
-c 32768 \
-b 2048 \
--temp 0.7

CPU服务器

llama-cli \
-m model.gguf \
-ngl 0 \
-t 32 \
-c 8192 \
-b 512

双 RTX 4090

llama-cli \
-m model.gguf \
-ngl all \
--split-mode layer \
--tensor-split 1,1 \
--flash-attn on \
-c 65536

调优原则

目标 主要调整参数

提高速度 增加 -ngl、batch、开启 flash-attn
降低显存 降低 ctx、KV cache 量化
提高输出质量 降低 temperature
长文本 增加 ctx-size
多GPU split-mode + tensor-split
减少重复 repeat-penalty

llama-cli 命令行手册

本文档翻译自 llama-cli -h 的输出，涵盖了所有可用参数。
版本信息与编译细节请使用 --version 查看。

一、通用参数（common params）

二、采样参数（sampling params）

三、推测解码参数（speculative params）

四、示例特定参数（example-specific params）

说明：本手册基于 llama-cli -h 输出翻译整理，具体行为可能随版本变化，请以实际运行时的帮助信息为准。

llama-server 特有参数（仅列出与 llama-cli 不同或新增的部分）

通用参数（如 -t, -c, --samplers, --spec-* 等）请参考 llama-cli 手册，此处不重复。

服务器专属参数（example‑specific）

说明：所有带 (env: ...) 的参数均支持对应环境变量，具体取值以实际程序输出为准。

┌─────────────┐
│ 前端聊天UI  │
│ ChatGPT类界面│
└──────┬──────┘
       │ HTTP请求(OpenAI格式)
       ↓
┌─────────────────┐
│ llama-server    │
│ localhost:8080  │
│ OpenAI兼容API   │
└──────┬──────────┘
       │
       ↓
┌─────────────┐
│ GGUF模型    │
│ Llama/Qwen  │
└─────────────┘

Chat接口（最常用）

POST /v1/chat/completions

http://localhost:9192/v1/chat/completions

请求格式：

{
  "model": "local-model",
  "messages": [
    {
      "role": "system",
      "content": "你是一个AI助手"
    },
    {
      "role": "user",
      "content": "你好，请介绍一下自己"
    }
  ],
  "temperature":0.7
}

返回：

{
 "choices":[
  {
   "message":{
    "role":"assistant",
    "content":"你好，我是一个基于..."
   }
  }
 ]
}

前端怎么调用？

<input id="msg">
<button onclick="send()">发送</button>

<div id="answer"></div>

<script>

async function send(){

 let text=document.getElementById("msg").value;

 let res=await fetch(
 "http://服务器IP:8080/v1/chat/completions",
 {
  method:"POST",

  headers:{
   "Content-Type":"application/json",
   "Authorization":"Bearer YOUR_API_KEY"
  },

  body:JSON.stringify({

    model:"local-model",

    messages:[
      {
       role:"user",
       content:text
      }
    ]

  })

 });

 let data=await res.json();

 document.getElementById("answer").innerHTML=
 data.choices[0].message.content;

}

</script>

流式输出（打字效果）

请求增加：

{
 "stream":true
}

返回：

data:
{"content":"你"}

data:
{"content":"好"}

data:
{"content":"！"}

前端用：ReadableStream 读取即可。

限制访问量（1人）

nginx配置

新建/etc/nginx/conf.d/llama.conf

limit_conn_zone $binary_remote_addr zone=llama_limit:10m;

server {

    listen 8080;

    location / {

        # 单用户连接限制
        limit_conn llama_limit 1;

        # 超过限制返回503
        limit_conn_status 503;

        proxy_pass http://127.0.0.91:9192;

        proxy_http_version 1.1;

        # SSE流式输出必须
        proxy_set_header Connection "";

        proxy_buffering off;

        proxy_read_timeout 3600s;

    }

    # 自定义忙碌提示
    error_page 503 = @busy;

    location @busy {

        default_type application/json;

        return 503 '
        {
          "error":
          "AI服务器正在服务其他用户，请稍后再试"
        }';

    }

}

systemctl reload nginx

llama.cpp本身建议这样启动:

./llama-server \
-m model.gguf \
--host 127.0.0.91 \
--port 9192 \
--parallel 1 \
--api-key-file /service/ai/api.key

关键 --parallel 1 llama.cpp内部只允许一个推理上下文。

常用的完整 POST JSON 可以这样写：

{
  "model": "Talk-Qwen3-1.7B-Q8",
  "messages": [
    {
      "role": "system",
      "content": "你是一个专业、简洁、可靠的中文 AI 助手。回答要直接，不要输出 thinking，不要输出 <think> 标签。"
    },
    {
      "role": "user",
      "content": "请用三句话介绍一下 llama.cpp。"
    }
  ],
  "temperature": 0.6,
  "top_p": 0.85,
  "top_k": 40,
  "min_p": 0.05,
  "repeat_penalty": 1.2,
  "presence_penalty": 0.3,
  "frequency_penalty": 0.3,
  "max_tokens": 512,
  "stream": false
}

curl 示例：

curl http://127.0.0.91:9192/v1/chat/completions \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Bearer 你的key内容" \
  -d '{
    "model": "Talk-Qwen3-1.7B-Q8",
    "messages": [
      {
        "role": "system",
        "content": "你是一个专业、简洁、可靠的中文 AI 助手。回答要直接，不要输出 thinking，不要输出 <think> 标签。"
      },
      {
        "role": "user",
        "content": "请用三句话介绍一下 llama.cpp。"
      }
    ],
    "temperature": 0.6,
    "top_p": 0.85,
    "top_k": 40,
    "min_p": 0.05,
    "repeat_penalty": 1.2,
    "presence_penalty": 0.3,
    "frequency_penalty": 0.3,
    "max_tokens": 512,
    "stream": false
  }'

流式输出用：
"stream": true

多轮对话时，messages 自己带历史：

"messages": [
  {"role": "system", "content": "你是中文助手。"},
  {"role": "user", "content": "我叫张三。"},
  {"role": "assistant", "content": "好的，我记住了。"},
  {"role": "user", "content": "我叫什么？"}
]

不想有历史，就每次只传：

"messages": [
  {"role": "system", "content": "你是中文助手。"},
  {"role": "user", "content": "新的问题"}
]

单元文件（/etc/systemd/system/llama-server.service）

[Unit]
Description=llama.cpp router server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=/service/ai/llama.cpp
ExecStart=/service/ai/llama.cpp/build/bin/llama-server \
  --models-preset /service/ai/model/models.ini \
  --models-max 1 \
  --host 127.0.0.91 \
  --port 9192 \
  --api-key-file /service/ai/api.key

Restart=always
RestartSec=5
LimitMEMLOCK=infinity
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
root@serNCnJRbYWqCtG:~# cat /service/ai/model/models.ini
[*]
threads = 16
threads-batch = 16
batch-size = 512
ubatch-size = 128
parallel = 1
jinja = 1

temp = 0.6
top-k = 40
top-p = 0.85
min-p = 0.05

repeat-penalty = 1.2
repeat-last-n = 256
presence-penalty = 0.3
frequency-penalty = 0.3

n-predict = 4096
no-warmup = 1
mmap = 1

[✏️Coder-Qwen3-1.7B-Q5]
model = /service/ai/model/Coder/Qwen3-1.7b-coder-distilled-sft-Q5_K_M.gguf
ctx-size = 32768

[✏️Coder-Qwen3-30B-A3B-Q4]
model = /service/ai/model/Coder/Qwen3-Coder-30B-A3B-Instruct-Pruned-Q4_K_M.gguf
ctx-size = 16384

[🗣️Talk-Qwen3-1.7B-Q4]
model = /service/ai/model/Qwen/Qwen3-1.7B-Q4_K_M.gguf
ctx-size = 32768

[🗣️Talk-GLM4.7-23B-A3B-Q4]
model = /service/ai/model/GLM/GLM-4.7-Flash-REAP-23B-A3B-Q4_K_M.gguf
ctx-size = 16384

api.key文件生成

mkdir -p /service/ai
openssl rand -hex 32 > /service/ai/api.key
chmod 600 /service/ai/api.key
cat /service/ai/api.key

从GitHub克隆项目仓库并进入目录

直接下载：
https://github.com/ggml-org/llama.cpp/releases

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

如果需要，可以拉取子模块（通常用于ggml等依赖）：

git submodule update --init --recursive

安装依赖

sudo apt update
sudo apt install -y build-essential cmake git

编译命令

编译主要分为CPU基础版和GPU加速版。为了加速编译，可以使用 -j 参数指定并行任务数，例如 -j 8 表示用8个任务并行编译。

CPU 基础编译 (所有平台通用)

这是最基本的编译方式，生成仅使用CPU的程序。

cmake -B build
cmake --build build --config Release -j $(nproc)  # Linux/macOS用 $(nproc)，Windows可替换为具体数字如8

-B build: 在build文件夹中生成构建文件。
--config Release: 指定编译为发布版本，以获得最佳性能。
编译完成后，所有可执行文件（如llama-cli, llama-server）会位于 build/bin/ 目录下

启用硬件加速 (可选)

如需启用GPU加速，需要在CMake配置时添加相应参数

NVIDIA GPU (CUDA)
需提前安装好NVIDIA CUDA Toolkit

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

AMD GPU (ROCm)

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

Apple Silicon (Metal)

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

其他常用编译选项

调试版本 (Debug): 如需调试，可将 Release 替换为 Debug。

静态库: 如需构建静态库而非动态库，可添加 -DBUILD_SHARED_LIBS=OFF。

使用Ninja: Ninja 是一个更快的构建工具，可用 -GNinja 指定。

编译验证

编译成功后，可以进入 build/bin/ 目录，运行一个测试命令来验证：

cd build/bin
./llama-cli -m /path/to/your/model.gguf -p "Hello, world!" -n 64

如果想了解更详细的编译选项（如OpenBLAS、Vulkan等后端），建议查阅项目文档 docs/build.md

sudo swapoff /swapfile
sudo fallocate -l 4G /swapfile
# swapfile大小一般是内存的两倍
chmod 600 /swapfile
# 格式化为 Swap 空间
sudo mkswap /swapfile
# 重新启用 Swap
sudo swapon /swapfile
# 验证新大小是否生效
swapon --show
free -h
# 设置开机自动启用
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab