Документация

Профили моделей, контекст и Extra JSON

Что задаёт профиль

Модель в Sapphire I.C.D.S. описывает технические возможности, а профиль — правила её применения. Для одной модели можно создать, например, строгий профиль поддержки, лаконичный профиль классификации и расширенный профиль анализа. У каждого будут собственные системная инструкция, длина ответа и бюджет контекста, но все они обязаны оставаться внутри лимитов одной зарегистрированной модели.

В разделе AI Settings → Profiles выберите провайдера и модель. Они должны соответствовать друг другу: профиль нельзя связать с моделью другого провайдера. Profile key — устойчивый машинный идентификатор, например support_ru. Не используйте в нём имя сотрудника или временный номер задачи. Включённый профиль доступен для выбора, а профиль по умолчанию используется, когда клиент не указал конкретную запись. Назначайте default только после проверки.

Системная инструкция и формат ответа

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

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

Response format задавайте только в форме, которую понимает выбранный адаптер и модель. Для обычного диалога безопасной отправной точкой является текстовый ответ. Если нужен структурированный JSON, сначала проверьте поддержку модели и потребителя: строка в профиле сама по себе не гарантирует соответствие вашей бизнес-схеме.

Reasoning, Temperature и Top P

Reasoning effort применяйте только к моделям, которые документируют такой режим. Не копируйте значение из другого семейства. Temperature и Top P имеют отдельные переключатели. Если параметр выключен, профиль не должен навязывать его провайдеру; это предпочтительнее случайного нулевого значения. Обычно достаточно управлять одним способом вариативности, а второй оставить выключенным. Для извлечения фактов и классификации выбирают более стабильные настройки, для генерации вариантов — более свободные, но конкретный диапазон всегда сверяют с документацией модели.

Как рассчитывается контекст

В записи модели находятся три верхних предела: общий контекст, максимальный вход и максимальный выход. Профиль задаёт четыре рабочих значения. Max output tokens ограничивает один ответ. Active context tokens — бюджет, которым разрешено пользоваться агенту. Compaction reserve tokens — часть этого бюджета, оставленная для безопасного компактирования. Автоматический порог равен:

active_context_tokens - compaction_reserve_tokens

Резерв должен быть положительным и строго меньше активного бюджета. Активный бюджет не может превышать максимальный вход модели, лимит ответа — максимальный выход, а их сумма — полный контекст. Например, при контексте 128000, входе 120000 и выходе 8192 можно задать активный бюджет 64000, резерв 16000 и ответ 4096. Порог компактирования составит 48000. Это лишь пример арифметики, а не универсальная рекомендация для любой модели.

Maximum agent rounds ограничивает число циклов модель–инструмент, а Maximum agent runtime — общее время в секундах. Значение 0 означает отсутствие именно этого профильного потолка, но не отменяет лимиты провайдера, отмену пользователем, защиту от отсутствия прогресса и системные ограничения. Для критичного или затратного сценария задайте явные конечные значения и измерьте реальную работу до их увеличения.

Streaming и смена модели

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

Extra JSON без скрытых сюрпризов

Extra JSON — необязательный JSON-объект для дополнительных параметров, документированных конкретным провайдером. Это расширение, а не второй профиль. Начинайте с пустого объекта:

{}

Если API действительно требует дополнительную опцию, добавьте только её. Нейтральный пример формы:

{
  "metadata": {
    "integration": "sapphire-docs"
  }
}

Пример допустим лишь когда выбранный API поддерживает поле metadata. JSON должен быть объектом с двойными кавычками, без комментариев и завершающих запятых. Не помещайте сюда secret, Authorization, base URL, model key, пользовательские идентификаторы или конфиденциальный контент.

Не дублируйте в Extra JSON основные поля запроса вроде модели, инструментов, выбора инструмента, входных сообщений, temperature, Top P и max output tokens. Конфликт затруднит диагностику и может изменить поведение после обновления адаптера. Поле enable_tools не является способом обойти управление инструментами, а управляемая политика контекста не должна подменяться произвольной настройкой. Инструменты разрешаются серверным каталогом, правами группы и выбором сессии.

Проверка профиля

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

Если запрос отклоняется, сначала очистите Extra JSON, выключите необязательные sampling-параметры и повторите минимальный тест. Затем сверяйте лимиты и поддержку reasoning/response format. Такой порядок отделяет ошибку базовой регистрации от несовместимой дополнительной опции.

Как выбирать размер бюджета

Начинайте не с максимума модели, а с измеренного рабочего сценария. Оцените длину системной инструкции, типичную историю, ожидаемые результаты инструментов и запас для ответа. Слишком большой active context увеличивает стоимость и время обработки, а слишком маленький вызывает частое компактирование. Резерв должен позволять создать корректную сводку до достижения жёсткого предела, поэтому его нельзя сводить к символическому значению.

Профили для разных задач разделяйте, если у них различаются требования к длине, reasoning или времени. Один «универсальный» профиль сложнее проверять и безопасно менять. В названии и описании рабочей процедуры фиксируйте назначение профиля, но не зашивайте маршрутизацию или права в system prompt: выбор профиля и разрешение инструментов контролируются другими слоями.