> For the complete documentation index, see [llms.txt](https://docs.onerpa.ru/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onerpa.ru/mcp-servery-1c/servery/code-metadata-search/konfiguraciya.md).

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

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

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

| Переменная                 | Описание                                                                                                                                                                                                                                                             | Пример                     |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `LICENSE_KEY`              | Лицензионный ключ                                                                                                                                                                                                                                                    | `YOUR_LICENSE_KEY`         |
| `LICENSE_KEY_FILE`         | Предпочтительный способ передачи ключа: путь к смонтированному файлу, который содержит только лицензионный ключ. Значение ключа не попадает в окружение процесса. Файл должен быть обычным, непустым, небольшим и на POSIX недоступным для чтения группе и остальным | `/run/secrets/license_key` |
| `LICENSE_KEY_FILE_CONSUME` | Удалить файл ключа сразу после чтения                                                                                                                                                                                                                                | `false`                    |
| `CODE_PATH`                | Корень Designer XML-выгрузки или проекта 1C:EDT                                                                                                                                                                                                                      | `/app/code`                |

`METADATA_PATH` больше не обязателен. Он нужен только для совместимого режима `METADATA_SOURCE=report` с готовым текстовым отчётом.

### Настройки сервера

| Переменная                         | Описание                                                                                                                                                                                                                                              | По умолчанию                |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| `MCP_HOST`                         | Хост для привязки сервера                                                                                                                                                                                                                             | `0.0.0.0`                   |
| `MCP_PORT`                         | Порт сервера и адресата встроенной проверки здоровья контейнера                                                                                                                                                                                       | `8000`                      |
| `MCP_PATH`                         | Путь MCP-эндпоинта                                                                                                                                                                                                                                    | `/mcp`                      |
| `USESSE`                           | Включить SSE-транспорт для legacy-клиентов. По умолчанию используется `streamable-http`                                                                                                                                                               | `false`                     |
| `FASTMCP_STATELESS_HTTP`           | Не хранить состояние между HTTP-вызовами; уменьшает число долгоживущих сессий                                                                                                                                                                         | `true`                      |
| `MCP_STRUCTURED_CONTENT`           | Дублировать ответы-словари и списки в `structuredContent`; по умолчанию сервер отдаёт один JSON-блок `text content`, чтобы большие ответы не попадали клиенту дважды                                                                                  | `false`                     |
| `MCP_SESSION_IDLE_TTL_SEC`         | Время простоя сессии до освобождения; `0` отключает ограничение                                                                                                                                                                                       | `1800`                      |
| `MCP_SESSION_MAX_LIFETIME_SEC`     | Максимальное время жизни сессии; `0` отключает ограничение                                                                                                                                                                                            | `86400`                     |
| `MCP_SESSION_MAX_CONCURRENT`       | Максимум одновременных MCP-сессий                                                                                                                                                                                                                     | `64`                        |
| `MCP_SESSION_CLEANUP_INTERVAL_SEC` | Интервал очистки завершённых и просроченных сессий                                                                                                                                                                                                    | `60`                        |
| `MCP_SESSION_BOUNDS_MODE`          | `enforce` применяет лимиты, `report` только считает нарушения                                                                                                                                                                                         | `enforce`                   |
| `MCP_IMAGE_REF`                    | Неизменяемая ссылка на образ с digest для проверки release identity в `stats`                                                                                                                                                                         | *(не задано)*               |
| `METADATA_SOURCE`                  | Источник метаданных: `xml` — читать их из `CODE_PATH`; `report` — требовать готовый отчёт в `METADATA_PATH`; `auto` — выгрузка в `CODE_PATH`, иначе отчёт                                                                                             | `xml`                       |
| `SOURCE_FORMAT`                    | Формат `CODE_PATH`: `auto`, `designer_xml` или `edt`                                                                                                                                                                                                  | `auto`                      |
| `PROJECT_ID`                       | Явно закрепить идентификатор проекта индекса. Если не задан — выводится из каталогов `CODE_PATH` и `METADATA_PATH`; закрепление переживает перенос точки монтирования                                                                                 | *(выводится)*               |
| `GENERATION_RETENTION_COUNT`       | Сколько поколений индекса хранить на диске (обслуживаемое плюс предыдущие, для отката); значение меньше 1 повышается до 1. Лишние поколения удаляются по окончании ближайшего прогона индексации — стартового или планового, даже если строить нечего | `2`                         |
| `EMBEDDING_JOURNAL`                | Вести журнал документных эмбеддингов (`embedding-journal/`, см. [Место на диске](#место-на-диске)); `false` — дорожки работают без него, существующие файлы журнала не трогаются                                                                      | `true`                      |
| `GENERATION_LEASE_RENEW_SEC`       | Интервал продления аренды поколения                                                                                                                                                                                                                   | `30`                        |
| `GENERATION_LEASE_TIMEOUT_SEC`     | Таймаут аренды поколения                                                                                                                                                                                                                              | `300`                       |
| `FILE_TRACKER_DB_PATH`             | Совместимый путь к устаревшей базе трекера файлов                                                                                                                                                                                                     | *(внутри `VECTOR_DB_PATH`)* |
| `VECTOR_DB_PATH`                   | Путь к общей директории векторного хранилища и служебных индексов                                                                                                                                                                                     | `/app/chroma_db`            |
| `CHROMA_DB_PATH`                   | Совместимый старый алиас для `VECTOR_DB_PATH`; внутри каталога теперь используются zvec-коллекции и SQLite-индексы                                                                                                                                    | `/app/chroma_db`            |

Когда очистка освобождает сессию с запросом в работе (обычно это держащийся SSE-поток `GET /mcp`), уже начатый ответ корректно дописывается и поток закрывается. Ответ, который ещё не начинался, клиент получает как JSON с причиной в `error.code` — `idle_timeout`, `max_lifetime` или `session_capacity_exhausted`: HTTP 404 для запроса с идентификатором сессии (стандартный для MCP сигнал «сессии больше нет», клиент открывает новую) и HTTP 503 для анонимного запроса. Завершённые ответы и остальные запросы не затрагиваются.

### Управление индексацией

| Переменная                         | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | По умолчанию               |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `RESET_DATABASE`                   | Переиндексировать при запуске                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `false`                    |
| `BACKGROUND_INDEXING`              | Выполнять стартовую индексацию в фоне, не блокируя запуск MCP                                                                                                                                                                                                                                                                                                                                                                                                                                              | `true`                     |
| `INCREMENTAL_INDEXING`             | Сверять SHA-256 файлов и обновлять только изменившиеся данные. Переключение этого флага само по себе не делает сохранённые embeddings несовместимыми и не требует их повторного расчёта                                                                                                                                                                                                                                                                                                                    | `true`                     |
| `INCREMENTAL_HASH_CHUNK_BYTES`     | Размер блока чтения при расчёте SHA-256                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `65536`                    |
| `REINDEX_INTERVAL_SEC`             | Интервал периодической инкрементальной индексации в секундах. `0` — явное отключение (остаётся только ручной `reindex()`). Тик без изменений в исходниках стоит только расчёта SHA-256 и сверки инвентаря: поколение не создаётся и полосы индексации не запускаются. Пустая коллекция включённой полосы, для которой в выгрузке нет ни одного файла (справка при `INDEX_HELP=true` в выгрузке без `.html`), такой тик в сборку не превращает (с 13.10.2026; раньше каждый тик публиковал новое поколение) | `3600`                     |
| `REINDEX_INTERVAL_HOURS`           | Пользовательский алиас интервала в часах; явный `REINDEX_INTERVAL_SEC` имеет приоритет                                                                                                                                                                                                                                                                                                                                                                                                                     | *(не задано)*              |
| `PARSE_WORKERS`                    | Число параллельных обработчиков файлов: разбор, хеширование, чтение каталогов и размеров модулей перед сверкой                                                                                                                                                                                                                                                                                                                                                                                             | от 1 до 8, по числу CPU    |
| `EMBEDDING_CONCURRENCY`            | Максимум параллельных запросов эмбеддингов                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `6`                        |
| `EMBED_BATCH_SIZE_API`             | Размер пакета для внешнего embedding API                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `64`                       |
| `EMBED_BATCH_SIZE_LOCAL`           | Размер пакета для локальной embedding-модели                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `64`                       |
| `EMBED_QUEUE_CAPACITY`             | Ёмкость очереди подготовленных пакетов; если не задана, вычисляется как четыре размера активного пакета                                                                                                                                                                                                                                                                                                                                                                                                    | *(авто)*                   |
| `BATCH_MAX_RETRIES`                | Максимум попыток пакета при временной ошибке embedding-провайдера                                                                                                                                                                                                                                                                                                                                                                                                                                          | `10`                       |
| `BATCH_BACKOFF_BASE`               | Основание экспоненциальной паузы между попытками                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `2.0`                      |
| `BATCH_BACKOFF_MAX`                | Максимальная пауза между попытками, секунды                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `60.0`                     |
| `EMBEDDING_API_TIMEOUT`            | Секунд ожидания ответа на один запрос к API эмбеддингов. Пакет, не получивший ответа за `BATCH_MAX_RETRIES` + 1 попыток, останавливает обращения к провайдеру в этом прогоне: индексация завершается с ошибкой `provider_failure`, поколение сохраняется, следующий старт продолжает с оставшихся файлов                                                                                                                                                                                                   | `600`                      |
| `EMBEDDING_QUERY_TIMEOUT`          | Секунд ожидания эмбеддинга поискового запроса, не больше `EMBEDDING_API_TIMEOUT`. Запрос повторяется один раз, затем поиск отвечает полнотекстовой стадией                                                                                                                                                                                                                                                                                                                                                 | `10`                       |
| `SUB_INDEX_WORKERS`                | Число параллельно строящихся вспомогательных индексов                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `4`                        |
| `SUB_INDEX_PROGRESS_WARN_SEC`      | Через сколько секунд непрерывной работы над одним файлом или стадией вывести предупреждение с относительным путём, стадией, временем, прогрессом и числом активных воркеров. Это только диагностика: она не прерывает и не отменяет работу. `0` полностью отключает монитор                                                                                                                                                                                                                                | `300`                      |
| `SUB_INDEX_PROGRESS_HEARTBEAT_SEC` | Минимальный интервал повторных предупреждений, пока та же работа остаётся активной. Пока проход живой, INFO с `N/M file(s) done` пишется не реже чем раз в минуту (или с этим интервалом, если он короче минуты). Значения меньше 5 секунд поднимаются до 5, чтобы исключить лавину сообщений                                                                                                                                                                                                              | `300`                      |
| `SUB_INDEX_LIVENESS_WITNESS`       | Запускать независимый свидетель живости — отдельный процесс, который читает публикуемую родителем запись о стадии и единице работы и сообщает о зависании, даже когда наблюдаемый интерпретатор не выполняет ни одной строки Python. Пороги те же, что у внутрипроцессного монитора; `0` в них выключает и монитор, и свидетеля. Если процесс не удалось запустить, сервер один раз предупреждает и продолжает работу                                                                                      | `false`                    |
| `SUB_INDEX_BULK_LOAD`              | Загружать вспомогательные индексы пакетно                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `true`                     |
| `SHUTDOWN_GRACE_SEC`               | Время ожидания активных HTTP-запросов при остановке                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `5`                        |
| `INDEX_METADATA`                   | Индексировать метаданные                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `true`                     |
| `INDEX_CODE`                       | Индексировать BSL-код                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `true`                     |
| `INDEX_STRUCTURAL`                 | Строить структурный индекс символов. `false` полностью исключает запись и финализацию этой дорожки, переводит readiness-дорожку `symbols` в `disabled`; `search_function` использует ограниченный grep-fallback                                                                                                                                                                                                                                                                                            | `true`                     |
| `STRUCTURAL_PARSE_TIMEOUT_SEC`     | Жёсткая граница времени на структурный разбор одного BSL-модуля. Положительное значение выносит разбор в отдельный дочерний процесс: модуль, не уложившийся в границу, снимает процесс вместе с деревом, дорожка `structural` помечается `failed` с причиной `parse_failure`, сборка не публикуется, а ранее опубликованное поколение продолжает обслуживать запросы. `0` отключает границу — разбор идёт внутри процесса индексации, как раньше                                                           | `0`                        |
| `STRUCTURAL_EXCLUDE`               | Аварийное исключение отдельных BSL-модулей из структурного парсера. Значение — строго JSON-массив строк (не больше 64) с glob-шаблонами относительно `CODE_PATH`, через прямой слэш; `*`, `?` и `[...]` поддерживаются, `*` пересекает разделитель каталогов. Не JSON, не список или превышение лимита отвергают политику целиком; пустой, абсолютный или выходящий за корень элемент отбрасывается отдельно                                                                                               | *(не задано)*              |
| `INDEX_DEPENDENCY_GRAPH`           | Строить граф зависимостей. `false` полностью исключает его запись и финализацию, а также запись объектов расширений из XML-прохода графа                                                                                                                                                                                                                                                                                                                                                                   | `true`                     |
| `INDEX_FORM_INDEX`                 | Строить индекс форм. `false` полностью исключает запись и финализацию этой дорожки и переводит readiness-дорожку `forms` в `disabled`                                                                                                                                                                                                                                                                                                                                                                      | `true`                     |
| `INDEX_XSD_SCHEMAS`                | Генерировать XSD-схемы в help-фазе. Применяется вместе с `INDEX_HELP`: `false` отключает только XSD-дорожку, оставляя индекс HTML-справки включённым                                                                                                                                                                                                                                                                                                                                                       | `true`                     |
| `INDEX_HELP`                       | Индексировать HTML-справку                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `true`                     |
| `INDEX_PHASE_ORDER`                | Порядок фаз; метаданные всегда выполняются первыми                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `metadata,code,help`       |
| `INDEX_NESTED_CONFIGURATIONS`      | Индексировать вложенные конфигурации поставщика отдельными источниками                                                                                                                                                                                                                                                                                                                                                                                                                                     | `false`                    |
| `NESTED_CONFIGURATION_PATHS`       | Список относительных каталогов-контейнеров вложенных конфигураций через запятую                                                                                                                                                                                                                                                                                                                                                                                                                            | `Ext/ParentConfigurations` |
| `CHUNK_SIZE`                       | Совместимая настройка отпечатка и предела контекстного окна. Текущий splitter создаёт фрагменты фиксированного размера 1000 символов, поэтому изменение переменной не меняет их нарезку, но делает сохранённое поколение несовместимым                                                                                                                                                                                                                                                                     | `1000`                     |
| `CHUNK_OVERLAP`                    | Совместимая настройка отпечатка. Текущий splitter использует фиксированное перекрытие 200 символов; изменение переменной не меняет нарезку, но делает сохранённое поколение несовместимым                                                                                                                                                                                                                                                                                                                  | `200`                      |
| `SUB_INDEX_INTEGRITY_GATE`         | Режим проверки целостности вспомогательных индексов: `auto`, `blocking`, `report_only` или `off`                                                                                                                                                                                                                                                                                                                                                                                                           | `auto`                     |

`INDEX_CODE` остаётся общим переключателем векторной индексации BSL-кода. Три вспомогательные дорожки управляются независимо: выключенная дорожка не создаёт и не финализирует свои артефакты и не блокирует `/ready`. Если выключить все три, общий проход вспомогательных индексов пропускается целиком, но векторная индексация кода продолжается.

**Область действия `STRUCTURAL_EXCLUDE` — только структурный парсер.** Исключённый `.bsl` по-прежнему читается, попадает в векторный индекс кода и в граф зависимостей; дорожки `metadata`, `help` и `forms` не затрагиваются. Теряются символы самого модуля, рёбра иерархии вызовов, *исходящие* из него, и объявленные в нём аннотации расширений (аннотация из другого модуля, целящаяся в исключённый, получает `unresolved_target`). `get_module_structure` для такого модуля отвечает `reason="structural_excluded"`, а не «не найдено». Дорожка `symbols` остаётся `ready`/`complete` — это решение оператора, а не деградация, — но получает `source_complete=false` и блок `omissions` с именем политики и счётчиками в `/ready` и в `stats()`. Без политики оба поля отсутствуют. Политика входит в отпечаток дорожки `structural`, поэтому её изменение перестраивает дорожку, а уже записанные исключённые модули удаляются из хранилища на ближайшем проходе.

**Живой структурный проход пишет в журнал сам.** Строки `code progress` / `metadata progress` / `help progress` относятся к векторным дорожкам. Структурный проход пишет другое: `Sub-index pass: started` и примерно раз в минуту INFO `N/M file(s) done` с числом воркеров и секундами с старта. Для этих строк переменные менять не нужно. Отсутствие `code progress` не означает, что структурная дорожка стоит.

**Диагностика зависшей единицы, не всего прохода.** Warning `still active past` называет относительный путь, стадию, время и число воркеров, когда *одна* единица держится дольше `SUB_INDEX_PROGRESS_WARN_SEC` (по умолчанию 300 секунд). Чтобы warning появился раньше, поставьте `SUB_INDEX_PROGRESS_WARN_SEC=60`; `SUB_INDEX_PROGRESS_HEARTBEAT_SEC` задаёт интервал повтора того же warning и, если он короче минуты, также частоту INFO. Стадии: `source_walk`, `source_attribution`, `origin_purge`, `store_prepare`, `structural_read`, `structural_parse`, `structural_write`, `dependency_graph`, `form_index`, `worker_wait`, `fts_rebuild`, `extension_resolution`, `sub_index_gate`. При `SUB_INDEX_LIVENESS_WITNESS=true` то же самое повторит отдельный процесс. `0` в пороге выключает и INFO, и warning. Имя модуля из строки `structural_parse` подставляется в `STRUCTURAL_EXCLUDE`; если таких модулей много, дорожку целиком выключает `INDEX_STRUCTURAL=false`. Один подозрительный модуль измеряется отдельно, без полного прохода: `python src/structural_probe.py <путь>/Module.bsl --json` (по умолчанию таймаут 600 секунд, отключает его только явный `--timeout 0`); печатаются размер, время по стадиям, счётчики и типизированный отказ, исходный текст и абсолютные пути — никогда. После изменения переменных пересоздайте контейнер с сохранением тома данных: `docker restart` новые переменные не применяет.

**Границы процедур в выгруженных модулях форм.** Парсер считает концом процедуры и функции не только `КонецПроцедуры` / `КонецФункции` с начала строки, но и хвост той же строки: `Вызов(...);КонецПроцедуры`. Такие однострочные обработчики типичны для Designer XML. Строковый литерал `"КонецПроцедуры"` концом не считается. Старый разбор без этого правила писал ложное `Overlapping definition` на следующей процедуре и после двух таких предупреждений мог часами не печатать прогресс.

### Индексация расширений конфигурации

Расширения индексируются вместе с основной конфигурацией: явно указанные корни берутся первыми, а остальное сервер находит сам рядом с `CODE_PATH`. В коллекцию метаданных попадают и объекты, которые расширение добавляет (дескрипторы в папках типов без `ObjectBelonging = Adopted`, Designer и EDT); источник «отчёт по конфигурации» (`METADATA_PATH`) расширений не читает. В листинг `compact_metadata` попадают собственные объекты расширения всех видов, в том числе общие картинки, подсистемы и пакеты XDTO (выгрузка Конфигуратора); формы и макеты объекта расширения отдельными объектами не считаются. Происхождение каждого результата возвращается в блоке `origin` — см. [провенанс расширений](https://docs.onerpa.ru/pages/djaqTA3ObVXuMD3hd6mc#%D0%BF%D1%80%D0%BE%D0%B2%D0%B5%D0%BD%D0%B0%D0%BD%D1%81-%D1%80%D0%B0%D1%81%D1%88%D0%B8%D1%80%D0%B5%D0%BD%D0%B8%D0%B9).

| Переменная                  | Описание                                                                                                                                                                 | По умолчанию  |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| `INDEX_EXTENSIONS`          | Индексировать найденные расширения. `false` отключает индексацию, но не отключает их обнаружение: состав расширений по-прежнему виден в `stats`                          | `true`        |
| `EXTENSION_PATHS`           | Явные корни расширений через запятую; путь абсолютный или относительный к `CODE_PATH`. Несуществующий путь пропускается с предупреждением, а не останавливает индексацию | *(не задано)* |
| `EXTENSION_DISCOVERY_DEPTH` | На сколько уровней выше `CODE_PATH` подниматься при поиске соседних выгрузок расширений. `0` отключает поиск по соседям — тогда работают только `EXTENSION_PATHS`        | `1`           |
| `EXTENSION_EXCLUDE`         | Идентификаторы или объявленные имена расширений через запятую, которые не индексируются. Обнаружение по-прежнему сообщает о них                                          | *(не задано)* |

Набор расширений — свойство прогона, построившего индекс, а не запроса: изменение этих переменных не меняет происхождение уже сохранённых строк, оно применяется при следующей индексации.

**Повторное чтение только расширений (Code от 31.10.2026).** `reindex(force=true, origin="extension")` заново читает файлы всех расширений, `reindex(force=true, origin="ext:<Имя>")` — одного. Это обычное обновление: новое поколение собирается из копии опубликованного, основная конфигурация и остальные расширения не перечитываются, эмбеддинги неизменившегося текста подставляются из журнала (`EMBEDDING_JOURNAL`). Нужен, когда исправление касается только того, как читаются XML или модули расширений. Места на диске нужно столько же, сколько при любом обновлении: на время сборки — копия опубликованного поколения; поиск всё это время отвечает по опубликованному. Список файлов и их хеши при этом сверяются по всей выгрузке, а не только по выбранному расширению: прогон собирает полное новое поколение, а узнать, что основная конфигурация не изменилась, можно только сверив её файлы. На томе с диска Windows для этого нет более дешёвого признака: дата каталога не меняется при правке файла внутри него, а уведомления об изменениях через такой том в контейнер не приходят. Сколько занимает сверка и как её ускорить — в разделе [Время индексации](https://docs.onerpa.ru/pages/UzUG2evPhPPS60qisAYA#%D0%B8%D0%B7-%D1%87%D0%B5%D0%B3%D0%BE-%D1%81%D0%BA%D0%BB%D0%B0%D0%B4%D1%8B%D0%B2%D0%B0%D0%B5%D1%82%D1%81%D1%8F-%D0%B2%D1%80%D0%B5%D0%BC%D1%8F).

**Корень, убранный из `EXTENSION_PATHS` (Code от 31.10.2026).** Расширение, которое индекс содержал и которого больше нет в `EXTENSION_PATHS`, удаляется из индекса целиком при следующем обновлении, как исключённое через `EXTENSION_EXCLUDE`: модули, граф зависимостей, карточки и то, что расширение добавляло в заимствованные объекты, привязки перехватов, индекс форм, векторы и записи трекеров. Заимствованные объекты остаются с описанием основной конфигурации. Если путь вернуть в `EXTENSION_PATHS`, слой читается целиком, как новый; эмбеддинги неизменившегося текста берутся из журнала, пока каталог расширения не удаляли с диска. Если путь в `EXTENSION_PATHS` остался, а каталог временно недоступен или пуст, данные расширения не трогаются, и после его возвращения ничего не перечитывается. Так же сохраняются данные расширения, найденного рядом с выгрузкой без `EXTENSION_PATHS`, если его каталог пропал. До 31.10.2026 корень, убранный из настройки, оставался в индексе частично: модули и карточки сохранялись, а векторы метаданных удалялись. Чтобы только перечитать расширение, удалять путь не нужно — используйте `reindex(force=true, origin=...)`.

Карточка заимствованного объекта следует за дескриптором расширения и при обычном обновлении: реквизит, табличная часть, форма или команда, которые расширение добавило, появляются в `get_metadata_details`, удалённые — исчезают, а если расширение перестало заимствовать объект, его вклад снимается. Собственные объекты расширения после полной сборки хранятся вместе с реквизитами, как после правки их дескриптора (до 31.10.2026 — только строкой объекта). Исключение расширения через `EXTENSION_EXCLUDE` снимает только его вклад: объект основной конфигурации, который расширение заимствовало, остаётся со своим описанием (в образе от 29.10.2026 его карточка удалялась вместе с расширением). После полной сборки следующее обычное обновление читает только изменившиеся XML-файлы, а не все XML выгрузки.

Расширение, выгруженное внутрь `CODE_PATH` (подкаталог со своим `Configuration.xml`), обход выгрузки находит сам. Если тот же каталог назван и в `EXTENSION_PATHS` — относительным путём или через второй том с той же выгрузкой (одна папка смонтирована и как `/app/code`, и как `/app/extensions`), — расширение индексируется один раз, из `EXTENSION_PATHS`, и в журнале появляется строка `Skipping … inside the export: it is the extension root …`. В образах до 30.09.2026 такое расширение шло дважды, вторым источником `ext:<Имя>@<каталог>`; первый прогон нового образа удаляет строки этого второго источника, как у исключённого расширения, остальной индекс не пересчитывается.

{% hint style="info" %}
В 1C:EDT элемент `configurationExtensionPurpose` в `src/Configuration/Configuration.mdo` не пишется, когда назначение — значение по умолчанию «Исправление» (`Patch`). Такой корень всё равно считается расширением: проект с nature `V8ExtensionNature` или с элементом `namePrefix` получает назначение `Patch`. Соседняя база с `V8ConfigurationNature` (или без этих признаков) расширением не становится и при `INDEX_NESTED_CONFIGURATIONS=false` остаётся `nested_configuration` / `policy_excluded`. Явный путь в `EXTENSION_PATHS` не отменяет это распознавание: Patch без тега индексируется как `extension`, а не как вложенная конфигурация. В выгрузке Конфигуратора признак по-прежнему обязателен.
{% endhint %}

### Бюджет ответа по умолчанию

Параметры вызова `max_chars`, `max_items` и `detail_level` со значением `0` / `""` берут значение из этих переменных. Явный параметр запроса всегда имеет приоритет. Без `max_chars` в вызове и без `RESPONSE_MAX_CHARS` ответ ограничен 32768 символами: большой ответ приходит страницами с `truncated: true` и `next_cursor`, а не обрезается клиентом.

| Переменная              | Описание                                                                                                                                                                   | По умолчанию        |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `RESPONSE_MAX_CHARS`    | Предел размера ответа в символах для всей установки. Значение ограничивается сервером диапазоном 2048–262144; выход за него отмечается полем `clamped`. `0` снимает предел | `32768`             |
| `RESPONSE_MAX_ITEMS`    | Максимум элементов на странице для всей установки; серверный потолок — `500`                                                                                               | `0` *(без предела)* |
| `RESPONSE_DETAIL_LEVEL` | Уровень детализации по умолчанию: `outline` или `full`                                                                                                                     | `full`              |

### Качество поиска

| Переменная                      | Описание                                                                                                                                                                                                                                                                                                                                                                                             | По умолчанию |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `BM25_ALPHA`                    | Вес семантического поиска при гибридном ранжировании (0–1). Остаток `1 - alpha` уходит на BM25. Меньше — больший вес точным совпадениям, больше — больший вес семантической близости                                                                                                                                                                                                                 | `0.5`        |
| `MMR_ENABLED`                   | Включить MMR: похожие по нормализованным словам фрагменты уступают место другим релевантным результатам. Дополнительные запросы к embedding API не выполняются                                                                                                                                                                                                                                       | `false`      |
| `MMR_LAMBDA`                    | Вес релевантности в MMR (0–1). `1` сохраняет порядок по оценке; меньшие значения сильнее снижают повторение. Первый результат всегда выбирается по релевантности                                                                                                                                                                                                                                     | `0.5`        |
| `CONTEXT_EXPANSION`             | `siblings`: фрагменты той же процедуры для кода и соседи для справки; `window`: соседи во всех трёх поисках; `none`: отключить                                                                                                                                                                                                                                                                       | `siblings`   |
| `CONTEXT_WINDOW_SIZE`           | Число соседних фрагментов с каждой стороны для режима окна                                                                                                                                                                                                                                                                                                                                           | `1`          |
| `OVERFETCH_MULTIPLIER`          | Множитель расширения выборки для запросов по пути или идентификатору                                                                                                                                                                                                                                                                                                                                 | `4`          |
| `SEMANTIC_OVERFETCH_MULTIPLIER` | Множитель расширения выборки для семантических запросов                                                                                                                                                                                                                                                                                                                                              | `6`          |
| `OVERFETCH_HARD_CAP`            | Жёсткий предел пула кандидатов до ранжирования                                                                                                                                                                                                                                                                                                                                                       | `200`        |
| `OVERFETCH_COLLECTION_FRACTION` | Максимальная доля коллекции в пуле кандидатов                                                                                                                                                                                                                                                                                                                                                        | `0.1`        |
| `MAX_CHUNKS_PER_SOURCE`         | Максимум фрагментов одного источника в итоговой выдаче                                                                                                                                                                                                                                                                                                                                               | `2`          |
| `CODE_SEARCH_MAX_PER_MODULE`    | Максимум результатов одного модуля на странице `codesearch` (`MAX_CHUNKS_PER_SOURCE` считает по процедурам, поэтому один большой общий модуль заполнял всю страницу). Первый результат модуля, остальные находки которого не вошли, несёт `module_results_withheld`. `0` — без ограничения. Применяется при поиске и не входит в отпечаток индекса: смена значения не переиндексирует (с 10.10.2026) | `3`          |
| `RRF_K`                         | Константа reciprocal-rank fusion                                                                                                                                                                                                                                                                                                                                                                     | `20`         |
| `FUSION_PRIOR_WEIGHT`           | Вес априорной релевантности при объединении результатов                                                                                                                                                                                                                                                                                                                                              | `0.2`        |
| `FALLBACK_ON_EMPTY`             | Выполнять резервный поиск, если основной маршрут ничего не вернул                                                                                                                                                                                                                                                                                                                                    | `true`       |
| `MIN_SCORE_THRESHOLD`           | Минимальный порог combined\_score для включения результата (0–1). `0` — без отсечения, `0.3` — агрессивное                                                                                                                                                                                                                                                                                           | `0.15`       |
| `EMBEDDING_CACHE_SIZE`          | Размер LRU-кэша для эмбеддингов поисковых запросов. Сокращает вызовы API при повторных запросах. `0` — отключить                                                                                                                                                                                                                                                                                     | `256`        |
| `LIVE_XML_FALLBACK`             | Дочитывать XML-выгрузку напрямую, когда индекс не содержит нужного факта                                                                                                                                                                                                                                                                                                                             | `true`       |
| `LIVE_XML_CACHE_SIZE`           | Размер кэша разобранных XML-файлов                                                                                                                                                                                                                                                                                                                                                                   | `2000`       |
| `LIVE_XML_MAX_FILES`            | Максимум файлов, просматриваемых при live-чтении XML                                                                                                                                                                                                                                                                                                                                                 | `50000`      |
| `GREP_FILE_CACHE_SIZE`          | Размер кэша файлов текстового поиска по коду                                                                                                                                                                                                                                                                                                                                                         | `500`        |
| `GREP_BROAD_DIR_THRESHOLD`      | Порог числа файлов, после которого каталог считается слишком широким для текстового поиска                                                                                                                                                                                                                                                                                                           | `10000`      |
| `GREP_MAX_RESULTS`              | Предел числа результатов слоя точного текстового поиска (grep)                                                                                                                                                                                                                                                                                                                                       | `50`         |
| `GREP_DEADLINE_SEC`             | Общий бюджет одного fallback-сканирования в секундах; `0` отключает предел                                                                                                                                                                                                                                                                                                                           | `10`         |
| `GREP_MAX_CACHED_FILE_MB`       | Файлы крупнее этого размера читаются, но не остаются в LRU-кэше                                                                                                                                                                                                                                                                                                                                      | `8`          |
| `MCP_TOOL_WORKERS`              | Число потоков для тел MCP-инструментов; долгий синхронный поиск не блокирует `/live` и другие вызовы                                                                                                                                                                                                                                                                                                 | `4`          |
| `INJECT_GRAPH_DEPENDENCIES`     | Добавлять в индексируемый текст связи графа зависимостей объекта                                                                                                                                                                                                                                                                                                                                     | `false`      |

Поле `context` дополняет исходный `document` и ограничено размером `3 × CHUNK_SIZE` (по умолчанию 3000 символов). Совпавший фрагмент остаётся в центре при обрезке. Контекст соблюдает область запроса и читается из того же опубликованного поколения. Если у старых чанков ещё нет числового порядка или один файл достигает предела чтения 10000 чанков, возвращается исходный фрагмент без неполного контекста. После обновления образа обычная индексация перестроит затронутые векторные поколения; неизменившиеся embeddings могут быть взяты из журнала.

{% hint style="warning" %}
`INDEX_STRUCTURAL`, `INDEX_DEPENDENCY_GRAPH`, `INDEX_FORM_INDEX`, `INDEX_XSD_SCHEMAS`, `SUB_INDEX_PROGRESS_WARN_SEC`, `SUB_INDEX_PROGRESS_HEARTBEAT_SEC`, `SUB_INDEX_LIVENESS_WITNESS`, `STRUCTURAL_PARSE_TIMEOUT_SEC`, `STRUCTURAL_EXCLUDE`, `GREP_DEADLINE_SEC`, `GREP_MAX_CACHED_FILE_MB` и `MCP_TOOL_WORKERS` описывают текущую реализацию исходников. Перед применением к опубликованному образу проверьте наличие переменных в его release notes или `/release`; ранее опубликованные образы могут их не содержать.
{% endhint %}

Если grep-fallback упирается в время или ширину дерева, он возвращает уже найденное и помечает ответ `partial`: `reason=scan_deadline_reached` или `reason=scan_scope_capped`. Бюджет общий для всех проходов одного вызова, поэтому синонимы не умножают допустимое время. Файлы крупнее `GREP_MAX_CACHED_FILE_MB` по-прежнему читаются — ограничивается только кэширование.

`metadatasearch`, `codesearch` и `helpsearch` уходят в grep только до первой публикации индекса и при пустой коллекции. Во время переиндексации поиск отвечает из опубликованного поколения (в образах до 27.09.2026 идущая сборка переводила эти инструменты на grep).

### Векторное хранилище zvec

| Переменная                            | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | По умолчанию  |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| `VECTOR_PROFILE`                      | Профиль zvec: `fast_index`, `balanced`, `memory_saver` или `quality`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `fast_index`  |
| `VECTOR_INDEX_TYPE`                   | Тип индекса: `hnsw`, `ivf` или `flat`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | из профиля    |
| `VECTOR_QUANTIZATION`                 | Квантизация: `none`, `fp16` или `int8`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | из профиля    |
| `VECTOR_STORAGE_MODE`                 | Режим хранения: `memory` или `mmap`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | из профиля    |
| `VECTOR_HNSW_M`                       | Параметр связности HNSW                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | из профиля    |
| `VECTOR_HNSW_EF_CONSTRUCTION`         | Глубина построения HNSW                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | из профиля    |
| `VECTOR_HNSW_EF_SEARCH`               | Явная глубина поиска HNSW; иначе `max(порог профиля, множитель × topk)`. В любом случае не больше 2048 — предел zvec (образы от 19.09.2026; раньше расширенное окно поиска с фильтром по области могло запросить больше, и векторная полоса такого запроса молча отвечала пустотой)                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | *(авто)*      |
| `VECTOR_IVF_NLIST`                    | Число кластеров IVF                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | из профиля    |
| `VECTOR_IVF_NPROBE`                   | Число просматриваемых кластеров IVF                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | из профиля    |
| `VECTOR_MEMORY_LIMIT_MB`              | Ограничение памяти zvec в МБ                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | *(не задано)* |
| `VECTOR_QUERY_THREADS`                | Число потоков поиска                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | *(авто)*      |
| `VECTOR_WARMUP_ENABLED`               | Прогрев векторного индекса. После старта и после каждого переключения на новое поколение сервер в фоне делает по одному дешёвому векторному запросу на каждую включённую полосу (метаданные, код, справка, формы). Тогда первый поиск пользователя не платит за загрузку индекса: на слитом индексе он заметно медленнее следующих, на большом проекте мог упираться в таймаут клиента. Прогрев идёт тем же путём, что обычный поиск: не читает параллельно с другим чтением той же полосы и не трогает поколение, которое закрывается. Полоса с неслитыми документами не прогревается, по ним запрос — полный перебор. Готовность сервера прогрева не ждёт, в журнале — строка `Vector warm-up of generation …`. `false` — без прогрева. С 13.10.2026 | `true`        |
| `VECTOR_OPTIMIZE_THREADS`             | Число потоков оптимизации                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | *(авто)*      |
| `VECTOR_OPTIMIZE_ENABLED`             | Разрешить периодическую оптимизацию zvec и финальную оптимизацию кандидата перед публикацией поколения                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `true`        |
| `VECTOR_OPTIMIZE_EVERY`               | Число новых документов между оптимизациями; `0` — только финальная (в образах до 27.09.2026 значение `0` не действовало: слияния шли каждые 100000)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `100000`      |
| `VECTOR_OPTIMIZE_FINAL_MIN_DOCS`      | Если к концу фазы слияния ждут меньше N документов, финальная оптимизация не запускается (исход `skipped_below_threshold` в `stats`): документы остаются во временном буфере, находятся векторным и полнотекстовым поиском, переходят в следующее поколение и сливаются, когда их наберётся N. На полосу с `rebuild_required` не действует, переиндексацию не вызывает. `0` — сливать любой непустой хвост. С 27.09.2026                                                                                                                                                                                                                                                                                                                               | `0`           |
| `VECTOR_FLUSH_EVERY`                  | Число новых документов между промежуточными сбросами на диск; `0` — только финальный сброс                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `2000`        |
| `VECTOR_OPTIMIZE_DEADLINE_SEC`        | Максимальное ожидание оптимизации в фоновой индексации                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `1800`        |
| `VECTOR_OPTIMIZE_CANCEL_DEADLINE_SEC` | Максимальное ожидание оптимизации из запроса или принудительной переиндексации                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `5`           |
| `VECTOR_WRITE_FAILURE_THRESHOLD`      | Последовательные ошибки записи до перевода коллекции в терминальное состояние                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `5`           |
| `INDEX_STALL_HEARTBEAT_SEC`           | Через сколько секунд без завершённого файла фаза индексации пишет в журнал, чего ждёт: очередь, файлы в работе, идущее слияние векторного индекса. С 01.10.2026 (вечер) строка называет полный путь самого долгого файла, сколько его чанков готово и сколько чанков записано за интервал: большой модуль, который ещё эмбеддится, отличается от остановившегося провайдера. `0` — выключить                                                                                                                                                                                                                                                                                                                                                           | `300`         |

Перед публикацией нового поколения сервер завершает оптимизацию и переоткрывает хранилище кандидата. Это сохраняет изменения FTS, которые одного `flush()` в zvec 0.6 недостаточно перенести в следующую копию поколения. Поиск в это время обслуживается предыдущим поколением. Если коллекция уже помечена `fts_index_incompatible` (старым образом или после того, как процесс убили посреди слияния), первый обычный прогон восстанавливает её из сохранённых в ней документов — см. раздел «Восстановление FTS после обновления кодека». `reindex(force=true)` нужен, если коллекция осталась `rebuild_required` и после этого прогона.

`VECTOR_OPTIMIZE_ENABLED=false` оставляет запись и поиск по буферизованным документам доступными, но отключает уплотнение и построение ANN-индекса. На большом корпусе это может увеличивать время поиска, расход памяти и диска: неслитые документы и векторный, и полнотекстовый поиск читают перебором, и на сотнях тысяч фрагментов запрос идёт минутами. С 13.10.2026 при старте с этой настройкой сервер пишет предупреждение `Collection '<полоса>' opened with ~N document(s) not merged into its vector index. VECTOR_OPTIMIZE_ENABLED=false: …`. Такой обход не даёт гарантии ограниченного роста ресурсов; после обновления и восстановления повреждённых дорожек оптимизацию можно включить обратно.

С 13.10.2026, если в опубликованном поколении есть неслитые документы (индекс собирался с `VECTOR_OPTIMIZE_ENABLED=false`, слияние прерывалось), а слияние включено, первый же прогон индексации — стартовый или периодический — один раз собирает новое поколение даже при неизменной выгрузке: все файлы переносятся без повторного эмбеддинга, документы сливаются в ANN-индекс, и только после этого поколение публикуется (в журнале — `Vector lane(s) … hold documents no merge has indexed yet`). Раньше слияние шло только в сборке после изменения выгрузки, и неслитый буфер мог оставаться навсегда. Хвост меньше `VECTOR_OPTIMIZE_FINAL_MIN_DOCS` такой сборки не вызывает. Слияние большого индекса занимает часы, поиск всё это время обслуживает прежнее поколение; не останавливайте контейнер, пока идёт слияние.

{% hint style="warning" %}
**Слияние векторного индекса и запись.** zvec складывает новые документы во временный плоский буфер и переносит их в HNSW-индекс при оптимизации; периодическая оптимизация запускается каждые `VECTOR_OPTIMIZE_EVERY` документов в фоновом потоке. В образах до 18.09.2026 (zvec 0.6) вставка была сериализована с оптимизацией внутри самого хранилища: пока шло слияние, потоки записи ждали, обращений к эмбеддингам не было, очередь заполнялась. В zvec 0.7 запись продолжается во время слияния; в образах от 18.09.2026 он стоит на обеих платформах: `arm64` — из опубликованного пакета, x86 (`latest`, `light`) — собранный из исходников без обязательного AVX2 (совместимость с CPU без AVX2; такая сборка сливает медленнее опубликованного пакета, но запись во время слияния идёт). Хранилище, созданное 0.6, открывается на 0.7 без переиндексации. Какое поведение у вашей инсталляции, видно по строке `zvec optimize DONE … (writers waited N s for it)`. Длительность одного слияния растёт с размером индекса и размерностью векторов: на корпусе в миллион фрагментов с 4096-мерными эмбеддингами последние слияния занимают часы; на прежних образах именно так выглядел «хвост» фазы кода — счётчик файлов стоит, CPU низкий, размер хранилища растёт. Это не зависание, и в журнале это видно: в журнале есть `zvec optimize START … (merging N buffered docs …)`, при первом ожидающем писателе — `zvec add on <lane> waits for the background merge in flight (…)`, по завершении — `zvec optimize DONE … (writers waited N s for it)`, а каждые `INDEX_STALL_HEARTBEAT_SEC` без завершённого файла — строка `<lane> phase: no file completed for N min … merge in flight: …`. Строка прогресса ведёт скорость и ETA по последнему интервалу (`files/min (recent; avg)`), а не по среднему за фазу.

Что с этим делать. Не останавливайте контейнер во время слияния: прерванное слияние оставляет маркер, и на следующем старте полоса переносится в rebuild-лейн, то есть переиндексируется целиком. `VECTOR_OPTIMIZE_EVERY` задаёт число слияний (больше значение — меньше слияний, каждое дольше; суммарная работа та же), `VECTOR_OPTIMIZE_THREADS` — число потоков слияния (по умолчанию `min(8, cpu)`). Фаза не считается завершённой, а поколение не публикуется, пока не завершены все файлы и финальная оптимизация, если её не пропустил порог `VECTOR_OPTIMIZE_FINAL_MIN_DOCS`, — это видно в `get_indexing_status`. Для большого индекса с небольшими правками, например `VECTOR_OPTIMIZE_FINAL_MIN_DOCS=50000`, хвост меньше 50 000 документов остаётся в буфере до следующих прогонов. Держите порог намного меньше размера индекса: неслитые документы ищутся перебором.
{% endhint %}

### Нейронный реранкер (cross-encoder)

Опциональный нейронный реранкер для повышения качества семантического поиска. При включении оценивает пары (запрос, документ) совместно, что значительно улучшает релевантность результатов.

| Переменная                          | Описание                                                                                      | По умолчанию  |
| ----------------------------------- | --------------------------------------------------------------------------------------------- | ------------- |
| `ENABLE_RERANKER`                   | Включить нейронный реранкер. `true` — использовать cross-encoder, `false` — использовать BM25 | `false`       |
| `RERANKER_MODEL`                    | Модель реранкера. Если не указано — автовыбор в зависимости от окружения                      | *(авто)*      |
| `RERANKER_TOP_K`                    | Максимальное количество кандидатов, передаваемых реранкеру                                    | `20`          |
| `RERANKER_API_BASE`                 | URL API реранкера, если он отличается от `EMBEDDING_API_BASE` / `OPENAI_API_BASE`             | *(не задано)* |
| `RERANKER_API_KEY`                  | Ключ API реранкера, если он отличается от ключа эмбеддингов                                   | *(не задано)* |
| `RERANKER_REQUEST_TIMEOUT_S`        | Таймаут одного запроса к реранкеру, секунды                                                   | `10`          |
| `RERANKER_MAX_CONSECUTIVE_FAILURES` | Число подряд идущих ошибок до временного отключения реранкера                                 | `3`           |
| `RERANKER_COOLDOWN_SECONDS`         | Пауза перед повторной попыткой после отключения реранкера                                     | `30`          |

{% hint style="info" %}
**Автовыбор модели реранкера:**

* Если `OPENAI_API_BASE` задан → API-режим, модель по умолчанию: `Qwen/Qwen3-Reranker-8B`
* Если `OPENAI_API_BASE` не задан → локальный режим, модель: `Qwen/Qwen3-Reranker-0.6B`

Цепочка деградации: cross-encoder → BM25 → только вектор
{% endhint %}

### Embedding модели (LM Studio / Ollama)

| Переменная                     | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Пример                                                        |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `EMBEDDING_API_BASE`           | URL API сервера. При использовании OpenRouter: `https://openrouter.ai/api`. Суффикс `/v1` добавляется автоматически                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `http://host.docker.internal:1234/v1`                         |
| `EMBEDDING_API_BASE_NO_V1`     | Передавать базу API дословно, без автодобавления `/v1` (значения `1`, `true`, `yes`) — для шлюзов, отдающих OpenAI-совместимый API без суффикса `/v1`. С 10.10.2026                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `1`                                                           |
| `EMBEDDING_API_KEY`            | Ключ API (для LM Studio — любой, для OpenRouter — ваш ключ)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `lm-studio`                                                   |
| `EMBEDDING_MODEL`              | Название модели для API или локального режима (для OpenRouter: `qwen/qwen3-embedding-8b`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `sentence-transformers/paraphrase-multilingual-mpnet-base-v2` |
| `EMBEDDING_DIMENSIONS`         | Явное указание размерности эмбеддингов. Поддерживается моделями с переменной размерностью (Qwen3, text-embedding-3). Если не указано — определяется автоматически: по профилю модели, а для модели, профиль которой размерность не задаёт (например, `text-embedding-qwen3-embedding-4b` в LM Studio), — одним пробным запросом эмбеддинга при старте. Размерность входит в fingerprint поколения индекса, поэтому вычисляется одинаково при холодном старте и в работающем процессе; для неизвестной модели при недоступном в момент старта провайдере она записывается как `0` с предупреждением в журнале — задайте переменную явно, чтобы fingerprint не зависел от доступности провайдера | *(авто)*                                                      |
| `EMBEDDING_PROVIDER`           | Явно выбрать `remote` или `local`; если не задано, сервер выводит режим из варианта образа и настроек endpoint                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | *(авто)*                                                      |
| `EMBEDDING_PROVIDER_AMBIGUITY` | Поведение при неоднозначной legacy-конфигурации: ошибка или вывод режима                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `error`                                                       |
| `EMBEDDING_MEMORY_BUDGET_MB`   | Допустимая оценка памяти для локальной модели до загрузки весов                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `4096`                                                        |
| `EMBEDDING_MEMORY_BUDGET_MODE` | `refuse`, `warn` или `off` при превышении бюджета                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `refuse`                                                      |
| `EMBEDDING_MEMORY_SAMPLE_SEC`  | Интервал измерения памяти локального embedding-процесса                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `30`                                                          |
| `EMBEDDING_MEMORY_WARN_RATIO`  | Доля бюджета, после которой состояние помечается предупреждением                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `0.9`                                                         |

{% hint style="info" %}
**Поддержка OpenRouter:** Сервер автоматически определяет OpenRouter по URL и добавляет необходимые HTTP-заголовки (`HTTP-Referer`, `X-Title`).
{% endhint %}

### Embedding модели (CPU)

| Переменная        | Описание                                                               | Пример                                                        |
| ----------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------- |
| `EMBEDDING_MODEL` | Модель с Hugging Face; та же переменная выбирает модель и в API-режиме | `sentence-transformers/paraphrase-multilingual-mpnet-base-v2` |

Старые имена `OPENAI_API_BASE`, `OPENAI_API_KEY` и `OPENAI_MODEL` пока принимаются как совместимые алиасы, но новые конфигурации следует создавать с `EMBEDDING_*`.

{% hint style="warning" %}
Здесь есть два разных значения по умолчанию. Если `EMBEDDING_MODEL` не задан в полном образе, исходники используют локальную `sentence-transformers/paraphrase-multilingual-mpnet-base-v2`; удалённый профиль поставки явно закрепляет `qwen/qwen3-embedding-8b`. По измерению от 31.08.2026 ни одна проверенная замена не прошла общий gate, поэтому `qwen/qwen3-embedding-8b` остаётся удалённой моделью поставки.

Смена `EMBEDDING_MODEL` или `EMBEDDING_DIMENSIONS` — миграция, а не дешёвая настройка: меняется fingerprint и полностью переэмбеддируются дорожки `metadata`, `metadata_xml`, `code`, `help` и `form_index`. Для отката верните прежние модель и размерность; после этого потребуется обратная пересборка тех же дорожек.

Чтобы сменить модель, поменяйте переменные и пересоздайте контейнер; `RESET_DATABASE` не нужен. С 23.09.2026 сервер стартует на прежнем поколении индекса, но его векторные дорожки построены старой моделью, поэтому в поиске не участвуют (журнал называет каждую дорожку и отличающуюся настройку), а поиск по ним идёт через файловый fallback. Тем временем собирается новое поколение, и сервер переключается на него после публикации. Более ранние сборки в этой ситуации останавливались с ошибкой `zvec store signature mismatch`.
{% endhint %}

Профиль совместимости — это то, что реестр принимает и с чем сервер умеет работать. Рекомендация качества — отдельное решение: модель становится удалённым умолчанием только если прошла заранее зафиксированный gate. Измерение 31.08.2026 сравнило, среди прочих, `qwen/qwen3-embedding-8b`, `baai/bge-m3` и `openai/text-embedding-3-small`. Замены отклонены; превосходства без этих цифр документация не обещает.

| Модель                                                                                    | Размерность    | Инструкция запроса | Совместима | Рекомендация качества        |
| ----------------------------------------------------------------------------------------- | -------------- | ------------------ | ---------- | ---------------------------- |
| `qwen/qwen3-embedding-8b`                                                                 | 4096           | инструкция Qwen3   | да         | удалённое умолчание поставки |
| `Qwen3-Embedding-4B`, `Qwen3-Embedding-0.6B` (любое имя с `qwen3-embedding-4b` / `-0.6b`) | пробный запрос | инструкция Qwen3   | да         | не измерялась                |
| Ollama: `qwen3-embedding:8b`, `:4b`, `:0.6b` (любое другое имя с `qwen3-embedding`)       | пробный запрос | инструкция Qwen3   | да         | не измерялась                |
| `embeddinggemma-300m` (в том числе `text-embedding-embeddinggemma-300m-qat` в LM Studio)  | 768            | нет                | да         | не измерялась                |
| `baai/bge-m3`                                                                             | 1024           | нет                | да         | нет: не прошла gate          |
| `openai/text-embedding-3-small`                                                           | 1536           | нет                | да         | нет: не прошла gate          |

Инструкция Qwen3 для запроса — `Instruct: Given a web search query, retrieve relevant passages that answer the query` и перевод строки перед `Query:`, как в карточке модели. Формулировки под 1С («retrieve the matching 1C code fragment … or configuration metadata object») на том же корпусе оказались хуже (nDCG\@10 0,836–0,844 против 0,866, проигрыш на запросах о методах), поэтому у CodeMetadataSearchServer остаётся текст карточки; у остальных серверов инструкция сформулирована под их корпус (см. [Инструкция к запросу у Qwen3](https://docs.onerpa.ru/pages/zZx7MZNnC5Ejse6V9TZC#%D0%B8%D0%BD%D1%81%D1%82%D1%80%D1%83%D0%BA%D1%86%D0%B8%D1%8F-%D0%BA-%D0%B7%D0%B0%D0%BF%D1%80%D0%BE%D1%81%D1%83-%D1%83-qwen3)). До 22.09.2026 запросы к Qwen3-8B шли с префиксом `query:` , а к 0.6B и 4B — вообще без префикса. На том же корпусе, что и замер 31.08, инструкция подняла у `qwen/qwen3-embedding-8b` MRR с 0,855 до 0,941 и nDCG\@10 с 0,733 до 0,858. Префикс документов в замере на качество не повлиял (0,939 / 0,859 с `document:` ).

С 23.09.2026 (поздний вечер) префиксов нет совсем: документы и запросы уходят в модель как есть, и только запрос к Qwen3 идёт с инструкцией. `EMBEDDING_QUERY_PREFIX` и `EMBEDDING_DOCUMENT_PREFIX` больше не применяются, заданная переменная выводит предупреждение в журнал. Индекс, документы которого записаны с префиксом (модели e5, EmbeddingGemma, `qwen/qwen3-embedding-8b` с `document:` или заданный `EMBEDDING_DOCUMENT_PREFIX`), при первом запуске новой сборки один раз пересобирается целиком в новом поколении; прежнее поколение отвечает, пока новое не опубликовано. Остальные индексы не пересчитываются.

Флаг `rerank_capable` в профиле при поставке по умолчанию не читается: кросс-энкодер включается только `ENABLE_RERANKER=true`. Ни одна модель из этого замера флаг не несёт, поэтому смена эмбеддинга сама по себе реранкер не меняет.

### Плагины

| Переменная                    | Описание                                                                                                                                                                                                      | По умолчанию   |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| `PLUGIN_DIR`                  | Каталог, из которого читаются файлы плагинов                                                                                                                                                                  | `/app/plugins` |
| `PLUGIN_STRICT_DERIVED_STATE` | `true` — упавший derived-state хук (`on_source_file`, `on_chunk`, `on_metadata_object`) роняет сборку целиком; при `false` единица индексируется без изменений, а ошибка считается и попадает в сводку сборки | `false`        |
| `PLUGIN_HOOK_TIMEOUT_SECONDS` | Бюджет времени одного вызова хука в секундах; превысивший его хук считается упавшим и call-scoped отключается до следующей перезагрузки каталога                                                              | `5.0`          |

Каталог читается при каждом старте, флага включения нет: пустой или отсутствующий каталог ничего не загружает и ничего не меняет. Подробности: [Доработка MCP: система плагинов](https://docs.onerpa.ru/mcp-servery-1c/sistema-pluginov.md).

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

| Хост                        | Контейнер        | Назначение                                                                     |
| --------------------------- | ---------------- | ------------------------------------------------------------------------------ |
| `E:/1C_Export/Report`       | `/app/metadata`  | Необязательный legacy-отчёт только для `METADATA_SOURCE=report`                |
| `E:/1C_Export/Files`        | `/app/code`      | Выгрузка в файлы                                                               |
| `E:/bases/mcp_codemetadata` | `/app/chroma_db` | Векторная база данных                                                          |
| `./my-plugins`              | `/app/plugins`   | Свой каталог плагинов; монтирование поверх сохраняет плагины при `docker pull` |

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

### Минимальная (CPU)

```powershell
docker run -d -p 8000:8000 `
  --name 1c_code_metadata_mcp `
  -e LICENSE_KEY=YOUR_LICENSE_KEY `
  -e CODE_PATH="/app/code" `
  -e METADATA_SOURCE=xml `
  -e SOURCE_FORMAT=auto `
  -v "E:/1C_Export/Files:/app/code" `
  comol/1c_code_metadata_mcp:latest
```

### Рекомендуемая (LM Studio)

```powershell
docker run -d -p 8000:8000 `
  --name 1c_code_metadata_mcp `
  -e LICENSE_KEY=YOUR_LICENSE_KEY `
  -e CODE_PATH="/app/code" `
  -e METADATA_SOURCE=xml `
  -e SOURCE_FORMAT=auto `
  -e RESET_DATABASE=false `
  -e EMBEDDING_API_BASE=http://host.docker.internal:1234/v1 `
  -e EMBEDDING_API_KEY=lm-studio `
  -e EMBEDDING_MODEL=Qwen3-Embedding-4B `
  -v "E:/1C_Export/Files:/app/code" `
  -v "E:/bases/mcp_codemetadata:/app/chroma_db" `
  comol/1c_code_metadata_mcp:latest
```

### С OpenRouter (облачные эмбеддинги)

```powershell
docker run -d -p 8000:8000 `
  --name 1c_code_metadata_mcp `
  -e LICENSE_KEY=YOUR_LICENSE_KEY `
  -e CODE_PATH="/app/code" `
  -e METADATA_SOURCE=xml `
  -e SOURCE_FORMAT=auto `
  -e RESET_DATABASE=false `
  -e EMBEDDING_API_BASE=https://openrouter.ai/api `
  -e EMBEDDING_API_KEY=YOUR_OPENROUTER_KEY `
  -e EMBEDDING_MODEL=qwen/qwen3-embedding-8b `
  -v "E:/1C_Export/Files:/app/code" `
  -v "E:/bases/mcp_codemetadata:/app/chroma_db" `
  comol/1c_code_metadata_mcp:latest
```

### Облегчённый образ (light) с LM Studio

```powershell
docker run -d -p 8000:8000 `
  --name 1c_code_metadata_mcp `
  -e LICENSE_KEY=YOUR_LICENSE_KEY `
  -e CODE_PATH="/app/code" `
  -e METADATA_SOURCE=xml `
  -e SOURCE_FORMAT=auto `
  -e RESET_DATABASE=false `
  -e EMBEDDING_API_BASE=http://host.docker.internal:1234/v1 `
  -e EMBEDDING_API_KEY=lm-studio `
  -e EMBEDDING_MODEL=Qwen3-Embedding-4B `
  -v "E:/1C_Export/Files:/app/code" `
  -v "E:/bases/mcp_codemetadata:/app/chroma_db" `
  comol/1c_code_metadata_mcp:light
```

### С реранкером и тюнингом поиска

```powershell
docker run -d -p 8000:8000 `
  --name 1c_code_metadata_mcp `
  -e LICENSE_KEY=YOUR_LICENSE_KEY `
  -e CODE_PATH="/app/code" `
  -e METADATA_SOURCE=xml `
  -e SOURCE_FORMAT=auto `
  -e RESET_DATABASE=false `
  -e ENABLE_RERANKER=true `
  -e BM25_ALPHA=0.5 `
  -e EMBEDDING_API_BASE=http://host.docker.internal:1234/v1 `
  -e EMBEDDING_API_KEY=lm-studio `
  -e EMBEDDING_MODEL=Qwen3-Embedding-4B `
  -v "E:/1C_Export/Files:/app/code" `
  -v "E:/bases/mcp_codemetadata:/app/chroma_db" `
  comol/1c_code_metadata_mcp:latest
```

### С настройкой индексации

```powershell
docker run -d -p 8000:8000 `
  --name 1c_code_metadata_mcp `
  -e LICENSE_KEY=YOUR_LICENSE_KEY `
  -e CODE_PATH="/app/code" `
  -e METADATA_SOURCE=xml `
  -e SOURCE_FORMAT=auto `
  -e RESET_DATABASE=false `
  -e INDEX_CODE=true `
  -e INDEX_METADATA=true `
  -e INDEX_HELP=true `
  -e EMBEDDING_API_BASE=http://host.docker.internal:1234/v1 `
  -e EMBEDDING_API_KEY=lm-studio `
  -e EMBEDDING_MODEL=Qwen3-Embedding-4B `
  -v "E:/1C_Export/Files:/app/code" `
  -v "E:/bases/mcp_codemetadata:/app/chroma_db" `
  comol/1c_code_metadata_mcp:latest
```

## Возобновление расчёта эмбеддингов

При SIGTERM сервер прекращает приём новых работ, а текущая запись или нативное слияние индекса завершается до выхода процесса. `SHUTDOWN_GRACE_SEC` задаёт только ожидание HTTP-запросов. Для остановки во время длительного слияния увеличьте Docker stop timeout, например `docker stop --time 600 <контейнер>` или `stop_grace_period: 10m` в Compose. По истечении внешнего срока Docker применяет SIGKILL, который приложение обработать не может; срок выбирается с учётом длительности слияния на вашей конфигурации.

Подготовка описаний форм и их эмбеддинг тоже проверяют флаг остановки: на каждой форме и на каждой пачке (Code от 01.10.2026; раньше этап форм доходил до конца и не давал контейнеру остановиться). Ход этапа виден в журнале: `forms progress: prepared N/M summaries`, затем `Phase forms: N summaries prepared in X s (...); embedding K` и `forms progress: embedded N/M summaries`.

**Длинные описания форм (Code от 02.10.2026).** Описание формы (элементы, реквизиты, команды, обработчики) длиннее 4 000 символов эмбеддится частями: текст режется по концам строк, каждая следующая часть начинается со строк `Форма: <объект> / <форма>`, `Заголовок: …` и `Фрагмент N из M`, ничего не отбрасывается. 4 000 символов такого текста — около 1 200–1 600 токенов, часть помещается и в модель с контекстом 2 048 токенов. Раньше описание уходило одним запросом любой длины: у крупной формы документа (30 тыс. символов, около 8 900 токенов) модель с лимитом 8 192 токена отвечала `400 ContextWindowExceededError`, форма не эмбеддилась, и поколение не публиковалось. `search_forms` возвращает форму один раз, какой бы из её частей ни нашёлся. Описания короче 4 000 символов (на ЗУП — 96 % форм) не меняются и заново не эмбеддятся; длинные формы, сохранённые раньше целиком, пересчитываются частями при следующей индексации форм.

Если провайдер отвечает, что текст длиннее, чем принимает модель (ответ `400`/`413`/`422` со словами `maximum context length`, `ContextWindowExceededError`, `input is too long` и т. п.), запрос не повторяется: пакет сразу уходит на поштучную отправку, а слишком длинный фрагмент пропускается с предупреждением `Chunk … is longer than the embedding model accepts; dropping this chunk`. Такой пропуск, как и ответ без данных эмбеддинга, не останавливает публикацию поколения. Раньше пакет повторялся `BATCH_MAX_RETRIES` раз, затем каждый фрагмент ещё столько же.

**Провайдер не отвечает (Code от 01.10.2026, вечер).** Один запрос к API эмбеддингов ждёт ответа не дольше `EMBEDDING_API_TIMEOUT` секунд (по умолчанию 600), повторов внутри клиента нет; пакет повторяется до `BATCH_MAX_RETRIES` раз с паузой `BATCH_BACKOFF_*`. Если и после этого ответа нет (таймаут или обрыв соединения), сервер перестаёт обращаться к провайдеру в этом прогоне, не разбирает оставшиеся файлы и завершает дорожку ошибкой `provider_failure`: поколение не удаляется, завершённые файлы записаны в трекер, уже полученные векторы лежат в журнале, следующий старт продолжает с оставшихся файлов. Раньше такой провайдер держал все потоки эмбеддинга часами. Ответ провайдера с ошибкой (429, 5xx) по-прежнему ведёт к повтору пакета по одному чанку. Чтобы замечать молчащий провайдер быстрее, уменьшите оба значения, например `EMBEDDING_API_TIMEOUT=120` и `BATCH_MAX_RETRIES=2` (около 6 минут на пакет); для провайдера на CPU с большой очередью запросов таймаут должен покрывать ожидание в его очереди.

**Временный отказ шлюза (Code от 29.10.2026).** Ответ `403` с текстом `Access denied by security policy` не считается отказом ключа: запрос повторяется в пределах `BATCH_MAX_RETRIES`, с паузой и общим ожиданием для всех потоков эмбеддингов. Если попытки исчерпаны, прогон перестаёт обращаться к провайдеру и завершается возобновляемой ошибкой: уже посчитанные файлы сохраняются, следующий `reindex` без `force` продолжает с оставшихся. Ошибка `401` и любой другой `403` по-прежнему завершают прогон сразу и не повторяются. Само это изменение отпечаток индекса не меняет. Выпуск 29.10.2026 при этом меняет разбор форм: индекс от образа до 29.10.2026 при первом прогоне один раз пересобирает структурный индекс, граф зависимостей и индекс форм и заново запрашивает эмбеддинги сводок форм (с образом от 01.11.2026 — только тех, чей текст изменился) — подробности и замеры в [выпусках](https://docs.onerpa.ru/mcp-servery-1c/vypuski.md).

Успешные батчи документных эмбеддингов сохраняются до записи в zvec в SQLite-журнале `<VECTOR_DB_PATH>/projects/<project_id>/embedding-journal/<lane>.sqlite3`. Монтируйте постоянный том для всего `/app/chroma_db`: журнал находится за пределами удаляемых поколений индекса.

Если индексацию прервали перезапуском контейнера, SIGTERM или недоступностью embedding-модели, поколение не удаляется. После инициализации (инвентарь, recovery) сервер продолжает ту же сборку: завершённые дорожки берутся из их чекпоинтов, а прерванная дорожка кода — из `file_tracker` этого поколения (уже учтённые файлы не разбираются и не эмбеддятся заново). Журнал дополнительно подставляет уже оплаченные векторы, если файл всё же попал в повтор. Частичный прогресс не делает индекс готовым к публикации.

Журнал требует дополнительного места: 4 байта на измерение вектора плюс ключи и служебные данные SQLite (в образах до 18.09.2026 — 8 байт; такие записи остаются читаемыми и заменяются по мере изменения файлов). Устаревшие записи очищаются при успешной обработке дорожки, а очистка старых поколений сохраняет журнал. Освобождённые страницы SQLite переиспользуются, но файл не уменьшается. `EMBEDDING_JOURNAL=false` выключает журнал. Удаление тома или смена проекта лишает восстановления сохранённых данных. Запрос, который провайдер уже обработал, но сервер ещё не сохранил, может повториться; однократная оплата внешнего API не гарантируется.

## Место на диске

Внутри `<VECTOR_DB_PATH>/projects/<project_id>/` живут две крупные сущности:

* `generations/<id>/` — поколения индекса: zvec-коллекции (векторы в типе профиля — `fp16` для `fast_index`, HNSW-граф, тексты фрагментов), FTS и служебные SQLite-индексы. Обслуживается одно поколение; новое строится рядом и публикуется атомарно, так что во время сборки на диске всегда два. После публикации предыдущие хранятся в количестве `GENERATION_RETENTION_COUNT` (по умолчанию `2`, то есть текущее и одно предыдущее для отката) и удаляются по окончании ближайшего прогона индексации — стартового после перезапуска или планового ежечасного, даже если строить нечего. `GENERATION_RETENTION_COUNT=1` оставляет только обслуживаемое поколение; поколение, которое ещё удерживает читатель, не удаляется до освобождения.
* `embedding-journal/<lane>.sqlite3` — журнал документных эмбеддингов (раздел выше): по одной записи на текущий фрагмент каждой дорожки с векторами, `4 байта × размерность`. Он не временный буфер и после `INDEXING COMPLETE` не сокращается: его назначение — при следующей полной пересборке (смена версии раскладки индекса в новом образе, `reindex(force=true)`, прерванная дорожка) подставить уже посчитанные векторы вместо повторных обращений к embedding-модели. Удалять его можно только при остановленном контейнере (или между сборками, когда в `get_indexing_status` нет активного поколения); ничего в индексе от этого не меняется, а цена — следующая полная пересборка посчитает эмбеддинги заново. Чтобы журнал не рос снова, задайте `EMBEDDING_JOURNAL=false`.

Ориентир для планирования на 100 000 фрагментов при 4096-мерных эмбеддингах: поколение в профиле `fast_index` (fp16) — 2–2,7 ГБ (измерено на корпусах 350 тыс. и 1 млн фрагментов), журнал — 1,7 ГБ (`4 байта × 4096 × 100 000` плюс служебные данные SQLite; в образах до 18.09.2026 — 3,4 ГБ). При `GENERATION_RETENTION_COUNT=2` и включённом журнале: около 7 ГБ на 100 000 фрагментов; при `GENERATION_RETENTION_COUNT=1` без журнала — 2,7 ГБ, но во время пересборки в любом случае нужно место под два поколения. Размерность вектора входит линейно: при 1024 измерениях делите цифры на четыре.

## Восстановление FTS после обновления кодека

В прежней portable amd64-сборке zvec поддержка AVX2 была отключена при компиляции, но диспетчер FTS всё равно мог выбрать AVX2-заглушки на современном процессоре. Это вызывало SIGSEGV, дубликаты и пропуск совпадений. Простая замена библиотеки не восстанавливает уже повреждённые полнотекстовые блоки.

Сборка с исправлением проверяет ревизию FTS-поля. Если её нет, обычный инкрементальный проход создаёт новую генерацию и пересоздаёт FTS из сохранённых текстов. Неизменившиеся файлы не отправляются на повторный расчёт embeddings. До успешной публикации остаются доступны векторный поиск и поиск подстроки; полнота полнотекстового поиска восстанавливается после переключения поколения. В диагностике коллекции состояние обозначается `fts_repair_required`.

Оставьте `RESET_DATABASE=false` и `INCREMENTAL_INDEXING=true`. Для этой ошибки удалять том или принудительно пересчитывать всю конфигурацию не требуется. Ремонт использует место для копии поколения и сохраняет число документов. При сбое кандидат не публикуется; опубликованное поколение не изменяется. Отдельные повреждения, уже отмеченные как `rebuild_required` или `quarantined`, этот ремонт кодека не устраняет — для них сохраняется штатное восстановление.

Коллекцию `rebuild_required` (например, после того как процесс убили посреди слияния) восстанавливает следующий обычный прогон — стартовый, плановый или `reindex()` без `force`, даже если выгрузка не менялась. Он копирует все документы, которые хранит коллекция, дословно — векторы и поля — в новый каталог, сливает его и публикует вместе с поколением. Исходники не разбираются, эмбеддинги не запрашиваются; по времени это одно полное слияние дорожки, по месту — ещё одна копия её каталога. Копия, число документов в которой не совпало с исходной коллекцией, не публикуется. Пока восстановление идёт или если оно не удалось, поиск отвечает из опубликованного поколения, а запись в дорожку отклоняется; неудачная попытка не повторяется на каждом опросе неизменной выгрузки. В журнале восстановление начинается строкой `copying N stored document(s)`, успех — `rebuilt from N stored document(s)`, неудача — `could not be rebuilt from its stored documents`.

Если коллекция осталась `rebuild_required` и после такого прогона, а также для `quarantined` используйте `reindex(force=true)`. При неизменных модели, проекте и отпечатках здоровых коллекций сервер перестраивает только повреждённые, сохраняя остальные. Изменение модели или проекта по-прежнему требует полной перестройки.

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

```json
{
  "mcpServers": {
    "1c-code-metadata-mcp": {
      "url": "http://localhost:8000/mcp",
      "connection_id": "1c_metadata_service_001"
    }
  }
}
```

## Доработка

Сервер поддерживает [систему плагинов](https://docs.onerpa.ru/mcp-servery-1c/sistema-pluginov.md). В отличие от остальных серверов справочник лежит не в корне образа, а в `/app/src/plugin_api.py` — команда `docker run --rm comol/1c_code_metadata_mcp:latest ls /app/plugin_api.py` даст ложное «нет плагинов». Проверять нужно так:

```powershell
docker run --rm comol/1c_code_metadata_mcp:latest ls /app/src/plugin_api.py /app/plugins
```

Без плагинов поведение сервера настраивается форматом источника (`METADATA_SOURCE`, `SOURCE_FORMAT`, `CODE_PATH`, вложенные конфигурации) и параметрами поиска: `BM25_ALPHA`, `MIN_SCORE_THRESHOLD`, `ENABLE_RERANKER`, `VECTOR_PROFILE` и множителями выборки.
