Конфигурация

Переменные окружения

Обязательные

Переменная	Описание	Пример
LICENSE_KEY	Лицензионный ключ. Без него сервер не стартует	YOUR_LICENSE_KEY

Embedding

Переменная	Описание	По умолчанию
EMBEDDING_API_BASE	URL OpenAI-совместимого API, включая /v1. Пробуется раньше локальной модели	http://host.docker.internal:1234/v1
EMBEDDING_API_BASE_NO_V1	Передавать базу API дословно, без автодобавления /v1 (значения 1, true, yes) — для шлюзов, отдающих OpenAI-совместимый API без суффикса /v1. С 10.10.2026	false
EMBEDDING_API_KEY	Ключ API (LM Studio значение не проверяет)	lm-studio
EMBEDDING_MODEL	Имя модели — и для API, и для локального режима. У модели Qwen3-Embedding запрос идёт с инструкцией задачи (см. Инструкция к запросу у Qwen3)	intfloat/multilingual-e5-small
EMBEDDING_API_TIMEOUT	Сколько секунд один запрос к embedding API ждёт ответа. Если модель считает на CPU и обрабатывает INDEXING_WORKERS батчей по очереди, последний из них может ждать дольше — увеличьте значение (или уменьшите INDEXING_WORKERS)	600
EMBEDDING_MAX_ATTEMPTS	Сколько раз отправляется один запрос к API эмбеддингов: лимит запросов (429) и ответы 500/502/503 повторяются до этого числа; таймаут и обрыв соединения повторяет попытка пакета. Повторов внутри клиента OpenAI нет	6
BATCH_MAX_RETRIES	Сколько раз пробуется пакет индексации. Пакет отправляет к провайдеру не больше BATCH_MAX_RETRIES × EMBEDDING_MAX_ATTEMPTS запросов (по умолчанию 30; раньше клиент сам повторял каждый запрос ещё дважды — до 90 без настройки). Для провайдера с платой за запрос уменьшите оба значения, например EMBEDDING_MAX_ATTEMPTS=1 и BATCH_MAX_RETRIES=2. Индекс не перестраивается	5
EMBEDDING_ALLOW_OFFLINE_FALLBACK	Можно ли заменить недоступный на старте embedding API встроенной моделью. true — как раньше: после неудачной проверки грузится встроенная модель. false — старт ждёт API (см. подсказку ниже). С 27.09.2026	false, если задан EMBEDDING_API_BASE; иначе true
HF_HOME	Каталог кэша модели; в полный образ модель уложена сюда при сборке	/app/model_cache
HF_HUB_OFFLINE	Запрет загрузок при старте; 0 разрешает докачать модель	1
RESET_CACHE	Очистить кэш моделей при старте (удаляется только содержимое HF_HOME, сам том сохраняется)	false

RESET_CACHE=true вместе с HF_HUB_OFFLINE=1 (значение по умолчанию) удаляет уложенную в образ модель без возможности скачать её обратно. Если кэш нужно чистить, модель должна приходить извне — смонтированным каталогом в HF_HOME.

OPENAI_API_BASE, OPENAI_API_KEY и OPENAI_MODEL поддерживаются как устаревшие алиасы. В новых конфигурациях используйте EMBEDDING_*.

Если EMBEDDING_API_BASE задан, а API не отвечает при старте (сеть поднялась позже контейнера, провайдер временно недоступен), сервер не переходит на встроенную модель, а ждёт: повтор через 5, 10, 20 … до 60 секунд, пока API не ответит. В журнале — строки The embedding API is unavailable (attempt N: …); retrying in N s. Ошибки, которые ожиданием не исправить (неверный ключ, модель не найдена), переводят сервер в degraded с причиной в /ready; индекс при этом не трогается — исправьте настройки и перезапустите контейнер. Поведение с 27.09.2026.

Пути и данные

