在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

ggml-org/llama.cpp

菜单

基本用法

相关源文件

本页面介绍了安装 llama.cpp 后如何使用其提供的基本命令行工具。内容涵盖了运行语言模型推理所需的常用操作，重点关注主要的命令行界面。有关安装说明，请参阅 安装；有关更高级的用法，请参阅 用户界面 下的特定工具部分。

命令行工具概述

llama.cpp 提供了多种用于不同目的的命令行工具

工具目的主要文件
llama-cli主要的文本生成和聊天界面examples/main/main.cpp
llama-server具有 OpenAI 兼容 API 的 HTTP 服务器examples/server/server.cpp
llama-perplexity使用困惑度衡量模型质量examples/perplexity/perplexity.cpp
llama-quantize将模型压缩到更小的尺寸examples/quantize/quantize.cpp
llama-embedding生成文本嵌入examples/embedding/embedding.cpp
llama-bench基准测试推理性能examples/llama-bench/llama-bench.cpp

让我们探索一下这些工具的基本用法。

模型准备

在运行推理之前，您需要一个 GGUF 格式的模型。您可以

  1. 使用 Hugging Face 下载预量化 GGUF 模型

  2. 使用转换脚本将模型从不同格式转换

  3. 将模型量化为更小的尺寸

来源：README.md255-279 examples/quantize/quantize.cpp105-135

使用 llama-cli 进行基本文本生成

用于生成文本的主要命令行界面是 llama-cli。以下是如何使用它进行基本文本补全：

使用 -p 或 --prompt 参数指定输入文本，并使用 -n 控制生成多少个 token。

来源：examples/main/README.md28-36 examples/main/main.cpp85-107

关键命令行参数

以下是 llama-cli 最重要的参数：

参数描述默认
-m, --model FNAMEGGUF 模型文件的路径-
-p, --prompt PROMPT输入提示-
-n, --n-predict N要预测的 token 数量-1 (无限)
-c, --ctx-size N上下文窗口大小4096
-t, --threads NCPU 线程数系统依赖
-ngl, --n-gpu-layers N要卸载到 GPU 的层数0
-sys, --system-prompt PROMPT聊天模式下的系统提示-
-cnv, --conversation启用对话模式汽车
-no-cnv禁用对话模式-

来源：examples/main/README.md85-98 examples/main/README.md185-190 examples/main/main.cpp45-51

命令行工作流程

来源：common/arg.cpp639-683 common/common.cpp1770-1811 tools/main/main.cpp200-250

交互式聊天模式

llama-cli 支持通过几种模式进行交互式对话

在交互模式下

  • 按 Enter 键让模型继续
  • 输入结束时使用 \ 进入新行
  • 输入结束时使用 / 提交而不换行
  • 按 Ctrl+C 可在模型生成时打断

来源：examples/main/README.md108-124 examples/main/main.cpp424-463

聊天模板系统

来源：examples/main/main.cpp267-278 examples/main/main.cpp282-312

运行 HTTP 服务器

通过网络提供具有 OpenAI 兼容 API 的模型

该服务器提供了与 OpenAI API 兼容的端点，包括：

  • 用于聊天的 /v1/chat/completions
  • 用于嵌入的 /v1/embeddings
  • 根 URL 处的简单 Web UI

来源：README.md343-396

衡量困惑度

llama-perplexity 工具通过计算困惑度（越低越好）来帮助评估模型质量。

它会输出困惑度分数，该分数估算了模型在预测测试文本方面的表现。

[1]15.2701,[2]5.4007,[3]5.3073,[4]6.2965,[5]5.8940,[6]5.6096,[7]5.7942,[8]4.9297, ...
Final estimate: PPL = 5.4007 +/- 0.67339

来源：README.md413-437 examples/perplexity/perplexity.cpp294-437

模型量化

llama-quantize 允许您将模型压缩到更小的尺寸，同时保持合理的质量。

可用量化类型包括：

类型描述近似大小质量影响
Q4_04 位量化4.34GB+0.47 ppl @ 8B
Q5_05 位量化5.21GB+0.13 ppl @ 8B
Q8_08 位量化7.96GB+0.003 ppl @ 8B
F1616 位浮点14.00GB+0.002 ppl @ 7B

来源：examples/quantize/quantize.cpp20-58 README.md276-278

生成嵌入

为语义搜索或其他应用创建文本嵌入

该工具提供可用于相似性匹配的嵌入，并支持向量归一化和导出为各种格式的选项。

来源：examples/embedding/embedding.cpp82-326

模型状态管理

对于长期运行的应用，您可以保存和加载模型状态

这允许

  • 将 KV 缓存和模型状态保存到磁盘
  • 加载之前的模型状态以继续生成
  • 在不同实例之间转移状态

来源： examples/save-load-state/save-load-state.cpp58-246

基本用法架构

来源： README.md32-54 common/common.cpp350-364 CMakeLists.txt171-198

常见问题与解决方案

问题可能解决方案
内存不足使用更量化的模型（例如 Q4_0 而不是 F16）
生成速度慢使用 -t 增加线程数或使用 -ngl 启用 GPU
上下文长度超出使用 -c 增加上下文大小（如果模型支持）
重复输出调整采样参数（温度、top_p 等）
未找到模型检查路径或尝试使用 -hf 选项下载

来源： examples/main/README.md108-127 examples/main/README.md160-179

下一步

在熟悉了基本用法后，您可能还想探索