Схема и архитектура классификатора RAG официальной документации Godot

Дата создания: 21 июня 2026 г.

Цель

Сформировать базовую архитектуру для соединения полного набора официальной документации Godot в поток JSONL -> PostgreSQL -> Retriever -> Validator -> Qwen 3.6. Этот документ не является инструкцией по непосредственному созданию обучающих данных, а определяет проектные критерии для структурирования уже собранных в outputs/godot_docs_full/pages Markdown‑файлов официальной документации в форму, пригодную для поиска и создания базы доказательств.

Текущие входные данные

Результаты сбора официальной документации находятся в репозитории под outputs/godot_docs_full.

Текущие базовые показатели:

Полный конвейер

1. crawler собирает официальную документацию Godot из интернета.
2. Результаты сбора сохраняются в виде Markdown‑файлов по страницам.
3. Markdown нормализуется и к нему добавляются метаданные, после чего он преобразуется в записи JSONL.
4. JSONL импортируется в PostgreSQL.
5. PostgreSQL сохраняет фрагменты документов, сопоставления API и прототипы меток раздельно.
6. При запросе пользователя на анализ исходного кода Godot AST‑парсер структурирует код проекта.
7. Retriever ищет доказательства в PostgreSQL, используя вопрос пользователя и результаты анализа AST.
8. Validator объединяет вопрос, результаты AST и найденные доказательства и передаёт их Qwen 3.6.
9. Qwen 3.6 не является окончательным судьёй; он формирует ответ, опираясь на проверенные доказательства.
10. Validator проверяет доказательства/формат/запрещённые шаблоны ответа и возвращает результат пользователю.

Преобразование Markdown в JSONL