Переменная	Описание	По умолчанию
1C_BIN_PATH	Смонтированный каталог с shcntx_ru.hbk (папка bin платформы, сама папка с архивом или путь к файлу). Не задан — берётся архив, поставляемый с образом	(не задано)
PLUGIN_DIR	Каталог плагинов; смонтируйте свой, чтобы не пересобирать образ	/app/plugins
PLUGIN_STRICT_DERIVED_STATE	true — упавший hook on_document роняет сборку индекса; false — документ берётся как прочитан, а ошибка считается	false

Индексация

Переменная	Описание	По умолчанию
RESET_DATABASE	Разрешить разрушающие операции и очистить индекс	false
INDEX_RETAIN_GENERATIONS	Сколько прошлых поколений индекса хранить для отката	1
INDEXING_WORKERS	Максимум параллельных батчей индексации; запросы к embedding API могут выполняться одновременно	5
INDEXING_BATCH_SIZE	Строк в одной записи при индексации; именно это ограничивает память сборки — уменьшите на машине, которой её не хватает	100

INDEXING_WORKERS ограничивает число одновременно обрабатываемых батчей, но не гарантирует ускорения пропорционально значению. Чтение и подготовка документов должны успевать снабжать пул работой; запись в индекс сериализована. В полном образе локальная модель тоже вызывается последовательно, чтобы избежать конфликтов токенизатора. При работе через API сам сервер допускает параллельные HTTP-запросы, но провайдер может ставить их в очередь.

После изменения переменной пересоздайте контейнер. В начале индексации журнал показывает фактическое INDEXING_WORKERS и предел батчей в обработке. Для проверки конкурентности API сопоставляйте одновременно начатые запросы в журнале MCP и очередь на стороне провайдера; одинаковое время двух прогонов само по себе не означает, что настройка проигнорирована.

Пересборка индекса не разрушает работающий: новое поколение собирается в staging и начинает обслуживать только после проверки. Упавшая сборка уходит в index/quarantine и никогда не обслуживает запросы, а отвечает по-прежнему предыдущее поколение.

Транспорт и HTTP-сессии

Переменная	Описание	По умолчанию
USESSE	Использовать SSE-транспорт (для legacy-клиентов)	false
MCP_SESSION_IDLE_TTL_SECONDS	Время простоя сессии Streamable HTTP до уборки	1800
MCP_SESSION_MAX_LIFETIME_SECONDS	Максимальное время жизни сессии	86400
MCP_SESSION_CAP	Максимум одновременных stateful-сессий	1000
MCP_SESSION_CLEANUP_INTERVAL_SECONDS	Интервал сверки времени жизни сессий и метрик	60

/mcp и /mcp/ обслуживаются одним и тем же эндпоинтом напрямую — клиента никогда не просят повторить MCP-запрос через redirect. Счётчики активных сессий и уборки видны в ответе /health.

Тонкая настройка поиска

Значения измерены на этом корпусе и на поставляемой модели; менять их нужно только осознанно.

Переменная	Описание	По умолчанию
RELEVANCE_MAX_VECTOR_DISTANCE	Максимальная cosine-distance векторного кандидата; меньше — лучше совпадение	0.35
RELEVANCE_MAX_LEXICAL_RANK	Сколько первых кандидатов лексической дорожки допускается независимо от численного score	2
CHUNK_MAX_TOKENS	Бюджет токенов одного чанка. Задавайте только для API-модели, не сообщающей свой лимит. Изменение вызывает переиндексацию	окно модели
CHUNK_OVERLAP_TOKENS	Сколько предыдущего чанка повторяет следующий. Изменение вызывает переиндексацию	48
CHUNK_MAX_PER_PARENT	Максимум чанков одного документа в одном ответе	3
CHUNK_DUPLICATE_THRESHOLD	Порог схожести, выше которого два чанка одного документа считаются одним ответом	0.85
FILTERED_FETCH_FACTOR	Во сколько раз шире опрашиваются дорожки при заданном doc_type	4
DOCINFO_FALLBACK_CANDIDATES	Предел числа кандидатов, когда имя не совпало точно	5
DOCINFO_AMBIGUITY_CANDIDATES	Предел числа кандидатов в одном ответе для неоднозначного имени	20
LEXICAL_PROFILE	Токенизация лексической дорожки: stemmed, plain, folded, verbatim. Изменение вызывает переиндексацию	stemmed
RESPONSE_MAX_TOKENS	Дополнительно ограничивать ответ в токенах, если модель отдаёт токенизатор. max_chars действует всегда	(не задано)
RESPONSE_CURSOR_SECRET	Ключ подписи курсоров постраничного вывода	(не задано)

