llama-cli

llama-cli¶

• 命令行工具

1.快速上手¶

Quick Start

（1）一次结束¶

• 回答完prompt中的问题后，就会停止运行

llama-cli \
    --model ~/02Software/llama.cpp-master/models/DeepSeek-R1-Distill-Qwen-7B-GGUF/DeepSeek-R1-Distill-Qwen-7B-Q4_K_M.gguf \
    --prompt '<｜User｜>What is 1+1?<｜Assistant｜>' \
    --cache-type-k q8_0 \
    --threads 8 \
    --n-gpu-layers 8 \
    -no-cnv

# 如果模型放在了llama.cpp的models文件夹中，可以如下操作
--model models/DeepSeek-R1-Distill-Qwen-7B-GGUF/DeepSeek-R1-Distill-Qwen-7B-Q4_K_M.gguf

参数介绍：

--prompt '<｜User｜>What is 1+1?<｜Assistant｜>'

• 指定初始对话提示，其中包含特殊的对话标记 <｜User｜> 和 <｜Assistant｜>。
• 这种格式有助于模型区分用户输入和助手回复，适用于对话场景的提示模板

-no-cnv

• 禁用 自动会话模式（auto conversation mode）。
• 如果启用 自动会话模式，程序可能会根据上下文自动调整对话格式；而这里通过该参数关闭此功能，能使得模型严格按照提供的 prompt 进行处理。

--threads 8

• 设置程序运行时使用 16 个 CPU 线程
• 充分利用多核 CPU 的计算能力，从而**提高推理速度**。

--n-gpu-layers 8

• 这个参数只有在你的系统中有 GPU、同时配置了 GPU 运行环境时，才会生效

• 如果显存足够（例如 RTX 4090 24GB），可以使用20，即将模型的 20 层卸载到 GPU 上计算，以加速推理。

• 对于 GeForce RTX 2060 Mobile 这种显存相对有限（一般为 6GB 左右）的 GPU，建议从较低的层数开始尝试。例如，可以先设置为 8 层

• 补充：如果threads 和n-gpu-layers同时启用，就是 CPU+GPU 混合加速了

--cache-type-k q8_0

• 指定模型内部 K 缓存（键/值缓存）的量化类型为 q8_0。
• 这种设置用于**加速推理过程**，特别是在量化模型中，通过优化缓存数据的存储和访问

补充：--cache-type-k¶

• --cache-type-k 参数用于设置模型在推理过程中生成的 key/value 缓存的数值精度。这里的缓存主要在 Transformer 模型的自注意力机制中使用，用来保存中间计算结果，以加速后续计算。

• 具体说明如下：

1.常见设置：

• f32（32 位）：使用浮点 32 位精度的缓存，计算最精确，但占用显存较高，适合高端硬件（例如 RTX 4090）。
• q8_0（8 位）：这是一个常见折中的选择，可以在较低的内存占用下保持较好的精度，适合大部分用户（例如 RTX 2060 Mobile）。
• q4_0（4 位）：最节省内存，但计算过程中可能会带来更大的量化误差，适合显存极度紧张的场景。

2.缓存精度和模型权重量化是独立的：

这也是模型与缓存精度可以不对齐的原因

• 模型权重量化（Q4）：

• 模型文件名中的 Q4_K ，表示模型权重在存储时采用了 4 位量化

• 模型在训练和存储时经过量化（比如 Q4），主要是为了减小模型体积和内存占用。

• 缓存精度（--cache-type-k）：

• 这个参数设置的是，在推理过程中模型内部生成的 key/value 缓存的精度。

  • 缓存 用于存储中间计算结果，它的精度可以独立于模型权重的量化方式来设置。

• 推理时的缓存精度，主要影响计算过程中的数值稳定性和精度

  • 所以使用 更高精度的缓存( 如 q8 或 f32），可以在计算过程中“补偿”模型权重量化带来的精度损失，从而获得更准确的推理结果。

• 所以，即便模型权重是 Q4 量化的，你仍然可以选择用更高精度（比如 Q8 或 f32）来计算缓存、存储中间计算结果，以在推理时获得更高的数值精度。

3.选择建议：显卡好上 32，其次 8，最后 4

• 如果硬件资源充足，可以选择更高精度的缓存（f32 或 q8_0），以提升推理质量。
• 对于显存有限的设备，q8_0 是较好的平衡选项。
• 只有在极端显存受限的情况下才考虑使用 q4_0

（2）对话模式¶

• 允许用户与模型持续交互

llama-cli \
    --model ~/02Software/llama.cpp-master/models/DeepSeek-R1-Distill-Qwen-7B-GGUF/DeepSeek-R1-Distill-Qwen-7B-Q4_K_M.gguf \
    -cnv \
    --chat-template gemma \
    --cache-type-k q8_0 \
    --threads 8 \
    --n-gpu-layers 8

• cnv开启对话模式
• chat-template指定聊天模版

2.常用选项¶

options

-m FNAME, --model FNAME

• 指定 LLaMA 模型文件的路径
• 例如 models/gemma-1.1-7b-it.Q4_K_M.gguf
• 若设置了--model-url，则可从中推断。

-mu MODEL_URL, --model-url MODEL_URL

• 指定用于下载模型文件的远程 HTTP URL【了解，一般都是下载到本地后-m】
• 例如：https://huggingface.co/…。

-i, --interactive

• 以交互模式运行程序，允许用户直接输入并实时获取响应。

-n N, --n-predict N

• 设置生成文本时预测的标记数，从而控制生成文本的长度。

-c N, --ctx-size N

• 设置提示上下文的大小，默认值为 4096；
• 若模型支持更长的上下文，增大此值可获得更好的效果。

-mli, --multiline-input

• 允许用户输入或粘贴多行内容，而不必在每行末尾添加特殊字符。

-t N, --threads N

• 设置生成文本时使用的线程数
• 建议设置为系统物理 CPU 核心数，以获得最佳性能。

-ngl N, --n-gpu-layers N

• 当启用 GPU 支持时，该选项**允许将部分模型层卸载到 GPU 上以加速计算，通常能提升性能**。

3.交互选项¶

控制与 LLaMA 模型的交互方式，定制对话和文本生成过程

(1) 输入提示词¶

--prompt PROMPT

• 直接提供一个提示符作为命令行选项

--file FNAME

• 提供一个 包含一个或多个提示词的文件。

(2) 交互模式¶

-i,--interactive

• 启动交互模式，允许用户实时对话或向模型提供指令。

--interactive-first

• 会在开始文本生成之前立即等待用户输入。

-cnv, --conversation

• 在对话模式下运行，使用默认聊天模板，不显示特殊令牌和前后缀（默认：false）。

--color

• 启用彩色输出，方便区分提示、用户输入和生成的文本。

(3) 反向提示¶

-r PROMPT, --reverse-prompt PROMPT

• 反向提示是使用 LLaMA 模型创建类似聊天的体验的一种强大方法，它在遇到特定文本字符串时暂停文本生成，并切换到交互模式, 这有助于创建更具交互性和对话性的体验。
• 例如，-r "User:" 可用于在轮到用户发言时，跳回到对话中。
• 但是，当以空格结尾时，反向提示符不起作用。
• 克服这个限制，可以使用--in-prefix标志在反向提示符后，添加一个空格或任何其他字符

--in-prefix

• 作用：
• 用于在用户接下来的输入的最前面，添加一个预设的字符串，通常是一个空格。
• 为何需要：
• 在使用 **反向提示**时，系统会在检测到特定提示（例如 "User:"）后,暂停生成并切换到交互模式。
• 如果反向提示后直接跟着用户的输入，可能会导致提示和输入混在一起，或因反向提示以空格结尾，而无法正确触发。
• 而通过 --in-prefix，可以在用户接下来的输入前，自动添加一个空格（或其它字符），确保反向提示和用户输入之间，有明显的分隔。
• 示例说明：

./llama-cli -r "User:" --in-prefix " "

当模型生成到 "User:" 时，会触发交互模式，并自动在用户输入前添加一个空格，使输入显示为 "User: "，从而避免混淆和触发问题。

--in-suffix

• 在用户输入结束后添，加一个指定的后缀字符串
• 通常用来显示诸如 "Assistant:" 的提示，提示接下来是模型的回复。
• 示例说明：

./llama-cli -r "User:" --in-prefix " " --in-suffix "Assistant:"

(4) 聊天模板¶

反向提示的更进一步，集成了很多反向提示词

--chat-template JINJA_TEMPLATE

• 设置自定义的 Jinja 聊天模板，支持多种预定义模板，如 llama2, gemma, vicuna, 等。
• 如果启用了 --in-prefix 或 --in-suffix，则会禁用聊天模板

4.上下文配置¶

（1）前置知识¶

• “上下文”是指模型在生成文本时，能处理的输入信息的范围。可以从两个方面来理解：

1.输入的令牌（Tokens）：LLaMA 模型在生成文本时，将输入文本分解为多个“token”，这些 token 是构成句子的基本单元（通常是词或词的一部分）。

• 模型有一个最大长度限制，即它只能处理一定数量的 token（例如，4096 个 token）。
• 当输入文本超过这个长度时，模型只能关注最近的这些令牌，或者模型内部会重置，从而可能丢失对话或指令开始时的信息。

2.提示的上下文（Prompt Context）：提示上下文是指你提供给模型的初始输入，也可以是一个问题、一段对话的开头或其他信息。这个提示文本可以被分解为 token，在模型生成文本时，模型会根据这些 token 来理解你的需求并进行生成。

• 上下文大小设置 (--ctx-size) ，就是控制这个“提示”分解时的最大 token 数量。

• 举个例子：

• 如果你给模型一个长段文字或对话，模型会从中提取并处理一定数量的 token（比如最多 4096 个）。如果文字超过了这个限制，模型会丢弃一些最早的部分，只记住最近的部分。

• 你可以通过调整 --ctx-size 来决定模型能够处理的上下文大小。如果模型是微调的，且支持更长的上下文，你可以设置更大的上下文来提高效果。

• 简而言之，上下文就是模型在生成文本时“记住”并考虑的信息量，它由你输入的文本（令牌）组成，并影响模型生成的连贯性和一致性

（2）选项¶

-c N，--ctx-size N

• 作用：设置提示上下文大小
• 默认值：4096，0 =从模型加载
• 如果模型本身支持更长的上下文，增加该参数的值可获得更好的长文本生成效果。

**--rope-scale N **

• 作用：扩展上下文
• N 是微调模型使用的线性比例因子。
• 部分微调模型通过缩放 RoPE ，扩展了上下文长度
• 例如，如果原始预训练模型的上下文长度（最大序列长度）为 4096（4k），而微调模型的上下文长度为 32 k，即 缩放因子为 8
• 这时，应该同时设置--ctx-size为 32768（32 k）和--rope-scale为 8，来让模型工作

--keep N

• 作用：是否保留原始提示
• 该参数允许在模型重置上下文时，保留初始提示中的部分 token，以确保与最初指令或话题的连贯性。默认值为 0（不保留），设置为 -1 则表示保留所有初始 token。
• 具体使用：
• 保留原始提示：
  • 适用场景：当你希望模型在长对话或长文本生成过程中，始终参考最初的指令、设定或背景信息时。这样，即使后续输入填满了上下文，模型仍然能保持对初始要求的记忆，确保生成的文本与原始主题保持一致。
  • 如何设置：可以将 --keep 设为正数（比如保留前 100 个 token）或者设置为 -1（保留所有初始 token）。
• 不保留原始提示：
  • 适用场景：如果你希望模型完全关注最新的上下文信息，或者初始提示在当前生成过程中已不再关键，这时可以不保留初始提示。默认值 0 就是不保留任何 token。
  • 考虑因素：保留 token 会占用部分上下文窗口空间，如果初始提示对当前生成已无重要作用，保留可能反而会减少模型处理新信息的空间。
• 总的来说，是否保留原始提示取决于对连续性与新信息关注的需求：
• 如果需要持续参考最初的指令或背景，建议保留（设置非 0 的值）；
• 如果只关注当前对话的最新内容，则可不保留（默认 0）

5.文本生成控制¶

• 该配置用户控制文本生成过程，并根据需要微调所生成文本的多样性、创造性和质量

要预测的令牌数量¶

-n N, --predict N

• 作用：设定生成文本时，预测的令牌数量。预测令牌数量
• 默认：-1 表示无限生成；-2 表示生成直到上下文填满。
• 何时使用
• 需要生成固定长度文本时，可指定正整数。
• 若希望文本持续生成（尽管上下文有限），可用 -1
  • 注意，上下文满时可能会暂停并丢弃部分早期令牌
• 若不希望在上下文填满后出现停顿，则可用 -2，让生成在达到上下文上限时立即停止。

温度¶

--temp N

• 作用：控制生成文本的温度。
• 较高值（如 1.5）使输出更随机、富有创造性；较低值（如 0.5）使输出更确定和保守；0 则生成完全确定的文本。
• 何时使用
• 希望文本更加多样和有创意时，可调高温度；
• 需要精确、可控的输出时，调低温度。

重复惩罚¶

简单重复惩罚¶

--repeat-penalty N

• 作用：控制重复 token 被惩罚的力度【控制惩罚力度】

• 有助于防止模型生成重复或单调的文本

• 较高的值（例如，1.5)将更强烈地惩罚重复，而较低的值（例如，0.9)会更加宽容。