pages/*.md — это удобные для чтения оригиналы страниц, но они слишком крупны для RAG. Поэтому скрипт преобразования делит страницу на секции/члены API/примеры и сохраняет исходный URL и тип документа.

Общие правила нормализации

Выходные файлы JSONL

Схема docs_chunks.jsonl

{
  "chunk_id": "godot-stable:classes/class_node.html#description:0001",
  "doc_version": "stable",
  "source_url": "https://docs.godotengine.org/en/stable/classes/class_node.html",
  "source_file": "outputs/godot_docs_full/pages/classes__class_node__....md",
  "source_sha256": "...",
  "doc_type": "class_reference",
  "symbol": "Node",
  "section_path": ["Node", "Description"],
  "heading": "Description",
  "content": "Nodes are Godot's building blocks...",
  "code_blocks": [],
  "language_tags": ["gdscript"],
  "godot_version_tags": ["4.x", "stable"],
  "api_symbols": ["Node", "_ready", "_process", "queue_free"],
  "token_count": 420,
  "metadata": {
    "status": "copied_old",
    "bytes": 12345
  }
}

Обязательные поля:

Схема api_mapping.jsonl

{
  "mapping_id": "godot3-to-4:kinematicbody2d-to-characterbody2d",
  "source_api": "KinematicBody2D",
  "target_api": "CharacterBody2D",
  "change_type": "rename_or_replacement",
  "godot_from": "3.x",
  "godot_to": "4.x",
  "confidence": "verified_from_docs",
  "evidence_chunk_ids": [
    "godot-stable:tutorials/migrating/upgrading_to_godot_4.html#..."
  ],
  "match_terms": ["KinematicBody2D", "CharacterBody2D"],
  "notes": "Godot 4 character movement node replacement candidate.",
  "negative_patterns": ["do not suggest KinematicBody2D for Godot 4 projects"]
}

Принципы:

Схема label_prototypes.jsonl

{
  "prototype_id": "label:godot3-api-in-godot4:kinematicbody2d",
  "label": "godot3_api_in_godot4",
  "task_type": "version_classification",
  "input_pattern": "extends KinematicBody2D",
  "expected_finding": "Godot 3 style physics body API detected.",
  "recommended_action": "Use CharacterBody2D or CharacterBody3D depending on project dimension.",
  "evidence_mapping_ids": [
    "godot3-to-4:kinematicbody2d-to-characterbody2d"
  ],
  "evidence_chunk_ids": [],
  "severity": "high",
  "validator_rules": {
    "requires_ast_symbol": "KinematicBody2D",
    "forbidden_answer_terms": ["KinematicBody2D is recommended in Godot 4"]
  }
}

Лейбл кандидаты:

Черновик схемы PostgreSQL

PostgreSQL предполагает использование pgvector. Поиск по ключевым словам осуществляется с помощью tsvector или trigram‑индекса.

docs_chunks

Индексы:

api_mapping

Индексы:

label_prototypes

Индексы:

Ввод/вывод AST‑парсера

AST‑парсер преобразует пользовательский исходный код в структуру, пригодную для поиска, перед тем как передать его LLM. Первоначально поддерживаются файлы .gd, .tscn, project.godot.

Ввод

Вывод схемы

{
  "project_id": "local-analysis-...",
  "godot_project": {
    "config_version": 5,
    "features": ["4.4", "Forward Plus"]
  },
  "files": [
    {
      "path": "scripts/player.gd",
      "language": "gdscript",
      "extends": "CharacterBody2D",
      "class_name": "Player",
      "symbols": ["CharacterBody2D", "Input", "move_and_slide"],
      "annotations": ["@onready"],
      "version_signals": ["godot4_annotation_syntax"],
      "diagnostics": []
    }
  ],
  "version_evidence": {
    "godot4": ["config_version=5", "@onready"],
    "godot3": []
  }
}

Начальные поля извлечения:

| resource_paths | Проверка связей отсутствующих ресурсов и ассетов |

Работа Retriever

Retriever — это уровень, который выбирает доказательства раньше, чем LLM.

1. Из вопроса пользователя извлекаются намерение и целевая задача.
2. Из результата AST Parser берутся символы API, сигналы версии и пути к файлам.
3. Сначала выполняется точный поиск в api_mapping.
4. В docs_chunks одновременно выполняются фильтрация по символам API, поиск по ключевым словам и векторный поиск.
5. Из label_prototypes берутся похожие метки и правила проверки.
6. Результаты поиска упорядочиваются в пакет доказательств.

Пакет доказательств:

{
  "query_id": "analysis-...",
  "task_type": "version_classification",
  "ast_summary": {},
  "doc_evidence": [],
  "api_mapping_evidence": [],
  "label_evidence": [],
  "retrieval_scores": {
    "exact_api_hits": 2,
    "keyword_hits": 8,
    "vector_hits": 12
  }
}

Разделение ролей Validator и Qwen 3.6

Qwen 3.6 — это модель, читающая найденные доказательства и формирующая ответ. Финальную метку, принятие доказательств и проверку запрещённых шаблонов выполняет Validator.

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

Порядок внедрения

1. Проверить outputs/godot_docs_full/summary.json и failed.json.
2. Загрузить manifest.json и pages/*.md.
3. Создать отчёт о нормализации Markdown.
4. Сгенерировать docs_chunks.jsonl.
5. В документе migration/class создать кандидат api_mapping.jsonl.
6. На основе утверждённых правил и типовых примеров создать label_prototypes.jsonl.
7. Вставлять (upsert) в PostgreSQL только те записи, которые прошли проверку схемы JSONL.
8. Сгенерировать эмбеддинги и обновить векторный индекс.
9. Обновить индекс ключевых слов и точный индекс.
10. Проверить результаты Retriever с помощью образцовых вопросов.

Список проверки качества

Приоритет реализации

1. Составить отчет об анализе структуры pages/*.md
2. Написать скрипт преобразования docs_chunks.jsonl
3. Создать скрипт проверки схемы JSONL
4. Составить DDL для PostgreSQL
5. Внедрить docs_chunks и проверить поиск
6. Сгенерировать кандидаты api_mapping и оформить процесс ручного утверждения
7. Подготовить начальный набор меток label_prototypes
8. Извлечь минимальные поля с помощью AST‑парсера
9. Вывести пакет доказательств Retriever
10. Связать цикл сортировки ответов Validator + Qwen 3.6

Ключевые принципы

• Оригинальный Markdown официальной документации не изменяется и сохраняется.
• JSONL рассматривается как промежуточный воспроизводимый артефакт.
• В базе данных обязательно сохраняются оригинальный путь, оригинальный URL, хеш и версия скрипта преобразования.
• Не позволять LLM придумывать новые метки.
• Определение Godot 3/4 производится на основе сигналов AST, сопоставления API и доказательств из официальной документации.
• Не использовать неопределённые кандидаты напрямую в обучающих данных, а оставлять их в состоянии candidate.
• Qwen 3.6 выступает в роли агрегатора ответов, а критерии оценки задаются Retriever и Validator.

Следующая задача

Следующий шаг — проанализировать образец структуры Markdown в outputs/godot_docs_full/pages. Особенно, поскольку документы справочника классов, миграции и учебные материалы имеют разные структуры, их нельзя объединять под единым правилом чанкования; необходимо сначала определить стратегию чанкования для каждого типа документа.