LobeChat объединяет модели разных провайдеров, плагины и базу знаний в одном интерфейсе. Настроек много, поэтому ошибки легко истолковать неверно. Чаще всего проблема не в самой модели, а в одном из четырёх слоёв: ключ не применяется, адрес или имя модели неверны, достигнут лимит квоты или параллелизма, сеть или CORS недоступны. Сначала классифицируйте ошибку, затем проверяйте по слоям — это эффективнее повторной установки клиента.

Разберём 401, 404, 429 и сбои соединения, а также проблемы потокового вывода, плагинов и базы знаний. Названия интерфейса и переменных окружения меняются от версии к версии — сверяйтесь с документацией своей версии. Модели и цены — на странице цены на модели, тарифы могут меняться.

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

1. Сначала зафиксируйте факты, потом определяйте категорию

Симптом Частый статус или сообщение Первая гипотеза Что проверить
401 Unauthorized invalid_api_key, пустой ответ Ключ не распознан Целостность ключа, принадлежность адресу, способ передачи
404 / model not found not_found_error, model_not_found Неверный путь или имя модели Base URL, /v1, ID модели
429 Too Many Requests rate_limit_error, insufficient_quota Лимит или нехватка квоты Параллелизм, расход, счёт
Failed to fetch Нет статуса, ошибка браузера Запрос не получил ответ DNS, прокси, файрвол, CORS
5xx server_error, страница ошибки шлюза Сбой upstream или шлюза Повтор и запись ID запроса
Сбой плагина или базы знаний Ошибка вызова инструмента, сбой загрузки Нет возможности или зависимости Вызов функций, хранилище, Embedding

Перед диагностикой зафиксируйте как минимум: время, версию, способ развёртывания (desktop, веб или Docker), статус, тело ответа и ID запроса. Без этих данных остаётся только угадывать.

2. 401: ключ не распознан

401 означает, что сервер отклонил ключ. Частые причины:

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

Сначала обойдите клиент. Отправьте минимальный запрос тем же ключом и на тот же адрес:

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":"ваш-model-id","messages":[{"role":"user","content":"Ответь только OK"}]}' \
  -w "\nHTTP %{http_code}\n"

Ответ 200 с choices означает, что ключ и адрес рабочие; если снова 401, проблема в копировании, правах или прокси. В Docker убедитесь, что переменная попала в контейнер: docker exec lobe-chat env | grep -i openai, имя контейнера уточните через docker ps. Настройки интерфейса принадлежат текущему пользователю и могут исчезнуть после смены устройства или очистки кеша; для команды предпочтительны переменные окружения.

3. 404 и model not found: проверьте адрес и модель по отдельности

404 бывает двух видов: путь не существует и модель не существует. В первом случае смотрите URL, во втором — ID модели.

В поле адреса прокси LobeChat иногда достаточно домена, иногда нужен /v1 — зависит от того, пересылает ли шлюз /v1 сам. Критерий простой: в итоговом адресе /v1 должен встречаться один раз. Частая ошибка — хост уже заканчивается на /v1, а путь добавляет ещё один, получается /v1/v1/chat/completions. Адрес прокси должен указывать на корень API, а не на полный /chat/completions.

model not found не связан с путём. ID модели различает регистр, суффикс версии и префикс провайдера; копируйте его со страницы цены на модели или из консоли. Если список ведётся через CUSTOM_MODELS, сначала проверьте минимальный набор -all,+одна-рабочая-модель, затем добавляйте остальные; запятые — латинские, без пробелов. Даже если модель есть в списке, убедитесь, что её тип и переключатели возможностей соответствуют реальности, иначе первый же вызов завершится ошибкой.

403 обычно означает, что ключ распознан, но модель или функция недоступна; не путайте с 401 и не меняйте ключ наугад.

4. CORS, прокси и TLS: ловушки прямого подключения из браузера

Когда веб-версия LobeChat отправляет запрос из браузера, шлюз должен разрешать кросс-доменные запросы с её домена. Типичный признак сбоя CORS — сообщение Access to fetch ... has been blocked by CORS policy в консоли, при этом curl работает нормально. Есть два решения: разрешить соответствующий Origin на шлюзе или использовать серверную пересылку, обойдя браузерную проверку CORS.

Если LobeChat развёрнут за Nginx, Caddy или Cloudflare, прокси-слой должен иметь доступ к шлюзу; не путайте хост API и адрес HTTP-прокси. Системный прокси, VPN, HTTP_PROXY и HTTPS_PROXY в контейнере могут накладываться друг на друга — оставьте один слой и исключите внутренние адреса через NO_PROXY.

Проблема TLS часто проявляется как UNABLE_TO_VERIFY_LEAF_SIGNATURE, обычно при корпоративном прокси с расшифровкой. Правильное решение — установить корпоративный корневой сертификат; установка NODE_TLS_REJECT_UNAUTHORIZED в 0 годится только для временной диагностики и снижает безопасность.

Сервис плагинов также должен разрешать Origin LobeHub. При самостоятельном развёртывании проверьте, что функция плагинов включена, а модель поддерживает вызов функций, иначе плагин упадёт на этапе выполнения.

5. 429: лимиты, параллелизм и квота

У 429 два частых значения: слишком много запросов или недостаточно квоты. Первое обычно сопровождается rate_limit_error, второе — insufficient_quota; действия противоположны.

  • Слишком много запросов: снизьте параллелизм, закройте лишние сеансы и клиенты; длинный контекст увеличивает расход токенов.
  • Недостаточно квоты: проверьте расход и счёт на шлюзе, пополните баланс или смените ключ; простые повторы не помогут.
  • Если в заголовках есть Retry-After, ждите по нему; если нет — используйте экспоненциальную задержку со случайным разбросом и задайте предел попыток.
  • При общем ключе несколько устройств и окон делят один лимит параллелизма.

Если 429 появляется только в длинных диалогах, сначала сожмите контекст или создайте новый чат, затем проверьте контекстное окно модели. Уменьшение «максимального числа сообщений контекста» лишь смягчает давление, но не заменяет управление расходом.

6. Обрыв потокового вывода: ответ оборвался на середине

LobeChat по умолчанию использует потоковый ответ. Обрыв чаще вызван не поломкой модели, а буферизацией SSE прокси, тайм-аутом простоя соединения или разрывом upstream во время генерации. Симптом: первая половина приходит нормально, вторая внезапно заканчивается, либо интерфейс бесконечно показывает «печатает».

Сначала, если версия позволяет, отключите потоковый вывод и повторите тот же вопрос. Если без потока ответ приходит целиком, проблема в цепочке SSE. На обратном прокси отключите буферизацию ответа и увеличьте тайм-аут чтения, например proxy_buffering off и proxy_read_timeout в Nginx; CDN вроде Cloudflare тоже может буферизовать поток событий. Рассуждающие модели долго «думают» перед текстом, и это похоже на зависание — сначала проверьте нестриминговым запросом, есть ли ответ вообще.

7. Отдельные ошибки плагинов и базы знаний

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

База знаний — отдельный набор зависимостей: PostgreSQL с PGVector для векторов, S3-совместимое хранилище для исходных файлов и доступная модель Embedding. Модель встраивания по умолчанию часто относится к линейке OpenAI, но ваш шлюз может её не предоставлять — её нужно настроить отдельно; имена переменных и формат значений смотрите в документации текущей версии.

При сбое загрузки проверьте адрес бакета, ключ, права и CORS; при сбое поиска — построен ли индекс и совпадает ли размерность Embedding. После смены модели встраивания старый индекс обычно нужно пересоздать. Разбор PDF и Word может зависеть от дополнительных сервисов: если простой текст загружается, а сложный формат нет, ищите причину там.

8. Логи и сбор доказательств

  1. Откройте панель Network в инструментах разработчика, найдите неудачный запрос и зафиксируйте URL, статус, тело и заголовки; перед отправкой удалите ключ.
  2. Проверьте ошибки запуска, миграций и тайм-ауты соединения через docker logs -f lobe-chat.
  3. Убедитесь в наличии переменных через docker exec lobe-chat env, обратите внимание на написание и кавычки.
  4. Выполните curl или nslookup внутри контейнера, чтобы отделить сеть контейнера, DNS и внешний шлюз.
  5. Для подробных логов запустите с DEBUG=lobe:* и LOG_LEVEL=debug и отслеживайте вывод.
  6. При обращении в поддержку приложите версию, способ развёртывания, время, статус и ID запроса; формулировка «не подключается» почти не помогает.

9. Фиксированный порядок диагностики

  1. Проверьте шлюз напрямую через curl: действуют ли ключ, хост и модель.
  2. Если curl падает: проверьте DNS, прокси, TLS, файрвол и состояние шлюза.
  3. Если curl работает, а LobeChat нет: проверьте тип API, дублирование /v1, ID модели, CORS и клиентский прокси.
  4. Разделяйте по статусу: 401 — ключ, 404 — путь и модель, 429 — расход и параллелизм, сбой соединения — сеть и сертификаты.
  5. Меняйте по одной переменной за раз, сразу повторяйте тест и записывайте результат.

Такой порядок отделяет проблемы клиента от проблем сервера. Большинство «ошибок LobeChat» в итоге сводится к конкретной настройке или сетевому слою. Если нужен единый учёт ключей, расхода и входа моделей, зарегистрируйтесь в ZSQH AI Gateway; доступные модели и тарификация — на странице цены на модели.

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

LobeChat пишет Failed to fetch — это ошибка ключа?

Не обязательно. Сообщение означает лишь, что браузер не получил корректный ответ. Сначала проверьте тот же адрес через curl; если curl тоже падает, ищите DNS, прокси, файрвол и сертификат; если работает — проверяйте CORS, склейку пути и клиентский прокси.

Почему curl работает, а LobeChat отвечает 401 или пустотой?

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

Модель добавлена в CUSTOM_MODELS, но не появляется в списке

Проверьте, совпадает ли имя переменной с текущей версией, что запятые латинские и без пробелов, что контейнер пересоздан, а не просто перезапущен. Сначала протестируйте -all,+одна-рабочая-модель, затем добавляйте остальные.

Восстановится ли 429, если повторять запросы?

429 из-за лимита может исчезнуть после паузы и снижения параллелизма; 429 из-за квоты повторами не исправить — проверьте счёт, расход или смените ключ. Сначала смотрите тип ошибки в теле ответа, потом решайте, повторять ли.

Сбой загрузки в базу знаний — та же проблема, что и с API диалога?

Обычно нет. Диалог идёт через чат-интерфейс, а база знаний зависит от БД, векторного расширения, объектного хранилища и модели Embedding. Сначала проверьте эти настройки, затем формат файлов и сервис разбора.

Читайте также: