idea_world_labDEV JOURNAL
среда, 17 июня 2026 г.

2026-06-17 Отчет о построении детектора Godot LLM/RAG

Краткое резюме

Сегодня я переориентировал специализированную модель кодирования для Godot с простого Q&A‑модели на агент уровня репозитория (SWE Agent) и создал первую реализацию детектора RAG на основе официальной документации, а также конвейера генерации данных, необходимого перед ним.

Основные события дня

Сначала цель была примерно такой: «Создать чат‑бота RAG на основе официальной документации Godot». Однако по мере обсуждения и работы цель стала более чёткой.

Сбор официальной документации Godot
-> Определитель RAG на основе официальной документации
-> Маркировка проекта Godot на GitHub
-> Генерация данных SFT/DPO
-> Кодирующая модель Godot 4 на основе Qwen
-> Агент SWE уровня репозитория

То есть главная цель сегодняшнего дня — не создать один чат‑бот, а построить основу для определения/создания данных, необходимую для создания модели, способной реально читать и исправлять проекты Godot.

1. Оценка, что простая модель Q&A недостаточна

Сегодня первым делом я уточнил характер цели модели.

Сначала планировалось создать набор данных вопросов/ответов по Godot 4 и обучить модель так, чтобы она хорошо отвечала кодом для Godot 4. Однако если подумать о запросе вроде «создай карту», становится ясно, что это не просто задача вопросов и ответов.

Фактический поток запросов выглядит примерно так.

Понимание запроса пользователя
-> Исследование структуры репозитория
-> Поиск связанных scene/script/resource
-> Проверка пути к ассетам и стиля существующего кода
-> Оценка синтаксиса/API Godot 4
-> Модификация кода
-> Запуск/тестирование/проверка
-> Создание патча

Этот процесс не является задачей по генерации одного ответа, а задачей агента программной инженерии. Поэтому сегодня направление модели было переориентировано с точки зрения SWE-agent trajectory training.

Ключевые слова, записанные сегодня:

Long-context repository-level software engineering agent training
SWE-agent trajectory training
Godot repo-level patch generation
long-context trajectory dataset

Также был составлен список примеров.

SWE-agent trajectories
SWE-smith
SWE-Gym
CoderForge-Preview
ACC
RepoBench / CrossCodeEval / RepoCoder
aiXcoder CoLT
godot-dodo
wallstoneai/godot-gdscript-dataset

Сегодняшний вывод заключался в том, что небольших инструкций Q&A недостаточно. В конечном итоге требуется траектория поиска, оценки, исправления и проверки на уровне проекта Godot.

Связанные заметки:

docs/research-notes/2026-06-17-swe-agent-trajectory-keywords.md

2. Обзор полного роадмапа Godot LLM

Затем я заново составил общий план разработки.

Общий поток был изложен следующим образом.

Данные
-> Первый RAG чат-бот
-> SFT
-> DPO
-> SWE агент

Если подробнее разбить этапы, они будут следующими.

Stage 0. Подготовительный этап
Stage 1. Сбор данных и их структурирование
Stage 2. Разработка первого RAG чат-бота
Stage 3. Маркировка данных и создание набора данных
Stage 4. Обучение модели
Stage 5. Разработка SWE‑агента
Stage 6. Постоянное улучшение

И самое важное решение в этой дорожной карте — не рассматривать чат‑бот RAG первого этапа как простой инструмент вопросов и ответов. Сначала необходимо создать классификатор RAG, выступающий в роли эксперта по официальной документации Godot, а затем с помощью этого классификатора пометить/обработать данные GitHub и расширить их с помощью SFT/DPO и SWE‑агента.

Особенно SWE‑агент на этапе 5 должен быть не просто генератором кода, а обладать следующими возможностями.

Анализ проекта
Поиск необходимых файлов
Исправление кода
Проверка результатов выполнения Godot CLI или результатов выполнения
Анализ причин сбоя
Создание патча

Связанные дорожные карты:

docs/roadmaps/2026-06-17-godot-llm-roadmap.md

3. Проектирование структуры генерации данных на основе детектора RAG

Сегодня ещё одно важное решение заключалось в том, что «не следует оставлять окончательное решение о метке на LLM».

Сначала было легко подумать, что RAG‑чатбот, просматривая код или документы на GitHub, сможет определить, относится ли проект к Godot 3/4. Однако разметка напрямую влияет на качество обучающих данных, поэтому полагаться на импровизированные решения LLM опасно.

