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

Ниже разобраны 401, 404, 429, сбои соединения, обрывы потока и ошибки базы знаний, а также порядок диагностики, команды проверки и сбор доказательств. Названия пунктов меню и расположение журналов зависят от версии — ориентируйтесь на текущую.

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

1. Сначала зафиксируйте порядок проверки

При ошибке сохраните четыре вещи: HTTP-статус, текст ошибки в теле ответа, время запроса и request ID от шлюза. Без них остаётся только «примерно однажды не сработало»; с ними можно найти конкретный запрос и апстрим.

Затем идите по порядку, меняя за раз только одну переменную:

  1. Обратитесь к шлюзу напрямую через curl и проверьте адрес, ключ и модель.
  2. curl работает, клиент — нет: смотрите настройки клиента, прокси и тип протокола.
  3. Не работает ни curl, ни клиент: проверьте ключ, лимит, ID модели и состояние шлюза.
  4. Ошибка только на длинных ответах или в базе знаний — смотрите потоковый режим, тайм-ауты и модель эмбеддингов.
Симптом Частая причина Что проверить первым
401 Ключ неверен, просрочен, содержит пробел или относится к другой платформе Совместимость ключа и Base URL
404 Not Found Лишний или отсутствующий /v1 Окончание адреса API
model not found Опечатка, регистр или модель не подключена ID модели и страница цен
429 Too Many Requests Параллелизм, частота или лимит Заголовки ответа и расход в шлюзе
Тайм-аут соединения Прокси, DNS, межсетевой экран или сертификат Системный прокси и сеть
Ответ оборвался посередине Поток разорван прокси или тайм-аутом Сравнение с отключённым потоком

2. 401: ключ и авторизация

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

  • при копировании попали пробел, перевод строки или кавычки, и строка отправляется неполной;
  • ключ принадлежит другой платформе, но вписан при текущем Base URL;
  • ключ удалён, ротирован, проект отключён или лимит исчерпан;
  • клиент не сохранил ключ: в поле он виден, а в запросе пуст;
  • для OpenAI-совместимой точки используется протокол Anthropic или Gemini, и формат заголовка не совпадает.

Действие: вставьте ключ заново, убедитесь, что до и после нет пробелов, и проверьте, что Base URL и ключ относятся к одной платформе. Если клиент умеет «проверять подключение», выполните проверку, затем повторите через curl. Если curl проходит, а клиент даёт 401, ищите, действительно ли ключ сохранён и не выбран ли неверный тип протокола.

3. 404 и model not found

404 не обязательно означает, что интерфейс закрыт; чаще это ошибка склейки пути:

  • в Base URL указан полный адрес интерфейса, и клиент ещё раз добавляет /chat/completions — путь дублируется;
  • /v1 отсутствует там, где нужен, или добавлен там, где не нужен;
  • выбран неверный тип провайдера: OpenAI-совместимая точка настроена как Anthropic или Gemini;
  • ID модели не совпадает со страницей цен по регистру, суффиксу даты, дефисам;
  • модель существует, но у ключа нет к ней доступа.

model not found и 404 стоит разделять: первое означает, что адрес доступен, но модель неверна; второе — что мог не совпасть даже маршрут. Сначала запросите /v1/models и посмотрите список; если интерфейс недоступен, скопируйте точный ID со страницы цены на модели, добавьте вручную и повторите.

4. 429: частота, параллелизм или лимит

У 429 как минимум два значения, и лечатся они по-разному:

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

Смотрите тело и заголовки ответа. retry-after подсказывает время ожидания; если в ошибке прямо упомянуты quota или balance, не продолжайте повторы с задержкой, а сначала проверьте лимит в консоли. Экспоненциальная задержка подходит только для чистого ограничения частоты, и её нужно дополнять случайным разбросом, чтобы все клиенты не повторяли запрос в одну секунду.

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

5. Сбой соединения, SSL и прокси

Сбой соединения выглядит как бесконечное вращение, затем тайм-аут, невозможность подключиться или ошибка сертификата. В Cherry Studio обычно есть три режима прокси: системный, собственный и без прокси; они находятся в системных или общих настройках, название зависит от версии.

