DeepSeek Harness: подключение своего сервиса моделей

Встроенный маршрут подходит в тех случаях, когда задача ограничивается прямым подключением официального API DeepSeek. Официальная документация указывает совместимый формат API, базовый адрес, способ авторизации и доступные идентификаторы моделей; для такого сценария создание дополнительного Provider не даёт полезной изоляции, но добавляет ещё одну точку для ошибки. В текущей документации в качестве базового адреса OpenAI-совместимого API указан https://api.deepseek.com, а среди примеров моделей — deepseek-v4-flash и deepseek-v4-pro. Официальная инструкция по первому API-запросу описывает эти параметры и пример вызова.

Пользовательский Provider оправдан, если выполняется хотя бы одно условие:

• запросы должны проходить через внутренний модельный шлюз с журналированием, квотами или маршрутизацией;
• модель обслуживается внутри компании или в отдельном self-hosted inference-сервисе;
• endpoint не входит во встроенный каталог DeepSeek Harness;
• одна и та же модель должна вызываться через разные окружения — например, тестовое и производственное;
• компании требуется заменить ключ, адрес или модель независимо от встроенного маршрута.

Важно не смешивать четыре разных сценария:

Официальный репозиторий прямо помечает DeepSeek Harness как developer preview и предупреждает о возможных ломающих изменениях. Поэтому встроенный маршрут предпочтительнее не только из-за простоты: он уменьшает количество параметров, которые придётся заново проверять после обновления. Статус проекта и способ запуска следует сверять перед каждым обновлением рабочего окружения.

Что может пойти не так ещё до первого запроса

У пользовательской схемы есть несколько скрытых расходов:

1. Проблема идентичности. Provider ID становится ссылкой, по которой Harness может находить запросы, настройки сессии и секреты. Позднее переименование может выглядеть как создание нового маршрута, а не как изменение старого.
2. Разрыв между базовым адресом и маршрутом API. Base URL может указывать на корень шлюза, тогда как клиент ожидает конкретный путь для чата или каталога. Успешное открытие корня в браузере не доказывает, что API-путь собран правильно.
3. Неполная совместимость. Сервис может принимать текстовый запрос, но не поддерживать tools, streaming, reasoning-поля или требуемый формат истории сообщений.
4. Разные права доступа. Ключ, разрешающий чат-запрос, не обязательно имеет право получать каталог моделей.
5. Сохранение старого состояния. Новая настройка по умолчанию не переписывает уже отправленную историю сессии, поэтому исправный новый Provider может казаться нерабочим.

Перед заполнением формы или файла конфигурации следует записать короткий реестр маршрута:

• стабильный Provider ID;
• назначение маршрута — тестовый, внутренний или производственный;
• владелец endpoint;
• базовый адрес;
• API-протокол;
• ссылка на секрет или имя переменной окружения;
• точный идентификатор модели;
• дата последней проверки;
• рабочий маршрут для отката.

Provider ID лучше выбирать по назначению, а не по текущему названию модели. Например, смысловой идентификатор «gateway-test» легче сохранить при замене модели внутри шлюза, чем имя, содержащее конкретную версию. При этом нельзя использовать один ID для двух разных endpoint: иначе логи и старые сессии перестанут однозначно объяснять, куда ушёл запрос.

Сначала фиксируется протокол, затем Base URL. Эти параметры решают разные задачи:

• Provider ID отвечает за идентичность конфигурации внутри Harness;
• Base URL определяет, куда отправляется HTTP-запрос;
• API-протокол описывает структуру запроса и ответа;
• учётные данные позволяют пройти авторизацию;
• модельный ID сообщает сервису, какую модель нужно вызвать;
• каталог моделей позволяет Harness проверить, что указанная модель действительно объявлена endpoint.

