Быстрый старт¶
Synth можно поставить тремя способами. Выберите подходящий: npm — самый быстрый, Docker Compose — если не хотите ставить Node.js, из исходников — для разработки.
После любого способа откройте UI по адресу http://localhost:4300 и введите API-ключ.
Способ 1. npm (глобальная установка)¶
Быстрее всего — установить публикуемую CLI-обёртку @itphx/synth. Она поднимает
core и UI одной командой.
Откройте http://localhost:4300 и введите ключ
my-secret-key.
Контекстное окно и 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/'' — сброс.
type: ollama работает только нативно. URL всегда нормализуется к
/api/chat: старый базовый URL с суффиксом /v1 (или
/v1/chat/completions) сработает — суффикс снимается, а в лог уходит
предупреждение. OpenAI-совместимый путь Ollama подключается отдельным
провайдером — type: openai/generic с URL http://localhost:11434/v1
(там num_ctx не применяется).
Альтернатива на стороне Ollama — задайте окно как серверный дефолт:
Либо соберите модель с явным num_ctx через Modelfile:
Бюджет контекста самого Synth считается по contextWindow модели
(синхронизируется из Ollama /api/tags или задаётся вручную), но фактическое
окно определяет Ollama.
Способ 2. Docker Compose¶
Подходит, если не хотите устанавливать Node.js. Docker Compose поднимет Synth (и, при желании, Ollama).
Откройте http://localhost:4300 и введите ключ
my-secret-key. Логи — docker compose logs -f synth.
Ollama в Compose
Ollama вынесена в отдельный профиль. Запустите docker compose --profile ollama up -d,
затем загрузите модель: docker compose exec ollama ollama pull qwen3.8:27b.
Контекстное окно в Compose задаётся переменной OLLAMA_CONTEXT_LENGTH
(по умолчанию 262144).
Способ 3. Из исходников (разработка)¶
Для участия в разработке. Требуются Node.js >= 22 и pnpm >= 11.
Для разработки удобен ./scripts/dev.sh (backend + UI, порты и переменные уже
настроены).
После запуска¶
- Адрес: UI отдаётся вместе с пакетом
@itphx/synth-uiи доступен на http://localhost:4300 (host и порт —--host/--port). - Ключ: если
--api-keyне задан (--api-key/SYNTH_API_KEY/core.apiKey),synth serveсгенерирует устойчивый ключ, сохранит его в{dataDir}/secrets/api-keyи напечатает при старте. Локальный API-ключ core даёт роль ADMIN. - Провайдер: чтобы получать ответы модели, подключите провайдера — Провайдеры и модели.
Что дальше¶
- Первый вход — войти и осмотреться.
- Локальный запуск — подробнее о локальном сценарии.
- CLI — чат и работа с провайдерами из терминала.