使用教程
# Use a local model file
llama-cli -m my_model.gguf
# Or download and run a model directly from Hugging Face
llama-cli -hf ggml-org/gemma-3-1b-it-GGUF
# Launch OpenAI-compatible API server
llama-server -hf ggml-org/gemma-3-1b-it-GGUF
- llama-cli：命令行交互 / 生成工具（以前叫 main），适合快速测试、脚本调用、benchmark。
- llama-server：轻量级 OpenAI API 兼容 HTTP 服务器 + 自带现代 WebUI，适合日常聊天、多用户、手机/网页访问、集成到其他程序。
下面是 Ubuntu 下最实用的使用教程（假设你已编译好，binary 在 build/bin/ 目录下）。
1. 通用准备（两个工具都适用）
把模型文件放在方便的位置，例如：
mkdir -p ~/models
# 示例：下载一个常用模型（Qwen3 中文很强）
# wget https://huggingface.co/Qwen/Qwen3-8B-Instruct-GGUF/resolve/main/Qwen3-8B-Instruct-Q5_K_M.gguf -O ~/models/qwen3-8b-q5.gguf
常用高频参数（几乎所有命令都会用到）：
| 参数 | 推荐写法 | 说明 |
|---|
-m / --model | 必填 | GGUF 模型路径 |
-ngl / --n-gpu-layers | 999 / 40 / 30 | GPU 层数（999 = 尽可能全卸载） |
-c / --ctx-size | 8192～65536 | 上下文长度（越大越占内存） |
-fa / --flash-attn | 开启 | 加速 + 省显存（几乎必开） |
--color | 开启 | 彩色输出（CLI 好看） |
--temp 0.7 | 0.6～0.8 | 创造性 |
--top-k 40 | 30～60 | |
--top-p 0.9 | 0.85～0.95 | 经典采样组合 |
--min-p 0.05 | 0.05～0.1 | 近年很流行，提高一致性 |
2. llama-cli 使用教程（命令行聊天 / 生成）
最简单交互聊天（推荐新手第一步）
cd ~/llama.cpp/build/bin
./llama-cli \
-m ~/models/qwen3-8b-q5.gguf \
-ngl 999 \
-c 24576 \
--temp 0.75 --top-k 50 --top-p 0.92 --min-p 0.06
- 启动后直接输入消息，回车发送
- 输入
/bye 或 Ctrl+C 退出
- 支持多轮对话（模型有内置 chat template 的话自动使用）
指定系统提示 + 更现代的对话模式
./llama-cli \
-m model.gguf -fa -ngl 999 -c 32768 --color \
--chat-template chatml # 或 qwen、llama3、mistral 等（看模型支持）
--system "You are a helpful AI assistant. Answer in Chinese." \
--temp 0.7 --repeat-penalty 1.1
一句话生成（非交互，适合脚本）
echo "写一首关于月亮的五言绝句" | \
./llama-cli -m model.gguf -ngl 999 -fa --color \
-n 256 --temp 0.8 --top-p 0.9 -p
-p 表示把管道输入作为 prompt。
常用进阶组合（2026 年流行）
3. llama-server 使用教程（Web 界面 + API）
这是 2025–2026 年最推荐的日常使用方式。
启动基本服务器（带新版 WebUI）
cd ~/llama.cpp/build/bin
./llama-server \
-m ~/models/qwen3-14b-q5.gguf \
--host 0.0.0.0 --port 8080 \
-c 32768 -ngl 999 \
-fa --color --jinja \
--temp 0.7 --top-k 40 --top-p 0.9 --min-p 0.05
- 浏览器打开：
http://localhost:8080（或局域网 IP:8080）
- 支持功能（2026 年版）：
- 现代 Svelte WebUI
- 多会话 / 分支对话
- 上传 txt / pdf / 图片（视觉模型）
- OpenAI 兼容 API（
/v1/chat/completions 等）
- JSON schema / grammar 约束
- 并行推理（多用户同时问）
推荐启动组合（日常最舒服）
./llama-server \
-m model-q5_k_m.gguf \
--host 0.0.0.0 --port 8080 \
-ngl 999 -fa --jinja --reasoning-format deepseek \
-c 65536 --ubatch-size 1024 --batch-size 2048 \
--temp 0.75 --top-k 50 --top-p 0.92 --min-p 0.05 \
--repeat-penalty 1.05
--jinja：启用现代 jinja chat template（很多新模型必开）--reasoning-format deepseek：部分模型支持 <think>...</think> 标签
用 OpenAI 兼容 API 调用（python 示例）
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8080/v1",
api_key="sk-xxx" # 可以随便填，server 不校验
)
response = client.chat.completions.create(
model="local-model",
messages=[{"role": "user", "content": "今天天气怎么样？"}],
temperature=0.7,
max_tokens=512
)
print(response.choices[0].message.content)
4. 快速对比总结
| 项目 | llama-cli | llama-server |
|---|
| 主要用途 | 命令行快速测试、脚本、benchmark | 日常聊天、WebUI、多用户、API 集成 |
| 界面 | 纯终端 | 浏览器 WebUI（手机也很好用） |
| 多轮对话 | 支持（需正确 template） | 自动管理、多分支 |
| API | 无 | OpenAI 兼容 + 更多 endpoint |
| 资源占用 | 稍低 | 稍高（webui + 并行支持） |
| 推荐场景 | 开发调试、一次性生成 | 主力使用方式（几乎所有人最终都用这个） |