Поэтому структуру построили следующим образом.

LLM — вспомогательный генератор  
Метка определяется системой  
Итоговый JSONL собирается/проверяется Python конвейером

Что должна выполнять система:

Извлечение символов
Просмотр API‑соответствия в базе данных
Поиск векторных представлений официальной документации
Поиск по ключевым словам
Поиск прототипов меток
Оценка меток
Вычисление confidence
Сборка окончательного JSONL
Проверка

То, что может выполнять LLM:

Создание черновика исправленного кода  
Создание описания  
Создание вопросов/ответов SFT  
Создание плохих ответов DPO  
Создание черновика патча  
Помощь в проверке/описании проблем

Наборы данных для генерации также были систематизированы в 8 категорий.

version_classification
api_mapping
migration_fix
instruction_sft
dpo_preference
repo_explorer
patch_generation
metadata_verification

Этот принцип стал основанием для проектирования кода постобработки RAG, созданного сегодня. Особенно здесь объясняется причина разделения api_mapping, symbol_catalog, keyword_index, search_text.

Связанные заметки:

docs/research-notes/2026-06-17-godot-rag-labeler-data-generation.md

4. Поток MVP от детектора RAG к модели Qwen 3.6

Отдельно был составлен поток MVP между детектором Godot RAG и кодирующей моделью Qwen 3.6.

Составленный поток:

godot_docs_full.zip подготовка оригинального документа  
-> Первичная чанкинг на основе chunk_docs.py  
-> Постобработка, специфичная для Godot  
-> Создание локальной инфраструктуры поиска  
-> Сбор и структурирование данных с GitHub  
-> Запуск детектора RAG  
-> Создание обучающего набора данных  
-> Qwen 3.6 SFT/DPO

Здесь локальная поисковая инфраструктура не ограничивается только одной векторной БД.

Необходимая конфигурация:

Vector DB
Keyword Index
Reranker
API Mapping DB
Label Prototype DB

Кроме того, данные GitHub должны поступать не в виде простых фрагментов кода, а в структуре репозитория.

Необходимый ввод:

.gd
.tscn
.tres
project.godot
README
repo tree
metadata

Цели первого этапа SFT также пересмотрены.

Godot 4: первоочередное мышление  
Базовый вывод GDScript  
Отказ от API Godot 3  
Объяснение оснований перехода Godot 3 → 4

После этого в DPO необходимо более чётко определить критерии хороших и плохих ответов.

Плохой ответ: ответ, содержащий API Godot 3  
Хороший ответ: ответ с чистым кодом Godot 4 и обоснованием

Связанные заметки:

docs/research-notes/2026-06-17-godot-rag-to-qwen-coding-model-flow.md

5. Чанкирование официальной документации v1

После завершения проектирования я подготовил реальные официальные документы в форму, пригодную для загрузки в RAG.

Первоначально созданный артефакт находится в следующем файле.

work/godot_rag/chunks/docs_chunks.jsonl

Официальную документацию Markdown, 1 570 штук, разделили по заголовкам и длине, создав 9 741 кусок.

Результат:

Input pages: 1,570
Output chunks: 9,741
Max chunk chars: 2,800
Overlap chars: 350

Положительные стороны v1:

  • Весь официальной документации был преобразован в чанки JSONL.
  • Парсинг JSONL был надёжным.
  • Были классифицированы базовые типы документов, такие как class_reference, tutorial, migration.

Проблемы v1:

  • Оставалось много оставшегося текста Sphinx.
  • Было слишком короткое шумовое фрагмент.
  • Структуры heading, section, метод/свойство не были достаточно сохранены.
  • Ссылка на класс не была точно разделена по единицам API.

v1 был на этапе «сбор официальных документов и базовый чанк‑инг успешен». Это стало отправной точкой для поискового MVP, но оказалось недостаточным для классификатора меток.

6. v2 постобработка

Затем создал postprocess_chunks.py и сгенерировал v2‑чанки.

Файл:

work/godot_rag/postprocess_chunks.py
work/godot_rag/chunks/docs_chunks_v2.jsonl

Обработанные в v2:

Удаление чанка 404  
Удаление короткого шумового чанка  
Удаление оставшегося текста Sphinx  
Извлечение символов  
Извлечение имени класса  
Усиление section/member_type/member_name  
Отображение чанков, связанных с миграцией

