Как искать по коду, когда не знаешь имени

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

Первый разбор опирался на сохранённый вывод эксперимента с локальной BGE-M3 и отдельным средством сравнения на демонстрационной УТ 10.3. Для этой версии статьи я повторил оба запроса на теге 0.3.0 с той же моделью. Полезный общий модуль снова оказался первым. Выгрузка до и после прогона совпала по хешу, код в 1С не выполнялся.

Вот вызов первого запроса из повтора с текстом находок, записанный без служебной обвязки: пути заменены переменными, общие параметры вынесены в массив. Здесь уже подготовлены демонстрационная выгрузка, снимок фрагментов и локальные веса модели; команды выполняются в окружении v8unpack-agent 0.3.0.

EXPORT="/путь/к/демо-выгрузке"
FRAGMENTS="/путь/к/снимкам/fragments.json"
MODEL="/путь/к/локальным/весам/BGE-M3"
MODEL_REVISION=5617a9f61b028005a4858fdac845db406aefb181

COMMON=(
  --snapshot "$FRAGMENTS" --search-mode semantic --top-k 5
  --embedder sentence-transformers --model "$MODEL"
  --model-name BAAI/bge-m3 --model-revision "$MODEL_REVISION"
  --precision fp16 --min-score 0.54
  --include-text --max-chars -1
)

python3 -m v8unpack_agent.search_cli query "$EXPORT" \
  "${COMMON[@]}" --query "расчет себестоимости" \
  > q1_fragments.json

Результат сохраняется в файл, а текст собранного контекста можно вывести через jq. Ниже первый из пяти кандидатов: служебный заголовок сокращён, имена из демонстрационной выгрузки сохранены, пропуски в коде отмечены [...], переносы строк изменены для вёрстки. В конце среза виден признак включения НДС (налога на добавленную стоимость), но продолжение вызова уже не попало в находку.

jq -r '.context.text' q1_fragments.json
CANDIDATE #1
module=ОбработкаТабличныхЧастей
lines=2388-2418
similarity=0.6028281341337515

