LobeChat — открытое приложение для диалогов с ИИ; проект и образы постепенно переходят на имя LobeHub. Само приложение не предоставляет моделей: качество ответов зависит от подключённого API-провайдера. Для команд, использующих единый шлюз, ценность собственного API очевидна: один Base URL и один ключ позволяют переключаться между моделями и видеть расход в одном месте.

Материал опирается на распространённую версию 2026 года и идёт от способа развёртывания к настройке провайдера, проверке соединения, а затем к ассистентам, плагинам, базе знаний и командному развёртыванию. Интерфейс и имена переменных меняются от версии к версии, поэтому перед началом сверьтесь с документацией своей версии.

Примечание: LobeChat и LobeHub — продукты и товарные знаки их правообладателей, OpenAI — товарный знак OpenAI, Inc. Материал носит технический характер и не означает подчинения или сотрудничества с указанными компаниями. Состав моделей и цены — на странице цены на модели.

1. Сначала выберите способ развёртывания

LobeChat можно запустить только локально или развернуть на сервере для команды. Зависимости у этих сценариев разные:

Способ Когда подходит Основные зависимости Что учесть
Один контейнер Личная проверка, тест функций Docker, PostgreSQL Быстрее всего запустить; для долгой работы нужны хранилище и резервные копии
Docker Compose Долгая командная работа PostgreSQL, S3-совместимое хранилище, опционально Redis Официально рекомендуется, полный набор функций
Хостинг вроде Vercel Лёгкая проверка, минимум эксплуатации Внешний PostgreSQL, S3 У serverless есть лимит времени функции и нет поддержки WebSocket

В серверной версии 2026 года PostgreSQL стал обязательным компонентом; для базы знаний нужны pgvector и плагин полнотекстового поиска, для загрузки файлов — S3-совместимое хранилище. В старых версиях был чисто браузерный режим, новые в основном серверные, поэтому перед началом проверьте зависимости своей версии. Если готовите решение для команды, сразу планируйте по схеме Compose — меньше переделок позже.

2. Подготовьте три параметра

При любом способе развёртывания для собственного API нужны три вещи:

  • Base URL: https://ai.zhongshangqihang.com/v1 — OpenAI-совместимая точка входа.
  • API Key: создаётся в консоли после регистрации в ZSQH AI Gateway, с именем по проекту или среде.
  • ID модели: скопируйте API-идентификатор со страницы цены на модели, а не отображаемое имя на сайте.

Чаще всего ошибаются в двух последних: ключ вставляют с пробелом, а в ID модели добавляют суффикс версии или теряют заглавную букву. Сохраните ключ в менеджере паролей до начала настройки.

3. Запустите сервис и задайте переменные окружения

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

# пример lobehub.env, секреты сгенерируйте сами и храните безопасно
APP_URL=https://chat.example.com
DATABASE_URL=postgres://postgres:change-me@postgres:5432/postgres
AUTH_SECRET=сгенерируйте через openssl rand -base64 32
KEY_VAULTS_SECRET=сгенерируйте отдельно тем же способом
OPENAI_API_KEY=sk-ваш-ключ-шлюза
OPENAI_PROXY_URL=https://ai.zhongshangqihang.com/v1
OPENAI_MODEL_LIST=-all,+ваш-ID-модели

Подключите файл при запуске контейнера:

docker run -d --name lobehub -p 3210:3210 \
  --env-file lobehub.env lobehub/lobehub

Дождитесь в журнале сообщений о завершении миграции базы и Ready, затем откройте http://адрес-сервера:3210. Если журнал останавливается на ошибке подключения к базе, проверьте имя хоста, порт и пароль в DATABASE_URL; localhost внутри контейнера не равен хосту. Перед обновлением образа фиксируйте тег версии и не используйте latest постоянно.

4. Добавьте OpenAI-совместимого провайдера в интерфейсе

Переменные окружения подходят для общей конфигурации, настройки в интерфейсе — для личной проверки или временных изменений. На примере распространённой версии:

  1. Войдите и откройте настройки, раздел «AI-провайдеры».
  2. Выберите OpenAI или добавьте собственного провайдера с понятным названием, например «командный шлюз».
  3. В поле API-адреса укажите https://ai.zhongshangqihang.com/v1, только до /v1.
  4. Вставьте ключ шлюза и убедитесь, что нет лишних пробелов.
  5. Добавьте ID модели в список и отметьте реальные возможности: зрение, вызов инструментов, файлы.
  6. Сохраните и назначьте провайдера по умолчанию или выбирайте модель вручную в диалоге.

Собственный провайдер поддерживает метки возможностей модели, и это часто упускают. Неверная метка не вызовет ошибку сразу, но плагин, понимание изображений или загрузка файлов сломаются посреди работы. Если не уверены, сначала отметьте меньше возможностей и дополните после проверки на реальной задаче.

5. Проверка: сначала curl, потом диалог