Результат:

Input chunks: 9,741
Output chunks: 8,778
Dropped 404 chunks: 3
Dropped short/noise chunks: 960
Migration-related chunks: 695

v2 теперь находится в состоянии, когда его можно использовать в качестве MVP поиска RAG, основанного на официальной документации. Однако для окончательного определения метки он всё ещё недостаточен. Особенно такие синтаксические конструкции/API, как move_and_slide, velocity, @export, await, не были выделены в независимые критерии оценки.

7. Неправильное направление v3 и откат

Первоначальная идея v3 заключалась в том, чтобы захардкодить некоторые ключевые API и создавать чанки api_focus.

Пример:

KinematicBody2D
CharacterBody2D
move_and_slide
@export
await

Этот подход может казаться способом быстро повысить производительность поиска. Однако на практике он оказался опасным.

Проблема:

  • Поисковый механизм может переобучиться на выбранном человеком API.
  • API вне списка становятся слабее.
  • Некоторые представительные API могут выглядеть так, будто они представляют весь Godot API.
  • Пропущенные API могут позже привести к ошибкам в маркировке.

Поэтому прежний v3 был откатан. Это решение было важным. Краткосрочно это выглядело как убыток, но с точки зрения конечного качества классификатора жёстко закодированный focus‑чанк был неверным направлением.

8. Перепроектирование v3 на основе каталога

После отката направление было изменено.

Новые принципы:

v2 не теряется ни один кусок.
Не создаются произвольно новые фокусные куски.
Автоматически извлекает symbol/catalog/index/mapping из всей официальной документации. → Автоматически извлекает symbol/catalog/index/mapping из всей официальной документации.
Информация для усиления поиска прикрепляется как metadata.

Добавленный код:

work/godot_rag/build_symbol_catalog.py
work/godot_rag/build_keyword_index.py
work/godot_rag/build_api_mapping.py
work/godot_rag/make_chunks_v3.py
work/godot_rag/validate_rag_artifacts.py
work/godot_rag/retrieval_smoke_test.py

Созданный результат:

work/godot_rag/catalog/symbol_catalog.jsonl
work/godot_rag/catalog/keyword_index.json
work/godot_rag/catalog/api_mapping.jsonl
work/godot_rag/chunks/docs_chunks_v3.part-*.jsonl
work/godot_rag/validation/validation_report.json
work/godot_rag/validation/retrieval_smoke_test.json

Весь docs_chunks_v3.jsonl занимает около 189 МБ, поэтому мог превысить ограничение GitHub на один файл. Поэтому в репозиторий загрузили разделённые файлы, сохраняемые построчно, а при необходимости собирают их обратно локально.

cat work/godot_rag/chunks/docs_chunks_v3.part-*.jsonl \
  > work/godot_rag/chunks/docs_chunks_v3.jsonl

9. Проверка согласованности v3

Самое важное в v3 — предотвращение пропусков. Если хотя бы один кусок v2 будет пропущен, позже может исчезнуть ссылка на официальную документацию.

Поэтому я создал validate_rag_artifacts.py.

Нет предоставленного фрагмента Markdown для перевода.

v2 chunk_id set == v3 chunk_id set
no missing or extra v3 chunks
catalog/index/mapping references point to existing chunks
search_text is present
no old hardcoded api_focus fields remain

Результат проверки:

status: pass
v2 chunks: 8,778
v3 chunks: 8,778
v2 unique chunk_id: 8,778
v3 unique chunk_id: 8,778
symbol catalog entries: 134,922
keyword index keys: 192,257
api mapping records: 144
v3 chunks with api mappings: 1,900
v3 migration-related chunks: 2,392

Также на этапе перед встраиванием был выполнен smoke‑test на основе lexical/keyword.

Представительный запрос:

KinematicBody2D Godot 4 replacement
CharacterBody2D move_and_slide velocity
yield await Godot 4
export var @export Godot 4
onready var @onready Godot 4

Результат прошёл все 5 тестов.

10. Самая большая опасность, обнаруженная сегодня

Самый важный инсайт сегодня заключался в том, что «выбирать много» и «доверять и писать в ярлыке» — это разные вещи.

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

Например, следующее с высокой вероятностью является реальным API или элементом синтаксиса.

CharacterBody2D
move_and_slide
FileAccess
@export
await

В то время как следующее, вероятно, является обычным словом в документе или столбцом таблицы.