Порядок проверки:

  1. Убедитесь, что системный прокси или VPN работает, а клиент использует режим системного прокси.
  2. Если задан собственный прокси, проверьте адрес и порт, например http://127.0.0.1:7890.
  3. Проверьте список обхода: нужный домен не должен быть ошибочно исключён или принудительно отправлен через прокси.
  4. Временно включите «без прокси» для сравнения — так видно, связана ли проблема с цепочкой прокси.
  5. Если корпоративная сеть перехватывает TLS, проверьте системные сертификаты и цепочку доверия клиента.
  6. Проверьте системное время: сильное расхождение ломает проверку сертификата.

Частая ошибка — вписать адрес прокси в поле адреса API. Адрес API — это HTTPS-адрес шлюза моделей, а прокси указывается в настройках прокси; не смешивайте их.

6. Обрыв потокового вывода

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

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

Различайте «модель действительно остановилась» и «соединение разорвали». В первом случае обычно есть маркер завершения, во втором — часто нет кода ошибки, остаётся лишь половина текста. Записывайте оба случая отдельно, чтобы потом понять, где причина: в клиенте, шлюзе или сети.

7. Ошибки базы знаний и эмбеддингов

Ошибки базы знаний обычно возникают не в диалоговом интерфейсе, а на этапе эмбеддингов или поиска:

  • настроена только диалоговая модель, а рабочая модель эмбеддингов отсутствует;
  • модель эмбеддингов не поддерживает используемый интерфейс или возвращает размерность, не совпадающую с индексом;
  • загруженный файл не разбирается: например, сканированный PDF без извлекаемого текста;
  • модель эмбеддингов сменили, но индекс не перестроили, и старые векторы не соответствуют новым запросам;
  • сервис переранжирования или поиска недоступен — поиск пуст или завершается тайм-аутом.

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

8. Журналы, команды диагностики и доказательства

В Cherry Studio есть режим разработчика: в настройках можно включить цепочку вызовов, чтобы локализовать ошибки модели и инструментов; расположение зависит от версии. На стороне шлюза должны сохраняться request ID, имя модели, длительность и расход токенов. Совпадение меток времени с обеих сторон показывает, на каком участке проблема.

Сначала выполните минимальное воспроизведение через curl:

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

# 1. Проверка адреса и ключа
curl -sS "https://ai.zhongshangqihang.com/v1/models" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -w "\nHTTP %{http_code}\n"

# 2. Проверка вызова модели
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"}]}' \
  -w "\nHTTP %{http_code}\n"

# 3. Отдельная проверка TLS и цепочки сертификатов
openssl s_client -connect ai.zhongshangqihang.com:443 -servername ai.zhongshangqihang.com </dev/null

Три команды отвечают на три вопроса: ключ и адрес, модель и параметры, TLS и сертификат. Где шаг упал — с того слоя и продолжайте; не меняйте одновременно ключ, адрес и модель.

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

Всегда ли помогает замена ключа при 401?

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

404 означает, что модель снята с продажи?

Чаще всего причина в неверном пути Base URL или в опечатке в ID модели. Запросите /v1/models через curl и сверьте идентификатор со страницей цены на модели; только если оба шага в порядке, рассматривайте снятие модели.

Обязательно ли снижать параллелизм при 429?

Не всегда. Смотрите текст ошибки: снижение параллелизма и задержка нужны при чистом ограничении частоты; при нехватке квоты замедление бессмысленно — проверяйте баланс или бюджет в консоли. Заголовок retry-after помогает оценить время ожидания.

Почему обрывается только потоковый ответ?

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

Нужно ли искать ошибки базы знаний отдельно от ошибок диалога?

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

Дальше

Порядок можно запомнить одной фразой: сначала curl, потом клиент; сначала статус, потом журналы; за раз — одна переменная. Если нужны единая OpenAI-совместимая точка входа, журналы запросов и управление расходом, можно зарегистрироваться в ZSQH AI Gateway; модели и цены — на странице цены на модели.

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