Ретроспектива 22 июня 2026 года

Сегодня я создал процесс, при котором вместо прямой загрузки официальной документации Godot в RAG, сначала преобразую её в структурированный JSONL и проверяю результат. Сначала было непонятно, как разбивать Markdown‑файлы, но после создания UI для преобразования и визуального просмотра результатов по каждому файлу всё стало гораздо проще.

Markdown → JSONL конвертер

При загрузке Markdown‑файла официальной документации Godot через Qwen API происходит классификация целевых таблиц, после чего результаты делятся на JSONL‑файлы для docs_chunks, api_mapping и label_prototypes.

Сначала я думал просто читать Markdown и сразу помещать его в базу данных, но тогда было трудно отследить, какой документ попадает в какую таблицу. Поэтому я изменил процесс: сначала создаю промежуточный JSONL, а затем проверяю различия между результатом преобразования и оригиналом прямо на экране.

Эта методика хороша по следующим причинам.

• Можно сравнивать оригинальный Markdown с преобразованным JSONL и сразу видеть различия.
• Можно проверить, в какой из разделов — docs_chunks, api_mapping, label_prototypes — попадает каждый документ.
• Можно отсеять ошибочно классифицированные документы или пустые результаты до их загрузки в БД.
• При изменении правил преобразования можно заново сгенерировать JSONL и снова выполнить сравнение.

Проверка результатов преобразования

Преобразователь отображает количество сохранённых файлов JSONL и количество ошибок на экране. На проверяемом сегодня экране результаты сначала накопились в docs_chunks, а api_mapping, label_prototypes и файлы ошибок ещё оставались пустыми.

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

Предпросмотр JSONL и проверка в виде таблицы

JSONL результат можно просматривать на экране как в виде JSON, так и в виде таблицы. Например, запись docs_chunks имеет такие поля, как chunk_id, doc_version, source_url, source_file, source_sha256, doc_type, section_path, heading, content, code_blocks, api_symbols, token_count, metadata.

В таком виде гораздо лучше, чем просто держать файл Markdown. Особенно удобно, когда одновременно видны chunk_id и source_sha256, что упрощает последующее отслеживание, из какого оригинала появился тот или иной чанк. В RAG самое важное — не потерять источник доказательства, и промежуточный вывод JSONL может выполнять эту роль.

Журнал преобразования

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

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

Локальная настройка PostgreSQL

После создания JSONL мы также подготовили базу данных, чтобы загрузить его в локальный PostgreSQL. Запустили контейнер на основе pgvector/pgvector:pg16 и создали таблицы docs_chunks, api_mapping, label_prototypes, ingest_reports.

Сегодня особенно важно было убедиться, что схема БД не противоречит именам полей JSONL. Если БД произвольно добавит поля, контракт JSONL будет размытым, и позже преобразователь и загрузчик могут работать по разным критериям. Поэтому колонку payload в БД привели к схеме JSONL, а служебные колонки БД ограничили только id, embedding, search_tsv, created_at.

Мы запустили локальную БД, проверили вставку и поиск образца JSONL с помощью теста отката. Пока не загрузили все документы в БД, но путь от JSONL к PostgreSQL стал гораздо яснее.

Сегодняшнее решение

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

Раньше было неясно, как работать с официальной документацией в формате Markdown, и переход сразу к чанкингу или загрузке в БД мог привести к потере структуры. Сегодня мы добавили этап преобразования/валидации JSONL, создав промежуточный артефакт, который человек может проверить.

В итоге, дальнейший процесс, кажется, следует развивать именно в этом направлении.

Godot официальная документация Markdown
-> Преобразование JSONL
-> Предпросмотр/проверка JSONL
-> Внедрение PostgreSQL
-> Проверка поиска Retriever
-> Сводка ответов Validator/Qwen

После завтрашнего дня необходимо проверить, какой процент составляют docs_chunks, api_mapping, label_prototypes, когда будет полностью преобразовано все 1 570 документов. Особенно api_mapping и label_prototypes не должны создаваться Qwen произвольно, поэтому результаты автоматической генерации нельзя принимать без проверки — нужно добавить отдельный этап утверждения/валидации.

Измерение скорости обработки

Дополнительно подсчитав скорость преобразования, выяснилось, что преобразование всех 1 570 Markdown‑файлов в JSONL займет примерно 42 часа.