• 默认 1.0，1.0 表示不启用惩罚；

• 何时使用

• 当生成的内容出现重复或单调时，适当调高重复惩罚值（例如 1.5）来抑制重复；
• 若允许一定重复，保持默认或稍低值即可。

--repeat-last-n N

• 作用：决定在历史上下文中，检查多少个最近生成的 token 来判断是否重复【控制惩罚范围】

• 即 N 控制检查的范围

• 值较大，将在生成的文本中向后查看；而值较小，将仅考虑最近的标记。

• 默认值为 64(查看最近 64 个)，值为 0 时禁用惩罚，值为-1 时将令牌数设置为等于上下文大小（ctx-size）

DRY 重复惩罚¶

作用：通过根据令牌最近的使用模式，对重复内容施加**指数型惩罚**，降低长距离重复并保持全局连贯。

• --dry-multiplier N：设置 DRY 采样乘数
• 控制 DRY 采样效果的**强度**
• 默认 0.0，值为 0.0 将禁用 DRY 采样，而值越大，其影响越大。典型的推荐值为 0.8
• --dry-base N：设置 DRY 采样基值
• 默认 1.75
• 设置 DRY 采样中指数惩罚计算的基值。更高的值导致更积极的惩罚重复
• --dry-allowed-length N：设置 DRY 采样的允许长度
• 默认 2
• 设置 不受惩罚的重复序列 的最大长度
  • 短于或等于此长度的重复不会受到惩罚，允许短短语或常见单词的自然重复
• --dry-penalty-last-n N：为最后 n 个 token 设置 DRY 惩罚【控制采样范围】
• 默认-1，即上下文大小
• 和--repeat-last-n N类似，值为 0 时禁用惩罚，值为-1 时将令牌数设置为等于上下文大小（ctx-size），使用正值时，将考虑限制为最近令牌的特定数量

• --dry-sequence-breaker STRING：为干取样增加一个顺序断路器。

• 使用此选项 可清除默认的分隔符，包括：['\n', ':', ' " ', '*']

• 如果提供字符串“none”，则不使用顺序断路器。

