Глобальные переменные и справочники

Глобальные переменные и справочники — два хранилища данных, из которых платформа берёт значения для сценариев (workflow), промптов и документов вместо того, чтобы вписывать одно и то же в каждый шаблон. Глобальная переменная хранит одно значение на рабочее пространство: наименование организации, ФИО подписанта, город, ИНН. Справочник хранит целый версионируемый набор данных уровня инстанса: нормативные таблицы, коэффициенты, закрытые перечни. Оба реестра администратор ведёт в разделе Администрирование → LLM и сценарии, обе возможности доступны с версии 1.409.

Что вам понадобится

• права администратора инстанса — общую схему переменных и справочники правят только из раздела Администрирование;
• право global_variables:write в рабочем пространстве — чтобы заполнять значения переменных;
• право global_variables:define — чтобы заводить переменные уровня пространства;
• второй администратор — версию справочника утверждает не тот, кто её загрузил;
• база знаний с документами-источниками, если справочник должен отслеживать изменения первоисточника.

Как завести глобальную переменную

Откройте Администрирование → LLM и сценарии → Глобальные переменные (/settings/administration/llm/global-variables) и нажмите Добавить. На этой странице вы задаёте только схему — общую для всех рабочих пространств: какие переменные существуют, как называются и какого они типа. Сами значения администратор здесь не вводит: их заполняют в каждом пространстве отдельно.

Ключ платформа собирает сама: транслитом из группы и названия, при совпадении добавляет суффикс — Суд + Город суда даёт sud.gorod_suda. Именно ключ подставляется в промпты и шаблоны.

Важно. Ключ переменной неизменяем: чтобы поменять его, заведите новую переменную и перенесите ссылки.

Тип значения меняется, только пока переменную не заполнило ни одно пространство. Иначе платформа отвечает Смена типа заблокирована: значения заданы в N пространств(е/ах). Переменную с заполненными значениями платформа удаляет только после отдельного подтверждения — вопроса «Удалить вместе со значениями?».

Важно. ⚠️ Кнопка Удалить всё удаляет переменную вместе с её значениями во всех пространствах безвозвратно.

Когда включать флаг «Секретная»

Включайте флаг для паролей, ключей доступа и других данных, которые не должны попадать в текст запроса к языковой модели (LLM). Платформа маскирует секретное значение в списке пространства, не показывает его в каталоге переменных при вставке в промпт и не подставляет при выполнении.

Причина — текст промпта платформа не маскирует: секрет ушёл бы в запрос к модели и в журнал прогона целиком. Для подстановки в документы и промпты заводите обычные переменные.

Как заполнить значения по рабочим пространствам

Значение вы задаёте отдельно в каждом пространстве: откройте Настройки пространства → Глобальные переменные (/settings/workspace/variables) и введите значение в колонке Значение пространства. Одна и та же переменная общей схемы получает своё значение в каждом пространстве — один шаблон документа работает во всех пространствах без копий.

Пока хотя бы одна обязательная переменная пуста, страница показывает предупреждение «Пространство требует настройки»; кнопка Показать и переключатель Только незаполненные оставляют в списке одни пробелы. Кнопка Подставить вставляет предложенное значение в поле, но не сохраняет — без сохранения значение не используется.

Колонка Источник отличает переменные общей схемы от собственных переменных пространства. Собственную переменную заводят кнопкой Новая переменная — она видна только в этом пространстве и требует права global_variables:define. Переменную общей схемы из пространства изменить нельзя: меню строки предлагает лишь Очистить значение.

Полную картину пробелов администратор видит в админском реестре: блок «Обязательные переменные без значений» показывает по каждой переменной, в скольких пространствах значение отсутствует.

Где платформа подставляет переменные

Платформа подставляет переменную по токену {{globals.<ключ>}} — например {{globals.sud.gorod_suda}}. Значение платформа берёт из активного рабочего пространства в момент выполнения, поэтому правка значения не требует переиздания сценариев и действий.

Токены с другим корнем платформа не трогает: фигурные скобки в примерах формата ответа остаются обычным текстом. В инструкции ассистента подстановка не работает — токен там сохраняется как текст. Предложенное значение из схемы тоже не подставляется: заготовка вместо реальных реквизитов исказила бы документ.

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

Как создать справочник и утвердить версию

Справочник — набор проверенных данных уровня инстанса, который сценарии читают целиком и без модели: таблицы порогов, коэффициенты, перечни. Откройте Администрирование → LLM и сценарии → Справочники (/settings/administration/llm/reference-sets) и нажмите Создать справочник.