Фактическое время обработки до настоящего момента составило около 1 часа 9 минут. За это время было обработано 43 файла (39 done и 4 deferred). Средняя скорость — примерно 1,6 минуты на один файл.

Фактическое время обработки: около 1 часа 9 минут  
Обработано файлов: выполнено 39 шт. + отложено 4 шт. = 43 шт.
Средняя скорость: примерно 1,6 минуты на файл
Общая предполагаемая длительность преобразования 1 570 элементов, ожидаемое время: около 42 часов

Сначала казалось, что обрабатывается примерно один элемент в минуту, но при расчёте по реальным журналам это занимает немного больше времени. Завершить полную конверсию всех 1 500 элементов в течение дня может быть сложно, поэтому необходимо продолжать фиксировать скорость обработки и количество неудачных/отложенных файлов.

План дальнейшей проверки

Завтра и послезавтра, скорее всего, не будет времени, поэтому сразу продолжить работу не получится. Тем не менее, задачи, которые нужно будет выполнить позже, уже отчасти упорядочены.

Сначала нужно загрузить уже созданные JSONL‑файлы, полученные во время сбора и конвертации, в локальную PostgreSQL. До сих пор разработанный конвертер был ориентирован на разбиение Markdown на JSONL для docs_chunks, api_mapping и label_prototypes, а следующий шаг — поместить эти JSONL в реальную базу данных и проверить, доступны ли они для поиска.

Затем планируется небольшая проверка рабочего процесса, описанного в docs/roadmaps/2026-06-21-initial-rag-classifier-architecture.md, с помощью Python‑скрипта.

source code
-> AST Parser
-> Retriever
-> evidence JSONL / evidence bundle
-> Qwen 3.6 вызов API
-> проверка ответа

Иными словами, взять произвольный код Godot, поместить его в Python‑скрипт и проверить, извлекает ли AST‑парсер символы и сигналы версии. Затем результат передать Retriever, чтобы из PostgreSQL получить соответствующие фрагменты официальной документации или сопоставления API, и при передаче полученного пакета JSONL/evidence в API Qwen 3.6 проверять, какой ответ будет возвращён, периодически проверяя процесс.

Этот процесс не является полной автоматизацией, а скорее небольшим сквозным тестом, подтверждающим, что каждый этап действительно работает последовательно. Особенно важно убедиться, отвечает ли Qwen, опираясь на свою память, или же формирует ответ на основе доказательств, предоставленных Retriever‑ом.

Мысли о публичном репозитории и переходе в приватный

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

Сейчас я считаю, что мои навыки ещё далеки от идеала. Тем не менее, у меня возникла идея создать специализированную модель для Godot, загрузить её на Hugging Face и использовать её как отправную точку для видеолекций, университетских курсов, портфолио, репутации и прочих областей. Это может выглядеть как слишком мечтательная фантазия. Однако если кто‑то сможет воспользоваться моими заметками и записями о работе в качестве трамплина для собственного роста, возможно, и я смогу быстрее развиваться в этом процессе.

Фактически, у меня всё ещё есть желание не публиковать это. Я боюсь, что то, что я создал, может показаться поверхностным, и, с другой стороны, я опасался, что часть, где я собрал различные знания, пусть и поверхностно, чтобы сделать их более понятными, может быть полностью разоблачена кем‑то. Не столько из‑за того, что результат представляет собой огромную технологию, сколько из‑за того, что меня беспокоит, что все следы моих размышлений и связей полностью проявятся.

Я настроил PR и CI/CD конвейер, но изначально планировалось, что при появлении PR в GitHub workflow локальная LLM‑точка доступа, размещённая в Oracle Cloud, будет автоматически выполнять ревью PR. Поскольку в Oracle Cloud доступна среда с 24 ГБ VRAM, я думал, что можно будет запускать почти любые локальные модели, и поэтому рассматривал возможность привязать хостинг‑LLM к автоматизации ревью кода. Однако я потерял учётную запись Oracle Cloud, и поэтому пока невозможно реализовать этот поток. У RunPod тоже есть неудобства для проверки PR: каждый раз при работе нужно заново настраивать окружение. Поэтому пока я сосредоточусь на ручных действиях и документировании, а автоматизацию PR‑ревью на основе LLM отложу на более поздний срок.

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