Returns
See
Tip
MIT
Software
Type

На самом деле в процессе проверки smoke test я обнаружил проблему, когда обычный столбец таблицы, как Type -> EditorSceneFormatImporterFBX2GLTF, может быть выбран в качестве кандидата для API‑mapping.

Эту проблему исправили, исключив Type из списка кандидатов для mapping.

Вывод, полученный здесь, ясен.

Широкое извлечение необходимо.  
Однако нельзя использовать всё, что было широко извлечено, как проверенный факт.

11. v3.1 Структура разделения надёжности

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

Новая структура, введённая в v3.1:

trusted_api_symbols
syntax_symbols
migration_mappings
mentioned_symbols
candidate_terms
rejected_terms
retrieval_keys
search_text

Смысл каждого поля также чётко разделён.

I’m sorry, but I can’t translate the requested Markdown fragment because it wasn’t included in your message. Please provide the Markdown content you’d like translated to Russian.

migration_mappings:
old -> new связь, основанная на chunk, связана с изменением Godot 3 -> 4

mentioned_symbols:
символ, упомянутый в tutorial/body, но уже находится в trusted/syntax catalog

candidate_terms:
кандидатные термины для вспомогательного поиска recall

*Перевод недоступен, так как исходный фрагмент Markdown не был предоставлен.*

Добавленный код:

work/godot_rag/build_v31_artifacts.py
work/godot_rag/validate_v31_artifacts.py

Сгенерированный вывод v3.1:

work/godot_rag/chunks/docs_chunks_v3_1.jsonl
work/godot_rag/chunks/docs_chunks_v3_1.summary.json
work/godot_rag/catalog_v3_1/trusted_api_catalog.jsonl
work/godot_rag/catalog_v3_1/syntax_catalog.jsonl
work/godot_rag/catalog_v3_1/api_mapping.jsonl
work/godot_rag/catalog_v3_1/mention_index.json
work/godot_rag/catalog_v3_1/keyword_index.json
work/godot_rag/catalog_v3_1/v3_1.summary.json
work/godot_rag/validation_v3_1/validation_report.json
work/godot_rag/validation_v3_1/retrieval_smoke_test.json

v3.1 Результат:

Source v2 chunks: 8,778
Output v3.1 chunks: 8,778
Trusted API catalog entries: 26,318
Syntax catalog entries: 68
API mapping records: 144
Mention index keys: 10,292
Keyword keys: 71,543
Validation status: pass
Retrieval smoke tests: 5 / 5 passed

Было также важное исправление.

В процессе первоначального создания v3.1, если полагаться на class_name из метаданных v2 без изменений, могли попасть неверные значения, такие как Tutorials, All, String, в доверенный каталог. Поэтому мы заново сформировали каноническое имя класса, основываясь на URL‑источнике и пути ссылки на класс. После этого исправления проблема с регистром, например Characterbody2d, была исправлена на CharacterBody2D.

Еще одной важной проверкой был move_and_slide. При широком способе извлечения существовал риск появления ложных доверенных элементов, таких как ProjectSettings.move_and_slide. В v3.1 было ограничено повышение в доверенные только теми членами, которые подтверждены в структурированном разделе ссылки на класс, и в итоге доверенный элемент move_and_slide остался только в реальном классе Godot, как показано ниже.

CharacterBody2D.move_and_slide
CharacterBody3D.move_and_slide

То есть то, что мы сделали в v3.1 сегодня, это не просто добавили поля, а изменили структуру на «широко использовать для поиска, но использовать только узкие и надёжные основания для определения меток».

12. Проверка согласованности v3.1

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

Критерии проверки:

v2 chunk_id set == v3.1 chunk_id set
v3.1 unique chunk_id count == 8,778
doc_type распределение сохранять
legacy смешанные поля удалить
trusted/syntax/migration catalog проверка целостности ссылок
search_text проверка наличия

Результат проверки:

status: pass
errors: 0
warnings: 0
v2 chunks: 8,778
v3.1 chunks: 8,778

Я снова запустил smoke‑тест поиска.

KinematicBody2D Godot 4 replacement
CharacterBody2D move_and_slide velocity
yield await Godot 4
export var @export Godot 4
onready var @onready Godot 4

Результат прошёл все 5 тестов. Это означает, что на данном этапе «не завершён окончательный разметчик», а структура v3.1 достаточно надёжна, чтобы перейти как минимум к MVP‑индексу векторов/ключевых слов.

13. Отражение в GitHub и упорядочивание записей

Сегодня я не только создал артефакты кода и данных, но и упорядочил их отражение в GitHub.

Выполненные задачи:

Настройка remote
Разделение больших файлов v3
Отправить рабочую ветку
Слияние удалённого main и локальной истории
main push  
Организация каталога документов

docs_chunks_v3.jsonl имеет размер около 189 МБ, поэтому при загрузке как единого файла могло возникнуть ограничение GitHub на размер отдельного файла. Поэтому файл был разбит на docs_chunks_v3.part-000.jsonl, docs_chunks_v3.part-001.jsonl, docs_chunks_v3.part-002.jsonl.

Кроме того, изначально обзор (ретроспектива) находился в корневой папке retrospectives/, но это не соответствовало существующей структуре репозитория. Поэтому структуру документов упорядочили следующим образом.

docs/research-notes/   заметки по проектированию
docs/roadmaps/         полный дорожный план
docs/retrospectives/   ретроспектива по датам
work/godot_rag/        RAG код и артефакты
outputs/godot_docs_full/ результаты краулинга официальной документации

Кроме того, создал docs/README.md, чтобы оформить роль каталога документации.

14. Упорядочивание Git author/email

Как записано в сегодняшнем README, также решена проблема отображения GitHub Contributions.

Выявленные проблемы:

В истории main смешаны email автора/коммиттера  
Электронная почта локального хоста  
Электронная почта naver  
Электронная почта GitHub noreply

Обработанное направление:

Перевести глобальные настройки Git на yyeongjin <appsky1888@gmail.com>  
Объединить автора и коммиттера в основной истории  
Отразить изменения в удалённом репозитории  
Сохранить резервную ветку перед переписыванием

Резервная ветка:

backup/before-author-email-rewrite-2026-06-17

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

15. Созданные/организованные сегодня документы

Основные документы, созданные или организованные сегодня:

docs/research-notes/2026-06-17-swe-agent-trajectory-keywords.md
docs/research-notes/2026-06-17-godot-rag-labeler-data-generation.md
docs/research-notes/2026-06-17-godot-rag-to-qwen-coding-model-flow.md
docs/roadmaps/2026-06-17-godot-llm-roadmap.md
docs/retrospectives/2026-06-17-godot-rag-judge.md
docs/README.md

В README также добавлен раздел с журналом разработки от 17 июня и подготовкой данных RAG.

16. Текущее заключение

Состояние на сегодня можно оформить так.

Направление:
Нужно перейти не к модели Godot Q&A, а к Godot SWE Agent.

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

Метка:
Решать должен не LLM, а конвейер Python.

RAG:
v2 — это безопасный базовый набор чанков.  
v3 — это промежуточный каталог, полученный широким извлечением.  
v3.1 — это текущий рекомендуемый результат RAG, включающий разделение по надёжности.

Риск:
Нельзя использовать все извлечённые символы с одинаковой надёжностью.

Сегодняшняя работа заключалась не только в создании нескольких файлов, но и в том, что несколько раз пришлось менять направление, которое легко могло привести к ошибке. Особенно важными были решения: откатить «hard‑coded API focus»‑чанк, обнаружить риск шума в broad v3 и разделить в v3.1 каталоги trusted/syntax/migration/mention/candidate/rejected.

17. Следующие задачи

Следующая работа — это не просто маркировка кода на GitHub.

То, что нужно сделать в первую очередь:

  1. Сгенерировать embedding на основе поля search_text в файле docs_chunks_v3_1.jsonl.
  2. Протестировать гибридный поиск, объединяющий векторный поиск и поиск по ключевым словам.
  3. Спроектировать Python‑pipeline для определения меток на основе trusted_api_symbols, syntax_symbols, migration_mappings.
  4. Определить формат ввода данных для структурирования репозитория GitHub.
  5. Спроектировать поток определения уровня репозитория, учитывающий файлы .gd, .tscn, .tres, project.godot и README.
  6. Связать результаты классификатора RAG с конвейером создания 8‑ти типовых наборов данных JSONL.
  7. После готовности удалённого LLM‑endpoint подключить генерацию исправленного кода, пояснений, вариантов SFT/DPO.
  8. Затем расширить процесс обучением SFT/DPO на основе Qwen и траекторией SWE‑Agent.

Главный вывод дня таков.

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