• 可多次使用，以添加多个顺序断路器

• 何时使用

• 当生成长文本且容易出现重复时，启用 DRY 采样可帮助减少冗余；
• 适合需要细致控制重复现象的场景。

异同与何时使用¶

• 重复惩罚 和 DRY 重复惩罚 都是为了解决文本生成中的重复问题
• 但它们在原理和使用场景上有所不同

1.重复惩罚

• 原理：
• 在生成时，检查最近一段文本（由 --repeat-last-n 控制）中已经出现过的令牌，并对它们施加一个固定的惩罚（由 --repeat-penalty 控制）。
• 如果某个令牌已经出现过，则在计算其生成概率时按比例降低，从而减少重复出现的可能性。
• 特点：
• 机制简单、直观。
• 适合处理短距离内的重复问题，比如避免连续重复某个词或符号。
• 对于较长文本生成时，可能只关注最近部分，无法完全防止全局层面的冗余。
• 使用场景：
• 当遇到短文本或局部上下文中明显重复时，直接调高 --repeat-penalty（如 1.5）即可。

2.DRY 重复惩罚

• 原理：
• “DRY”代表“Don't Repeat Yourself”，该机制不仅检查重复的令牌，还结合最近使用模式和上下文分布对重复内容施加**指数型惩罚**。
• 使用多个参数（如 --dry-multiplier、--dry-base、--dry-allowed-length、--dry-penalty-last-n 和 --dry-sequence-breaker）来更细致地控制对重复内容的惩罚力度和范围。
• 特点：
• 更为复杂，能够处理长距离重复和更复杂的冗余模式。
• 除了简单地降低重复令牌的概率，还能通过指数方式根据重复程度进行更精细的调整，保持全局连贯性。
• 对参数的调试要求较高，需要根据具体生成场景进行细致调整。
• 使用场景：
• 当生成长篇或复杂文本时，简单的重复惩罚可能不足以防止内容冗余，此时可以启用 DRY 重复惩罚。
• 适合在需要全局连贯性和减少长距离重复的场合，比如创作小说、报告或其他大段落文本时。

3.总结

• 简单重复问题：
• 使用 重复惩罚（配合 --repeat-last-n），主要解决局部和短距离的重复，设置简单，开销较低。
• 复杂/长距离重复问题：
• 使用 DRY 重复惩罚，能够对整个生成过程中的重复进行更精细、动态的控制，适用于需要更高质量、连贯性更强的长距离长文本的生成。

采样方法配置¶

Top-K 采样¶

--top-k N

• 作用：限制模型选择的下一个令牌范围，只有概率最高的 K 个令牌可以被选择
• 默认：40。
• 调大 K 值可增加多样性，调小 K 值则使输出更保守。
• 何时使用：
• 避免生成无意义的词或字符：例如，生成产品描述时，如果 K 值较低（比如 K=10），模型只会从最常见的词中选择，减少出现无关的或错误的单词。
• 创造性写作：如果你希望生成更具创意和多样性的内容，可以增大 K 值（如 K=100），允许模型从更多可能的词汇中选取，使得输出更加开放和不拘一格。

Top-P 采样¶

又称 核心采样，即控制核心内容的范围

--top-p N

• 作用：限制令牌选择范围，令牌的累计概率之和达到 p。
• 简单来说，Top-P 采样会“积累”令牌的概率，直到满足阈值 p。
• 默认：0.9。
• 提高 top-p（例如 0.95）可以生成更丰富的文本，降低则生成更集中和保守的文本。
• 何时使用：
• 需要平衡 多样性和连贯性时：例如，在生成对话时，--top-p常常设置为 0.9 或 0.95，以保证对话自然且有创造力，同时不会偏离上下文太远。
• 生成文档或长文本时：如果要生成较长的文本，如技术文档或报告，可以将 top-p 调低（如 0.8），确保文本内容连贯而不失去逻辑。

最小 P 采样¶

--min-p N

• 作用：设定令牌选择的最低概率阈值，只有概率高于该值的令牌才会被选中
• 默认 0.1
• 何时使用：
• 需要严格筛选低概率令牌时：例如，当你在生成歌词或广告词时不希望使用低概率且可能是无关的词，设置较高的 min-p（如 0.2）可以确保生成的内容更相关，避免不自然的词汇。
  • 是 Top-P 采样的替代方法，旨在确保质量和品种的平衡
• 与 Top-P 结合使用：例如，可以使用 Top-P 设置为 0.9 来控制核心内容的范围，再设置min-p=0.2来避免出现不相关或冷门的词汇（？存疑，官方文档没这样说）

局部典型抽样¶

--typical N

• 作用：启用局部典型抽样，来控制生成文本的典型性和多样性
• 接近 1 的值将促进更多上下文一致的令牌，而接近 0 的值将促进更多不同的令牌。值等于 1 时(默认)禁用局部典型采样。
  • 若要求严格的上下文一致性，可保持或接近 1.0。
  • 调低会增加创造性，但过低会导致前后不连贯
• 何时使用：
• 需要在创造性和一致性之间取得平衡时：例如，生成短篇故事时，可以将 --typical 设置为 0.9，这样生成的文本会更加丰富且具有一定的创造性，同时不会偏离故事的主旨。
• 对话系统或互动性内容：如果你希望对话既自然又不失创造性，可以将该值调低，确保内容既有创新又能保持上下文的相关性

