Cherry Studio — распространённый настольный ИИ-клиент для Windows, macOS и Linux. Он сам не предоставляет модели: они берутся у настроенного вами API-провайдера. Помимо встроенных провайдеров, можно добавить собственный OpenAI-совместимый endpoint — это удобно командам с единым шлюзом: один Base URL и один ключ позволяют переключаться между моделями.

Статья основана на распространённых версиях 2026 года и проходит путь от установки до провайдера, моделей, ассистентов, базы знаний и командного использования. Названия интерфейса меняются от версии к версии — ориентируйтесь на текущую.

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

1. Установка: предпочитайте официальные каналы

Cherry Studio предоставляет настольные установочные пакеты; обычные точки загрузки — официальный сайт и GitHub Releases проекта. Выберите пакет для своей системы:

  • Windows: скачайте установщик и следуйте подсказкам.
  • macOS: скачайте dmg и перетащите приложение в каталог программ; если система блокирует первый запуск, разрешите его по подсказке.
  • Linux: установите AppImage или пакет дистрибутива, предоставленный проектом.

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

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

Для пользовательского провайдера нужны три вещи, и каждую легко заполнить неверно:

Параметр Как заполнять Пояснение
Тип провайдера OpenAI Используется OpenAI-совместимый протокол
API-адрес https://ai.zhongshangqihang.com/v1 Указывать до /v1, не полный путь метода
API-ключ sk-... Создаётся в консоли шлюза, с названием по проекту
ID модели Идентификатор API со страницы цен Не отображаемое имя на сайте

Ключ создаётся в консоли после регистрации в ZSQH AI Gateway. Рекомендуется один ключ на проект — так проще смотреть расход, задавать лимиты и отзывать доступ. ID модели копируйте со страницы «Модели и цены», обращая внимание на регистр, дефисы и суффикс версии.

3. Добавление пользовательского провайдера

На примере распространённой текущей версии порядок такой:

  1. Откройте Cherry Studio и нажмите значок шестерёнки в левом нижнем углу, чтобы войти в настройки.
  2. Выберите «Сервисы моделей».
  3. Нажмите «+ Добавить провайдера» под списком провайдеров.
  4. В окне «Добавить пользовательского провайдера» заполните название, например «Шлюз ZSQH».
  5. Укажите «API-ключ».
  6. В «Настройках endpoint» выберите OpenAI; если шлюз предоставляет протокол Responses, в «Дополнительных настройках» можно выбрать OpenAI Responses.
  7. Укажите API-адрес, например https://ai.zhongshangqihang.com/v1.
  8. Нажмите «Добавить», чтобы сохранить.

Если в вашей версии нет пункта «+ Добавить провайдера», сначала обновите клиент. В разных версиях типы endpoint называются по-разному, но ключевые поля неизменны: название, ключ, адрес. Генерация и редактирование изображений — отдельные варианты Base URL; не смешивайте их с адресом чат-моделей.

4. Добавление моделей и проверка связи

После сохранения провайдера вернитесь к списку его моделей. Добавить модель можно двумя способами:

  • Получить список моделей: клиент запрашивает у шлюза доступные модели, после чего отметьте нужные.
  • Добавить вручную: нажмите «+» и введите ID модели. Этот способ используйте, если шлюз не открывает интерфейс списка или запрос не удался.

ID модели должен полностью совпадать со страницей цен. После ручного добавления проверьте, что тип модели — «диалог» или «чат»; при неверном типе модель не появится в селекторе интерфейса чата. Модели эмбеддингов и изображений добавляются отдельно по назначению.

Кнопка «Проверить» в интерфейсе в основном проверяет доступность API-ключа и не означает, что каждая модель вам открыта. После сохранения создайте новый диалог, выберите добавленную модель и отправьте «Ответь только OK» — это полная проверка.

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, адрес, ключ и модель как минимум работают, и проблема скорее в полях клиента или сетевом прокси. При 401 сначала проверьте ключ и пробелы, при 404 — /v1 и ID модели, при 429 — расход и параллельность. Меняйте за раз только одну переменную, не переключайте одновременно ключ, адрес и модель.

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

«Ассистенты» Cherry Studio сохраняют системный промпт, модель и параметры и подходят для повторяющихся задач. Практичное разделение:

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

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

