Локальную нейросеть можно запустить прямо на домашнем компьютере: без ежемесячной подписки, оплаты API и отправки рабочих данных на сторонние серверы. В этой инструкции разберём установку llama.cpp на Windows, загрузку модели gpt-oss-20b в формате GGUF с Hugging Face, запуск через видеокарту NVIDIA и проверку OpenAI-совместимого API.
Что получится в итоге?
- локальная нейросеть, работающая без облачного API;
- запуск вычислений на видеокарте NVIDIA через CUDA;
- встроенный веб-интерфейс llama-server;
- маршруты /v1/models и /v1/chat/completions;
- готовый BAT-файл для повторного запуска модели;
- понимание основных параметров llama.cpp и способов уменьшить расход видеопамяти.
Что потребуется?
- Windows 10 или Windows 11 x64;
- видеокарта NVIDIA со свежим драйвером;
- желательно 16 ГБ видеопамяти для gpt-oss-20b;
- 32 ГБ оперативной памяти;
- примерно 20–30 ГБ свободного места;
- стабильное соединение для первоначального скачивания модели.
Запуск только на процессоре тоже возможен, но скорость генерации будет заметно ниже. Дальше рассматривается CUDA-сборка для NVIDIA.
Почему gpt-oss-20b?
gpt-oss-20b — открытая модель OpenAI, которую можно запускать локально. Она подходит для обычного диалога, генерации текстов, анализа кода, структурированных ответов и автоматизации через API. Модель достаточно сильная для домашнего использования, но при этом её можно разместить на видеокарте с 16 ГБ памяти при разумном размере контекста.
Модель поддерживает большое окно контекста, однако максимальное значение не означает, что его нужно сразу включать. Контекст занимает дополнительную память под KV-кеш. Для чата, программирования и анализа статей разумно начинать с 8 192 или 16 384 токенов.
Что такое GGUF и какую квантизацию выбрать
GGUF — формат моделей, используемый llama.cpp. Обычно модель распространяется в нескольких вариантах квантизации. Квантизация уменьшает размер весов и расход памяти, иногда с небольшой потерей качества.
| Вариант | Расход памяти | Когда выбирать |
| Q4_K_M | минимальный из рекомендуемых | лучший старт для 12–16 ГБ VRAM |
| Q5_K_M | немного выше Q4 | компромисс между размером и качеством |
| Q6_K | выше среднего | если после загрузки остаётся запас памяти |
| Q8_0 | самый высокий среди перечисленных | если важнее качество и хватает VRAM |
| F16 | очень высокий | для домашней видеокарты обычно нецелесообразен |
Шаг 1. Создаём папки
В примерах используется следующая структура:
E:\ai\
├── llama\
└── models\
└── gpt-oss-20b\Пути можно изменить. Главное — потом указать те же директории в BAT-файле.
Шаг 2. Скачиваем llama.cpp для Windows и NVIDIA
Откройте страницу релизов официального репозитория llama.cpp и скачайте сборку для Windows x64 с поддержкой CUDA. Не выбирайте архив, предназначенный только для CPU, иначе видеокарта использоваться не будет.
Официальный репозиторий: github.com/ggml-org/llama.cpp. Готовые сборки находятся в разделе Releases.
Распакуйте файлы в папку:
E:\ai\llamaВ ней должны находиться как минимум:
llama-server.exe
llama-cli.exe
llama-bench.exe
ggml.dll
ggml-base.dll
ggml-cpu.dll
ggml-cuda.dllСостав DLL меняется между версиями, поэтому не переносите один EXE отдельно: распаковывайте весь архив сборки.
Проверяем сборку llama.cpp
cd /d E:\ai\llama
llama-server.exe --version
llama-server.exe --list-devices
В списке устройств должна появиться видеокарта, например CUDA0: NVIDIA GeForce RTX .... Если отображается только CPU, вероятнее всего скачана неверная сборка, не распакованы CUDA-библиотеки или требуется обновить драйвер NVIDIA.
Шаг 3. Устанавливаем Hugging Face CLI
Модель можно скачать через браузер, но для файла размером более 10 ГБ удобнее использовать официальную команду hf: она умеет возобновлять загрузку после обрыва.
Вариант A: официальный установщик для Windows
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"После установки закройте PowerShell, откройте его заново и выполните:
hf --help
hf versionВариант B: установка через Python
Этот вариант подходит, если Python уже установлен и добавлен в PATH.
py -m pip install --upgrade "huggingface_hub[cli]"
hf --helpШаг 4. Скачиваем gpt-oss-20b с Hugging Face
Создадим отдельную папку модели:
New-Item -ItemType Directory -Force "E:\ai\models\gpt-oss-20b"Скачиваем рекомендуемый файл Q4_K_M:
hf download unsloth/gpt-oss-20b-GGUF gpt-oss-20b-Q4_K_M.gguf --local-dir "E:\ai\models\gpt-oss-20b"После завершения должен появиться файл:
E:\ai\models\gpt-oss-20b\gpt-oss-20b-Q4_K_M.ggufКак скачать Q8_0
hf download unsloth/gpt-oss-20b-GGUF gpt-oss-20b-Q8_0.gguf --local-dir "E:\ai\models\gpt-oss-20b"Как посмотреть объём загрузки заранее
hf download unsloth/gpt-oss-20b-GGUF gpt-oss-20b-Q4_K_M.gguf --dry-runЧто делает --local-dir
Параметр --local-dir кладёт модель в понятную директорию, а не только во внутренний кеш Hugging Face. Рядом может появиться служебная папка .cache. Она помогает проверять файлы и возобновлять загрузку.
Можно ли скачать модель прямо через llama.cpp
Да. llama.cpp умеет загружать модель с Hugging Face самостоятельно:
llama-server.exe -hf unsloth/gpt-oss-20b-GGUF:Q4_K_M
Для постоянного сервера удобнее заранее скачать GGUF и явно указать путь через --model. Тогда всегда понятно, какой именно файл запускается.
Шаг 5. Создаём BAT-файл
Создайте файл start-gpt-oss-20b.bat и вставьте следующий код:
@echo off
chcp 65001 >nul
setlocal
title gpt-oss-20b - llama.cpp
set "LLAMA_DIR=E:\ai\llama"
set "MODEL=E:\ai\models\gpt-oss-20b\gpt-oss-20b-Q4_K_M.gguf"
set "PORT=8090"
echo ============================================
echo gpt-oss-20b - llama.cpp
echo ============================================
echo.
echo Model: %MODEL%
echo Local API: http://127.0.0.1:%PORT%/v1
echo.
if not exist "%LLAMA_DIR%\llama-server.exe" (
echo ERROR: llama-server.exe not found:
echo %LLAMA_DIR%\llama-server.exe
pause
exit /b 1
)
if not exist "%MODEL%" (
echo ERROR: model not found:
echo %MODEL%
pause
exit /b 1
)
cd /d "%LLAMA_DIR%"
echo Starting llama-server...
echo.
llama-server.exe ^
--model "%MODEL%" ^
--host 127.0.0.1 ^
--port %PORT% ^
--alias gpt-oss-20b ^
--ctx-size 16384 ^
--parallel 1 ^
--n-gpu-layers auto ^
--fit on ^
--fit-target 2048 ^
--fit-ctx 16384 ^
--device CUDA0 ^
--flash-attn on ^
--cache-type-k q8_0 ^
--cache-type-v q8_0 ^
--batch-size 256 ^
--ubatch-size 128 ^
--reasoning off ^
--jinja ^
--temp 0.6 ^
--top-p 0.95 ^
--top-k 20 ^
--min-p 0.0 ^
--presence-penalty 0.0 ^
--repeat-penalty 1.05 ^
--timeout 1800
echo.
echo llama-server stopped.
pauseРазбор BAT-файла
@echo off
Отключает вывод каждой команды BAT-файла. В консоли остаются только наши сообщения и логи llama.cpp.
chcp 65001 >nul
Переключает консоль Windows на UTF-8, чтобы русский текст отображался корректно. >nul скрывает служебное сообщение о смене кодовой страницы.
setlocal
Ограничивает переменные окружения текущим BAT-файлом. После закрытия окна значения LLAMA_DIR, MODEL и PORT не останутся в системе.
set LLAMA_DIR, MODEL и PORT
В начале BAT-файла пути вынесены в переменные. Это удобнее, чем искать и менять один и тот же путь в нескольких местах.
set "LLAMA_DIR=E:\ai\llama"
set "MODEL=E:\ai\models\gpt-oss-20b\gpt-oss-20b-Q4_K_M.gguf"
set "PORT=8090"Проверка существования файлов
Два блока if not exist сразу сообщат, если неверно указан путь к серверу или модели. Без этой проверки окно могло бы просто закрыться с неочевидной ошибкой.
cd /d
Переходит в папку llama.cpp. Ключ /d позволяет одновременно сменить диск, например с C: на E:.
Символ ^
В BAT-файле символ ^ переносит длинную команду на следующую строку. После него не должно быть пробелов.
Разбор параметров llama-server
--model
--model "%MODEL%"
Указывает путь к GGUF-файлу. Короткая форма параметра — -m. Кавычки обязательны, если в пути есть пробелы.
--host 127.0.0.1
Сервер принимает подключения только с текущего компьютера. Это безопасный вариант для локальной работы. Не заменяйте адрес на 0.0.0.0, если не планируете открывать доступ другим устройствам и не настроили авторизацию.
--port 8090
Порт локального HTTP-сервера. После запуска интерфейс будет доступен по адресу http://127.0.0.1:8090. Если порт занят, можно заменить его, например, на 8091.
--alias gpt-oss-20b
Задаёт удобное имя модели в OpenAI-совместимом API. Клиенты смогут отправлять model: gpt-oss-20b, не зная полного имени GGUF-файла.
--ctx-size 16384
Размер контекста в токенах. В него входят системный промт, история диалога, текст документа и генерируемый ответ. Большой контекст требует больше памяти под KV-кеш.
| Значение | Подходит для |
| 4096 | коротких запросов и экономии памяти |
| 8192 | обычного чата и небольших документов |
| 16384 | кода, статей и длинных инструкций |
| 32768 и выше | только при достаточном запасе RAM/VRAM |
--parallel 1
Количество одновременно обслуживаемых последовательностей. Для одного пользователя значение 1 экономит память. Несколько параллельных слотов нужны только при одновременной работе нескольких клиентов.
--n-gpu-layers auto
Определяет, сколько слоёв модели разместить на видеокарте. Режим auto позволяет llama.cpp подобрать подходящее значение. Режим all пытается загрузить всё на GPU и может вызвать нехватку памяти.
--fit on
Разрешает серверу подстраивать параметры размещения модели под доступную память. Особенно полезно, когда модель находится на границе возможностей видеокарты.
--fit-target 2048
Просит оставить примерно 2 ГБ свободной видеопамяти после размещения модели. Этот запас нужен для рабочих CUDA-буферов, KV-кеша и обработки запросов.
--fit-ctx 16384
Минимальный размер контекста, который должен сохранить автоматический режим fit. Если требуется более агрессивная экономия памяти, можно поставить 8192.
--device CUDA0
Явно выбирает первую CUDA-видеокарту. Если в системе одна NVIDIA, обычно это CUDA0. Доступные устройства показывает команда llama-server.exe --list-devices.
--flash-attn on
Включает Flash Attention. На поддерживаемых видеокартах это может ускорить вычисления и уменьшить расход памяти. При проблемах замените значение на auto.
--cache-type-k q8_0 и --cache-type-v q8_0
Задают формат ключей и значений KV-кеша. Q8_0 экономит память по сравнению с F16 и обычно сохраняет хорошее качество.
При нехватке VRAM можно уменьшить кеш:
--cache-type-k q4_0
--cache-type-v q4_0--batch-size 256
Логический размер батча при обработке входного промта. Большое значение ускоряет разбор длинного текста, но требует больше памяти. Для 16 ГБ VRAM значение 256 является осторожным стартом.
--ubatch-size 128
Физический размер микробатча. Его уменьшение снижает пиковое потребление памяти, но может замедлить обработку длинных промтов.
--reasoning off
Отключает вывод отдельного канала рассуждений для задач, где нужен только готовый ответ. Это удобно для автоматизации и генерации JSON. Для интерактивного режима параметр можно изменить в соответствии с возможностями конкретной версии llama.cpp.
--jinja
Включает применение чат-шаблонов Jinja. Модель получает сообщения в том формате, на котором была обучена. Обычно подходящий шаблон уже записан в метаданных GGUF.
--temp 0.6
Температура управляет случайностью генерации. Низкое значение делает ответы более предсказуемыми, высокое — более разнообразными.
| Температура | Поведение |
| 0.2–0.4 | строгий код, извлечение данных, классификация |
| 0.5–0.7 | универсальный режим |
| 0.8–1.0 | более творческие тексты |
| выше 1.0 | повышенный риск странных ответов |
--top-p 0.95
Оставляет набор токенов, суммарная вероятность которых достигает 95%. Работает вместе с temperature и помогает контролировать разнообразие.
--top-k 20
Оставляет двадцать наиболее вероятных вариантов следующего токена. Меньшее значение делает ответы стабильнее.
--min-p 0.0
Минимальная относительная вероятность токена. Значение 0 отключает этот фильтр. При необходимости более строгой генерации можно попробовать 0.05.
--presence-penalty 0.0
Штраф за повторное использование уже появлявшихся токенов. Нулевое значение не вмешивается в терминологию и особенно удобно для кода.
--repeat-penalty 1.05
Небольшой штраф за повторы. Значение 1.0 фактически отключает его. Слишком высокий штраф может портить названия переменных, команды и технические термины.
--timeout 1800
Максимальное время ожидания в секундах для долгих операций. 1 800 секунд — это 30 минут. Такой запас полезен при обработке больших статей и медленной генерации.
Шаг 6. Первый запуск
Запустите BAT-файл двойным щелчком. Первая загрузка модели может занять некоторое время. В консоли должны появиться сообщения об обнаружении CUDA и размещении слоёв на GPU.
После успешного запуска откройте:
http://127.0.0.1:8090Не закрывайте окно llama-server: пока оно открыто, локальный API работает.
Шаг 7. Проверяем сервер через PowerShell
Проверка состояния
Invoke-RestMethod "http://127.0.0.1:8090/health"При готовой модели сервер должен вернуть статус ok.
Получаем список моделей
Invoke-RestMethod "http://127.0.0.1:8090/v1/models"Отправляем первый запрос
$model = (
Invoke-RestMethod "http://127.0.0.1:8090/v1/models"
).data[0].id
$body = @{
model = $model
messages = @(
@{
role = "system"
content = "Ты полезный русскоязычный помощник."
},
@{
role = "user"
content = "Кратко объясни, что такое REST API."
}
)
temperature = 0.6
max_tokens = 300
} | ConvertTo-Json -Depth 10
$response = Invoke-RestMethod `
-Uri "http://127.0.0.1:8090/v1/chat/completions" `
-Method Post `
-ContentType "application/json; charset=utf-8" `
-Body ([System.Text.Encoding]::UTF8.GetBytes($body))
$response.choices[0].message.contentОшибка cudaMalloc failed: out of memory
Ошибка означает, что llama.cpp не смог выделить нужный объём видеопамяти. Модель, KV-кеш, контекст и рабочие буферы используют память одновременно.
cudaMalloc failed: out of memory
unable to allocate CUDA0 buffer
llama_model_load: error loading modelКак исправлять нехватку памяти
- Уменьшить --ctx-size с 16384 до 8192.
- Поставить --fit-ctx 8192 или 4096.
- Перевести KV-кеш с q8_0 на q4_0.
- Уменьшить --batch-size до 128 и --ubatch-size до 64.
- Использовать --n-gpu-layers auto вместо all.
- Скачать Q4_K_M вместо Q8_0.
- Закрыть игры, Stable Diffusion, другие модели и тяжёлые приложения, использующие GPU.
Как проверить занятую видеопамять
nvidia-smiОблегчённая конфигурация для экономии памяти
llama-server.exe ^
--model "%MODEL%" ^
--host 127.0.0.1 ^
--port %PORT% ^
--ctx-size 8192 ^
--parallel 1 ^
--n-gpu-layers auto ^
--fit on ^
--fit-target 2048 ^
--fit-ctx 4096 ^
--device CUDA0 ^
--flash-attn auto ^
--cache-type-k q4_0 ^
--cache-type-v q4_0 ^
--batch-size 128 ^
--ubatch-size 64 ^
--jinja ^
--temp 0.6 ^
--top-p 0.95 ^
--top-k 20 ^
--repeat-penalty 1.05Предупреждение о CORS
Современная версия llama-server может предупредить, что CORS разрешён для всех источников и API-ключ не установлен. При адресе 127.0.0.1 сервер доступен только на текущем компьютере, поэтому для локальной работы это предупреждение не мешает.
Доступ из локальной сети
Чтобы обращаться к модели с другого компьютера в домашней сети, можно использовать --host 0.0.0.0, но обязательно добавьте авторизацию и разрешите порт в брандмауэре только для частной сети.
--host 0.0.0.0
--api-key "замените-на-длинный-случайный-ключ"Клиент должен отправлять заголовок:
Authorization: Bearer замените-на-длинный-случайный-ключЧто можно подключить к локальному API
- Laravel и обычные PHP-скрипты;
- OpenCode и другие инструменты для программирования;
- Continue для Visual Studio Code;
- собственный чат-интерфейс;
- генерацию описаний, SEO-текстов и комментариев;
- обработку документов и статей;
- локальные очереди заданий без оплаты облачного API.
Полезные ссылки
Итог
Мы скачали CUDA-сборку llama.cpp, установили Hugging Face CLI, загрузили модель gpt-oss-20b в формате GGUF, создали BAT-файл и запустили локальный OpenAI-совместимый API.
Основной адрес сервера:
http://127.0.0.1:8090Маршрут для чата:
POST http://127.0.0.1:8090/v1/chat/completionsПосле этого нейросеть можно использовать не только как обычный чат, но и как локальный движок для автоматизации собственных сайтов и приложений.
Вот и всё! Удачи с нейронками!