Mirostat 采样¶

--mirostat N, --mirostat-lr N, --mirostat-ent N

• 作用：动态调节生成过程中的困惑度，保持输出质量与多样性之间的平衡。
• --mirostat：启用模式（0 禁用，1 = Mirostat，2 = Mirostat 2.0）；
• --mirostat-lr：学习率，默认 0.1；
• --mirostat-ent：目标熵，默认 5.0。
• 何时使用：
• 当需要主动控制生成质量、避免重复或混乱时，使用 Mirostat 算法；
• 生成复杂文本时：例如，在写作复杂的论文或技术文章时，可以使用 Mirostat 采样。通过调节熵值（--mirostat-ent）来保持输出的连贯性，同时避免过度重复。
• 需要平衡创新和一致性的任务：例如，在创作小说或剧本时，Mirostat 可以帮助控制多样性，同时避免生成不符合情节的内容。

XTC 采样¶

--xtc-probability N, --xtc-threshold N)

• 作用：通过概率设置，移除概率较高的令牌，从而打破常见写作模式和重复陈词滥调。
• 利用xtc-probability的机会，搜索概率为xtc-threshold及以上的令牌，然后删除所有这样的令牌
• 默认：xtc-probability 为 0.0（禁用），xtc-threshold 默认 0.1。
• 何时使用：
• 创意生成：例如，当你在生成小说的创意部分时，希望避开常见的词汇或表达方式，可以开启 --xtc，去除常见的、频繁出现的高概率词汇，创造更新颖的情节和表达。
• 避免过于公式化的内容：例如，在广告语生成时，使用 XTC 采样可以帮助避免生成过于传统的、看起来像模板化的广告语。
• 使用时建议的采样器组合：
• Min-P + XTC，其默认设置为： --sampling-seq mx --min-p 0.02 --xtc-probability 0.5

Top-nσ 抽样¶

--top-nsigma N

• 作用：基于 pre-softmax logits 的统计分布，仅从离最大 logit 在 n * σ 范围内的令牌中采样。
• 没有复杂的概率操作，它直接在 pre-softmax logit 上有效地过滤令牌。
• 默认值为-1 ，表示禁用。
• 值越高（例如，5) 将考虑更多噪声令牌，而较低值（例如，1)将集中在采样空间中信息量更大的区域。
• 何时使用：
• 在高温度下稳定输出：例如，在生成诗歌时，你可能希望模型有一定的创造性，但仍要保持较高的连贯性。此时，通过调整 Top-nσ（例如 n=2）可以在保证创造性的同时保持合理性，避免生成过于无序或偏离主题的内容。
  • 在需要保持采样空间稳定，特别是在高温度下进行推理任务时；
• 推理任务或求解任务：当进行推理任务时，需要稳定性和精确性，Top-nσ 可以帮助保持预测结果在合理范围内，同时避免偏离过远
  • 调节 n 值可以控制输出的多样性和专注性，较低值（如 1）聚焦于信息量更大的区域。

Logit 偏倚¶

-l TOKEN_ID(+/-)BIAS, --logit-bias TOKEN_ID(+/-)BIAS)

• 作用：允许你在生成文本时手动调整特定令牌（token）的生成概率。
• 模型在输出文本前，会为每个可能的令牌计算一个分数（称为 logit），这些分数经过 softmax 后转换为概率。
• 通过 Logit Bias，你可以对某个令牌的 logit 分数进行加减操作，从而改变它最终被选中的概率
• 具体说明
• 增加生成概率：如果你希望某个令牌更容易被选中，可以给它一个正的 bias。
  • 例如：--logit-bias 15043+1
  • 这意味着 token ID 为 15043（假设对应 "Hello"）的 logit 将增加 1，从而提升它的生成概率。
• 降低生成概率：如果你希望某个令牌不那么容易出现，可以给它一个负的 bias
  • 例如：--logit-bias 15043-1
  • 这会降低 token ID 15043 的生成概率。
• 完全禁止生成：如果你想确保某个令牌永远不出现，可以将 bias 设置为负无穷大。
  • 例如：--logit-bias 15043-inf
  • 这样 token ID 为 15043 的令牌将被完全屏蔽，不会在生成过程中被选中。
• 何时使用：
• 定制化文本生成：
  • 如果你正在生成某类文本，而某个词语或符号不应出现（比如某些敏感词或错误格式），可以使用 logit bias 将它们的生成概率降低到接近 0 或直接屏蔽掉。
  • 简单来说，屏蔽某些敏感词时用
• 避免模型常见错误：
  • 在 LLaMA 模型推理中，经常会看到一些 LaTeX 代码的意外生成。
  • 可以通过设置相关 token（例如表示 \begin 或 \end 的 token）的 bias 为负无穷大，来避免这些不需要的代码出现。
• 增强特定风格：
  • 如果你希望生成的文本中多出现某个特定的词汇（比如品牌名称或特定术语），可以给这些词汇相应的 token 设置一个正的 bias，提高它们的出现概率。

seed¶

(-s SEED, --seed SEED)