После настройки не начинайте работу сразу — подтвердите цепочку минимальным запросом:

export ZSQH_API_KEY="sk-ваш-ключ"

curl -sS "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"ваш-ID-модели","messages":[{"role":"user","content":"Ответьте только OK"}]}'

Если в ответе есть choices, адрес, ключ и модель как минимум работают. Затем вернитесь в LobeChat, создайте диалог, выберите ту же модель и отправьте «Ответьте только OK». Когда оба шага проходят, переходите к ассистентам и базе знаний.

Типовые коды состояний указывают направление: 401 — проверьте ключ и пробелы, 404 — путь /v1, model not found — совпадение ID модели со страницей цен, 429 — расход и параллелизм шлюза. Меняйте одну переменную за раз, иначе непонятно, что именно помогло.

6. Ассистенты: распределите модели по задачам

Ассистенты (в новых версиях также Agent) сохраняют системный промпт, модель и параметры. Практичный подход — разделить их по задачам, а не складывать все модели в список по умолчанию:

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

Пусть каждый ассистент решает один класс задач: чем короче промпт, тем проще его поддерживать. Команда может распространять промпты частых ассистентов как шаблоны, но ключей в них быть не должно.

7. Плагины и база знаний: сначала проверьте зависимости

Плагины зависят от умения модели вызывать функции. Если модель не поддерживает вызов инструментов, кнопка плагина может оставаться активной, но вызов завершится ошибкой. При собственном маркетплейсе плагинов нужно настроить адрес индекса и ключи плагинов; устанавливайте только плагины из доверенных источников и проверяйте, какие данные они читают.

У базы знаний больше зависимостей: обычно PostgreSQL, pgvector, S3-совместимое хранилище и модель эмбеддингов. Текущая версия по умолчанию использует модель эмбеддингов OpenAI, но через переменные окружения можно указать другую совместимую модель. При подключении шлюза сначала убедитесь, что он предоставляет интерфейс эмбеддингов и нужную модель; без этого семантический поиск в базе знаний не работает.

Рекомендуется сначала загрузить один-два файла с известными ответами, проверить поиск конкретными вопросами и только затем загружать пакет. Размер фрагментов, формат файлов и качество сканов влияют на результат; не меняйте несколько настроек сразу.

8. Командное развёртывание: конфигурация вместе, ключи врозь

При командном использовании придерживайтесь нескольких границ:

  • В серверных переменных окружения только общая конфигурация и модели по умолчанию; ключи — в хранилище секретов, не в Git.
  • Каждый участник использует свой ключ шлюза с именем по человеку, чтобы при увольнении или утечке отозвать отдельно.
  • База и S3 входят в план резервного копирования; файлы копий обрабатываются как чувствительные данные.
  • Публичное развёртывание требует HTTPS и контроля доступа на уровне обратного прокси.
  • Для потоковых ответов отключите буферизацию прокси, иначе ответ придёт целиком или зависнет.
  • На стороне шлюза задайте бюджет и лимит параллелизма, регулярно смотрите отчёт о расходе.

Если речь о небольшой внутренней команде, можно разделить ключи по проектам на стороне шлюза и дополнить их учётными записями LobeChat. Два уровня записей упрощают диагностику и расчёты.

Частые вопросы

Как связаны LobeChat и LobeHub?

LobeChat — раннее название проекта; в документации и образах новой версии 2026 года используется бренд LobeHub. Функциональность продолжается, но переменные окружения и входы интерфейса изменились; при развёртывании ориентируйтесь на актуальную официальную документацию.

Нужно ли указывать /v1 в Base URL?

Да. Достаточно https://ai.zhongshangqihang.com/v1, не указывайте полный путь /chat/completions: клиент добавит его сам. Некоторые прокси передают /v1 самостоятельно — ориентируйтесь на фактический результат проверки.

После настройки переменных список моделей всё равно пуст?

Сначала проверьте имя и синтаксис OPENAI_MODEL_LIST: -all,+ID-модели разделяется английской запятой без пробелов. После изменения переменных контейнер нужно пересоздать; простой перезапуск не всегда загружает новые значения.

Файл загружается в базу знаний, но поиск ничего не находит?

Проверяйте по порядку зависимостей: установлен ли плагин векторов в базе, доступен ли S3 для записи, вызывается ли модель эмбеддингов. Если хотя бы одно условие не выполнено, файл может выглядеть загруженным, но индекс не построится.

Можно ли команде использовать один ключ?

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

Дальше

Подключение LobeChat делится на три шага: выбрать способ развёртывания, согласовать Base URL, ключ и ID модели, проверить через curl и реальный диалог. После запуска постепенно добавляйте ассистентов, плагины и базу знаний — проблем будет меньше. Для единой точки входа и учёта расхода можно зарегистрироваться в ZSQH AI Gateway; доступные модели и цены — на странице цены на модели.

Полезное чтение: