2026 年 6 月 22 日回顾

今天我没有直接把 Godot 官方文档 Markdown 放入 RAG，而是先将其转换为结构化的 JSONL 并进行确认，构建了这样的流程。起初不知道该如何拆分官方文档的 Markdown，但通过制作转换 UI 并目视查看每个文件的结果，过程变得顺畅许多。

Markdown → JSONL 转换器

上传 Godot 官方文档的 Markdown 文件后，通过 Qwen API 对目标表进行分类，并将结果分别划分为 docs_chunks、api_mapping、label_prototypes 用的 JSONL。

起初我只想直接读取 Markdown 并写入数据库，但这样很难确认哪些文档进入了哪个表。于是改为先生成 JSONL 作为中间产物，在界面上对比转换结果与原文。

这种方式的好处如下。

• 可以边比较原始 Markdown 边查看转换后的 JSONL。
• 能确认单篇文档是进入 docs_chunks、api_mapping 还是 label_prototypes。
• 在将错误分类或空结果写入数据库前可以过滤掉。
• 以后即使更改转换规则，也只需重新生成 JSONL 并进行对比。

转换结果确认

转换器会在界面上显示已保存的 JSONL 文件数量和错误数量。今天看到的界面中，docs_chunks 的结果先积累，其余 api_mapping、label_prototypes 以及错误文件仍为空。

这种情况并非异常，而是因为前期文档大多是说明文档，自然会进入 docs_chunks。关键在于，结果不是直接写入数据库，而是先保存为 JSONL，供人工检查。

JSONL 预览与表格形式查看

可以在界面上以 JSON 形式和表格形式查看 JSONL 结果。例如，docs_chunks 记录包含 chunk_id、doc_version、source_url、source_file、source_sha256、doc_type、section_path、heading、content、code_blocks、api_symbols、token_count、metadata 等字段。

这样比单纯持有 Markdown 文件要好得多。尤其是 chunk_id 与 source_sha256 同时可见，后期追踪某个块来源于哪个原始文件变得容易。RAG 最关键的是不丢失来源依据，而 JSONL 的中间产物正好可以承担此角色。

转换日志

也查看了每个文件的转换日志。可以看到哪个文件开始处理、Qwen 将其分类到哪个表、以及产生了多少有效记录。

在今天的示例中，about__complying_with_licenses 文档被分类为 docs_chunks 并转换为多个块。相反，像 404 这样的文档因没有对应目标表而被跳过。拥有这些日志，后续处理 1,570 篇文档时能够追踪问题来源。

本地 PostgreSQL 设置

生成 JSONL 后，还整理了本地 PostgreSQL，以便将数据写入。基于 pgvector/pgvector:pg16 启动容器，并创建了 docs_chunks、api_mapping、label_prototypes、ingest_reports 表。

今天特别关注的是数据库模式必须与 JSONL 字段名保持一致。若数据库随意添加字段，会导致 JSONL 合约模糊，后续转换器和注入器可能基于不同标准运行。因此，数据库的 payload 列仅与 JSONL 模式对齐，运营列仅保留 id、embedding、search_tsv、created_at 等最小必要字段。

本地数据库已实际运行，使用示例 JSONL 进行插入和搜索，并通过回滚测试验证。虽然尚未将全部文档写入数据库，但从 JSONL 到 PostgreSQL 的路径已经清晰许多。

今日判断

今天构建的流程本身并不是最终的 RAG 判别器，但在当前阶段已经是相当重要的进展。

之前对官方文档的 Markdown 处理方式模糊，直接进行分块或数据库注入会导致结构丢失。今天在两者之间加入了 JSONL 转换/验证步骤，生成了可供人工检查的中间产物。

综上，接下来的流程应当如此推进。

Godot 官方文档 Markdown  
-> JSONL 转换  
-> JSONL 预览/验证  
-> PostgreSQL 注入  
-> Retriever 搜索 验证  
-> Validator/Qwen 响应 整理