• 作用：设置随机数生成器种子，从而使生成过程可重复。
• 默认：-1（表示随机种子，每次运行结果不同）。
• 何时使用：
• 通过设置特定的种子值，您可以在具有相同输入和设置的多次运行中获得一致且可重现的结果。
  • 这有助于测试、调试或比较不同参数配置对生成文本的影响，以查看它们何时出现分歧
  • 从而测试出适合机器的最佳参数
• 若希望每次生成都有新变化，则使用默认的随机种子。

6.性能调整和内存选项¶

线程数¶

-t N, --threads N 、 -tb N, --threads-batch N)

• 参数解释:
• -t N：设置模型生成文本时使用的线程数。
• -tb N：设置处理 prompt 和 batch 数据时，使用的线程数。
• 使用场景:
• 优化生成速度 ( -t N ): 例如，在快速生成文本摘要、代码片段或者进行实时对话的应用中，设置合适的线程数可以显著减少生成时间。 建议将其设置为物理 CPU 核心数，而非逻辑核心数（可以理解为实际的物理核心数）。
• 提升 prompt 处理速度 ( -tb N ): 当处理长篇 prompt 时，或者在批处理模式下处理大量 prompt 时，增加 -tb N 的值可以更快地完成 prompt 的解析和预处理。某些情况下，-tb N 设置为比 -t N 更大的值是有益的。
• 场景示例：
  • 文本摘要服务： 一个在线文本摘要服务需要快速处理用户提交的文本并生成摘要。合理设置 -t N 和 -tb N 可以保证服务的响应速度。
  • 代码生成助手： 一个 IDE 插件，根据用户的自然语言描述生成代码。快速的 prompt 处理和代码生成至关重要，因此需要优化线程数。
  • 批处理数据分析： 需要用 LLM 对大量的文档进行分析，可以增大 tb 来加速 prompt 的处理。

内存锁定¶

--mlock

• 参数解释: 将模型锁定在 RAM 中，防止操作系统将其换出到硬盘。
• 使用场景:
• 需要极低延迟的场景: 在对延迟有严格要求的应用中（例如实时翻译、语音助手），避免模型被换出，可以保证每次访问都能立即响应。
• 充足的 RAM: 如果你的机器有足够的 RAM 来完全容纳模型，并且运行其他程序后仍然有剩余，那么使用 --mlock 是一个不错的选择。
• 场景示例：
• 实时语音助手： 语音助手需要快速响应用户的语音指令，模型被换出导致的延迟是不可接受的。
• 高频交易系统： 某些量化交易会利用 LLM，此类场景对延迟非常敏感。

禁止内存映射¶

(--no-mmap)

• 参数解释: 禁用内存映射，强制将整个模型加载到 RAM 中。
• 使用场景:
• RAM 不足，且出现页面错误: 如果你的 RAM 略小于模型大小，且在运行过程中频繁出现页面错误（pageout），可以尝试禁用 mmap。
• 避免页面错误： 禁用 mmap 可能会减少 pageout。
• 注意事项:
• 如果模型大于你的总 RAM，禁用 --no-mmap 会导致模型无法加载。
• 禁用 --no-mmap 会显著增加模型加载时间。

NUMA 支持¶

前置知识¶

• NUMA 架构原理: 在多处理器系统中，NUMA 是一种内存架构，其中每个处理器节点（Node）都拥有自己的本地内存。访问本地内存的速度远快于访问其他节点的远程内存。

• 这种架构旨在减少内存访问延迟，提高系统整体性能。

• NUMA 的核心问题: 是内存访问的非一致性。

• 不同处理器访问不同内存区域的延迟不同，需要针对性优化。

• NUMA 优化原则: 尽量将计算任务和数据放置在同一个 NUMA 节点上，减少跨节点的数据传输。

选项配置¶

• 如果你的服务器是 NUMA 架构、有多个 NUMA 节点，并且希望优化内存访问性能，可以使用这些选项

--numa distribute

• 实现: 将进程的线程 affinity ，设置为**均匀分布**在所有 NUMA 节点的核心上。

• 这通过操作系统提供的 API (如 sched_setaffinity 在 Linux 上) 实现。

• 目标: 尝试均衡地利用所有 NUMA 节点的内存带宽。

• 适用场景分析:

• 当模型数据和计算任务可以在所有 NUMA 节点上均匀分布时，--numa distribute 能够最大化内存吞吐量。

• 但如果数据局部性较强，跨 NUMA 节点的数据访问会引入额外的延迟。

• 潜在问题: 可能增加跨 NUMA 节点的数据传输开销，特别是当工作负载对内存位置敏感时。

--numa isolate

• 实现: 将进程的所有线程绑定到进程启动时所在的 NUMA 节点。
• 目标: 尽可能减少跨 NUMA 节点的数据访问，最大化本地内存访问效率。
• 适用场景分析: 适用于模型数据和计算任务可以完全容纳在单个 NUMA 节点上的情况。能够提供最低的内存访问延迟。

--numa numactl

• 实现: 利用 numactl 命令行工具，提供对线程 affinity 的精细控制。

• 需要在启动 llama.cpp 之前，使用 numactl 命令设置线程与核心的映射关系。

• 目标: 根据具体的应用场景和硬件拓扑，实现最佳的资源分配。

