Настройка локального PostgreSQL для классификатора Godot RAG

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

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

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

JSONL -> PostgreSQL -> Retriever -> Validator -> Qwen 3.6

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

Базовый проектный документ:

docs/roadmaps/2026-06-21-initial-rag-classifier-architecture.md

Конфигурация локальной БД

Docker Compose файл:

infra/postgres/docker-compose.yml

Используемое изображение:

pgvector/pgvector:pg16

Информация о подключении:

Пункт	Значение
база данных	`godot_rag`
пользователь	`godot_rag`
пароль	`godot_rag_local`
хост	`localhost`
порт	`5432`

Базовый URL для локальной разработки:

postgresql://godot_rag:godot_rag_local@localhost:5432/godot_rag

Создаваемые расширения

extension	цель
`vector`	Сохранение эмбеддингов фрагментов документа и прототипов меток
`pg_trgm`	Помощь в нечетком/частичном поиске по имени API, заголовку, символу

Внимание:

Столбец embedding является типом vector, размерность которого в настоящее время не фиксирована.  
Индексы HNSW/IVFFlat в pgvector требуют фиксированной размерности, поэтому,  
реальный векторный индекс создаётся отдельной миграцией после того, как размерность модели embedding будет определена.

Шаблон:

infra/postgres/init/004_vector_index_templates.sql

Создаваемая схема

Имя схемы БД:

godot_rag

Таблица:

Таблица	Роль
`godot_rag.docs_chunks`	Описание официальной документации, учебные материалы, фрагменты справочника классов
`godot_rag.api_mapping`	Правила изменения API Godot 3 → 4, переименования, замены, устаревания
`godot_rag.label_prototypes`	Прототипы примеров классификации/преобразования/отклонения/коррекции
`godot_rag.ingest_reports`	Журналы предупреждений, пропусков и проверок процесса преобразования/загрузки JSONL

Проектирование таблиц

`docs_chunks`

Хранит фрагменты официальной документации. Каждая строка должна сохранять исходный URL, путь к исходному файлу и хеш исходного Markdown.

Основные столбцы:

Столбец	Описание
`chunk_id`	Детерминированный ID, не меняющийся при повторных запусках
`doc_version`	Версия документа, например `stable`, `4.6`
`source_url`	Исходный URL официальной документации Godot
`source_file`	Путь к Markdown в репозитории
`source_sha256`	Хеш исходного Markdown
`doc_type`	Тип документа, например `class_reference`, `tutorial`, `migration`
`symbol`	Представляющий символ класса/API
`section_path`	Иерархия заголовков в виде JSON
`content`	Текст, подлежащий поиску и встраиванию
`code_blocks`	Массив блоков кода, извлечённых из текста
`api_symbols`	Обнаруженные символы Godot API в тексте
`embedding`	Векторное представление pgvector
`search_tsv`	tsvector для поиска по ключевым словам

`api_mapping`

Хранит правила изменения Godot 3/4.

Важные принципы:

Если есть подтверждение в официальной документации, ставьте confidence = 'verified_from_docs'.
Автоматически извлечённые правила, ещё не проверенные, получают confidence = 'candidate'.
Правила, используемые непосредственно в обучении/разметке, после проверки человеком получают confidence = 'approved' или управляются отдельным JSONL‑файлом одобрения.

`label_prototypes`

Хранит критерии меток вывода классификатора и типичные шаблоны.

Начальные варианты меток:

Метка	Значение
`godot4_valid_api`	Использование API, действительного в Godot 4
`godot3_api_in_godot4`	В проекте Godot 4 смешан API Godot 3
`deprecated_or_removed_api`	Использование удалённого/устаревшего API
`migration_required`	Требуется преобразование Godot 3 → 4
`ambiguous_version_signal`	Недостаточно данных или конфликт для определения версии
`non_godot_noise`	Данные, не связанные с Godot (Python, веб, Unity и т.п.)
`unsafe_or_obfuscated_code`	Обфусцированный, управляющие символы, подозрительный код

Как запустить

Запуск БД:

docker-compose -f infra/postgres/docker-compose.yml up -d

В текущей локальной среде используется команда docker-compose, а не плагин docker compose.

Проверка работоспособности:

docker inspect --format='{{json .State.Health.Status}}' godot-rag-postgres

Подключение изнутри контейнера:

docker exec -it godot-rag-postgres psql -U godot_rag -d godot_rag

Проверьте таблицу:

docker exec godot-rag-postgres \
  psql -U godot_rag -d godot_rag \
  -c "\\dt godot_rag.*"

Расширение подтверждено:

docker exec godot-rag-postgres \
  psql -U godot_rag -d godot_rag \
  -c "select extname from pg_extension where extname in ('vector', 'pg_trgm') order by extname;"

Инициализация

Используется только при полном создании новой БД. Будьте осторожны, так как локальный том будет удалён.

docker-compose -f infra/postgres/docker-compose.yml down -v
docker-compose -f infra/postgres/docker-compose.yml up -d

Планируемый путь внедрения JSONL

Скрипт внедрения ещё не создан. Сначала создайте и проверьте следующий вывод JSONL, а затем добавьте скрипт upsert.

Файл	Целевая таблица
`work/godot_rag/jsonl/docs_chunks.jsonl`	`godot_rag.docs_chunks`
`work/godot_rag/jsonl/api_mapping.jsonl`	`godot_rag.api_mapping`
`work/godot_rag/jsonl/label_prototypes.jsonl`	`godot_rag.label_prototypes`
`work/godot_rag/jsonl/ingest_report.jsonl`	`godot_rag.ingest_reports`

Последующие задачи

Создать отчёт об анализе структуры outputs/godot_docs_full/pages.
Утвердить критерии чанкинга для каждого типа документа.
Написать скрипт проверки схемы docs_chunks.jsonl.
Написать скрипт upsert для JSONL.
Проверить качество поиска Retriever с помощью образцовых вопросов.