7. База знаний: модель эмбеддингов не обязательна

База знаний создаётся слева через «База знаний» → «Добавить». Укажите название, отражающее границы материалов, и выберите модель эмбеддингов. В текущей версии есть три способа:

  • Не использовать: только ключевой поиск BM25, дополнительная настройка не нужна — подходит для первой проверки процесса.
  • Облачная модель эмбеддингов: нужен рабочий сервис соответствующей модели; поиск сочетает ключевые слова и векторы.
  • Локальная модель эмбеддингов: сначала скачайте модель в «Настройки → Локальные модели», затем выберите её в базе знаний.

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

Смена модели эмбеддингов может запустить «перестроение базы знаний». Перед перестроением убедитесь в доступности новой модели и не меняйте одновременно модель и настройки разбиения — иначе будет непонятно, из-за чего изменился результат.

8. Порядок диагностики типичных сбоев

Симптом Частая причина Что делать
401 — ошибка аутентификации Неверный ключ, лишние пробелы или настройки не сохранены Вставьте заново, убедитесь, что ключ относится к текущему шлюзу
404 Not Found В API-адресе лишний или пропущенный /v1 Оставьте адрес до /v1, не указывайте полный путь
model not found Неверный ID модели или модель не подключена Скопируйте точный идентификатор со страницы цен
Не удаётся получить список моделей Шлюз не открывает интерфейс списка Добавьте ID модели вручную
Плохое качество базы знаний Разбиение, способ поиска или качество материалов Сначала протестируйте на небольшом наборе, затем настройте разбиение
Обрыв потока в диалоге Прокси, firewall или нестабильная сеть Отключите потоковый режим для теста, проверьте прокси и таймауты

Корпоративная сеть или прокси могут блокировать SSE-поток: запрос уходит, но ответ не возвращается. Временно отключите потоковый вывод; если без потока всё работает, ищите причину в прокси и firewall, а не в модели.

9. Командное использование: общие правила, а не общий ключ

Cherry Studio — настольный клиент, и публичная документация не относит управление многопользовательскими правами к его ключевым возможностям. Командное использование скорее означает «единые правила конфигурации плюс локальный клиент у каждого». Рекомендации:

  • У каждого свой ключ шлюза с именем сотрудника; при уходе или утечке отзывайте только его.
  • Смотрите расход и лимиты на стороне шлюза, разносите затраты по проектам.
  • Соберите системные промпты часто используемых ассистентов в текстовые шаблоны и раздавайте централизованно.
  • Материалы базы знаний храните в контролируемом общем месте, чтобы не поддерживать разные версии.
  • Для резервных копий используйте WebDAV или S3-совместимое хранилище, но помните, что копия содержит настройки провайдеров и API-ключи.
  • Не отправляйте файлы резервных копий в общие чаты и не кладите на недоверенные сетевые диски.
  • Не сохраняйте долгоживущие ключи на общих компьютерах и не вставляйте в диалог персональные данные и необезличенные договоры.

Если команде нужны единый аудит, лимиты и права, основной акцент следует делать на стороне шлюза.

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

Cherry Studio бесплатен?

Сам клиент можно использовать бесплатно, но стоимость вызовов моделей взимает настроенный вами API-провайдер. Конкретные условия зависят от текущей версии клиента и страницы цен шлюза.

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

В большинстве OpenAI-совместимых конфигураций да, указывайте до https://ai.zhongshangqihang.com/v1. Не вписывайте /v1/chat/completions: клиент добавит путь метода сам.

Что делать, если не удаётся получить список моделей?

Сначала проверьте, открывает ли шлюз интерфейс списка моделей. Если он закрыт или запрос не удался, нажмите «+» и введите ID модели вручную — результат будет тем же. ID модели берите из идентификатора API на странице цен.

Обязательно ли настраивать модель эмбеддингов для базы знаний?

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

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

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

Что дальше

Подключение Cherry Studio несложное; сложность в том, чтобы согласовать три вещи — Base URL, ключ и ID модели. Сначала прогоните curl, затем переходите в клиент; при проблемах проверяйте в порядке 401, 404, model not found. Если нужен единый вход к моделям и управление расходом, можно зарегистрироваться в ZSQH AI Gateway; модели и цены смотрите на странице «Модели и цены».

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