1. Заполните Ключ — постоянный идентификатор вида normative.uk-rf.228, по нему узел сценария находит справочник.
2. Укажите Название и Описание — что внутри набора и откуда взяты данные.
3. Задайте ID базы знаний-источника, если данные извлечены из документов базы знаний: идентификатор берётся из адреса страницы базы /knowledge/<идентификатор-базы>.
4. Задайте Порог устаревания, дней или оставьте поле пустым — тогда действует общий порог 7 дней.
5. Нажмите Создать, затем в карточке справочника — Импорт версии (JSON) и вставьте данные набора.

Импорт создаёт черновик, а не рабочую версию. Карточка показывает дифф черновика с активной версией таблицей «Путь · Было (активная) · Станет (черновик)»: изменённые значения перечислены поимённо, совпавшие свёрнуты в счётчик. Второй администратор просматривает дифф, пишет Комментарий к решению и нажимает Утвердить и активировать vN либо Отклонить черновик.

Важно. Автор черновика не утверждает его сам: платформа отклоняет такое решение по правилу четырёх глаз.

Версии неизменяемы: утверждение переводит черновик в статус active, прежнюю версию — в superseded, отклонённый черновик получает статус rejected. Все решения и проверки видны в блоке Аудит.

Как платформа следит за актуальностью

Раз в сутки платформа сверяет хеши документов-источников активной версии с текущими документами базы знаний. Совпали — платформа обновляет отметку актуальности и не вызывает модель. Разошлись — набор получает признак источник изменился, и куратор готовит новую версию.

Кнопка Проверить источники в карточке запускает ту же сверку немедленно. Набор без базы знаний-источника помечен как внешний импорт и сверке не подлежит.

Порог устаревания вы задаёте у каждого справочника отдельно, общий по умолчанию — 7 дней (UNICA_REFERENCE_SET_STALE_AFTER_DAYS); интервал суточной сверки — 24 часа (UNICA_REFERENCE_SET_REFRESH_INTERVAL_HOURS).

Чем справочник отличается от базы знаний

База знаний отвечает на вопрос по смыслу, справочник — по ключу. Из базы знаний ассистент достаёт фрагменты текста, похожие на запрос, и модель формулирует по ним ответ. Из справочника сценарий получает точное значение по имени таблицы и строки — без поиска, без модели и без разночтений.

Справочник не заменяет базу знаний: первоисточник норм остаётся документом, а справочник хранит выверенную выжимку из него с указанием версии и даты подтверждения.

Как читать справочник из сценария

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

Следующие узлы ссылаются на выходы штатными плашками steps.<узел>.payload и steps.<узел>.meta. Номер версии и хеш попадают в журнал прогона, поэтому по любому отчёту видно, на каких данных он собран.

Утверждение новой версии применяется со следующего прогона: узлы с закреплённой версией продолжают читать прежние данные. Если справочник недоступен или активной версии нет, узел не подставляет старые значения молча: прогон продолжается с признаком degraded, а зависимые проверки уходят на ручной разбор.

Частые вопросы

Почему токен {{globals.…}} остался в тексте

Подстановка работает в промпте действия и в слотах узла «Типизированный шаблон»; в инструкции ассистента и в сообщении чата токен остаётся обычным текстом. Проверьте:

• токен написан в поле Промпт действия, а не в инструкции ассистента;
• корень токена — globals., ключ совпадает с ключом из каталога;
• ключ вставлен кнопкой {} или Ctrl+Space, а не набран вручную.

Почему вместо значения подставилась пустота

Платформа подставляет пустую строку, когда переменная не заполнена в этом пространстве, помечена как секретная или её значение не проходит проверку по типу. Проверьте:

• значение сохранено именно в том пространстве, из которого запускается действие;
• переменная не помечена флагом Секретная;
• подставленное кнопкой Подставить значение сохранено, а не осталось в поле ввода.

Почему сценарий сообщает, что справочник недоступен

Узел не нашёл активную версию по ключу или не получил ответ реестра. Проверьте:

• ключ в поле Ключ справочника совпадает с ключом в реестре посимвольно;
• у справочника есть версия в статусе active, а не только черновик;
• закреплённый в узле номер версии существует.

Что дальше

• Раздел администрирования — остальные разделы администрирования инстанса.
• Роли и права доступа — раздать права на переменные участникам пространства.
• Базы знаний — подготовить документы-источники для справочника.
• Действия ассистентов — вставить глобальную переменную в промпт действия.