• 适用场景分析: 最灵活的选项，可以针对复杂的 NUMA 拓扑结构和特定的工作负载进行优化。

• 例如:

  • 可以将计算密集型线程，绑定到具有高速缓存和高内存带宽的节点
  • 将数据传输线程，绑定到具有高速网络连接的节点。

• sh # 将 llama.cpp 绑定到 NUMA 节点 0 和 1 的核心 numactl --cpunodebind=0,1 --membind=0,1 ./llama-cli -m model.bin -t 16 --numa numactl

批量大小¶

Batch Processing 的本质: Batch Processing 是一种利用矩阵运算并行性的技术。

• 通过将多个输入样本组合成一个批次，可以充分利用 GPU 或 CPU 的并行计算能力，提高计算效率

**-ub N, --ubatch-size N **

• 定义: 硬件层面上，一次处理的最大 token 数量（物理批处理大小）
• 默认值：512
• 增加此值可以提高 提示处理 的性能，但会增加内存使用量
• 技术解释: ubatch-size 决定了在模型内部张量运算中，使用的最小矩阵维度。

**-b N, --batch-size N **

• 定义: 软件层面上，呈现给用户的批处理大小（逻辑批处理大小）
• 可以理解为将多个物理批次，组合成一个逻辑批次。
• 默认值：2048

• 技术解释:

• 在多 GPU pipeline 并行中，每个 GPU 负责模型的一部分计算。

• 增大 batch-size 可以让每个 GPU 处理更多的数据，从而提高 GPU 的利用率和整体吞吐量，减少 GPU 之间的通信开销。
  • 将该值增加到 物理批处理大小 的值以上，可以提高即时处理性能

• 但过大的 batch-size 可能导致 OOM 错误或增加延迟。

• 使用场景:

• 提升 prompt 处理速度: 增加这两个值，通常可以加快 prompt 处理速度。
• 多 GPU 并行: 当使用多个 GPU 进行流水线并行时，-b N 可以设置为大于 -ub N 的值，以提升性能。
• 资源受限环境: 需要根据实际的显存或内存大小，调整到合适的值， batch-size 过大可能导致 OOM 错误或增加延迟。
  • 要确保 ubatch-size 和 batch-size 不超过硬件的内存限制
• 场景示例：
• 高并发 LLM 服务： 如果你的 LLM 服务需要同时处理大量用户的请求，增加批量大小可以提高吞吐量。

提示缓存¶

--prompt-cache FNAME

• 参数解释: 将初始 prompt 的模型状态，缓存到文件中，以便下次快速加载。
• 使用场景:
• 重复使用相同或相似 prompt: 如果你经常使用相同的 prompt，或者只是在 prompt 的末尾添加新的内容，可以使用 prompt 缓存来显著减少启动时间。
• 场景示例：
• 聊天机器人： 在聊天机器人的场景中，**用户的对话历史**可以作为 prompt 的一部分。
  • 如果每次都从头开始处理整个对话历史，会非常耗时
  • 使用 prompt 缓存可以避免重复计算。
• 注意：恢复缓存提示并不意味着恢复会话保存时的确切状态（不能完全保证一样的意思）
• 因此，即使指定了特定的种子，也不能保证获得与原始生成相同的令牌序列。

7.语法和 JSON 模式¶

--grammar GRAMMAR、 --grammar-file FILE 、 --json-schema SCHEMA)

• 参数解释:
• --grammar: 指定一个语法，约束模型输出的格式。
• --json-schema: 指定一个 JSON 模式，约束模型输出为有效的 JSON 结构。
• 使用场景:
• 结构化数据生成： 如果你需要模型生成特定格式的数据（例如 JSON、XML），可以使用这些选项。
• 数据验证： 确保模型输出的数据符合预定义的格式规范。
• 场景示例:
• API 数据生成： 一个应用程序需要从 LLM 生成符合特定 API 接口规范的 JSON 数据。
• 游戏 AI： 游戏 AI 需要生成符合游戏逻辑的指令，可以使用语法来约束 AI 的输出。

8.LoRA 适配器【重要】¶

• LoRA 适配器是一种强大的工具
• 它可以在不改变原始模型权重的情况下，修改或微调基础模型的行为

8.1 简单适配器¶

--lora FNAME

• 作用：当使用 --lora参数时，每个适配器都会以默认的 1.0 缩放因子被应用

• 应用场景：想进行单一的专门化适配，比如添加特定领域的知识，或改变模型的写作风格

• 语言专业化应用

  • 通过同时应用语言和领域适配, 更好地处理中文技术文档任务

./llama-cli -m models/llama-7b.gguf --lora chinese_support.gguf --lora technical_vocabulary.gguf

8.2 缩放适配器¶

--lora-scaled FNAME

• 作用：选项允许你通过指定缩放因子，来**控制**每个适配器对模型输出的**影响程度**

• 可以与--lora混合使用(--lora的缩放因子会固定为 1)

• 并且可以重复使用多个适配器

• 应用场景

• 多领域知识平衡

  • 模型能够处理医疗文档的同时，保持一定的法律术语理解能力的场景。
  • 通过缩放因子，可以很好地平衡不同领域的影响力