Векторная дорожка проходит по distance, лексическая — по рангу. У лексической дорожки в текущем контракте отдельного score-порога нет. Старый RELEVANCE_MIN_LEXICAL_SCORE больше не читается: при его наличии сервер пишет предупреждение и требует перейти на RELEVANCE_MAX_LEXICAL_RANK.

Журналирование

Переменная	Описание	По умолчанию
LOG_DIR	Каталог файлов журнала	logs
LOG_FILE	Имя текущего файла журнала	app.log
LOG_MAX_BYTES	Размер, при котором журнал ротируется	10485760 (10 МиБ)
LOG_BACKUP_COUNT	Сколько ротированных файлов хранится	5
LOG_LEVEL	Уровень записи в файл. DEBUG добавляет записи по документам и текст запросов	INFO
LOG_CONSOLE_LEVEL	Уровень вывода в stdout, если он должен отличаться	значение LOG_LEVEL
LOG_PROGRESS_EVERY	Через сколько пакетов писать прогресс индексации	10

На уровне по умолчанию журнал не содержит текста поисковых запросов: запрос записывается длиной и коротким хешем, а все записи одного вызова несут общий correlation id. Именно его называет клиенту ответ с ошибкой.

Монтируемые тома

Хост	Контейнер	Назначение
E:/bases/mcp_docs	/app/index	Индекс (поколения zvec) — обязательно
E:/bases/mcp_model_cache	/app/model_cache	Кэш embedding-моделей
C:/Program Files/1cv8/X.X.XX.XXXX/bin	/1c_docs	Папка bin платформы, если нужна справка своей версии (только чтение)
E:/plugins/mcp_docs	/app/plugins	Свои плагины

Раньше индекс лежал в /app/chroma_db. Сервер больше не использует ChromaDB; актуальный путь — /app/index. Перенос старого индекса — разовой командой миграции, см. Установка.

Примеры конфигураций

Минимальная (встроенная CPU-модель)

docker run -d -p 8003:8003 `
  --name 1c_help_mcp `
  -e LICENSE_KEY=YOUR_LICENSE_KEY `
  -v "E:/bases/mcp_docs:/app/index" `
  comol/1c_help_mcp:latest

Рекомендуемая (LM Studio + своя версия платформы)