Официальный API DeepSeek поддерживает формат, совместимый с OpenAI, а документация показывает базовый адрес и формат Authorization: Bearer .... Однако это не означает, что любой сторонний шлюз с похожим URL автоматически поддерживает весь набор возможностей Harness. Раздел с форматом API и примером запроса используйте как эталон для прямого DeepSeek API, а не как доказательство совместимости конкретного self-hosted сервиса.

Не стоит копировать названия полей из старого скриншота или стороннего руководства. В developer preview интерфейс и конфигурационный каталог могут меняться. Перед сохранением нужно сверить текущую форму и актуальный официальный раздел интеграции DeepSeek Harness, если он доступен для установленной версии.

Чек-лист перед сохранением

• [ ] Provider ID записан в журнале изменений и больше не будет переименован без миграции.
• [ ] Base URL проверен без лишнего завершающего пути.
• [ ] Протокол соответствует документации конкретного endpoint.
• [ ] Секрет хранится в менеджере секретов или переменной окружения, а не в рабочем репозитории.
• [ ] Точный модельный ID получен от сервиса, а не угадан по отображаемому имени.
• [ ] Понятно, имеет ли ключ право на список моделей.
• [ ] Сохранён прежний рабочий маршрут для отката.

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

Если endpoint реализует каталог моделей, сначала выполняется его проверка. В официальном DeepSeek API для этого используется GET /models; ответ содержит массив моделей, а идентификатор id затем применяется в API-запросе. Схема метода списка моделей показывает ожидаемую структуру ответа и прямо указывает, что id — это идентификатор, используемый API.

У результата есть четыре practically полезных сигнала:

• Успешный ответ с нужным ID. Можно переходить к минимальному текстовому запросу.
• 401 или 403. Сначала исправляются ключ, ссылка на секрет, заголовок авторизации и права доступа к каталогу.
• Успешный ответ без нужной модели. Сервис доступен, но модельный ID не совпадает либо модель не опубликована в этом окружении.
• Каталог не поддерживается. Нельзя объявлять модель обнаруженной только потому, что чат endpoint отвечает. Следует проверить, допускает ли текущая версия Harness ручное добавление модели, и какие сведения о её возможностях обязательны.

Ошибка «модель не найдена» после успешного сохранения обычно не требует немедленного пересоздания Provider. Сначала нужно сравнить строку модельного ID посимвольно: регистр, дефисы, суффиксы версии и внутренние алиасы часто отличаются от отображаемого названия.

Если запрос списка моделей возвращает 401, действие выбирается по уровню сбоя:

1. проверить, что используется секрет именно этого Provider;
2. убедиться, что запрос идёт на правильный endpoint;
3. сверить формат заголовка авторизации с документацией шлюза;
4. проверить права ключа на каталог;
5. повторить проверку вне Harness тем же адресом и тем же секретом;
6. только после этого менять конфигурацию Harness.

Для прямого API DeepSeek официальная документация также публикует коды ошибок и рекомендации по их интерпретации. Для внутреннего шлюза эти коды могут быть преобразованы прокси, поэтому в журнале следует сохранять не только HTTP-статус, но и тело ответа, request ID и фактический маршрут.

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

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

1. Создайте отдельную тестовую сессию и явно выберите новый Provider.
2. Укажите одну модель без алиаса и без автоматического переключения.
3. Отправьте короткое текстовое задание, например просьбу вернуть фиксированную строку.
4. Сохраните фактический Provider, модель, HTTP-статус, request ID и сообщение об ошибке.
5. Повторите запрос с потоковой выдачей, только если этот режим заявлен как поддерживаемый.
6. Сравните фактический ответ с ожидаемой структурой: текст должен находиться там, где его ожидает Harness, а не только присутствовать в сыром JSON.
7. При сбое вернитесь к последнему проверенному Provider, не изменяя старую рабочую сессию.

Официальный пример DeepSeek использует POST /chat/completions, передаёт модель и массив сообщений, а также показывает варианты параметров thinking и streaming. Это полезная контрольная точка для прямого API, но внутренний шлюз может ограничивать отдельные поля. Пример запроса в официальной документации следует адаптировать только после проверки текущего протокола пользовательского endpoint.