./llama-cli -m models/llama-7b.gguf --lora-scaled medical_terms.gguf 0.7 --lora-scaled formal_writing.gguf 0.3

• 风格与内容混合
  • 用于生成创意内容的同时，保持适度的正式语气
  • 特别适合专业博客写作或营销内容创作

./llama-cli -m models/llama-7b.gguf --lora creative_writing.gguf --lora-scaled formal_tone.gguf 0.3

8.3 技术要点¶

(1) 格式要求¶

• 所有 LoRA 适配器必须是 GGUF 格式。
• 如果是 Hugging Face 格式的适配器，需要先进行转换：

python convert-lora-to-gguf.py --input-dir path/to/hf/lora --output-file converted_lora.gguf

(2) 内存效率¶

• 与早期版本不同，现在的 llama.cpp 会将 LoRA 适配器与主模型分开加载，并在推理过程中应用。这带来了几个重要优势：

• 基础模型在内存中保持不变

• 可以在不重新加载主模型的情况下，加载和卸载多个适配器

• 完全支持内存映射（mmap），提高了内存使用效率

(3) 渐进式增强¶

• 可以叠加多个适配器，来逐步增强模型的能力：

./llama-cli -m models/llama-7b.gguf \
  --lora base_enhancement.gguf \
  --lora-scaled domain_specific.gguf 0.8 \
  --lora-scaled style_adjustment.gguf 0.4

• 这种分层方法允许你构建复杂的适配组合，同时通过缩放因子保持对模型输出的精确控制。
• 每个适配器都可以专注于特定方面的增强，而它们的效果可以通过缩放因子进行精细调整。
• 这种方式特别适合需要在多个维度上 同时优化模型表现 的复杂应用场景。

9.其他选项¶

9.1 帮助¶

-h, --help

• 通过这个命令，你可以随时查看最新的参数列表和默认值，确保你使用的是最新的配置选项。

9.2 提示词显示控制【重要】¶

--verbose-prompt

• 在生成过程中，显示完整提示词，适合调试和优化提示词的场景

--no-display-prompt

• 隐藏提示词显示，适合部署在生产环境或制作干净的输出结果时使用

9.3 多 GPU 管理【重要】¶

• 特别重要，

(1) 主 GPU 控制¶

-mg, --main-gpu

• 这个参数用于多 GPU 环境下的计算优化。
• 举例来说，如果你有三张 GPU：

./llama-cli -m model.gguf --main-gpu 1

• 这条命令会将小型张量计算分配到 GPU 1 上。
• 这很适合当你的某张 GPU 性能更好或内存更大的情况。

(2) 张量分割控制¶

-ts, --tensor-split

• 这个参数允许你精确控制大型张量在多个 GPU 之间的分配比例。
• 例如：

./llama-cli -m model.gguf --tensor-split 3,2,1

• 这个配置会将：

• 50% 的计算分配给第一个 GPU

• 33.3% 分配给第二个 GPU

• 16.7% 分配给第三个 GPU

• 这种分配特别适合在 GPU 性能不同的情况下优化计算效率。

9.4 Hugging Face 模型下载¶

了解，国内下载特别慢

-hfr, --hf-repo

• -hfr后跟 Hugging Face 模型库的 URL
• 与--hf-file或-hff结合使用。
• --hf-file 指定要从 Hugging Face 下载的具体文件名，通常是 GGUF 格式的模型文件
• -m/--model 指定模型文件的本地存储路径
• 模型被下载并存储在-m或--model提供的文件中。
• 如果未提供-m，模型将存储在LLAMA_CACHE环境变量指定的路径中

# 下载到默认缓存（`LLAMA_CACHE`环境变量指定的路径中）
./llama-cli -hfr "deepseek/deepseek-coder" --hf-file "model.gguf"

# 下载到指定路径
./llama-cli -hfr "deepseek/deepseek-coder" --hf-file "model.gguf" -m "./models/deepseek.gguf"

实际应用¶

开发环境¶

• 优化调试和实验

• 更高的温度值、更大的上下文、启用对话模式(cnv)和 verbose 输出

./llama-cli \
    --model /path/to/model.gguf \
    --threads 16 \
    --n-gpu-layers 8 \
    --cache-type-k q8_0 \
    --temp 0.8 \
    --ctx-size 4096 \
    --seed 3407 \
    --batch-size 512 \
    --verbose-prompt \
    --repeat-penalty 1.1 \
    --mlock \
    -cnv

• 根据 GPU 性能，有倾斜地控制

./llama-cli -m model.gguf \
  --main-gpu 0 \
  --tensor-split 2,1 \
  --verbose-prompt \
  --ctx-size 2048

这个组合适合：

• 使用双 GPU 设置
• 需要监控提示词效果
• 对性能分配有特定要求的场景

生产环境¶

• 优化性能和稳定性

• 保持当前的温度和上下文设置，增加 batch size 提升吞吐量，使用 q4_0 缓存节省资源

./llama-cli \
    --model /path/to/model.gguf \
    --threads 64 \
    --n-gpu-layers 0 \
    --cache-type-k q4_0 \
    --temp 0.6 \
    --ctx-size 1024 \
    --seed 3407 \
    --batch-size 2048 \
    --no-display-prompt \
    --repeat-penalty 1.2 \
    --mlock \
    -no-cnv