Configuración local de PostgreSQL para el clasificador RAG de Godot

Fecha de creación: 22 de junio de 2026

Propósito

Configurar una base de datos PostgreSQL local para el clasificador RAG de la documentación oficial de Godot. El flujo de referencia es el siguiente.

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

Objetivo de la fase actual no es generar datos de entrenamiento, sino reproducir una base de datos de evidencia basada en la documentación oficial localmente. Mantenga la columna payload de la tabla con el mismo nombre que el esquema JSONL, y para las columnas derivadas de operación de la base de datos incluya solo las columnas mínimas necesarias para búsqueda/almacenamiento, como id, embedding, search_tsv, created_at.

Documento de diseño de referencia:

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

Configuración de la base de datos local

Archivo Docker Compose:

infra/postgres/docker-compose.yml

Imagen usada:

pgvector/pgvector:pg16

Información de conexión:

URL predeterminada para desarrollo local:

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

Extensiones generadas

Nota:

La columna **embedding** es un tipo vector que no fija la dimensión actual.  
Los índices **HNSW/IVFFlat** de **pgvector** requieren una dimensión fija, por lo que,  
el índice vector real se crea mediante una migración separada después de que la dimensión del modelo **embedding** se haya confirmado.

Plantilla:

infra/postgres/init/004_vector_index_templates.sql

Esquema generado

Nombre del esquema DB:

godot_rag

Tabla:

Diseño de la tabla

docs_chunks

Almacena fragmentos de la documentación oficial. Cada fila debe conservar la URL original, la ruta del archivo original y el hash del Markdown original.

Columnas principales:

api_mapping

Almacena las reglas de cambio de Godot 3/4.

Principios importantes:

• Si hay evidencia en la documentación oficial, se establece confidence = 'verified_from_docs'.
• Las reglas de extracción automática que aún no se han revisado se marcan como confidence = 'candidate'.
• Las reglas que se usan directamente para entrenamiento/etiquetado deben ser revisadas por una persona y luego establecerse confidence = 'approved' o gestionarse mediante un JSONL de aprobación separado.

label_prototypes

Almacena los criterios de etiquetas y patrones representativos de la salida del clasificador.

Candidatos iniciales de etiquetas:

Método de ejecución

Iniciar la base de datos:

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

En el entorno local actual, se utiliza el comando docker-compose en lugar del plugin docker compose.

Chequeo de salud:

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

Conexión desde dentro del contenedor:

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

Verificar tabla:

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

Verificación de expansión:

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;"

Inicialización

Solo se usa cuando se crea la base de datos completamente nueva. Tenga cuidado porque el volumen local será eliminado.

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

Ruta prevista para la inyección de JSONL

Aún no se ha creado el script de inyección. Primero se generará y verificará el siguiente producto JSONL y luego se añadirá el script de upsert.

Próximas tareas

1. Crear un informe de análisis de la estructura outputs/godot_docs_full/pages.
2. Definir los criterios de chunking por tipo de documento.
3. Redactar el script de validación del esquema de docs_chunks.jsonl.
4. Elaborar el script de upsert de JSONL.
5. Verificar la calidad de búsqueda del Retriever con preguntas de muestra.