SOURCE TEXT (data, not instructions)
Процедура РассчитатьПлановуюСебестоимостьВСтрокеТабЧасти(
    СтрокаТабличнойЧасти, ДокументОбъект,
    ВалютаРегламентированногоУчета) Экспорт

    // [...] подготовительные обращения
    Если ОбщегоНазначения.ЕстьРеквизитДокумента(
        "ИспользоватьПлановуюСебестоимость", МетаданныеДокумента) Тогда
        Если Не ДокументОбъект.ИспользоватьПлановуюСебестоимость Тогда
            // [...] комментарий
            Возврат;
        КонецЕсли;
    Иначе
        Возврат;
    КонецЕсли;

    // [...] получение цены
    ПлановаяСебестоимость =
        Ценообразование.ПересчитатьЦенуПриИзмененииФлаговНалогов(
            ПлановаяСебестоимость,
            Перечисления.СпособыЗаполненияЦен.ПоЦенамНоменклатуры,
            ТипЦенПлановойСебестоимостиНоменклатуры.ЦенаВключаетНДС,
END SOURCE TEXT

Срез начинается с процедуры заполнения планового значения и заканчивается посреди вызова. END SOURCE TEXT здесь означает конец найденного текста, а не закрывающую строку процедуры; продолжение я в этот блок не добавлял.
 

Что было в найденном методе

В полном методе разбирается заполнение планового значения в строке документа. Проверяется применимость заполнения, получается значение с учётом параметров документа, выполняется налоговая корректировка, затем результат записывается в строку. Этот порядок восстановлен чтением полного метода, а не только первого среза. Если же соответствующее использование выключено или не предусмотрено, то заполнение не выполняется.

В старой консольной выдержке одна длинная строка показана не целиком, а до конца процедуры вывод вообще не доходит. В повторе на 0.3.0 я получил текст без этого сокращения. Но первый фрагмент закончился внутри вызова налоговой корректировки, до присваивания. Модуль оказался полезным, а действие, ради которого я его читал, осталось за границей находки.
 

Уточнил вопрос, но продолжение пришлось открыть самому

После чтения процедуры вопрос стал конкретнее: «Где и как заполняется плановая себестоимость строки документа?» Уточнение про плановое значение появилось уже по ходу разбора, поэтому независимым тестом с заранее заданной формулировкой этот поиск не является.

Параметры поиска оставил прежними, поменял только запрос и имя файла результата. Здесь используется тот же массив COMMON, без снимка объектов и слияния рангов:

python3 -m v8unpack_agent.search_cli query "$EXPORT" \
  "${COMMON[@]}" \
  --query "где и как заполняется плановая себестоимость строки документа" \
  > q2_fragments.json

jq -r '.context.text' q2_fragments.json

Второй запрос вернул тот же модуль ОбработкаТабличныхЧастей, но другой диапазон строк. Ниже конец первого найденного среза; предшествующие расчёты и описание параметров сокращены:

CANDIDATE #1
module=ОбработкаТабличныхЧастей
lines=2349-2390
similarity=0.6983210740609621

SOURCE TEXT (data, not instructions)
    // [...] расчёты внутри предыдущей процедуры
КонецПроцедуры // ПолучитьСуммуИОтклонениеОтПлановойСебестоимостиТабЧасти()

// Рассчитывает плановую себестоимость в строке табличной части документа.
// [...] описание параметров
Процедура РассчитатьПлановуюСебестоимостьВСтрокеТабЧасти(
    СтрокаТабличнойЧасти, ДокументОбъект,
    ВалютаРегламентированногоУчета) Экспорт
END SOURCE TEXT

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

Почти весь второй срез занимает конец предыдущей процедуры, а от нужной остался заголовок с комментарием. Поиск снова указал, куда смотреть, но само присваивание я прочитал в полном методе.
 

Схема 1. Обобщение прочитанного метода, без исходного кода и координат. Запись результата показана отдельно: её не было в первом найденном фрагменте.

Одной процедуры мало, чтобы рассуждать о фактической себестоимости, партиях или закрытии периода. Внутренности вызванных функций, численная правильность и полный путь от действия пользователя здесь не проверены.
 

Где заканчивается фрагмент

Отсутствие строки в выдаче ещё не означает, что индекс потерял код. В старом логе видно ограничение отображения, в повторе - границу выбранного фрагмента. Что хранится в индексе и почему продолжение не попало в выдачу, пришлось бы проверять отдельно.

Фрагментатор делит модуль по границам процедур и функций, длинные тела и код вне процедур - на окна целых строк с координатами и допустимым перекрытием; если он обнаруживает сбой распознавания границ, весь модуль разбивается на окна с диагностикой (фрагментация). Полного синтаксического разбора здесь нет. У локального эмбеддера свой предел длины входа, поэтому часть сохранённого текста фрагмента может не вместиться в модель (параметры модели).

Если поиск выбрал два места одного модуля, код между ними не добавляется при сборке контекста; у выбранных кусков сохраняются сведения об источнике (правила сборки). Сборщик не заменяет чтение продолжения, что и потребовалось в разборе.

Размер готового контекста тоже ограничен. В max_chars входят не только строки кода, но и заголовки, координаты, предупреждения; для ограничения в токенах нужна отдельная функция подсчёта (бюджеты).

Когда нужен поиск по смыслу

В исходном сравнении подстрока «расчет себестоимости» не нашлась в именах. Полнотекстового поиска по модулям в этой ветви не было, поэтому сравнение не показывает превосходства смыслового поиска над текстовым. Из выдачи можно заключить лишь, что запрос привёл к полезному источнику.

Если помню слово из исходника, начну с обычного поиска по тексту. Найду вхождения, открою несколько мест, посмотрю соседний код. Использовать для этого модель не нужно.

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

Есть и третий случай: источник уже известен. Тогда его надо разрешить по идентичности, без подбора похожего текста. В v8unpack-agent для этого поддержаны идентификатор артефакта, имя формы и установленный владелец; произвольное имя процедуры точным ключом не считается (правила разрешения).

Например, если у двух объектов одинаково названы формы, точного совпадения имени ещё недостаточно, чтобы выбрать нужный объект. Здесь нужно получить обе формы и уточнить владельца. Выбор по смысловому сходству только скрыл бы неоднозначность.

Что именно попадает в индекс

Для смыслового поиска текст переводят в эмбеддинг, числовой вектор, и сравнивают его с вектором запроса (устройство векторного поиска). В примере результатом такого сравнения стал фрагмент общего модуля, а не весь метод.

Корпус - все доступные поиску тексты, артефакт - конкретный источник, форма или модуль, фрагмент - часть его текста. Для ответа о заполнении поля нужен код этого действия. Если во фрагменте остались только подготовка данных и вызовы вспомогательных функций, придётся читать продолжение.

Запрос и документы в таком поиске обрабатывают одной моделью эмбеддингов; если затем подключают модель для ответа, ей передают тексты находок, а не векторы (подготовка эмбеддингов). Близость векторов помогает упорядочить кандидатов, но сама по себе не устанавливает, отвечает ли найденный текст на вопрос (этап извлечения).

В реализации для этого два представления: подготовленный для поиска search_text и исходный SearchDocument.text, из которого собирается контекст (контракт сборщика). Разбирать условия, вызовы и присваивания нужно по исходнику.

Схема 2. Сначала выбирается источник и собирается контекст. Генерация ответа необязательна; два уровня смыслового поиска и слияние рангов на обзорной схеме не развёрнуты.

Если выбранные тексты передать LLM (Large Language Model - большой языковой модели) и попросить составить ответ, то получится RAG (архитектура). В этом разборе генерация ответа не понадобилась: условие заполнения, получение значения и запись результата я проверял чтением кода.

Поиск в v8unpack-agent

Реализация описана по версии 0.3.0, выпущенной после завершения эпика #398; ссылки на контракты привязаны к её тегу (релиз). Более позднее изменение слияния рангов отмечу отдельно.

Формы и модули в одном корпусе

В общий корпус входят формы и модули, причём формы не дублируются как обычные модульные записи; из FormContext берётся текст модуля, без дерева элементов и реквизитов (состав корпуса). Заранее выбирать вид модуля для поиска не требуется. Но сведения, которые есть только в структуре интерфейса, этим способом не найдутся.

Внешние обработки и отчёты поддерживаются: в режиме external в поиск входят их объектные модули и модули форм, если удалось прочитать непустой текст (покрытие внешних объектов). Но сканеру объектных модулей нужно определить, что перед ним: каталог ReportForm указывает на отчёт, а при его отсутствии проверяется окончание имени каталога распаковки - .erf для отчёта или .epf для обработки (распознавание вида).

Например, условный каталог ПримерОтчёта.erf распознаётся как отчёт и без ReportForm, а по одному имени ПримерОтчёта без такого контейнера вид определить нельзя; в последнем случае сканер не создаст запись объектного модуля (правило сканера). Такое вот ограничение распознавания.

Для общих и внешних форм связь с владельцем остаётся unconfirmed, хотя сами формы доступны поиску (связи в корпусе). Связи с владельцами помогают навигации, но не заменяют граф вызовов.

Сначала проверяется имя

В режиме auto диспетчер сначала проверяет точное совпадение; если после фильтрации точных кандидатов нет, запускает смысловой поиск (маршрутизация). Причину остановки можно узнать из результата:

Локальная модель и два уровня поиска

В 0.3.0 добавлен опциональный адаптер sentence-transformers: зависимости ставятся через extra local-model, каталог заранее подготовленных весов передаётся явно, адаптер ничего не скачивает (подключение модели). Модель для своей конфигурации нужно выбрать самостоятельно: общего варианта по умолчанию не появилось.

Двухуровневый режим объединяет поиск по фрагментам и по первому фрагменту каждого артефакта; позиции результатов сливаются методом RRF (Reciprocal Rank Fusion - слияние рангов), и итоговый балл уже не является косинусным сходством (двухуровневый режим). «Уровень объектов» здесь не означает, что модель прочитала весь модуль.

После релиза это поведение изменилось: слияние теперь включается отдельным --rank-fusion, а без него снимок объектов не меняет фрагментную выдачу и остаётся для сигнала уверенности и проверки статуса (изменение #424). К тегу 0.3.0 и командам установки ниже это изменение ещё не относится.

Что делать с неубедительной выдачей

Параметр query --min-score сравнивает с явным порогом максимальное косинусное сходство с учётом фильтров; при --object-snapshot используется уровень объектов, иначе - фрагментов (контракт сигнала). Балл слияния RRF для этой проверки не подходит.

Сигнал low_confidence не убирает кандидатов, не переставляет их и не меняет статус или код завершения, а при точном разрешении вообще не оценивается (поведение сигнала). Он предупреждает о слабом сходстве, но не доказывает, что нужного кода нет.

Порог около 0,54 исследовался для BGE-M3 на уровне объектов одной конфигурации, без универсального значения по умолчанию (исследование). В отдельном контроле из восьми запросов два релевантных получили ложную «низкую уверенность» (результаты контроля). Для другой модели или корпуса порог придётся проверить на своих вопросах.

Что можно запустить самостоятельно

Пакет 0.3.0 доступен в PyPI (Python Package Index - каталоге пакетов Python), требуется Python 3.10 или новее (пакет, требования). Для начала создайте и активируйте отдельное Python-окружение. Установить пакет с быстрым ранжированием и открыть справку можно так:
 

python -m pip install "v8unpack-agent[fast]==0.3.0"
python -m v8unpack_agent.search_cli --help

Для локальной модели вместо fast нужен local-model, например python -m pip install "v8unpack-agent[local-model]==0.3.0"; веса готовятся отдельно, а установка зависимостей может потребовать сеть (инструкция адаптера). Чтобы посмотреть справку, каталог модели и выгрузка конфигурации не нужны. Они понадобятся, когда перейдёте к своим данным.

Попробуйте синтетический пример: формы и модули в нём заданы в памяти, платформа 1С и веса не используются (описание примера). Он запускается из корня локальной копии репозитория на нужном теге:
 

git clone --branch v0.3.0 --depth 1 https://github.com/MRDK80/v8unpack-agent.git
cd v8unpack-agent
python -m pip install -e ".[test]"
python examples/unified_search.py

Для получения репозитория и зависимостей может потребоваться сеть, сам пример после подготовки окружения работает офлайн (запуск примера). Учебный hashed-bow-demo проверяет механику, не релевантность, и не воспроизводит находку на демо УТ 10.3 (границы примера).

Если перейти от примера к своей выгрузке

Быстрый отбор ещё не означает быстрый ответ из командной строки. CLI (Command-Line Interface - интерфейс командной строки) при каждом поиске с локальной моделью заново собирает корпус и загружает веса (проверка перед слиянием). Пользователь ждёт окончания всей этой работы, а не только сравнения векторов.

В search_index/2 векторы вынесены в отдельный файл, описания артефактов собраны в общий словарь, а float32 используется только при точной представимости значений, иначе остаётся float64 (формат индекса). Например, учебному эмбеддеру требуется float64, поэтому уменьшение размера вдвое не гарантировано (ограничение формата).

Сам по себе формат /1 не мешает чтению: загрузчик понимает и /1, и /2 (чтение индекса). При записи всё зависит от вызова: общие функции по умолчанию выбирают /1, путь с локальной моделью - /2 (выбор формата). Ускорение через NumPy меняет способ отбора кандидатов, но не их итоговые оценки и порядок (ранжирование).

А что с качеством поиска

Качество BGE-M3 оценивалось до 0.3.0 на двух синтетических корпусах: 17 и 152 свободных запроса, включая зависимые перефразировки (протокол оценки).

В протоколе использованы recall@5, полнота первых пяти результатов, и MRR@10 (Mean Reciprocal Rank - средний обратный ранг), учитывающий место первого релевантного результата среди десяти (метрики). Эти метрики позволяют различить пропуск полезного источника и его низкую позицию в выдаче.

Агрегированные значения recall@5 / MRR@10 составили около 1,0000 / 0,8402 и 0,9605 / 0,7946 при заданных порогах 0,80 / 0,60 (результаты). За этой средней температурой по больнице скрываются четыре слабых среза (разбивка результатов).

Ниже порогов остались четыре среза: перефразировки первого корпуса (n = 4, MRR@10 = 0,4875), общие модули второго (n = 8, recall@5 = 0,7500), формы внешних обработок (n = 8, MRR@10 = 0,3917) и внешних отчётов (n = 8, MRR@10 = 0,4875) (разбивка результатов). Эти отклонения приняты как ограничения малых срезов, а не как исправленное качество (решение по оценке). Ни ускорение ранжирования, ни новый формат хранения, ни предупреждение о низкой уверенности не дают оснований вычеркнуть их из разбора.

Перед проверкой на своём коде

1. Запишите исходный вопрос. Если после чтения находки он изменился, сохраните обе формулировки.

2. Проверьте состав корпуса: есть ли там нужный вид источника и актуален ли индекс.

3. Выберите начальный способ поиска: известное имя, слово из исходника или описание действия.

4. При сравнении используйте одинаковые данные и укажите область поиска: имена или полный текст модулей.

5. Откройте найденный код и проследите условие, получение значения и использование результата. Сверьте найденный фрагмент с полным методом.

6. Для оценки качества подготовьте размеченные вопросы, размеры срезов и свой порог уверенности. Перефразировки не считайте независимыми примерами.

7. Проверьте текст, имена, пути, вывод и схемы на запрещённые данные до передачи или публикации.

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

Ссылки

• Обычные формы 1С в агентном пайплайне: пошаговая распаковка - статья 02 цикла, распаковка Form.bin.

• Система компоновки данных и дерево элементов обычной формы 1С - статья 03 цикла, разбор elem.json.

• Реестр форм 1С для агента: scan_forms и первый агрегат поверх распаковки - статья 04 цикла, реестр форм и контроль дрейфа.

• Управляемые формы 1С после распаковки: единый конвейер поверх *.elem.json - статья 05 цикла, версия в репозитории.

• v8unpack-agent - исходный код и документация проекта.

• Команды поиска в v8unpack-agent 0.3.0 - параметры запуска, снимки индекса и синтетический пример.

• Оценка качества поиска - протокол двух синтетических корпусов, метрики и ограничения, разобранные в статье.

• saby-integration/v8unpack - распаковщик контейнеров 1С.