Godot RAG 分类器本地 PostgreSQL 设置

编写日期：2026 年 6 月 22 日

目的

为 Godot 官方文档 RAG 分类器设置本地 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

连接信息：

项目	值
database	`godot_rag`
user	`godot_rag`
password	`godot_rag_local`
host	`localhost`
port	`5432`

本地开发用默认 URL：

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

生成的扩展

extension	目的
`vector`	存储文档块和标签原型嵌入
`pg_trgm`	辅助 API 名称、标题、符号的模糊/部分搜索

注意：

embedding 列是当前未固定维度的 vector 类型。  
pgvector 的 HNSW/IVFFlat 索引需要固定维度，因此，实际的 vector 索引将在 embedding 模型维度确定后通过单独的 migration 创建。

模板：

infra/postgres/init/004_vector_index_templates.sql

生成的模式

DB 模式名称：

godot_rag

表格:

表格	角色
`godot_rag.docs_chunks`	官方文档说明、教程、class reference 章节
`godot_rag.api_mapping`	Godot 3 → 4 API 更改、重命名、替换、弃用规则
`godot_rag.label_prototypes`	分类/转换/拒绝/修改示例原型
`godot_rag.ingest_reports`	JSONL 转换/注入过程的警告、跳过、验证日志

表格设计

`docs_chunks`

保存官方文档章节。所有行必须保留原始 URL、原始文件路径、原始 Markdown 哈希。

主要列:

列	说明
`chunk_id`	即使重新运行也不变的决定性 ID
`doc_version`	`stable`、`4.6` 等文档版本
`source_url`	Godot 官方文档原始 URL
`source_file`	仓库内 Markdown 路径
`source_sha256`	原始 Markdown 哈希
`doc_type`	`class_reference`、`tutorial`、`migration` 等文档类型
`symbol`	class/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`	符合 Godot 4 标准的有效 API 使用
`godot3_api_in_godot4`	Godot 4 项目中混入了 Godot 3 API
`deprecated_or_removed_api`	使用已删除/废弃的 API
`migration_required`	需要将 Godot 3 → 4 迁移
`ambiguous_version_signal`	版本判断依据不足或冲突
`non_godot_noise`	与 Godot 无关的数据，如 Python/网页/Unity 等
`unsafe_or_obfuscated_code`	混淆、控制字符、疑似恶意代码

执行方法

DB 启动：

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 模式验证脚本。
编写 JSONL upsert 脚本。
使用示例问题验证 Retriever 检索质量。

Godot RAG 分类器 本地 PostgreSQL 设置

目的