Текстовая генерация и работа агента — разные уровни совместимости. Сервис может вернуть корректный ответ на сообщение, но неправильно обработать схему инструмента, аргументы, параллельные вызовы или возврат результата в историю.

Для первой инструментальной проверки выбирается безопасная функция без доступа к важным данным, например операция, которая принимает строку и возвращает заранее предсказуемый результат. Не следует начинать с shell-команд, записи файлов, доступа к сетевым ресурсам или операций в производственном репозитории.

Запишите следующие наблюдения:

• дошёл ли список tools до endpoint;
• вызвал ли модель инструмент именно с допустимыми аргументами;
• получил ли Harness результат инструмента в правильной роли сообщения;
• продолжилась ли сессия после возврата результата;
• сохранился ли исходный Provider во втором запросе;
• не исчезли ли поля reasoning или служебные части ответа, если текущая конфигурация их использует.

Если текст работает, а инструмент нет, это не «почти успешное» подключение. Для AI Agent такой маршрут следует считать ограниченным текстовым режимом до тех пор, пока инструментальный цикл не пройдёт проверку целиком. В рабочем каталоге можно зафиксировать возможности отдельно: текст, streaming, tools, структурированный вывод и многоходовая история.

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

Безопасная процедура выглядит так:

1. оставить старую сессию неизменной как контрольную;
2. создать новую сессию после изменения значения по умолчанию;
3. отправить минимальный текстовый запрос;
4. повторить инструментальную проверку;
5. сравнить Provider и модель в журнале;
6. только затем переносить рабочий prompt или задачу.

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

После внедрения нужно вести короткую карточку изменения для каждого endpoint. В неё включаются:

• предыдущий и новый Base URL;
• Provider ID;
• модельный ID;
• версия DeepSeek Harness;
• версия шлюза;
• изменённый секрет или ссылка на него;
• результаты текстовой и инструментальной проверки;
• подтверждённый маршрут отката.

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

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

При необходимости подготовить отдельный macOS-контур для такой проверки стоит сначала изучить руководство по помощи и эксплуатации NUKCLOUD, а затем сопоставить требования проекта с доступными вариантами аренды Mac. Это особенно полезно, когда шлюз доступен только из изолированной сети или тестовый агент должен оставаться онлайн в течение всего окна проверки.

Пользовательский Provider не является универсальным способом «разблокировать» любую модель. От него лучше отказаться, если:

• официальный API уже присутствует во встроенном каталоге;
• команда не может гарантировать стабильность Base URL;
• ключи выдаются без понятной ротации и аудита;
• endpoint поддерживает только один демонстрационный запрос;
• нет владельца, который будет проверять маршрут после обновлений;
• сервис не сообщает точный модельный ID;
• инструментальный цикл не проходит тест в изолированной сессии.

Самостоятельный сервис может дать контроль над данными, маршрутизацией и квотами, но одновременно добавляет обслуживание TLS, сетевых правил, секретов, каталогов моделей и совместимости формата. Для краткого теста это оправдано не всегда.

Если текущая схема работает через Windows или Linux-сервер, её слабые места обычно проявляются не в самом HTTP-запросе, а в непостоянном доступе, ручном обновлении секретов, отсутствии стабильной macOS-среды и сложном воспроизведении ошибки на том же окружении. Когда модельный шлюз нужно проверять в изолированной и постоянно доступной macOS-среде, аренда Mac через NUKCLOUD может оказаться удобнее разовой настройки собственного компьютера: не требуется заранее покупать отдельное оборудование, поддерживать его включённым и переносить тестовую конфигурацию между рабочими местами. При этом для постоянной тяжёлой нагрузки, физического доступа к периферии или долгосрочной экономии следует отдельно сравнить аренду с покупкой собственного Mac.

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