docker run -d -p 8003:8003 `
  --name 1c_help_mcp `
  -e LICENSE_KEY=YOUR_LICENSE_KEY `
  -e 1C_BIN_PATH=/1c_docs `
  -e EMBEDDING_API_BASE=http://host.docker.internal:1234/v1 `
  -e EMBEDDING_API_KEY=lm-studio `
  -e EMBEDDING_MODEL=Qwen3-Embedding-4B `
  -v "C:/Program Files/1cv8/8.3.23.1997/bin:/1c_docs" `
  -v "E:/bases/mcp_docs:/app/index" `
  -v "E:/bases/mcp_model_cache:/app/model_cache" `
  comol/1c_help_mcp:latest

Light-образ (без PyTorch, embedding только через API)

docker run -d -p 8003:8003 `
  --name 1c_help_mcp `
  -e LICENSE_KEY=YOUR_LICENSE_KEY `
  -e EMBEDDING_API_BASE=http://host.docker.internal:1234/v1 `
  -e EMBEDDING_API_KEY=lm-studio `
  -e EMBEDDING_MODEL=Qwen3-Embedding-4B `
  -v "E:/bases/mcp_docs:/app/index" `
  comol/1c_help_mcp:light

Локальной модели в light-образе нет: если embedding API недоступен, индекс не строится, /ready отвечает degraded с причиной в поле failure, а процесс продолжает работать.

CPU с выбором модели

docker run -d -p 8003:8003 `
  --name 1c_help_mcp `
  -e LICENSE_KEY=YOUR_LICENSE_KEY `
  -e EMBEDDING_MODEL=intfloat/multilingual-e5-base `
  -v "E:/bases/mcp_docs:/app/index" `
  -v "E:/bases/mcp_model_cache:/app/model_cache" `
  comol/1c_help_mcp:latest

Смена embedding-модели делает сохранённый индекс несовместимым: при следующем старте он пересобирается в staging-поколение, а предыдущее продолжает отвечать до конца сборки.

Плагины

Сервер поставляется скомпилированным, но расширяется плагинами. Плагин — один Python-файл в /app/plugins с функциями известных имён: ни базового класса, ни декоратора, ни регистрации, ни манифеста. Пустой файл — валидный плагин. Функции нет — hook не срабатывает. Упавший hook перехватывается, пишется в журнал с именем файла и трассировкой и отключается до следующей перезагрузки, но сервер не роняет.

Объявлены пять hooks — on_startup, on_request, on_query, on_result (в рамках вызова) и on_document (формирует индекс) — и две декларативные таблицы: ALIASES (дополнительные имена, которые разрешает docinfo) и TOOL_PRESETS (дополнительные MCP-инструменты как пресеты docsearch и docinfo).

Что	Где
Полный справочник хуков и таблиц	/app/plugin_api.py в образе (читаемый исходник)
Короткая версия	/app/plugins/AGENTS.md
Пример со всеми хуками (закомментирован)	/app/plugins/example.py
Проверить плагин без данных и индекса	docker run --rm -v "$PWD/my_plugin.py:/tmp/my_plugin.py" comol/1c_help_mcp:latest python3 plugin_host.py --dry-run /tmp/my_plugin.py
Что загружено и что отключено	GET /plugins
Перечитать каталог без перезапуска	POST /plugins/reload

Правка call-scoped хука действует со следующего вызова после перезагрузки и ничего не пересобирает. on_document формирует то, что пишется в индекс, поэтому исходник объявившего его файла входит в отпечаток годности индекса: правка делает сохранённый индекс устаревшим, и следующий старт пересобирает его в staging, пока обслуживающее поколение продолжает отвечать.

Общие правила, форма payload каждого хука и готовые примеры: Доработка MCP: система плагинов и справочник хуков HelpSearchServer.

Конфигурация Cursor

mcp.json

{
  "mcpServers": {
    "1c-docs-mcp": {
      "url": "http://localhost:8003/mcp",
      "connection_id": "1c_docs_service_001"
    }
  }
}

Путь к файлу

%APPDATA%\Cursor\User\globalStorage\mcp.json

GPU ускорение

NVIDIA GPU через Docker

docker run -d -p 8003:8003 `
  --gpus all `
  --name 1c_help_mcp `
  -e LICENSE_KEY=YOUR_LICENSE_KEY `
  -v "E:/bases/mcp_docs:/app/index" `
  -v "E:/bases/mcp_model_cache:/app/model_cache" `
  comol/1c_help_mcp:latest

Прямое GPU-ускорение контейнера доступно на Linux с NVIDIA Container Toolkit и на Windows 11 через Docker Desktop с WSL2. На macOS и в других средах без проброса NVIDIA GPU используйте LM Studio на хосте, CPU-режим или облачный embedding API и укажите серверу EMBEDDING_API_BASE.