Конфигурация
Переменные окружения
Обязательные
LICENSE_KEY
Лицензионный ключ
YOUR_LICENSE_KEY
SSL_VERSION
Версия БСП
3.1.11
Управление индексацией
RESET_DATABASE
Переиндексировать при запуске
false
FORCE_REINDEX_ON_DIMENSION_MISMATCH
Автоматически пересоздать коллекцию zvec при несовпадении размерности эмбеддингов. По умолчанию false — старт останавливается и сообщает, что нашёл, вместо того чтобы решать за оператора
false
INDEXING_THREADS
Число параллельных потоков генерации эмбеддингов при индексации
5
MIGRATE_VECTOR_STORE
Выполнить на этом старте миграцию векторного хранилища — перестроение корпуса рядом с обслуживающим поколением. Не выводится из манифеста: момент перестроения выбирает оператор
false
DEMOTE_VECTOR_STORE
Вернуть обслуживание предыдущему поколению. Ничего не удаляет: переписывается только то, какое имя обслуживает
false
Текущий рантайм zvec, обслуживающее поколение, запись манифеста и итог последней миграции показывает инструмент vector_store_state.
Транспорт
USESSE
SSE транспорт (для legacy клиентов)
false
Поиск и журналирование
MIN_SCORE
Порог cosine similarity для ssl_search; некорректное значение заменяется калиброванным
0.3826
EXACT_LOOKUP
Точный поиск по каноническому имени символа перед остальными маршрутами (lane=exact). false отключает только exact lane; hybrid/BM25 продолжает работать, пока отдельно не задано HYBRID_SEARCH=false
true
HYBRID_SEARCH
Опрашивать обе дорожки — векторную и полнотекстовую (BM25) — с объединением по reciprocal rank fusion. false оставляет только векторную, ничего не перестраивая: полнотекстовый индекс остаётся на месте, меняется лишь путь запроса
true
MAX_RESPONSE_CHARS
Бюджет длины ответа ssl_search в символах. Значение ниже 1024 поднимается до этого предела с записью в журнал: бюджет, в который не помещается один размеченный результат, — это отказ отвечать, а не бюджет
4000
MAX_QUERY_CHARS
Максимальная длина запроса до и после plugin/alias rewrite. Значение ниже 256 поднимается до 256; превышение даёт query_too_long без текста запроса в ошибке
2048
MAX_GUARDED_SEARCHES
Максимум поисков внутри deadline guard; ограничивает одновременно потоки и обращения к хранилищу
64
LOG_QUERIES
Разрешить запись полного текста запросов в журнал; по умолчанию журналируются только длина и хеш
false
LOG_DIR
Каталог файла журнала. Относительный путь отсчитывается от корня приложения, а не от рабочего каталога
<app>/logs
HTTP-сессии
Границы и счётчики сессий показывает инструмент session_state.
SESSION_IDLE_TTL
Время простоя сессии до освобождения, секунды
900
SESSION_MAX_LIFETIME
Максимальное время жизни сессии, секунды
14400
SESSION_MAX_CONCURRENT
Максимум одновременных сессий
128
SESSION_CLEANUP_INTERVAL
Интервал очистки просроченных сессий, секунды
30
Таймауты обращений к embedding-провайдеру
EMBEDDING_SEARCH_DEADLINE
Бюджет времени на кодирование запроса в одном ssl_search, секунды
15
EMBEDDING_PROBE_DEADLINE
Таймаут стартовой проверки провайдера, секунды
60
EMBEDDING_BATCH_DEADLINE
Таймаут одного пакета при индексации, секунды
300
EMBEDDING_MAX_ATTEMPTS
Максимум попыток при ошибке провайдера
4
EMBEDDING_BACKOFF_BASE
Базовая пауза между попытками, секунды
0.25
EMBEDDING_BACKOFF_CAP
Предел паузы между попытками, секунды
8
Размер пакетов и чанкование при индексации
EMBEDDING_MAX_BATCH_TOKENS
Максимум токенов в одном пакете к провайдеру
8192
EMBEDDING_MAX_BATCH_CHARACTERS
Максимум символов в одном пакете
131072
MAX_BATCH_SPLITS
Сколько раз пакет может быть разделён при отказе провайдера по размеру
8
EMBEDDING_TOKEN_LIMIT
Явный лимит токенов модели. 0 — определить автоматически; задавайте, если провайдер не сообщает свой лимит
0 (авто)
CHUNK_OVERLAP_TOKENS
Перекрытие соседних чанков длинной записи, в токенах (но не больше четверти лимита)
48
Остановка контейнера
SHUTDOWN_GRACE_SECONDS
Общий бюджет корректного завершения. Значение по умолчанию выбрано под docker stop, который даёт 10 секунд до SIGKILL
10
SHUTDOWN_FLUSH_SECONDS
Часть этого бюджета на сброс данных хранилища. Меньше общего: зависшее хранилище должно стоить свой собственный лимит и быть честно об этом сообщено, а не съедать всё время оператора
5
Плагины
PLUGIN_DIR
Каталог Python-плагинов внутри контейнера
/app/plugins
PLUGIN_STRICT_DERIVED_STATE
Останавливать индексацию при ошибке derived-state hook
false
Свой каталог можно подключить томом в /app/plugins. Текущее состояние показывает plugin_state, а plugin_reload перечитывает каталог без перезапуска контейнера.
Сервер расширяется плагинами: плагин — один Python-файл в /app/plugins, без базового класса, декоратора, регистрации и манифеста. Объявлены четыре hooks — on_startup, on_request, on_result (в рамках вызова) и on_entry (формирует векторную коллекцию) — и таблица QUERY_ALIASES (замены терминов в запросе перед эмбеддингом). Полный контракт лежит в образе: /app/plugin_api.py, /app/plugins/AGENTS.md, /app/plugins/example.py. Проверить файл без данных и индекса:
Правка on_entry делает сохранённую коллекцию устаревшей и вызывает переэмбеддирование выбранной базы БСП; call-scoped хуки и таблица ничего не пересобирают. Подробно: Доработка MCP: система плагинов и справочник хуков SSLSearchServer.
Embedding модели (LM Studio / Ollama / OpenRouter)
EMBEDDING_API_BASE
URL API сервера. Суффикс /v1 добавляется автоматически
http://host.docker.internal:1234/v1
EMBEDDING_API_KEY
Ключ API
lm-studio
EMBEDDING_MODEL
Имя модели, с которым вызывается API эмбеддингов
qwen/qwen3-embedding-8b
LOCAL_EMBEDDING_MODEL
Hugging Face repo id модели, которую загружает локальный (CPU) режим, когда API недоступен. Совместимый алиас — OFFLINE_EMBEDDING_MODEL. Если задана только EMBEDDING_MODEL, локальный режим использует её
intfloat/multilingual-e5-small
EMBEDDING_DIMENSIONS
Явное указание размерности эмбеддингов. Для моделей с переменной размерностью (Qwen3, text-embedding-3). Если не указано — определяется автоматически
(авто)
EMBEDDING_INPUT_TYPE_ENABLED
Включить параметр input_type для различения query/document при генерации эмбеддингов. Полезно для моделей Qwen3, BGE, E5
true
Старые имена OPENAI_API_BASE, OPENAI_API_KEY и OPENAI_MODEL остаются совместимыми алиасами.
Для предсказуемого обновления явно закрепляйте и EMBEDDING_MODEL, и LOCAL_EMBEDDING_MODEL. Если сохранённая коллекция построена другой моделью или API недоступен и сервер переходит на локальный fallback с другой размерностью, при FORCE_REINDEX_ON_DIMENSION_MISMATCH=false запуск останавливается, не изменяя коллекцию. Верните EMBEDDING_MODEL к модели из манифеста, либо осознанно перестройте индекс с FORCE_REINDEX_ON_DIMENSION_MISMATCH=true; безопасный side-by-side вариант — MIGRATE_VECTOR_STORE=true.
Смена модели без смены размерности проверкой размерности не ловится: 384 — ширина десятка разных энкодеров, и два из них размещают один и тот же текст в разных местах. Поэтому старт дополнительно сверяет имя модели, записанное в манифесте индекса, с моделью текущего процесса и при расхождении пересобирает коллекцию из корпуса — той же одной пересборкой, что и остальные причины устаревания. Манифест, не называющий модель вовсе, тоже считается неактуальным. Backend при этом не сравнивается: latest через API и arm64 локально с одной моделью дают одни и те же векторы, и переход на локальный fallback сам по себе пересборку не вызывает.
Раздельные defaults и этот сценарий миграции относятся к текущему beta-кандидату исходников; опубликованные beta-теги могли быть собраны раньше.
Монтируемые тома
E:/bases/mcp_ssl
/app/zvec_db
Векторная база данных zvec
Доступные версии БСП
Сервер поддерживает различные версии БСП. Укажите вашу версию в SSL_VERSION.
Примеры:
3.1.113.1.93.2.12.4.6
Примеры конфигураций
Минимальная (CPU)
Рекомендуемая (LM Studio)
Конфигурация Cursor
Last updated