Последняя дата валидации: 15.11.2026.

Последняя используемая версия llama.cpp:

llama version
version: 0.8.0-dev (build 12014, commit aa588a346)
built with GNU 11.4.0 for Linux x86_64

Вводная часть и список частей справки тут:

https://habr.com/ru/articles/1107998/

В этой части описываются Common Params (Общие параметры).

Параметры этой категории в основном полностью пересекаются между всеми утилитами: llama-cli, llama-completion, llama-server. Там где есть отличия, будут соответствующие комментарии.

Для каждого параметра сначала указывается его название, шаблон и краткое описание из штатной справки llama.cpp. Затем следует более развернутый комментарий.

----- common params -----

-h, --help, --usage

print usage and exit

Комментарий:

Показывает справку по всем основным параметрам: названия параметров в коротком и более развернутом виде, краткие описания параметров, возможные значения, значения по умолчанию, имена переменных окружения в ОС для некоторых параметров, а также, в отдельных случаях, ссылки на GitHub проекта с описанием/обсуждением определенных параметров.

--version

show version and build info

Комментарий:

Показывает информацию о текущей версии и данные конкретной сборки. Например, можно посмотреть поддерживает ли текущая сборка CUDA.

--license (в новых версиях параметр отсутствует)

show source code license and dependencies

Комментарий:

Показывает лицензионную информацию основного пакета llama.cpp, а также других используемых пакетов в составе llama.cpp.

-cl, --cache-list

show list of models in cache

Комментарий:

Показывает список моделей из кэша на диске. Модели скачиваются и кэшируются, когда указывается параметр “-mu, --model-url MODEL_URL”. Если вы самостоятельно скачиваете модели и подключаете их по прямому пути на диске, тогда скорее всего здесь ничего не будет и этот параметр вам не нужен.

--completion-bash

print source-able bash completion script for llama.cpp

Комментарий:

Выводит на экран bash-скрипт, выполнив который, терминал сможет: подсказывать для llama-cli параметры, дополнять флаги по TAB и тд.

-t, --threads N

number of CPU threads to use during generation

(default: -1)

(env: LLAMA_ARG_THREADS)

Комментарий:

Число CPU-потоков для генерации. В теории, чем больше потоков, тем выше скорость работы.

Ремарка: Генерация упирается в пропускную способность памяти, поэтому после некоторого числа потоков прирост почти исчезает, а лишние потоки даже могут замедлить скорость генерации, это нужно проверять на конкретной конфигурации и модели. Также есть мнение, что для процессоров серии Ryzen лучше указывать число физических ядер, тогда как для Intel число логических ядер.

По умолчанию: “--threads -1” (автовыбор).

env: LLAMA_ARG_THREADS - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-tb, --threads-batch N

number of threads to use during batch and prompt processing

(default: same as --threads)

Комментарий:

Число CPU-потоков для обработки входящего промпта и батчей токенов (prefill). Если не задан, берется значение “--threads”. В целом всё как в “--threads”, только там речь о генерации токенов и работе llama.cpp в целом, а здесь о только о prefill.

Ремарка: Генерация упирается в пропускную способность памяти, поэтому после некоторого числа потоков прирост почти исчезает. Обработка промпта хорошо масштабируется по потокам, поэтому в теории для “--threads-batch” оптимально большее число потоков, чем для общего “--threads”, но это нужно проверять на конкретной конфигурации и модели.

По умолчанию: “--threads-batch -1” (автовыбор).

-C, --cpu-mask M

CPU affinity mask: arbitrarily long hex. Complements cpu-range

(default: “”)

Комментарий:

Указать использование конкретных CPU-ядер через битовую маску в шестнадцатеричном формате.

Пример: “--cpu-mask 0xF” (0xF = 1111, использовать ядра CPU0, CPU1, CPU2, CPU3).

По умолчанию: не используется (маска не задана).

-Cr, --cpu-range lo-hi

range of CPUs for affinity. Complements --cpu-mask

Комментарий:

Указать использование конкретных CPU-ядер в заданном диапазоне. Дополнительный способ указать привязку к конкретным CPU-ядрам в заданном диапазоне. В отличии от “--cpu-mask” задается в привычном десятичном виде. Можно использовать оба параметра одновременно “--cpu-mask” + “--cpu-range”.

Пример: “--cpu-range 0-7” (ядра от 0 до 7, всего 8).

По умолчанию: не используется (не задано).

--cpu-strict <0|1>

use strict CPU placement

(default: 0)

Комментарий:

Дословно “использовать строгое размещение на CPU”. Работает вместе с “--threads/--cpu-mask/--cpu-range”. Без strict потоки “--threads” могут свободно перемещаться между ядрами CPU по усмотрению ОС. Со strict каждый поток жёстко закрепляется за отдельным ядром.

Возможные плюсы: меньшие задержки, более оптимальная работа кэша. Главный выигрыш от привязки в том, что потоки не переносятся между CPU и не теряют кэш. Но это только в теории, в большинстве случаев разница в задержках крайне незначительная. Причем, иногда strict может навредить, например если другой процесс занял один из закреплённых CPU, текущий поток не может уйти на свободный CPU и ждёт.

По умолчанию: “--cpu-strict 0” (отключено).

--prio N

set process/thread priority: low(-1), normal(0), medium(1), high(2), realtime(3)

(default: 0)

Комментарий:

Приоритет процесса llama.cpp в планировщике процессов ОС. Чем выше приоритет, тем llama.cpp получает больше CPU-времени при конкуренции с другими процессами в системе. Влияет только при конкуренции за CPU: на свободной системе разницы практически нет.

Возможные значения:

  • (-1) low - фоновый режим, llama.cpp уступает другим процессам.

  • 0 (normal, по умолчанию) - llama.cpp конкурирует с другими процессами на равных. Для большинства случаев лучший выбор.

  • 1 (medium) - llama.cpp получает немного больше CPU, чем другие процессы.

  • 2 (high) - llama.cpp получает существенно больше CPU, остальные процессы меньше.

  • 3 (realtime) - llama.cpp получает максимальный приоритет. Могут начать тормозить системные процессы, использовать не рекомендуется.

Для приоритетов medium(1), high(2), realtime(3) может понадобиться администраторский доступ, иначе llama.cpp просто проигнорирует эту директиву.

По умолчанию: “--prio 0” (normal).

--poll <0...100>

use polling level to wait for work

(0 - no polling, default: 50)

Комментарий:

Определяет, как долго поток активно ожидает новую работу после завершения текущей операции (polling).

На примерах:

“--poll 0” - поток засыпает сразу. Минимальная нагрузка на CPU, но пробуждение чуть дольше.

“--poll 100” - самое длительное активное ожидание. Пробуждение почти моментальное, но выше нагрузка и энергопотребление CPU.

Разница обычно очень не значительная, миллисекунды на токен, может быть немного заметна только на маленьких и быстрых моделях.

По умолчанию: “--poll 50”.

-Cb, --cpu-mask-batch M

CPU affinity mask: arbitrarily long hex. Complements cpu-range-batch

(default: same as --cpu-mask)

Комментарий:

Тоже самое, что “--cpu-mask”, только для батчей. Позволяет указать использование конкретных CPU-ядер через битовую маску в шестнадцатеричном формате.

Пример: “--cpu-mask-batch 0xF” (0xF = 1111, использовать ядра CPU0, CPU1, CPU2, CPU3).

По умолчанию: не используется (маска не задана).

-Crb, --cpu-range-batch lo-hi

ranges of CPUs for affinity. Complements --cpu-mask-batch

Комментарий:

Тоже самое, что “--cpu-range”, только для батчей. Дополнительный способ указать привязку к конкретным CPU-ядрам в заданном диапазоне. В отличии от “--cpu-mask-batch” задается в привычном десятичном виде. Можно использовать оба параметра одновременно “--cpu-mask-batch” + “--cpu-range-batch”.

По умолчанию: не используется (не задано).

--cpu-strict-batch <0|1>

use strict CPU placement

(default: same as --cpu-strict)

Комментарий:

