Провайдеры и модели¶
Synth поддерживает пять типов провайдеров: openai, anthropic, ollama,
decision и systemone (последние два — для decision-моделей).
Настроить провайдера можно тремя способами: переменными окружения, CLI или через
веб-интерфейс. Провайдеры хранятся как JSON-файлы в {dataDir}/providers/.
Ключи — на сервере
Ключи провайдеров централизованы: в командном (серверном) режиме они хранятся только на сервере и не попадают к клиентам. Все LLM-вызовы идут через LLM Gateway с аудитом.
Типы провайдеров¶
Тип (--type) |
Для чего | Примеры |
|---|---|---|
ollama |
Локальные и бесплатные модели | Qwen3, DeepSeek, Gemma |
openai |
OpenAI-совместимые API | OpenAI, LM-Studio, vLLM, Together, Groq |
anthropic |
Anthropic-совместимые API | Claude и совместимые сервисы |
decision |
Decision-модели через SystemOne-совместимый API | RouterAI и другие сервисы (Bearer) |
systemone |
Decision-модели в локальном Ollama | System One-модели (например, Clef) |
Ollama (локально)¶
Установите Ollama и загрузите модель:
Примеры моделей, которые можно использовать локально:
| Модель | Команда для установки |
|---|---|
| Qwen3.8 27B (рекомендуемая) | ollama pull qwen3.8:27b |
| DeepSeek Coder V2 16B | ollama pull deepseek-coder-v2:16b |
| DeepSeek R1 14B | ollama pull deepseek-r1:14b |
| Gemma 4 12B | ollama pull gemma4:12b |
| Qwen2.5 Coder 1.5B | ollama pull qwen2.5-coder:1.5b |
| Nomic Embed Text | ollama pull nomic-embed-text:latest |
Контекстное окно и num_ctx
Модель qwen3.8:27b даёт окно ~100k–256k токенов, но Ollama по
умолчанию поднимает его небольшим. num_ctx задаётся через Synth
(ProviderConfig.numCtx) и передаётся в теле запроса: провайдер
type: ollama работает через нативный /api/chat, поэтому
options.num_ctx применяется — как и think и нативный формат инструментов.
Базовый URL указывайте без суффикса /v1.
Задать num_ctx через Synth (приоритет: явный numCtx провайдера >
contextWindow модели):
# CLI — флаг есть только у `config provider add` (подкоманды `edit` нет)
synth config provider add \
--name ollama --type ollama \
--url http://localhost:11434 \
--model qwen3.8:27b \
--num-ctx 262144
# Переменная окружения (OLLAMA → ollama, `_` в имени → `-`)
export SYNTH_PROVIDER_OLLAMA_NUM_CTX=262144
Поле num_ctx (он же numCtx) принимается в POST/PATCH
/api/v2/providers, GET его отдаёт, null/'' — сброс; у существующего
провайдера оно правится через PATCH /api/v2/providers/:name.
type: ollama работает только нативно. URL всегда нормализуется к
/api/chat: старый базовый URL с суффиксом /v1 (или
/v1/chat/completions) сработает — суффикс снимается, а в лог уходит
предупреждение. OpenAI-совместимый путь Ollama подключается отдельным
провайдером:
synth config provider add \
--name ollama-openai --type openai \
--url http://localhost:11434/v1 \
--model qwen3.8:27b
там num_ctx не применяется.
Альтернатива на стороне Ollama — задайте окно как серверный дефолт:
Либо соберите модель с явным num_ctx через Modelfile:
Synth для бюджета контекста использует contextWindow модели
(синхронизируется из Ollama /api/tags или задаётся вручную), но фактическое
окно определяет Ollama.
OpenAI-совместимые¶
Подойдут OpenAI, LM-Studio, vLLM, Together, Groq и любой другой сервис с OpenAI-совместимым API. Нужны URL, API-ключ и имя модели.
Anthropic-совместимые¶
Claude и совместимые сервисы. Нужны URL, API-ключ и имя модели.
Decision-модели (System One)¶
Decision-модели — отдельный класс компактных моделей: они принимают решения
(да/нет, выбор из вариантов, оценка по шкале), а не генерируют текст.
Подключаются типом провайдера decision (SystemOne-совместимый API) или
systemone (локальный Ollama).
# SystemOne-совместимый API (удалённо)
export SYNTH_PROVIDER_ROUTERAI_DECISION_TYPE=decision
export SYNTH_PROVIDER_ROUTERAI_DECISION_URL=https://routerai.ru/api/v1
export SYNTH_PROVIDER_ROUTERAI_DECISION_API_KEY=sk-xxx
export SYNTH_PROVIDER_ROUTERAI_DECISION_MODEL=clef-flash
# Локальный Ollama
synth config provider add \
--name ollama-local --type systemone \
--url http://localhost:11434 \
--model clef-flash
Подробнее — Decision-модели.
Настройка через переменные окружения¶
Все переменные провайдеров имеют префикс SYNTH_PROVIDER_<NAME>_, где <NAME> —
имя провайдера в верхнем регистре.
Настройка через CLI¶
# Добавить провайдера (рекомендуемая локальная модель — qwen3.8:27b).
# URL без /v1: type: ollama ходит на нативный /api/chat.
synth config provider add \
--name ollama --type ollama \
--url http://localhost:11434 \
--model qwen3.8:27b
# Список провайдеров
synth config provider list
# Удалить провайдера
synth config provider delete ollama
Обязательные флаги: --name, --type (openai | anthropic | ollama |
decision | systemone). Опциональные: --url, --model, --api-key,
--data-dir.
Настройка через веб-интерфейс¶
Провайдерами и моделями можно управлять в UI, в разделе «Провайдеры». Там же удобно проверить доступность модели и выбрать модель для сессии.
Расширенные параметры (совместимость)¶
У провайдеров отличаются детали протокола: имя поля с рассуждениями, обязательность признака завершения ответа, поддержка запрета инструментов, формат маркеров кэша. Под каждый такой случай есть настройки совместимости — отдельно для провайдера (значения по умолчанию) и для модели (перекрывают провайдера).
В интерфейсе это сворачивающийся блок «Расширенные параметры» в форме провайдера и модели (раздел «Провайдеры»). Каждое поле — переключатель «Авто / Да / Нет» (для выбора из вариантов — «Авто / вариант»). «Авто» значит «не задавать»: действует автоопределение по провайдеру и имени модели либо общее значение.
| Параметр | Что делает | Когда менять |
|---|---|---|
reasoningField |
Имя поля с рассуждениями модели в истории запроса (reasoning_content по умолчанию; бывает reasoning, reasoning_text, своё) |
Провайдер отклоняет историю с рассуждениями — уточните имя поля у провайдера |
requireReasoning |
Требовать поле рассуждений у каждого сообщения ассистента, даже пустым | Thinking-модели DeepSeek: иначе ошибка «reasoning_content must be passed back» |
maxTokensField |
Какое поле лимита вывода отправлять: max_tokens или max_completion_tokens |
Новые модели OpenAI (o*, gpt-5) требуют max_completion_tokens |
requireAssistantAfterTool |
Вставлять служебное сообщение ассистента после результатов инструментов | Семейство Mistral — иначе ошибка чередования ролей |
streamUsage |
Запрашивать статистику токенов в стриме (stream_options.include_usage) |
Провайдер не понимает параметр — выключите |
supportsToolChoice |
Понимает ли провайдер запрет вызова инструментов (tool_choice) |
Ollama — «Нет»: запрет игнорируется |
cacheFormat |
Явные маркеры кэша промпта (anthropic / alibaba) вместо ключа кэша |
Провайдер поддерживает cache_control в сообщениях; у Qwen/Alibaba маркер на инструментах не ставится |
requireFinishReason |
Требовать признак завершения ответа (finish_reason) в стриме; по умолчанию — да |
Старый локальный сервер не присылает finish_reason — выключите |
supportsEffortUpdates |
Провайдер поддерживает параметр усилия рассуждений (output_config.effort); уровень усилия задаётся в настройках агента (поле «Усилие рассуждений», там же доступны xhigh и max) или выводится из уровня размышлений |
Включайте, только если провайдер его принимает; по умолчанию (в том числе «Авто») — нет, при сомнении оставьте выключенным |
Значения по умолчанию и API
«Авто» — это отсутствие поля: Synth сам решает по провайдеру и модели
(например, DeepSeek и Mistral распознаются по имени). Через API настройки
передаются объектом compatibility: объект заменяет прежние значения
целиком, null — сбрасывает, отсутствие поля — оставляет как было.
Особенности провайдеров¶
OpenAI-совместимые (OpenAI, RouterAI, LM Studio, vLLM, Groq, Together)¶
- Рассуждения thinking-моделей возвращаются в историю в поле, заданном
reasoningField; для DeepSeek поле обязательно даже пустым — это делаетrequireReasoning. - Лимит вывода по умолчанию отправляется в
max_tokens; для новых моделей OpenAI переключитеmaxTokensField. - Кэш промпта работает либо неявно (ключ кэша), либо явными маркерами
(
cacheFormat); одновременно эти механизмы не используются.
Anthropic¶
- Расширенное мышление включается уровнем размышлений агента: бюджет подстраивается под лимит вывода, температура принудительно выставляется в 1.
- Блоки рассуждений с подписями сохраняются автоматически — в том числе несколько блоков за один ход; при следующем запросе они передаются модели как есть.
- Если в сессии сменить модель, рассуждения прежней модели в новый запрос не передаются.
- С включённым
supportsEffortUpdatesSynth управляет глубиной рассуждений не бюджетом размышлений, а параметром усилия (output_config.effort): уровень берётся из настроек агента (поле «Усилие рассуждений»; если оставить «Авто» — из уровня размышлений), там же можно выбратьxhighиmax— их нельзя получить из уровня размышлений. Блоки рассуждений в истории тогда не передаются. - При смене уровня между шагами кэш промпта у провайдера может сбрасываться — ответы станут чуть дороже.
Ollama¶
- Работает через нативный API;
thinkвключается уровнем размышлений,num_ctx— параметром провайдера или модели. - Запрет вызова инструментов не поддерживается: на лимите шагов модель может попробовать вызвать инструмент — вызов не выполняется, а в ответ приходит детерминированный отчёт о лимите.
Decision-модели (SystemOne)¶
Это не чат: модель принимает состояние и вопросы, возвращает вероятности. Инструменты и рассуждения к decision-моделям не применяются.
Если модель отвечает ошибкой¶
| Сообщение провайдера | Причина | Что сделать |
|---|---|---|
reasoning_content ... must be passed back |
thinking-модель DeepSeek требует поле рассуждений в истории | включите requireReasoning (для DeepSeek достаточно «Авто») |
ошибка про thinking / signature |
в истории есть рассуждения модели, отличной от текущей | не меняйте модель внутри сессии — начните новую |
max_tokens must be greater than thinking.budget_tokens |
лимит вывода меньше бюджета рассуждений | увеличьте лимит вывода модели |
параметры temperature / tool_choice несовместимы с мышлением |
провайдер ограничивает их при включённом мышлении | Synth выставляет их автоматически; проверьте кастомные значения агента |
стрим оборвался без finish_reason |
провайдер не завершил ответ | для старых локальных серверов выключите requireFinishReason |
| инструменты «не отключаются» на лимите шагов | Ollama игнорирует запрет инструментов | ожидаемо: вызовы не выполняются, приходит отчёт о лимите |
Что дальше¶
- Первый вход
- Маршрутизация — автоматический выбор модели и быстрые ответы.
- Decision-модели — компактный слой быстрых решений и эскалация.