Как подключить локальную нейросеть через OpenAI-совместимый API
Раздел: API и интеграции.
OpenAI-совместимый API — это поддержка определённого формата HTTP-запросов и ответов. В локальном сценарии вычисление выполняет ваш движок, а не облачный сервис. При этом совместимость обычно частичная: обычный чат, изображения, инструменты и структурированный вывод нужно проверять по отдельности.
Сначала получите работающую модель
Запустите модель в AI Server Manager и проверьте короткий запрос через чат. Затем выясните адрес нужного сервиса: это может быть защищённый маршрут панели или внутренний HTTP-порт движка. Не смешивайте порт панели управления, порт API конкретной модели и адрес стороннего сервиса.
У разных движков модель идентифицируется по-разному. Используйте имя, которое реально обслуживает endpoint, а не автоматически придуманное имя папки на диске. Если доступен список моделей, проверьте фактический идентификатор через соответствующий маршрут.
Какие данные нужны приложению
- Базовый URL API, включая правильный префикс пути.
- Идентификатор запущенной модели.
- Способ аутентификации, если он предусмотрен выбранным маршрутом.
- Таймаут, подходящий для длины запроса и прогрева.
- Настройки streaming и предельной длины ответа.
Совместимый клиент может добавлять /v1 самостоятельно. Проверьте его правила, чтобы не получить адрес с двойным /v1. Адрес 127.0.0.1 внутри контейнера означает этот контейнер, а не автоматически хост или соседний сервис.
Пример минимального запроса
Ниже учебный пример для API, который уже доступен на локальном порту 8000 и действительно обслуживает модель local-model. Адрес, имя и способ авторизации необходимо заменить на ваши. Переменная LOCAL_AI_TOKEN должна быть задана безопасно, если сервер требует токен; не вставляйте реальный ключ в статью, репозиторий или историю задач.
curl --fail-with-body http://127.0.0.1:8000/v1/chat/completions \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $LOCAL_AI_TOKEN" \
-d '{"model":"local-model","messages":[{"role":"user","content":"Ответь одним словом: готово"}],"max_tokens":32,"stream":false}'
Сначала проверьте обычный ответ без streaming. Затем отдельно включайте потоковую выдачу в приложении: она меняет способ чтения ответа, но не исправляет отсутствие модели или несовместимый шаблон чата.
Как разбирать ошибки
401 или 403 означают, что нужно проверить доступ; повторная загрузка весов обычно не решает эту причину. При 404 проверьте маршрут и имя модели. При 400 изучите тело ответа: возможны неподдерживаемые параметры или неверный формат сообщения.
503 во время загрузки может означать, что модель ещё не готова обслуживать запросы. Но повторяющийся 503 после ошибки инициализации нельзя считать нормальным ожиданием: откройте консоль модели. Если клиент оборвал соединение по таймауту, перед повтором учитывайте, что предыдущая задача могла продолжить выполняться.
Проверяйте дополнительные функции отдельно
Для tools модель должна понимать соответствующий шаблон и runtime должен поддерживать разбор вызовов. Обычный текстовый ответ этого не подтверждает. То же относится к vision, JSON-режиму и отдельным маршрутам embeddings или audio.
Не публикуйте незащищённый внутренний порт движка ради удобства подключения. Используйте управляемый доступ и HTTPS для внешних соединений. Ключи храните на серверной стороне приложения, а не в общедоступном JavaScript браузера.
Начальная настройка: запуск и чат. Справка по конкретной реализации: OpenAI-совместимый сервер vLLM. Наличие похожего API у другого движка не означает идентичный набор функций.
О материале
Материал подготовлен с помощью ИИ с проверкой по пользовательскому руководству панели и указанным справочным источникам. Параметры и доступные функции зависят от версии установленной сборки; приведённые примеры не являются результатами отдельного бенчмарка.