Дословно: “использовать строгое размещение на CPU”. Работает вместе с “--threads-batch/--cpu-mask-batch/--cpu-range-batch”. Без strict потоки “--threads-batch” могут свободно перемещаться между ядрами CPU по усмотрению ОС. Со strict каждый поток жёстко закрепляется за отдельным ядром. Возможные плюсы: меньшие задержки, более оптимальная работа кэша. Главный выигрыш от привязки в том, что потоки не переносятся между CPU и не теряют кэш. Но это только в теории, в большинстве случаев разница в задержках крайне незначительная. Причем, иногда strict может навредить, например если другой процесс занял один из закреплённых CPU, текущий поток не может уйти на свободный CPU и ждёт.

По умолчанию: “--cpu-strict-batch 0” (отключено).

--prio-batch N

set process/thread priority: 0-normal, 1-medium, 2-high, 3-realtime

(default: 0)

Комментарий:

Тоже самое, что “--prio”, только для потоков обработки промпта и батчей (prefill). Чем выше приоритет, тем потоки батчей в llama.cpp получают больше CPU при конкуренции с другими процессами в системе. Влияет только при конкуренции за CPU: на свободной системе разницы практически нет. В теории в режиме high(2) prefill llama.cpp может работать немного быстрее, но тогда остальные процессы в ОС будут работать медленнее. В режиме realtime(3) prefill llama.cpp будет вытеснять все остальные процессы в системе, в том числе системные, ОС начнет сильно тормозить.

Возможные значения:

  • 0 (normal, по умолчанию) - llama.cpp prefill конкурирует с другими процессами на равных. Для большинства случаев лучший выбор.

  • 1 (medium) - llama.cpp prefill получает немного больше CPU, чем другие процессы.

  • 2 (high) - llama.cpp prefill получает существенно больше CPU, остальные процессы меньше.

  • 3 (realtime) - llama.cpp prefill получает максимальный приоритет. Могут начать тормозить системные процессы, использовать не рекомендуется.

Для приоритетов medium(1), high(2), realtime(3) может понадобиться администраторский доступ, иначе llama.cpp просто проигнорирует эту директиву.

По умолчанию: “--prio-batch 0” (normal).

--poll-batch <0|1>

use polling to wait for work

(default: same as --poll)

Комментарий:

Тоже самое, что “--poll”, только для батчей. Определяет, как долго поток батчей активно ожидает новую работу после завершения текущей операции (polling).

На примерах:

--poll-batch 0 - поток засыпает сразу. Минимальная нагрузка на CPU, но пробуждение чуть дольше.

--poll-batch 100 - самое длительное активное ожидание. Пробуждение почти моментальное, но выше нагрузка и энергопотребление CPU.

Разница обычно очень не значительная, миллисекунды на токен, может быть немного заметна только на маленьких и быстрых моделях.

По умолчанию: “--poll-batch 50”.

-c, --ctx-size N

size of the prompt context

(default: 0 - loaded from model)

(env: LLAMA_ARG_CTX_SIZE)

Комментарий:

Длина контекста. Обычно указывается длина контекста модели (если позволяет вместить память). Чем больше длина контекста, тем больше требуется памяти для работы с ним. Часто имеет смысл указать меньший размер контекста, например для коротких чатов или единичных запросов, например таких как вызовы функций/инструментов.

По умолчанию: “--ctx-size 0” (используется значение модели).

env: LLAMA_ARG_CTX_SIZE - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-n, --predict, --n-predict N

number of tokens to predict

(default: -1, -1 = infinity)

(env: LLAMA_ARG_N_PREDICT)

Комментарий:

Сколько токенов модель будет генерировать. При достижении указанного значения генерация текста прекратится (резко оборвется). Если не указать этот параметр, либо указать “--predict -1” (по умолчанию), то текст будет генерироваться до бесконечности или до завершающего токена (если таковой имеется для используемой модели). Считаются только новые токены, токены промпта сюда не входят.

Примечание: Завершающий токен (EOS/EOG) это специальный токен, которым при обучении заканчиваются тексты, так модель учится понимать, когда нужно закончить генерацию текста. Завершающие токены могут отличаться в разных моделях. Примеры завершающих токенов: <|endoftext|>, <end_of_turn>, , <|im_end|> и тд.

По умолчанию: “--n-predict -1” (бесконечно или до завершающего токена).

Важно: Для llama-completion есть еще один вариант значения для этого параметра: “-2 = until context filled”, дословно это переводится как “пока контекст не будет заполнен”. То есть, генерация прервется при достижении заданной длины контекста (смотрите “--ctx-size”).

Я пока затрудняюсь сказать, почему этот вариант есть только для llama-completion. Возможно дело в особенностях работы разных утилит: llama-cli и llama-server обычно работают в режиме диалога (бэкенд заточен под это), тогда как llama-completion работает исключительно в режиме генерации одного сообщения (разовый вызов).

env: LLAMA_ARG_N_PREDICT - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-b, --batch-size N

logical maximum batch size

(default: 2048)

(env: LLAMA_ARG_BATCH)

Комментарий:

Размер батча в токенах. Используется для входящего запроса (prefill - промпта, сообщения или цепочки сообщений). Если prefill большой, тогда он будет разбит на батчи, которые отправятся в последовательную обработку. Деление на батчи нужно для экономии памяти при вычислениях.

По умолчанию: “--batch-size 2048”.

env: LLAMA_ARG_BATCH - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-ub, --ubatch-size N

physical maximum batch size

(default: 512)

(env: LLAMA_ARG_UBATCH)

Комментарий: Суть параметра как “--batch-size”, только здесь указывается “физический” размер батча (микробатч), который фактически отправится в CPU/GPU. Например, если “--batch-size 2048”, а “--ubatch-size 512”, тогда “софтовый” батч в 2048 токенов будет разбит на физические батчи по 512 токенов, которые отправятся на вычисления в CPU/GPU.

Важно: значение “--ubatch-size” должно быть не больше “--batch-size”, иначе в этом параметре нет смысла, т.к. исходный размер батча задается в “--batch-size”, а “--ubatch-size” помогает лишь тем, что разбивает батч перед отправкой на CPU/GPU и не может быть больше исходного размера батча.

По умолчанию: “--ubatch-size 512”.

env: LLAMA_ARG_UBATCH - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

--keep N

number of tokens to keep from the initial prompt

(default: 0, -1 = all)

Комментарий:

Сколько токенов из начального промпта оставить в случае переполнения контекста, от остальной части убрать первую половину (старые токены). Когда контекст (“--ctx-size”) заканчивается, llama.cpp начинает обрезать токены с начала беседы, это называется context shift. Благодаря параметру “--keep” можно сохранить начало диалога, например полностью сохранить системный промпт, а окно контекста начнет обрезаться только после указанного значения.

Пример:

[n_past, n_left, n_discard - внутренние переменные llama.cpp, они вычисляются в процессе работы]

--ctx-size 4096, --keep 200, контекст заполнился (n_past = 4096).

n_left = 4096 - 200 = 3896 (не трогаем первые 200 токенов).

n_discard = 3896 / 2 = 1948 (из оставшихся 3896 удаляем половину - более ранние 1948 токенов).

При последующем заполнении контекста (n_past), context shift повторяется.

Если “--keep -1”, тогда сохраняется весь входящий промпт.

По умолчанию: “--keep 0” (без сохранения).

--swa-full

use full-size SWA cache

(default: false)

Комментарий:

Некоторые модели, например Gemma2/3, используют Sliding Window Attention (скользящее окно внимания) вместо полноценного внимания по всему контексту. По умолчанию llama.cpp оптимизирует SWA-кэш и хранит только нужное (ограниченное) окно внимания, это существенно экономит память. Если указать “--swa-full”, тогда включится полноразмерный SWA-cache без оптимизации. Полный SWA cache теоретически может дать лучшее качество и лучшую совместимость/стабильность, но требует существенно большего объема памяти для хранения всего KV-кэша.

По умолчанию: не используется.

-fa, --flash-attn [on|off|auto]

set Flash Attention use (‘on’, ‘off’, or ‘auto’, default: ‘auto’)

(env: LLAMA_ARG_FLASH_ATTN)

Комментарий:

Включение/отключение Flash Attention. FA это более эффективный метод вычисления Attention. Работает быстрее, потребляет меньше памяти (особенно на больших контекстах), но может дать чуть другой результат (как лучше, так и хуже, в большинстве случаев различия не заметны). Еще, “--flash-attn” нужно включать, если при инференсе модели используется квантование кэша V (“--cache-type-v”); также желательно его включать (но не обязательно), если используется квантование кэша K (“--cache-type-k”). О квантовании кеша KV (“--cache-type-k” и “--cache-type-v”) смотрите ниже.