明天之后，需要在完整转换 1,570 篇文档后，确认 docs_chunks、api_mapping、label_prototypes 的比例。特别是 api_mapping 和 label_prototypes 不能随意由 Qwen 生成，必须在不盲目信任自动生成结果的情况下，设置审批/验证环节。

处理速度测量

另外计算转换速度后，发现将全部 1,570 个 Markdown 转换为 JSONL 大约需要 42 小时左右。

截至目前的实际处理时间约为 1 小时 9 分钟。在此期间，共处理了 done 39 个和 deferred 4 个，总计 43 个文件。平均速度约为每个文件 1.6 分钟。

实际处理时间：约 1 小时 9 分钟  
当前处理的文件：已完成 39 个 + 延迟 4 个 = 43 个  
平均速度：每个文件约 1.6 分钟  
全部 1,570 个转换的预计时间：约 42 小时

最初感觉大约每分钟 1 条，但如果按实际日志计算会稍微久一点。由于在今天完成全部 1,500 条转换可能比较困难，需要在处理过程中持续记录处理速度以及失败/保留文件数量。

接下来的验证计划

明天和后天可能没有时间，无法直接继续工作。不过后续需要继续完成的任务已经基本整理完毕。

首先，需要将收集和转换过程中已经生成的 JSONL 导入本地 PostgreSQL。迄今为止编写的转换器侧重于将 Markdown 划分为 docs_chunks、api_mapping、label_prototypes 用的 JSONL，下一步是将这些 JSONL 实际写入数据库，并确认是否可以被检索。

随后，将对 docs/roadmaps/2026-06-21-initial-rag-classifier-architecture.md 中编写的工作流进行小规模的 Python 脚本验证。

source code  
-> AST Parser  
-> Retriever  
-> evidence JSONL / evidence bundle  
-> Qwen 3.6 API 调用  
-> 确认响应

即，將任意的 Godot 原始碼放入 Python 腳本中，確認 AST 解析器是否能提取符號和版本訊號。將結果放入 Retriever，讓 PostgreSQL 從相關官方文件片段或 API 映射中取得，然後在將返回的 JSONL/evidence 包傳遞給 Qwen 3.6 API 時，間歇性檢查會得到什麼回應。

此過程並非最終自動化，而是接近於驗證每個階段實際是否能連接的簡單端到端測試。特別需要確認 Qwen 是依靠記憶作答，還是根據 Retriever 提供的依據作答。

公開倉庫與私有轉換的想法

最近把這個倉庫公開過一次，之後又轉回私有。原因似乎很簡單：不想展示自己的實力。

現在的實力仍覺得很差。但同時也想製作專屬於 Godot 的模型，上傳到 Hugging Face，並以此為起點，向講課影片、學校、作品集、榮譽等多個領域擴展。這看起來像是過於夢幻的妄想。但如果有人能以我留下的回顧與工作記錄為踏腳石而成長，我自己在這個過程中也能更快成長，這樣的想法讓我產生了動力。

事實上我仍有不想公開的心情。害怕自己製作的東西看起來沒深度，或者相反，將各種知識稍微拼湊成看起來簡單的成果，會不會被人直接抄襲。結果物並非因為技術驚人，而是我迄今為止的思考與連結痕跡完整展現，這讓我感到壓力。

雖然已設定 PR 與 CI/CD 流程，但原本的想法是：當 GitHub workflow 有 PR 提出時，部署在 Oracle Cloud 的本地 LLM 端點會自動進行 PR 評審。Oracle Cloud 具備 24GB VRAM，應該能跑大部分本地模型，於是考慮將託管的 LLM 用於程式碼評審自動化。但因為遺失了 Oracle Cloud 帳號，這個流程暫時無法再使用。RunPod 也可用於 PR 驗證，但每次工作都需要重新設定，較為繁瑣。因此目前以手動操作與文件化為主，LLM 基於的 PR 評審自動化則留待日後再實作。

結論大概就是這樣。事實上可能沒人會看，但我對被抄襲的警覺性非常高。即使有人參考或使用我的作品，我也要以此為踏腳石讓自己變得更優秀。公開與否仍需謹慎決定，但不要因為恐懼而停止記錄。