Обзор API koboldcpp

В прошлой статье мы уже разбирали, что такое koboldcpp и как запустить его локально. Но графический интерфейс — это только верхушка айсберга. На практике koboldcpp становится куда интереснее, когда перестаёт быть просто окном для генерации текста и начинает работать как локальная LLM с API. Без интернета, без ключей доступа и с полным контролем над происходящим.

Что из себя представляет API koboldcpp

Если коротко, API в koboldcpp — это обычный HTTP-сервер, который принимает JSON и возвращает JSON. Для веб-разработчика порог входа минимальный.

По структуре запросов koboldcpp API во многом напоминает OpenAI API: prompt, параметрамы генерации, параметры ответа.

Из личных наблюдений: при одинаковых моделях koboldcpp субъективно работает чуть бодрее, чем LM Studio. Без бенчмарков и цифр, просто по ощущениям в реальных запросах. Для пет-проектов и экспериментов этого более чем достаточно.

С чего начать работу с API koboldcpp

На практике, если не углубляться в тонкую настройку, вам понадобятся всего два API-метода:

/api/v1/generate

Базовый режим генерации текста.

Подходит для:

• генерации текста по prompt,
• автодополнения,
• простых сценариев без истории диалога.

Это самый простой способ поработать с локальной LLM.

/v1/chat/completions

Чат-режим, знакомый всем, кто использовал OpenAI API.

Подходит для:

• диалогов,
• ассистентов,
• сценариев с контекстом и ролями.

Если хочется ощущение «как у OpenAI, только локально» — это он.

Минимальный пример работы с API (PHP)

Один запрос, один ответ, минимум параметров. Пример ниже — обычный POST-запрос к локальному серверу koboldcpp.

$url = 'http://localhost:5001/api/v1/generate';

$data = [
    'prompt' => 'Объясни, что такое локальная LLM простыми словами',
    'max_length' => 200,
    'temperature' => 0.7
];

$options = [
    'http' => [
        'header'  => "Content-Type: application/json\r\n",
        'method'  => 'POST',
        'content' => json_encode($data),
        'timeout' => 30
    ]
];

$context  = stream_context_create($options);
$response = file_get_contents($url, false, $context);

$result = json_decode($response, true);

echo $result['results'][0]['text'] ?? '';

Здесь нет ничего специфичного для koboldcpp — ровно тот же подход, что и при работе с любым другим API. Отправляем prompt, получаем сгенерированный текст.

Именно в этот момент становится понятно, почему локальная LLM — это не игрушка, а нормальный инструмент для внутренних сервисов и экспериментов.

Чат-режим: почти как OpenAI, только локально

Для диалоговых сценариев удобнее использовать /v1/chat/completions. Логика там привычная: сообщения, роли, история диалога.

$url = 'http://localhost:5001/v1/chat/completions';

$data = [
    'messages' => [
        ['role' => 'system', 'content' => 'Ты полезный ассистент'],
        ['role' => 'user', 'content' => 'Чем koboldcpp отличается от облачных LLM?']
    ],
    'temperature' => 0.7,
    'max_tokens' => 300
];

$options = [
    'http' => [
        'header'  => "Content-Type: application/json\r\n",
        'method'  => 'POST',
        'content' => json_encode($data)
    ]
];

$context  = stream_context_create($options);
$response = file_get_contents($url, false, $context);

$result = json_decode($response, true);

echo $result['choices'][0]['message']['content'] ?? '';

Ощущения — почти те же, что и при работе с OpenAI API. Только:

• всё крутится локально,
• нет лимитов,
• модель — та, которую вы выбрали сами.

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

Ограничения и нюансы

Важно не строить иллюзий: скорость и качество генерации здесь напрямую зависят от выбранной модели и доступного железа. На слабых машинах длинные ответы будут появляться заметно медленнее, а формулировки у локальных LLM иногда могут «плыть». Это нормальное поведение для таких решений. При этом отсутствие ограничений на количество запросов позволяет спокойно перебирать разные варианты промптов и оставлять только самые удачные. Хорошо подобранный запрос способен частично нивелировать галлюцинации модели и сделать ответы заметно стабильнее.

Заключение

Koboldcpp — это не только интерфейс для генерации текста, но и полноценная локальная LLM, с которой можно работать через API. Если хочется поэкспериментировать с LLM, не привязываясь к внешним сервисам, это один из самых простых способов начать.

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