По умолчанию: “--flash-attn auto” (автовыбор).

env: LLAMA_ARG_FLASH_ATTN - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-p, --prompt PROMPT

prompt to start generation with; for system message, use -sys

Комментарий:

Текст промпта, первое сообщение от пользователя. Не путать с системным промптом, который задается через параметры “-sys/--system-prompt” и “-sysf/--system-prompt-file”.

--perf, --no-perf whether to enable internal libllama performance timings (default: false)

Комментарий:

Включает внутренние тайминги производительности библиотеки libllama (llama.cpp): load time, prompt eval time, eval time, tokens/s и тд. Может использоваться для бенчмарков или отладки.

Возможные варианты:

“--perf” - включено (по умолчанию).

“--no-perf” - выключено.

По умолчанию: “--perf” (включено).

-f, --file FNAME

a file containing the prompt

(default: none)

Комментарий:

Загрузить промпт из файла. Используется вместо указания промпта в самом запросе к llama.cpp через параметр “--prompt”.

По умолчанию: не используется.

-bf, --binary-file FNAME

binary file containing the prompt

(default: none)

Комментарий:

Загружает промпт из файла в бинарном режиме побайтово как есть, не делает текстовое преобразование. Используется редко, может понадобиться для передачи сырых (raw) данных, в случае редкой кодировки исходного текста, каких-либо спецсимволов и тд., чтобы передать промпт в точности как есть.

По умолчанию: не используется.

-e, --escape, --no-escape

whether to process escapes sequences (\n, \r, \t, \', \", \\)

(default: true)

Комментарий:

Обрабатывать ли escape-последовательности. Применяется к тексту промпта и некоторым другим строковым параметрам.

Например: “-p “hello\nworld””, станет:

hello

world

Если выбрать “--no-escape”, то escape-последовательности будут передаваться как текст. Например: “-p “hello\nworld””, так и останется в виде текста: "hello\nworld".

По умолчанию: включено.

Параметры RoPE

RoPE (Rotary Positional Embeddings) - механизм позиционного кодирования. Чтобы понимать для чего нужны эти параметры, нужно в первую очередь понимать сам принцип RoPE. Если вкратце, существует технология увеличения окна контекста модели, например, вместо исходных 8192 токенов, можно сделать так, чтобы модель могла работать с контекстом в 32768 токенов и больше.

--rope-scaling {none,linear,yarn}

RoPE frequency scaling method, defaults to linear unless specified by the model

(env: LLAMA_ARG_ROPE_SCALING_TYPE)

Комментарий:

Метод масштабирования контекста. Варианты:

  • none - без масштабирования.

  • linear - простое линейное растяжение контекста.

  • yarn - более качественное масштабирование для длинных контекстов.

По умолчанию: “--rope-scaling linear” (линейный, если не указано иное в модели).

env: LLAMA_ARG_ROPE_SCALING_TYPE - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

--rope-scale N

RoPE context scaling factor, expands context by a factor of N

(env: LLAMA_ARG_ROPE_SCALE)

Комментарий:

Во сколько раз масштабировать контекст через RoPE scaling. Например: “--rope-scale 4”. Если модель была обучена на контексте в 8192 токенов, тогда она сможет работать с контекстом в 32768 токенов (x4).

Важно! Так как модель изначально не обучалась на размере контекста в 32768 токенов, качество работы будет хуже в сравнении с моделью, изначально обученной на контексте в 32768 токенов.

env: LLAMA_ARG_ROPE_SCALE - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

--rope-freq-base N

RoPE base frequency, used by NTK-aware scaling

(default: loaded from model)

(env: LLAMA_ARG_ROPE_FREQ_BASE)

Комментарий:

[Ремарка: описание работы параметра может быть не точным]

Тонкая настройка базовой частоты RoPE. Меняет распределение positional frequencies и поведение Attention на длинных контекстах. Используется в NTK scaling и long-context tuning. Позволяет сделать длинный контекст стабильнее, сохранить качество Attention на больших расстояниях. Большие значения расширяют рабочий контекст, но различимость близких позиций немного снижается.

Например, значение “--rope-freq-base 500000”. Модель с исходным контекстом 8192, но расширенная до контекста 32768 токенов, будет работать на длинных контекстах лучше, позиции за пределами исходного обучающего диапазона (8192) будут оставаться различимыми. Значение “--rope-freq-base 500000” условное и должно подбираться под каждую модель отдельно.

По умолчанию: loaded from model (используется значение модели).

env: LLAMA_ARG_ROPE_FREQ_BASE - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

--rope-freq-scale N

RoPE frequency scaling factor, expands context by a factor of 1/N

(env: LLAMA_ARG_ROPE_FREQ_SCALE)

Комментарий:

[Ремарка: описание работы параметра может быть не точным]

Тонкая настройка RoPE для long context. Умножает индексы позиций на N (линейная интерполяция), из-за чего длинная последовательность укладывается в диапазон позиций, на котором модель изначально обучалась. Это позволяет искусственно увеличивать контекст при инференсе.

Например, значение “--rope-freq-scale 0.25”, модель с исходным контекстом 8192, но расширенная до контекста 32768 токенов, будет работать на длинных контекстах примерно так, как-будто она изначально была обучена на контексте в 32768 токенов (очень грубо). Слишком маленькие значения могут ухудшать качество Attention и понимание локального контекста.

Важно! Так как модель изначально не обучалась на размере контекста в 32768 токенов, качество работы будет хуже в сравнении с моделью, изначально обученной на контексте в 32768 токенов.

env: LLAMA_ARG_ROPE_FREQ_SCALE - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

--yarn-orig-ctx N

YaRN: original context size of model

(default: 0 - model training context size)

(env: LLAMA_ARG_YARN_ORIG_CTX)

Комментарий:

[Ремарка: описание работы параметра может быть не точным]

Тонкая настройка способа растяжения контекста RoPE методом YaRN (“--rope-scaling yarn”). Задается исходная длина контекста модели, например “--yarn-orig-ctx 8192”. От этого значения YaRN считает, какие частотные измерения интерполировать, а какие нет.

По умолчанию: “--yarn-orig-ctx 0” (используется значение модели).

env: LLAMA_ARG_YARN_ORIG_CTX - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

--yarn-ext-factor N

YaRN: extrapolation mix factor

(default: -1.00, 0.0 = full interpolation)

(env: LLAMA_ARG_YARN_EXT_FACTOR)

Комментарий:

[Ремарка: описание работы параметра может быть не точным]

Как YaRN будет растягивать контекст.

Варианты значений:

  • 0.0 - только интерполяция.

  • 0 - больше экстраполяции.

  • 1.0 - максимум экстраполяции для высокочастотных измерений.

Промежуточные значения дают смесь (например “--yarn-ext-factor 0.5”, будет что-то среднее). Рекомендуется оставлять автоматический режим (-1).

По умолчанию: “--yarn-ext-factor -1” (авто).

env: LLAMA_ARG_YARN_EXT_FACTOR - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

--yarn-attn-factor N

YaRN: scale sqrt(t) or Attention magnitude

(default: -1.00)

(env: LLAMA_ARG_YARN_ATTN_FACTOR)

Комментарий:

[Ремарка: описание работы параметра может быть не точным]

Корретировка силы Attention при растяжении контекста. При растяжении контекста Attention размазывается, YaRN пытается это компенсировать. Рекомендуется оставлять автоматический режим (-1).

По умолчанию: “--yarn-attn-factor -1” (вычисляется автоматически).

env: LLAMA_ARG_YARN_ATTN_FACTOR - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

--yarn-beta-slow N

YaRN: high correction dim or alpha

(default: -1.00)

(env: LLAMA_ARG_YARN_BETA_SLOW)

Комментарий:

[Ремарка: описание работы параметра может быть не точным]

Порог для низкочастотных измерений позиционного кодирования, которые отвечают за дальние связи в тексте. Измерения ниже этого порога YaRN полностью сжимает, как при linear scaling. Чем больше значение, тем больше измерений будет сжато. Примерный диапазон значений 1-32. Рекомендуется оставлять автоматический режим (-1).

По умолчанию: “--yarn-beta-slow -1” (вычисляется автоматически).

env: LLAMA_ARG_YARN_BETA_SLOW - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

--yarn-beta-fast N

YaRN: low correction dim or beta

(default: -1.00)

(env: LLAMA_ARG_YARN_BETA_FAST)

Комментарий:

[Ремарка: описание работы параметра может быть не точным]

Порог для высокочастотных измерений позиционного кодирования, которые отвечают за точное различение соседних токенов. Измерения выше этого порога YaRN не трогает, локальная точность сохраняется. Чем меньше значение, тем больше измерений останется нетронутыми. Примерный диапазон значений 1-32. Рекомендуется оставлять автоматический режим (-1).

По умолчанию: “--yarn-beta-fast -1” (вычисляется автоматически).

env: LLAMA_ARG_YARN_BETA_FAST - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-kvo, --kv-offload, -nkvo, --no-kv-offload

whether to enable KV cache offloading

(default: enabled)

(env: LLAMA_ARG_KV_OFFLOAD)

Комментарий:

Размещение KV-кэша в VRAM (GPU) или RAM (CPU).

Возможные варианты:

“-kvo”, “--kv-offload” - размещение в VRAM (GPU).

“-nkvo”, “--no-kv-offload” - размещение в RAM (CPU).

Размещение KV-кэша в VRAM обычно увеличивает скорость генерации. Рекомендуется включать при наличии GPU.

По умолчанию: включено.

env: LLAMA_ARG_KV_OFFLOAD - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

--repack, -nr, --no-repack

whether to enable weight repacking

(default: enabled)

(env: LLAMA_ARG_REPACK)

Комментарий:

[Ремарка: описание работы параметра может быть не точным]

Перепаковка весов модели в более эффективный формат, оптимизированный под SIMD-инструкции CPU (AVX2, AVX512, NEON и др.). Влияет только при режиме работы на CPU.

Возможные варианты:

“--repack” - быстрее инференс, но медленнее загрузка весов модели в RAM.

“-nr”, “--no-repack” - медленнее инференс, но быстрее загрузка весов модели в RAM (веса читаются напрямую из файла без перепаковки).

Рекомендуется оставлять включенным.

По умолчанию: включено.

env: LLAMA_ARG_REPACK - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

--no-host

bypass host buffer allowing extra buffers to be used

(env: LLAMA_ARG_NO_HOST)

Комментарий:

[Ремарка: описание работы параметра может быть не точным]

Отключает использование стандартного Host Buffer (буфер в RAM для более быстрой передачи данных между RAM и VRAM), позволяя бэкенду использовать другие типы буферов для размещения весов модели. Буферы могут отличаться совместимостью, производительностью или доступностью, в этом смысл. При обычном использовании “--no-host” применяется редко.

env: LLAMA_ARG_NO_HOST - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-ctk, --cache-type-k TYPE

KV cache data type for K allowed values: f32, f16, bf16, q8_0, q4_0, q4_1, iq4_nl, q5_0, q5_1

(default: f16)

(env: LLAMA_ARG_CACHE_TYPE_K)

Комментарий:

Тип данных для кэширования значений K (Attention Key). По умолчанию тип данных “f16” (float16). Можно задать квантованные значения, либо тип данных “bf16” (bfloat16), либо более точный “f32” (float32). Тип данных “f32” (float32) потребует под кэш в 2 раза больше памяти, и скорее всего не улучшит заметно качество генерации текста. Меньшие (квантованные) значения потребляют меньше памяти, но хуже по качеству генерации и могут работать медленее из-за дополнительной распаковки значений.

Для некоторых задач квантованные значения K-кэша, например “q8_0”, работают не сильно хуже исходных “f16”, но в других задачах ухудшение может быть более заметным. Типы квантования “q4_*” сильнее ухудшают качество генерации. По некоторым данным, квантование K-кэша ухудшает качество генерации менее заметно, чем квантование V-кэша.

Важно! Если вы компилируете llama.cpp с поддержкой CUDA, тогда для поддержки всех типов квантования нужно указывать параметр: -DGGML_CUDA_FA_ALL_QUANTS=ON.

По умолчанию: “--cache-type-k f16” (float16).

env: LLAMA_ARG_CACHE_TYPE_K - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-ctv, --cache-type-v TYPE

KV cache data type for V allowed values: f32, f16, bf16, q8_0, q4_0, q4_1, iq4_nl, q5_0, q5_1

(default: f16)

(env: LLAMA_ARG_CACHE_TYPE_V)

Комментарий:

Тип данных для кэширования значений V (Attention Value). По умолчанию тип данных “f16” (float16). Можно задать квантованные значения, либо тип данных “bf16” (bfloat16), либо более точный “f32” (float32). Тип данных “f32” (float32) потребует под кэш в 2 раза больше памяти, и скорее всего не улучшит заметно качество генерации текста. Меньшие (квантованные) значения потребляют меньше памяти, но хуже по качеству генерации и могут работать медленнее из-за дополнительной распаковки значений.

Для некоторых задач квантованные значения V-кэша, например “q8_0”, работают не сильно хуже исходных “f16”, но в других задачах ухудшение может быть более заметным. Типы квантования “q4_*” сильнее ухудшают качество генерации. По некоторым данным, квантование V-кэша ухудшает качество генерации сильнее, чем квантование K-кэша. Для квантования V-кэша обязательно нужно включить Flash Attention (“-fa/--flash-attn”).

Важно! Если вы компилируете llama.cpp с поддержкой CUDA, тогда для поддержки всех типов квантования нужно указывать параметр: -DGGML_CUDA_FA_ALL_QUANTS=ON.

По умолчанию: “--cache-type-v f16” (float16).

env: LLAMA_ARG_CACHE_TYPE_V - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-dt, --defrag-thold N

KV cache defragmentation threshold (DEPRECATED)

(env: LLAMA_ARG_DEFRAG_THOLD)

Комментарий:

[Ремарка: описание работы параметра может быть не точным]

Порог фрагментации KV-кэша, при превышении которого запускается дефрагментация ячеек памяти. Параметр устарел и в новых версиях llama.cpp больше не используется.

Как это работало: KV-кэш состоит из ячеек памяти, по одной ячейке на токен. Когда токены удаляются или сдвигаются (смена контекста, удаление последовательности, завершение запроса в одном из слотов и тд.), в кэше остаются дыры. Раньше для нового батча нужен был непрерывный блок свободных ячеек, дефрагментация перемещала занятые ячейки в начало и уплотняла кэш. Порог “-dt” задавал долю дыр в памяти, после которой запускалась дефрагментация. В новых версиях llama.cpp кэш умеет размещать токены в не связанных ячейках, поэтому дефрагментация больше не нужна. Параметр сохранён для совместимости.

env: LLAMA_ARG_DEFRAG_THOLD - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-np, --parallel N

number of parallel sequences to decode

(default: 1)

(env: LLAMA_ARG_N_PARALLEL)

Комментарий:

[Ремарка: описание работы параметра может быть не точным]

Количество параллельных слотов для одновременной обработки запросов. Нужен для параллельной обработки нескольких запросов. В обычном одиночном режиме не используется.

По умолчанию: “--parallel 1”.

env: LLAMA_ARG_N_PARALLEL - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

--rpc SERVERS

comma-separated list of RPC servers (host:port)

(env: LLAMA_ARG_RPC)

Комментарий:

Подключение RPC-серверов для распределённого (удалённого) инференса. У каждого сервера указывается его IP-адрес и порт; можно указать несколько серверов через запятую. Например:

192.168.1.10:50051,192.168.1.11:50052.

По умолчанию веса модели и KV-кэш распределяются по всем устройствам (локальным и удалённым), пропорционально доступной памяти. Пропорции можно задать вручную через параметр “--tensor-split”.

Если сервер и клиент поддерживают RDMA (RoCEv2 на Linux или RDMA поверх Thunderbolt 5 на macOS), транспорт согласовывается автоматически. Для этого в “--rpc” нужно указывать адрес именно RDMA-совместимого интерфейса. Соединение через другой интерфейс останется на TCP.

Все экземпляры llama.cpp (основной и RPC) должны быть собраны с указанием параметра: “-DGGML_RPC=ON”.

Важно! RPC-бэкенд на стадии proof-of-concept, его функциональность не является надежной и безопасной. Не нужно запускать RPC-сервера в открытых сетях или в средах, содержащих конфиденциальные данные.

Более подробно про реализацию RPC в llama.cpp можно почитать тут:

https://github.com/ggml-org/llama.cpp/blob/master/tools/rpc/README.md

env: LLAMA_ARG_RPC - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-lm, --load-mode MODE

model loading mode.

  • auto: mmap, unless a device does not support it.

  • none: no special loading mode.

  • mmap: memory-map model (if mmap disabled, slower load but may reduce pageouts if not using mlock).

  • mlock: force system to keep model in RAM rather than swapping or compressing.

  • mmap+mlock: mmap + force system to keep model in RAM rather than swapping or compressing.

  • dio: use DirectIO if available.

(default: auto)

(env: LLAMA_ARG_LOAD_MODE)

Комментарий:

[Ремарка: описание работы параметра может быть не точным]

Выбор способа загрузки файла модели в память. Заменяет старые параметры “--mmap”, “--no-mmap”, “--mlock” и “--direct-io”.

Возможные варианты:

  • auto (по умолчанию) - использует mmap, если устройство это поддерживает.

  • none - особый режим не используется: llama.cpp полностью считывает файл модели с диска в выделенную оперативную память. Загрузка дольше, зато модель находится целиком в памяти и повторные обращения к диску не происходят. Фактически аналог старого “--no-mmap”.

  • mmap - файл модели отображается в адресное пространство процесса llama.cpp, а ОС подгружает нужные страницы в RAM (page cache) по мере обращения. Дает более быстрый старт, повторные запуски почти мгновенные, но при нехватке RAM ОС может выкинуть часть страниц и потом перечитать их с диска заново. Аналог старого “--mmap”.

  • mlock - запретить ОС выгружать модель из RAM в SWAP (файл подкачки) и сжимать её. Меньше возможных фризов, стабильнее скорость работы, но требует достаточного объема памяти. Аналог старого “--no-mmap --mlock” (модель читается в RAM и закрепляется там).

  • mmap+mlock - модель отображается через mmap, и все её страницы закрепляются в RAM. Аналог старого “--mmap --mlock”, самый предсказуемый по скорости вариант при достаточном объёме памяти.

  • dio - DirectIO: чтение файла модели с диска напрямую, минуя page cache ОС. Работает если доступна поддержка DirectIO на уровне ОС и файловой системы. Аналог старого “--direct-io”.

По умолчанию: “--load-mode auto” (автовыбор).

env: LLAMA_ARG_LOAD_MODE - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-lzm, --lazy-mode MODE

on-demand reading of certain tensors, for example per-layer embeddings

  • on: read the rows of such tensors from disk on demand instead of keeping them resident (requires mmap).

  • auto: on, but only for tensors larger than 4 GiB.

  • off: always keep them resident.

(default: auto)

(env: LLAMA_ARG_LAZY_MODE)

Комментарий:

[Ремарка: описание работы параметра может быть не точным]

Дословно: “считывание определенных тензоров по требованию, например, эмбеддингов для отдельных слоев”. Нужная строка тензора читается с диска только в момент обращения, соответственно весь тензор не находится в RAM постоянно. Это экономит память, но каждое обращение ожидает подгрузки с диска.

Возможные варианты:

  • on - читать такие тензоры по требованию, а не держать их в памяти постоянно (нужен mmap, “--load-mode mmap”).

  • auto (по умолчанию) - как “on”, только для тензоров крупнее 4 ГиБ. Меньшие тензоры всегда находятся в памяти.

  • off - всегда держать такие тензоры в памяти целиком.

env: LLAMA_ARG_LAZY_MODE - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

--mlock

В новых версиях llama.cpp параметр переехал в “-lm, --load-mode”, как один из режимов.

--mmap, --no-mmap

В новых версиях llama.cpp параметр переехал в “-lm, --load-mode”, как один из режимов.

-dio, --direct-io, -ndio, --no-direct-io

В новых версиях llama.cpp параметр переехал в “-lm, --load-mode”, как один из режимов.

--numa TYPE

attempt optimizations that help on some NUMA systems

  • distribute: spread execution evenly over all nodes

  • isolate: only spawn threads on CPUs on the node that execution started on

  • numactl: use the CPU map provided by numactl if run without this previously, it is recommended to drop the system page cache before using this see https://github.com/ggml-org/llama.cpp/issues/1437

(env: LLAMA_ARG_NUMA)

Комментарий:

[Ремарка: описание работы параметра может быть не точным]

Оптимизация для NUMA-систем (NUMA - Non-Uniform Memory Access, неоднородный доступ к памяти в многопроцессорных системах).

Возможные варианты:

  • distribute - равномерно распределяет потоки по NUMA-узлам.

  • isolate - потоки создаются только на CPU того узла, где стартовал процесс.

  • numactl - использует привязку CPU по маске, заданной через утилиту numactl.

Если до этого llama.cpp запускалась без этого параметра, перед его использованием рекомендуется сбросить системный page cache. Подробнее:

https://github.com/ggml-org/llama.cpp/issues/1437.

Параметр “--numa” может применяться на многосокетных серверах, для обычного применения не нужен.

env: LLAMA_ARG_NUMA - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-dev, --device <dev1,dev2,…>

comma-separated list of devices to use for offloading (none = don’t offload)

use --list-devices to see a list of available devices

(env: LLAMA_ARG_DEVICE)

Комментарий:

Какие устройства использовать для размещения модели, перечисляются через запятую. Список доступных устройств можно посмотреть через параметр “--list-devices”. Если указать “none” - не будет использоваться оффлоад вообще, модель останется на CPU/RAM. Если значения не указаны, будет использоваться доступные устройства по умолчанию.

env: LLAMA_ARG_DEVICE - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

--list-devices

print list of available devices and exit

Комментарий:

Посмотреть список доступных в системе устройств для размещения модели.

Запуск llama.cpp с этим параметром отобразит список устройств и завершит выполнение программы.

-ot, --override-tensor <tensor name pattern>=<buffer type>,…

(env: LLAMA_ARG_OVERRIDE_TENSOR)

Комментарий:

[Ремарка: описание работы параметра может быть не точным]

Дословно: “переопределить тип буфера тензора”.

Параметр позволяет вручную указать, в какой памяти (на каком устройстве) хранить конкретные тензоры модели. Правила задаются по шаблонам имен тензоров; если правил несколько, то они перечисляются через запятую. Шаблон задается через регулярные выражения по именам тензоров, а тип буфера задается именем устройства: CPU, CUDA0, Vulkan0 и тд. Список доступных устройств можно получить через “--list-devices”.

Зачем это нужно. Например в случае с параметром “--n-gpu-layers”, в GPU выгружаются целые слои. Выгрузка отдельных тензоров через “--override-tensor” дает более тонкий контроль: можно разнести по устройствам отдельные части слоев. Это может быть целесообразно, например, для MoE-моделей. В них основную часть весов занимают тензоры экспертов, но при генерации токенов единомоментно активна лишь их небольшая часть. Поэтому в некоторых случаях имеет смысл:

  • держать на более быстрых устройствах то, что используется постоянно и что сильно влияет на скорость: attention, нормализации, общие слои и др.

  • вынести тензоры экспертов на менее быстрые устройства (например CPU или менее быстрый GPU), так как они занимают много памяти, а одномоментно работает только часть из них. Ремарка: это просто пример, на деле могут использоваться различные устройства, например разные GPU установленные в системе, разные бэкенды (Cuda, Vulkan, Metal и др.), NPU, RPC и тд. Тензоры могут распределяться совершенно в разных пропорциях и по разным устройствам, все зависит от конкретной конфигурации, а также от используемых моделей.

env: LLAMA_ARG_OVERRIDE_TENSOR - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-cmoe, --cpu-moe

keep all Mixture of Experts (MoE) weights in the CPU

(env: LLAMA_ARG_CPU_MOE)

Комментарий:

Для MoE-моделей (Mistral, DeepSeek и др.). Все веса экспертов держать в RAM (CPU), а не в VRAM (GPU). Позволяет разгрузить GPU, но скорость обработки на CPU значительно медленнее.

env: LLAMA_ARG_CPU_MOE - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-ncmoe, --n-cpu-moe N

keep the Mixture of Experts (MoE) weights of the first N layers in the CPU

(env: LLAMA_ARG_N_CPU_MOE)

Комментарий:

Для MoE-моделей (Mistral, DeepSeek и др). В отличии от “-cmoe, --cpu-moe”, где размещаются все слои экспертов в RAM (CPU), здесь задается сколько первых N-слоев экспертов разместить в RAM (CPU), разгрузив тем самым VRAM (GPU). Компромисс между потреблением VRAM и скоростью.

env: LLAMA_ARG_N_CPU_MOE - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

--moe-cache-mib N

GPU cache size in MiB for the MoE experts kept in the CPU. with multiple GPUs, it is split among them like the layers (--tensor-split)

(default: 0 - disabled)

(env: LLAMA_ARG_MOE_CACHE_MIB)

Комментарий:

Параметр касается только MoE-моделей: для экспертов, которые загружены в RAM (через “-ncmoe” или “-cmoe”), разместить кэш в указанном размере в VRAM. То есть, сами эксперты остаются в медленной RAM (CPU), но кэш будет работать в более быстрой VRAM (GPU). Чем больше размер кэша, тем выше скорость, но меньший объем VRAM остаётся под контекст (KV-кэш). Размер задаётся в МиБ (мебибайт).

Если в системе несколько GPU, кэш будет распределяться между ними так же, как слои модели через параметр “--tensor-split”.

По-умолчанию: “--moe-cache-mib 0” (не используется).

env: LLAMA_ARG_MOE_CACHE_MIB - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-ncffn, --n-cpu-ffn N

keep the dense FFN weights of the first N layers in the CPU

(dense models; for MoE expert weights use --n-cpu-moe)

(env: LLAMA_ARG_N_CPU_FFN)

Комментарий:

По аналогии с “-ncmoe, --n-cpu-moe”, только для dense-моделей (классические модели без MoE, например GPT3, Llama3, Gemma2 и другие). Для весов FFN (Feed Forward Network), задается у скольких первых N-слоёв модели веса FFN разместить в RAM (CPU), остальные останутся в VRAM (GPU).

env: LLAMA_ARG_N_CPU_FFN - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

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

max. number of layers to store in VRAM, either an exact number, ‘auto’, or ‘all’

(default: auto)

(env: LLAMA_ARG_N_GPU_LAYERS)

Комментарий:

Количество слоев модели, которые будут размещены на GPU (VRAM). Значение указывается через число, либо ‘all’ - все слои, ‘auto’ - автовыбор. Размещение слоев модели на GPU даёт существенный прирост производительности. Если разместить модель на GPU целиком, прирост в сравнении с CPU будет наиболее значительным (часто в разы).

По умолчанию: “--gpu-layers auto” (автовыбор).

env: LLAMA_ARG_N_GPU_LAYERS - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-sm, --split-mode {none,layer,row}

how to split the model across multiple GPUs, one of:

  • none: use one GPU only

  • layer (default): split layers and KV across GPUs

  • row: split rows across GPUs

(env: LLAMA_ARG_SPLIT_MODE)

Комментарий:

Как делить модель между несколькими GPU. Возможные варианты:

  • none - использовать один GPU.

  • layer - слои модели и KV-кэш распределяются между GPU.

  • row - веса режутся по строкам между GPU, каждая карта считает свою часть каждого слоя. Промежуточные результаты и KV-кэш при этом лежат на основном GPU.

Если в системе несколько одинаковых GPU с быстрой связью (NVLink), в режиме “row” теоретически можно получить прирост скорости генерации. На PCIe без NVLink режим “row” скорее всего будет медленнее “layer” из-за постоянного обмена данными между картами.

По умолчанию: “--split-mode layer”.

env: LLAMA_ARG_SPLIT_MODE - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-ts, --tensor-split N0,N1,N2,…

fraction of the model to offload to each GPU, comma-separated list of proportions, e.g. 3,1

(env: LLAMA_ARG_TENSOR_SPLIT)

Комментарий:

Как распределять модель между GPU с указанием пропорций.

Примеры:

“--tensor-split 2,1,1” - сумма 4, соответственно: GPU0 = 2/4 = 50%, GPU1 = 1/4 ~ 25%, GPU2 = 1/4 ~ 25%.

“--tensor-split 4,2,1” - сумма 7, соответственно: GPU0 = 4/7 = 57%, GPU1 = 2/7 ~ 29%, GPU2 = 1/7 ~ 14%.

env: LLAMA_ARG_TENSOR_SPLIT - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-mg, --main-gpu INDEX

the GPU to use for the model (with split-mode = none), or for intermediate results and KV (with split-mode = row)

(default: 0)

(env: LLAMA_ARG_MAIN_GPU)

Комментарий:

Параметр связан с параметром “-sm, --split-mode”. Задает индекс основного GPU для размещения модели (при “--split-mode none”) или для промежуточных вычислений и KV-кэша (при “--split-mode row”). Например: “--main-gpu 1” - если в системе несколько GPU, llama.cpp будет считать GPU с индексом 1 основным (индексация начинается с 0). Этот GPU будет использоваться для наиболее важной части работы.

Это может понадобиться, например, если видеокарты в системе имеют разную производительность или разный объём VRAM, тогда целесообразно выбрать главной более быструю видеокарту или GPU с большим количеством VRAM.

По умолчанию: “--main-gpu 0” (будет использоваться первый GPU).

env: LLAMA_ARG_MAIN_GPU - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-fit, --fit [on|off]

whether to adjust unset arguments to fit in device memory (‘on’ or ‘off’)

(default: ‘on’)

(env: LLAMA_ARG_FIT)

Комментарий:

Помогает при нехватке памяти и невозможности загрузки модели. Автоматически меняет некоторые аргументы, чтобы модель поместилась в память (обычно VRAM). Работает совместно с параметрами “--fit-target” и “--fit-ctx”.

Возможные значения:

  • on - автоматически подгонять параметры.

  • off - не изменять параметры автоматически; при нехватке памяти загрузка модели завершится ошибкой.

По умолчанию: “--fit on” (включено).

env: LLAMA_ARG_FIT - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-fitt, --fit-target MiB0,MiB1,MiB2,…

target margin per device for --fit, comma-separated list of values, single value is broadcast across all devices

(default: 1024)

(env: LLAMA_ARG_FIT_TARGET)

Комментарий:

Задаёт объём памяти (в MiB), который следует оставить свободным. Работает совместно с параметром “--fit”. Если в системе несколько устройств - значения перечисляются через запятую. Если указать одно значение, оно будет применяться для всех устройств. Используется для подстраховки, чтобы оставить запас свободной памяти на каждом устройстве после размещения модели и контекста.

Например: “--fit-target 2048” - оставить 2048 MiB (2 GiB) свободными.

По умолчанию: “--fit-target 1024”.

env: LLAMA_ARG_FIT_TARGET - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-fitc, --fit-ctx N

minimum ctx size that can be set by --fit option

(default: 4096)

(env: LLAMA_ARG_FIT_CTX)

Комментарий:

Задаёт минимальный размер контекста (в токенах), ниже которого “--fit” не сможет уменьшать контекст для экономии памяти. Работает совместно с параметром “--fit”.

Например: “--fit-ctx 4096”. При заданной длине контекста “--ctx-size 32768”, если памяти не хватает и при включённом “--fit on” llama.cpp может автоматически уменьшать размер контекста, но не ниже 4096 токенов.

По умолчанию: “--fit-ctx 4096”.

env: LLAMA_ARG_FIT_CTX - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

--check-tensors

check model tensor data for invalid values

(default: false)

Комментарий:

Проверяет тензоры на некорректные значения при загрузке модели (NaN, Inf и тп.). Помогает выявить повреждённую модель, но может замедлять загрузку.

По умолчанию: не используется (выключено).

--override-kv KEY=TYPE:VALUE,…

advanced option to override model metadata by key. to specify multiple overrides, either use comma-separated values. types: int, float, bool, str. example: --override-kvtokenizer.ggml.add_bos_token=bool:false,tokenizer.ggml.add_eos_token=bool:false

Комментарий:

Переопределяет метаданные модели без изменения исходного файла GGUF. В файлах GGUF хранятся все сопутствующие данные модели: конфигурация, токенизатор, информация о спец-токенах и тд. Все в одном файле вместе с весами, в отличии от, например, моделей формата Hugging Face transformers. Через этот параметр можно переопределить метаданные (настройки) модели на лету при запуске, без правки GGUF файла.

Примеры:

“--override-kv tokenizer.ggml.add_bos_token=bool:false” - модель добавляла BOS-токен из метаданных GGUF, теперь не будет добавлять (может понадобиться для экспериментов).

“--override-kv llama.context_length=int:32768” - если было неправильно прописано значение “context_length”, можно подправить прямо при загрузке модели не трогая сам GGUF-файл.

--op-offload, --no-op-offload

whether to offload host tensor operations to device

(default: true)

Комментарий:

[Ремарка: описание работы параметра может быть не точным]

Следует ли переносить операции над тензорами на GPU, если веса лежат в RAM.

Подробнее. Когда веса лежат в RAM (CPU), но вычисления тяжёлые, например матричные умножения при обработке больших батчей (prompt processing), они всё равно выполняются на GPU: веса подгружаются туда на время операции. Это включено по умолчанию. Параметр “--no-op-offload” отключает это, все операции остаются на CPU. Это нужно, если, например, перемещение весов по PCIe съедает выигрыш (медленная шина) или в некоторых других случаях.

По умолчанию: “--op-offload” (включено).

--lora FNAME

path to LoRA adapter (use comma-separated values to load multiple adapters)

Комментарий:

Подключает LoRA-адаптер к модели. Указывается путь к LoRA. Можно указать несколько адаптеров через запятую.

Примечание: LoRA - это более легкий finetuning, который меняет поведение модели без её полного переобучения.

--lora-scaled FNAME:SCALE,…

path to LoRA adapter with user defined scaling

(format: FNAME:SCALE,…) note: use comma-separated values

Комментарий:

[Ремарка: описание работы параметра может быть не точным]

Подключает LoRA-адаптер к модели с указанием степени влияния LoRA. Как параметр “--lora”, только с указанием степени влияния. Задается путь к адаптеру и через двоеточие степень его влияния. Можно указать через запятую несколько LoRA и степень влияния каждого из них, значения суммируются.

SCALE: рабочий диапазон примерно от “-2.0” до “2.0”, но не ограничен этими значениями; 0 - нет эффекта. На практике обычно используется от “0.5” до “1.0”, значения >1 могут давать искажения. Например, коэффициенты: "0.5 - эффект LoRA слабее; 1.0 - средний (стандартный); 1.5 - эффект заметно сильнее и может давать искажения. При отрицательном значении эффект LoRA может быть непредсказуемым, использовать не рекомендуется.

--control-vector FNAME

add a control vector note: use comma-separated values to add multiple control vectors

Комментарий:

Подключает Control Vector для изменения поведения модели. Указывается путь к файлу, можно указать несколько векторов через запятую.

Примечание: Контрольные векторы меняют скрытые состояния модели во время инференса, в отличие от LoRA, которые меняют веса модели. Суть параметров примерно одинаковая - корректировка поведения модели, но осуществляется она разными методами.

--control-vector-scaled FNAME:SCALE,…

add a control vector with user defined scaling SCALE

(format: FNAME:SCALE,…) note: use comma-separated values

Комментарий:

[Ремарка: описание работы параметра может быть не точным]

Подключает Control Vector к модели с указанием степени влияния. Как параметр “--control-vector”, только с указанием степени влияния. Задается путь к контрольному вектору и через двоеточие степень его влияния. Можно указать через запятую несколько контрольных вектора и степень влияния каждого из них, значения суммируются.

SCALE: рабочий диапазон примерно от “-2.0” до “2.0”, но не ограничен этими значениями; 0 - нет эффекта. На практике обычно используется от “0.3” до “1.0”, значения >1 могут давать искажения. Например, коэффициенты: "0.3 - эффект слабее; 1.0 - средний (стандартный); 1.5 - эффект заметно сильнее и может давать искажения. При отрицательном значении эффект может быть непредсказуемым, использовать не рекомендуется.

--control-vector-layer-range START END

layer range to apply the control vector(s) to, start and end inclusive

Комментарий:

Ограничивает слои модели, к которым применяются контрольные вектора (параметры “--control-vector” или “--control-vector-scaled”).

START - первый слой, END - последний слой, нумерация начинается с 0.

Пример: “--control-vector-layer-range 10 20” - контрольные вектора действуют только на слои 10-20 включительно.

Параметр применяется глобально для всех подключаемых контрольных векторов.

-m, --model FNAME

model path to load

(env: LLAMA_ARG_MODEL)

Комментарий:

Загрузка модели из локального файла. Указывается относительный или абсолютный путь к файлу модели.

env: LLAMA_ARG_MODEL - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-mu, --model-url MODEL_URL

model download url

(default: unused)

(env: LLAMA_ARG_MODEL_URL)

Комментарий:

Скачивает модель по указанному URL и загружает её. Модель остается в кэше, который можно посмотреть по команде “--cache-list”.

По умолчанию: не используется.

env: LLAMA_ARG_MODEL_URL - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-dr, --docker-repo [<repo>/]<model>[:quant]

Docker Hub model repository. repo is optional, default to ai/.

quant is optional, default to :latest. example: gemma3

(default: unused)

(env: LLAMA_ARG_DOCKER_REPO)

Комментарий:

Загрузка модели из Docker Hub. Опционально можно указать конкретный “repo” (по умолчанию “ai/”). Также можно указать тип квантизации модели. Если не указать вариант квантизации, будет использоваться “:latest” (вариант модели по умолчанию).

Пример: “--docker-repo ai/gemma3:Q4_K_M”.

По умолчанию: не используется.

env: LLAMA_ARG_DOCKER_REPO - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-hf, -hfr, --hf-repo <user>/<model>[:quant]

Hugging Face model repository; quant is optional, case-insensitive,

default to Q4_K_M, or falls back to the first file in the repo if Q4_K_M doesn’t exist.

mmproj is also downloaded automatically if available. to disable, add --no-mmproj

example: unsloth/phi-4-GGUF:q4_k_m

(default: unused)

(env: LLAMA_ARG_HF_REPO)

Комментарий:

Загрузка модели из Hugging Face. Указывается владелец репозитория (user), имя модели (model), необходимая квантизация (quant, регистронезависимый параметр). Если не указать тип квантизации, будет выбран “Q4_K_M”; если такой квантизации в репозитории нет, будет выбран первый доступный вариант. Также будет автоматически скачан файл “mmproj” (при его наличии). Чтобы его не скачивать нужно указать параметр “--no-mmproj”.

Справка: “mmproj” - это проектор для мультимодальных моделей (модели, которые кроме текста понимают изображения/видео/речь). Он переводит выход энкодера (например, vision-энкодера) в пространство эмбеддингов LLM. В результате изображение превращается в последовательность векторов, которые LLM обрабатывает так же, как эмбеддинги обычных текстовых токенов.

Пример: “--hf-repo unsloth/phi-4-GGUF:Q6_K”.

По умолчанию: не используется.

env: LLAMA_ARG_HF_REPO - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-hff, --hf-file FILE

Hugging Face model file. If specified, it will override the quant in --hf-repo

(default: unused)

(env: LLAMA_ARG_HF_FILE)

Комментарий:

Загрузка модели с Hugging Face по имени файла. Используется совместно с “--hf-repo”. Если этот параметр задан, он переопределяет тип квантизации модели, указанный в “--hf-repo”. То есть, приоритет этого параметра выше.

Пример: “--hf-repo unsloth/phi-4-GGUF --hf-file phi-4-Q6_K.gguf”.

По умолчанию: не используется.

env: LLAMA_ARG_HF_FILE - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-hfv, -hfrv, --hf-repo-v <user>/<model>[:quant] (в новых версиях параметр отсутствует)

Hugging Face model repository for the vocoder model

(default: unused)

(env: LLAMA_ARG_HF_REPO_V)

Комментарий:

Загрузка vocoder-модели из Hugging Face. Указывается владелец репозитория (user), имя модели (model), необходимая квантизация (quant, регистронезависимый параметр). Если не указать тип квантизации, будет выбран “Q4_K_M”; если такой квантизации в репозитории нет, будет выбран первый доступный вариант.

Справка: Vocoder-модель - модель, которая превращает аудио-токены, выданные основной TTS-моделью, в звук. Соответственно, работает только совместно с основной TTS-моделью, которая подключается отдельно.

По умолчанию: не используется.

env: LLAMA_ARG_HF_REPO_V - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-hffv, --hf-file-v FILE (в новых версиях параметр отсутствует)

Hugging Face model file for the vocoder model

(default: unused)

(env: LLAMA_ARG_HF_FILE_V)

Комментарий:

Загрузка vocoder-модели с Hugging Face по имени файла. Используется совместно с “--hf-repo-v”.

По умолчанию: не используется.

env: LLAMA_ARG_HF_FILE_V - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-hft, --hf-token TOKEN

Hugging Face access token

(default: value from HF_TOKEN environment variable)

(env: HF_TOKEN)

Комментарий:

Токен доступа к Hugging Face. Нужен для приватных репозиториев и для моделей с gated-доступом (требуется принять лицензионное соглашение). Пример: “--hf-repo user/private-model --hf-token hf_xxxxxxxxx”.

По умолчанию: значение берется из переменной окружения HF_TOKEN.

env: HF_TOKEN - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

--log-disable

Log disable

Комментарий:

Отключает логирование. Ответы модели и базовая служебная информация не затрагиваются.

--log-file FNAME

Log to file

(env: LLAMA_LOG_FILE)

Комментарий:

Запись логов в файл. Указывается путь и имя файла, либо только имя файла.

Например “--log-file gemma3_q8_test.log” - лог запишется в текущую папку, где был запущен экземпляр llama.cpp.

env: LLAMA_LOG_FILE - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

--log-jsonl, --no-log-jsonl

Log as JSONL (one JSON object per line) to stdout, this also disables colored logging

(default: disabled)

Комментарий:

Включает вывод логов в структурированном формате JSONL (JSON Lines). Логи пишутся в stdout, каждая запись - это отдельный JSON-объект на отдельной строке.

JSONL удобен для пост-обработки логов: каждая запись структурирована (имеется “ключ” и “значение”), поэтому записи можно фильтровать, сортировать и искать по именам полей и тд. В обычном текстовом логе каждая строка представляет собой обычный текст без явной структуры, и для детального анализа его приходится разбирать регулярными выражениями. При использовании JSONL в большинстве случаев этого делать не нужно: записи уже структурированы. При включении этого формата логов, автоматически отключается цветной вывод логов (“--log-colors”).

Возможные варианты:

“--log-jsonl” - JSONL-логирование включено.

“--no-log-jsonl” - JSONL-логирование выключено (обычный текстовый формат логов).

По умолчанию: “--no-log-jsonl” (выключено).

--log-colors [on|off|auto]

Set colored logging (‘on’, ‘off’, or ‘auto’)

(default: ‘auto’ - enables colors when output is to a terminal)

(env: LLAMA_LOG_COLORS)

Комментарий:

Цветные логи. Возможные варианты:

  • on - цвета включены.

  • off - цвета выключены.

  • auto (по умолчанию) - цвета включаются, только если вывод идёт в терминал; при логировании в файл или pipe (передача вывода программы на вход другой программе) ANSI-коды цветов не добавляются.

По умолчанию: “--log-colors auto”.

env: LLAMA_LOG_COLORS - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-v, --verbose, --log-verbose

Set verbosity level to infinity (i.e. log all messages, useful for debugging)

Комментарий:

Включение режима детального логирования, в лог будут попадать максимум информации. Часто используется при отладке. Для обычного использования может быть избыточен.

--offline

Offline mode: forces use of cache, prevents network access

(env: LLAMA_OFFLINE)

Комментарий:

Включить автономный offline-режим работы. Будет принудительно использоваться локальный кэш (“--cache-list”) и блокироваться доступ к сети (например для скачивания моделей). То есть, будут использоваться модели из кэша, если не задано иного.

env: LLAMA_OFFLINE - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

-lv, --verbosity, --log-verbosity N

Set the verbosity threshold. Messages with a higher verbosity will be ignored.

Values:

  • 0: generic output

  • 1: error

  • 2: warning

  • 3: info

  • 4: debug

(default: 1)

(env: LLAMA_LOG_VERBOSITY)

Комментарий:

Уровень детализации логов. Сообщения с более высоким уровнем детализации не будут попадать в лог.

Возможные варианты:

  • 0 - общая информация.

  • 1 - сообщения об ошибках.

  • 2 - предупреждения.

  • 3 - информационные сообщения.

  • 4 - все подробности работы (отладка).

По умолчанию: “--log-verbosity 1” (общая информация и сообщения об ошибках).

env: LLAMA_LOG_VERBOSITY - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

--log-prefix

Enable prefix in log messages

(env: LLAMA_LOG_PREFIX)

Комментарий:

Добавление префикса к строкам лога.

Это может выглядеть как:

[INFO] loading model.

[WARNING] low memory.

[ERROR] failed to load model.

env: LLAMA_LOG_PREFIX - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

--log-timestamps

Enable timestamps in log messages

(env: LLAMA_LOG_TIMESTAMPS)

Комментарий:

Добавляет метку времени к каждому сообщению в логе.

env: LLAMA_LOG_TIMESTAMPS - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

--spec-draft-type-k, -ctkd, --cache-type-k-draft TYPE

KV cache data type for K for the draft model

allowed values: f32, f16, bf16, q8_0, q4_0, q4_1, iq4_nl, q5_0, q5_1

(default: f16)

(env: LLAMA_ARG_SPEC_DRAFT_CACHE_TYPE_K)

Комментарий:

Как параметр “--cache-type-k”, только для подключаемой draft-модели. Задает тип данных для кэширования значений K (Attention Key). По умолчанию тип данных “f16” (float16). Можно задать квантованные значения, либо тип данных “bf16” (bfloat16), либо более точный “f32” (float32). Тип данных “f32” (float32) потребует под кэш в 2 раза больше памяти, и скорее всего не улучшит заметно качество генерации текста. Меньшие (квантованные) значения потребляют меньше памяти, но хуже по качеству генерации и могут работать медленее из-за дополнительной распаковки значений.

Для некоторых задач квантованные значения K-кэша, например “q8_0”, работают не сильно хуже исходных “f16”, но в других задачах ухудшение может быть более заметным. Типы квантования “q4_*” сильнее ухудшают качество генерации. Квантование K-кэша обычно ухудшает качество менее заметно, чем V-кэша.

Справка: Draft-модель - маленькая быстрая модель, которая работает совместно с основной (большой) моделью. Она быстро предсказывает несколько следующих токенов и передаёт их на проверку основной модели. Если предсказание подтверждается, основная модель принимает эти токены, не генерируя их пошагово самостоятельно, что ускоряет общую генерацию текста.

По умолчанию: “--cache-type-k-draft f16” (float16).

env: LLAMA_ARG_CACHE_TYPE_K_DRAFT - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.

--spec-draft-type-v, -ctvd, --cache-type-v-draft TYPE

KV cache data type for V for the draft model allowed

values: f32, f16, bf16, q8_0, q4_0, q4_1, iq4_nl, q5_0, q5_1

(default: f16)

(env: LLAMA_ARG_SPEC_DRAFT_CACHE_TYPE_V)

Комментарий:

Как параметр “--cache-type-v”, только для подключаемой draft-модели. Задает тип данных для кэширования значений V (Attention Value). По умолчанию тип данных “f16” (float16). Можно задать квантованные значения, либо тип данных “bf16” (bfloat16), либо более точный “f32” (float32). Тип данных “f32” (float32) потребует под кэш в 2 раза больше памяти, и скорее всего не улучшит заметно качество генерации текста. Меньшие (квантованные) значения потребляют меньше памяти, но хуже по качеству генерации и могут работать медленее из-за дополнительной распаковки значений.

Для некоторых задач квантованные значения V-кэша, например “q8_0”, работают не сильно хуже исходных “f16”, но в других задачах ухудшение может быть более заметным. Типы квантования “q4_*” сильнее ухудшают качество генерации. Квантование V-кэша обычно ухудшает качество сильнее, чем K-кэша.

Справка: Draft-модель - маленькая быстрая модель, которая работает совместно с основной (большой) моделью. Она быстро предсказывает несколько следующих токенов и передаёт их на проверку основной модели. Если предсказание подтверждается, основная модель принимает эти токены, не генерируя их пошагово самостоятельно, что ускоряет общую генерацию текста.

По умолчанию: “--cache-type-v-draft f16” (float16).

env: LLAMA_ARG_CACHE_TYPE_V_DRAFT - переменная окружения в ОС, в ней можно указать значение этого параметра для текущей сессии.