2026-06-17 Godot LLM/RAG 判别器构建 回顾
一句话概括
今天将 Godot 专用编码模型的方向从单纯的 Q&A 模型重新定位为 repo 级别的 SWE Agent，并在其前端构建了基于官方文档的 RAG 判别器和数据生成流水线的初步实现。
今天一天的主要流程
起初的目标是“用 Godot 官方文档制作 RAG 聊天机器人”。但随着讨论和工作推进，目标变得更加明确。
收集 Godot 官方文档
-> 基于官方文档的 RAG 判别器
-> 为 GitHub Godot 项目标记
-> 生成 SFT/DPO 数据
-> 基于 Qwen 的 Godot 4 编码模型
-> 仓库级别的 SWE 代理即今天的核心不是制作一个聊天机器人，而是为以后能够实际读取并修复 Godot 项目的模型建立数据判别/生成的基础。
1. 判断单纯的 Q&A 模型不足
今天首先整理的是模型目标的性质。
之前的想法是制作 Godot 4 问答数据集，让模型能够很好地回答 Godot 4 代码。但如果考虑 “帮我做个地图” 之类的请求，这并不是单纯的 Q&A 问题。
实际的请求流程更接近于下面这样。
理解用户请求
-> 探索仓库结构
-> 查找相关的 scene/script/resource
-> 确认资产路径和现有代码风格
-> 判断 Godot 4 语法/API
-> 修改代码
-> 运行/测试/验证
-> 生成补丁此流程不是生成单个答案的问题，而是软件工程代理问题。因此，今天将模型方向重新定位为 SWE-agent trajectory training 视角。
今天记录的核心关键词：
Long-context repository-level software engineering agent training
SWE-agent trajectory training
Godot repo-level patch generation
long-context trajectory dataset也整理了参考案例。
SWE-agent trajectories
SWE-smith
SWE-Gym
CoderForge-Preview
ACC
RepoBench / CrossCodeEval / RepoCoder
aiXcoder CoLT
godot-dodo
wallstoneai/godot-gdscript-dataset今天的结论是仅靠小的 instruction Q&A 不足。最终需要的是 Godot 项目层面的探索、判断、修改、验证 trajectory。
相关备注：
docs/research-notes/2026-06-17-swe-agent-trajectory-keywords.md2. Godot LLM 整体路线图整理
然后，我们重新制定了整体开发路线图。
整体流程如下整理。
数据
-> 第一阶段 RAG 聊天机器人
-> SFT
-> DPO
-> SWE Agent如果将步骤进一步细分，结果如下。
Stage 0. 准备阶段
Stage 1. 数据收集与结构化
Stage 2. 第一次 RAG 聊天机器人开发
Stage 3. 数据标注与数据集生成
Stage 4. 模型训练
Stage 5. SWE 代理开发
Stage 6. 持续改进在此路线图中最重要的判断是：不要把第一阶段的 RAG 聊天机器人视为单纯的问答工具。首先，需要构建一个充当 Godot 官方文档专家角色的 RAG 判别器，并通过该判别器对 GitHub 数据进行标注/加工，然后再以 SFT/DPO 和 SWE Agent 的方式进行扩展。
特别是第 5 阶段的 SWE Agent 不应只是一个简单的代码生成器，而是必须具备以下能力。
项目分析
必要文件搜索
代码修改
验证 Godot CLI 或运行结果
失败原因分析
生成补丁相关路线图：
docs/roadmaps/2026-06-17-godot-llm-roadmap.md3. RAG 判别器基于数据生成结构设计
今天还有一个重要的判断是“不要把最终标签决定交给 LLM”。
一开始很容易认为 RAG 聊天机器人只要看 GitHub 代码或文档就能判断是 Godot 3 还是 4。但标签直接影响训练数据质量，如果把即兴判断交给 LLM 就很危险。
于是我们把结构安排成如下方式。
LLM是生成辅助
标签由系统决定
最终 JSONL 由 Python pipeline 组装/验证系统需要负责的事项：
符号提取
API映射数据库查询
官方文档向量搜索
关键词搜索
标签原型搜索
标签评分
置信度计算
最终 JSONL 组装
验证LLM可以负责的事项：
生成修改代码草案
生成说明
生成SFT问答
生成DPO错误答案
生成补丁草案
验证/问题说明辅助生成目标数据集也整理为8种。
version_classification
api_mapping
migration_fix
instruction_sft
dpo_preference
repo_explorer
patch_generation
metadata_verification这段内容成为了今天编写的 RAG 后处理代码的设计准则。特别是将 api_mapping、symbol_catalog、keyword_index、search_text 分离的原因也正是来源于此。
相关备注：
docs/research-notes/2026-06-17-godot-rag-labeler-data-generation.md4. RAG 判别器中使用 Qwen 3.6 模型的 MVP 流程
已单独整理了 Godot RAG 判别器与 Qwen 3.6 编码模型之间的 MVP 流程图。
整理的流程：
godot_docs_full.zip 原始文档准备
-> 基于 chunk_docs.py 的首次分块
-> Godot 专用后处理
-> 构建本地搜索基础设施
-> 收集并结构化 GitHub 数据
-> 运行 RAG 判别器
-> 生成训练数据集
-> Qwen 3.6 SFT/DPO这里的本地搜索基础设施并不只指单一的向量数据库。
所需的组成：
Vector DB
Keyword Index
Reranker
API Mapping DB
Label Prototype DB此外，GitHub 数据必须以仓库级别的结构而不是单纯的代码片段形式导入。
所需输入：
.gd
.tscn
.tres
project.godot
README
repo tree
metadata第一次 SFT 目标也重新整理了。
Godot 4 优先考虑
GDScript 基本输出
拒绝 Godot 3 API
说明 Godot 3 -> 4 转换依据之后在 DPO 中需要更明确地界定好答案和坏答案的标准。
糟糕的回答：混有 Godot 3 API 的回答
好的回答：使用 Godot 4 纯代码并有依据的回答相关备注：
docs/research-notes/2026-06-17-godot-rag-to-qwen-coding-model-flow.md5. v1 官方文档分块
在完成设计整理后，将实际的官方文档数据制作成可以放入 RAG 的形式。
最初制作的产出文件如下。
work/godot_rag/chunks/docs_chunks.jsonl官方文档 Markdown 1,570个按标题和长度标准划分，生成了 9,741 个块。
结果：
Input pages: 1,570
Output chunks: 9,741
Max chunk chars: 2,800
Overlap chars: 350v1中好的方面：
- 将官方文档整体制作成 JSONL 块。
- JSONL 解析非常稳定。
class_reference、tutorial、migration等基本文档类型已被分类。
v1的问题：
- 仍残留大量 Sphinx 的剩余文字。
- 存在过短的噪声块。
heading、section、method/property 结构未能充分保留。- 类引用未按 API 单位精细划分。
v1 是“官方文档收集与基本分块成功”阶段。虽然成为搜索 MVP 的起点，但对标签判别器来说仍不足。
6. v2 后处理
接下来创建 postprocess_chunks.py 并生成 v2 块。
文件：
work/godot_rag/postprocess_chunks.py
work/godot_rag/chunks/docs_chunks_v2.jsonl在 v2 中处理的内容：
删除 404 块
删除短噪声块
删除 Sphinx 剩余文字
提取 symbols
提取 class_name
强化 section/member_type/member_name
显示与 migration 相关的块结果：
Input chunks: 9,741
Output chunks: 8,778
Dropped 404 chunks: 3
Dropped short/noise chunks: 960
Migration-related chunks: 695v2已经可以作为基于官方文档的RAG检索MVP使用。但要作为最终标签判别器仍显不足。尤其是 move_and_slide、velocity、@export、await 等语法/API 的变化，并未作为独立的判别标准进行划分。
7. 错误的 v3 方向与回退
最初设想的 v3 是通过硬编码部分核心 API 来生成 api_focus 块的方式。
示例：
KinematicBody2D
CharacterBody2D
move_and_slide
@export
await这种方式看起来可以快速提升搜索性能。但实际上是有风险的。
问题：
- 人工挑选的 API 可能会导致搜索器过拟合。
- 列表之外的 API 会变得薄弱。
- 某些代表性 API 可能看起来像是整个 Godot API 的代表。
- 缺失的 API 可能会在后续的标注过程中导致错误。
因此我们回滚了原来的 v3。这一判断非常重要。虽然短期看起来像是损失，但考虑到最终判别器的质量，硬编码 focus 块的做法是错误的方向。
8. 基于 catalog 的 v3 重新设计
回滚之后，我们改变了方向。
新原则：
v2 块一个也不丢失。
不随意创建新的 focus 块。
在整个官方文档中自动提取 symbol/catalog/index/mapping。
将搜索强化信息附加为 metadata。添加的代码：
work/godot_rag/build_symbol_catalog.py
work/godot_rag/build_keyword_index.py
work/godot_rag/build_api_mapping.py
work/godot_rag/make_chunks_v3.py
work/godot_rag/validate_rag_artifacts.py
work/godot_rag/retrieval_smoke_test.py生成的产出：
work/godot_rag/catalog/symbol_catalog.jsonl
work/godot_rag/catalog/keyword_index.json
work/godot_rag/catalog/api_mapping.jsonl
work/godot_rag/chunks/docs_chunks_v3.part-*.jsonl
work/godot_rag/validation/validation_report.json
work/godot_rag/validation/retrieval_smoke_test.json整个 docs_chunks_v3.jsonl 大约 189 MB，可能会超过 GitHub 的单文件限制。因此在仓库中上传按行保存的分割文件，需要时在本地再合并。
cat work/godot_rag/chunks/docs_chunks_v3.part-*.jsonl \
> work/godot_rag/chunks/docs_chunks_v3.jsonl9. v3 正合性验证
在 v3 中最重要的是防止遗漏。因为如果 v2 的任何一个块缺失，后续的官方文档依据可能会消失。
所以创建了 validate_rag_artifacts.py。
验证标准：
v2 chunk_id set == v3 chunk_id set
no missing or extra v3 chunks
catalog/index/mapping references point to existing chunks
search_text is present
no old hardcoded api_focus fields remain验证结果:
status: pass
v2 chunks: 8,778
v3 chunks: 8,778
v2 unique chunk_id: 8,778
v3 unique chunk_id: 8,778
symbol catalog entries: 134,922
keyword index keys: 192,257
api mapping records: 144
v3 chunks with api mappings: 1,900
v3 migration-related chunks: 2,392此外，在嵌入前阶段也执行了基于词汇/关键字的冒烟测试。
代表查询：
KinematicBody2D Godot 4 replacement
CharacterBody2D move_and_slide velocity
yield await Godot 4
export var @export Godot 4
onready var @onready Godot 4结果全部通过了 5 项。
10. 今天发现的最大风险
今天最重要的洞察是 “大量抽取” 与 “信任并写入标签” 是不同的。
在官方文档整体上广泛抽取会提升 recall。但如果把这些结果都视为同等可信度，关键词索引会被污染。
例如下面的内容很可能是真实的 API 或语法元素。
CharacterBody2D
move_and_slide
FileAccess
@export
await相反，以下更可能是文档普通词或表格列。
Returns
See
Tip
MIT
Software
Type实际上在检查 smoke test 的过程中，发现了像 Type -> EditorSceneFormatImporterFBX2GLTF 这样的普通表列可能被当作 API 映射候选的问题。已对该问题进行修正，使 Type 从映射候选中排除。
这里得到的结论是明确的。
广泛提取是必要的。
但是不能把所有广泛提取的内容都写成可信事实。11. v3.1 可信度分离结构的改版
在确认上述风险后，判断不能直接将 v3 用于最终标签判别器。因此在 v3.1 中不再将 catalog 合并为一个整体使用，而是按可信度和用途进行分离。
v3.1 中新采用的结构：
trusted_api_symbols
syntax_symbols
migration_mappings
mentioned_symbols
candidate_terms
rejected_terms
retrieval_keys
search_text每个字段的含义也被明确划分。
trusted_api_symbols:
在 class reference 结构中直接确认的 class/method/property/signal/constant
syntax_symbols:
在 GDScript 语法文档和 migration 文档中确认的语法要素
migration_mappings:
带有依据块的 old -> new 关系，连接了 Godot 3 -> 4 的更改映射
mentioned_symbols:
在 tutorial/body 中提及但已存在于 trusted/syntax catalog 的符号
candidate_terms:
用于搜索 recall 的候选词
rejected_terms:
不能作为标签使用的普通词，如 Returns、See、Tip、MIT、Software 等添加的代码：
work/godot_rag/build_v31_artifacts.py
work/godot_rag/validate_v31_artifacts.py生成的 v3.1 输出物：
work/godot_rag/chunks/docs_chunks_v3_1.jsonl
work/godot_rag/chunks/docs_chunks_v3_1.summary.json
work/godot_rag/catalog_v3_1/trusted_api_catalog.jsonl
work/godot_rag/catalog_v3_1/syntax_catalog.jsonl
work/godot_rag/catalog_v3_1/api_mapping.jsonl
work/godot_rag/catalog_v3_1/mention_index.json
work/godot_rag/catalog_v3_1/keyword_index.json
work/godot_rag/catalog_v3_1/v3_1.summary.json
work/godot_rag/validation_v3_1/validation_report.json
work/godot_rag/validation_v3_1/retrieval_smoke_test.jsonv3.1 结果:
Source v2 chunks: 8,778
Output v3.1 chunks: 8,778
Trusted API catalog entries: 26,318
Syntax catalog entries: 68
API mapping records: 144
Mention index keys: 10,292
Keyword keys: 71,543
Validation status: pass
Retrieval smoke tests: 5 / 5 passed重要地修正了的部分也有。
在最初的 v3.1 生成过程中，如果直接相信 v2 元数据中的 class_name，会导致 Tutorials、All、String 等错误值被上传到 trusted catalog。因此我们依据 source URL 和 class reference 路径重新生成了规范的类名。此修改后，像 Characterbody2d 这样的大小写问题也被纠正为 CharacterBody2D。
另一个重要的验证是 move_and_slide。在宽松的提取方式下，可能会出现 ProjectSettings.move_and_slide 之类的错误 trusted 条目。v3.1 中，我们限制只有在 class reference 的结构化 section 中确认的成员才会提升为 trusted，最终 move_and_slide 的 trusted 条目仅保留在实际的 Godot 类中，如下所示。
CharacterBody2D.move_and_slide
CharacterBody3D.move_and_slide即今天在 v3.1 中所做的工作不仅是增加字段，而是将其改为“搜索时广泛使用，但在标签决定时仅使用狭窄且可信的依据”的结构。
12. v3.1 一致性验证
在 v3.1 中，遗漏尤其危险。因为如果 v2 的 8,778 个块中有任何一个缺失，官方文档的依据就可能消失。
验证标准：
v2 chunk_id set == v3.1 chunk_id set
v3.1 unique chunk_id count == 8,778
doc_type 保持分布
legacy 删除混合字段
trusted/syntax/migration catalog 检查引用完整性
search_text 确认存在验证结果:
status: pass
errors: 0
warnings: 0
v2 chunks: 8,778
v3.1 chunks: 8,778再次运行了搜索 smoke test。
KinematicBody2D Godot 4 replacement
CharacterBody2D move_and_slide velocity
yield await Godot 4
export var @export Godot 4
onready var @onready Godot 4结果全部 5 项均通过。此阶段的意义并不是“最终标注者已完成”，而是指 v3.1 结构已经足够完整，能够至少转移到 MVP 向量/关键词索引。
13. GitHub 反映与记录整理
今天不仅完成了代码和数据产出物的制作，还整理了 GitHub 的反映工作。
处理的事项：
remote 设置
大容量 v3 文件分割
工作分支 push
远程 main 与本地历史合并
main push
文档目录整理docs_chunks_v3.jsonl 大约 189 MB，直接上传可能会触及 GitHub 单文件大小限制。因此将其拆分为 docs_chunks_v3.part-000.jsonl、docs_chunks_v3.part-001.jsonl、docs_chunks_v3.part-002.jsonl。
另外，最初的回顾文件放在根目录 retrospectives/ 下，但与现有仓库结构不匹配。于是将文档结构整理如下。
docs/research-notes/ 设计备忘
docs/roadmaps/ 整体路线图
docs/retrospectives/ 按日期回顾
work/godot_rag/ RAG 代码和产出物
outputs/godot_docs_full/ 官方文档爬取结果另外创建了 docs/README.md，并整理了文档目录的作用。
14. Git 作者/邮箱 整理
正如今天在 README 中记录的那样，GitHub 草稿（grass）映射问题也已经整理完毕。
已确认的问题：
main 历史的 author/committer 邮箱混在一起
本地主机邮箱
naver 邮箱
GitHub noreply 邮箱处理的方向：
将全局 Git 设置更改为 yyeongjin <appsky1888@gmail.com>
统一 main 历史的 author/committer
推送到远程
在重写前保存备份分支备份分支：
backup/before-author-email-rewrite-2026-06-17此工作虽未直接关联 RAG 本身，但是今天重要的整理工作之一。之后为了使记录和提交能够正确反映在 GitHub 个人资料上，进行了基础对齐工作。
15. 今日创建/整理的文档
今天创建或整理的主要文档：
docs/research-notes/2026-06-17-swe-agent-trajectory-keywords.md
docs/research-notes/2026-06-17-godot-rag-labeler-data-generation.md
docs/research-notes/2026-06-17-godot-rag-to-qwen-coding-model-flow.md
docs/roadmaps/2026-06-17-godot-llm-roadmap.md
docs/retrospectives/2026-06-17-godot-rag-judge.md
docs/README.md在 README 中也添加了 6 月 17 日的开发日志和 RAG 数据准备章节。
16. 当前结论
可以这样整理今天的状态。
方向性：
Godot Q&A 模型而不是 Godot SWE Agent。
数据：
官方文档 RAG 应该作为生成学习数据的判别器角色。
标签：
不是 LLM，而是 Python pipeline 决定。
RAG：
v2 是安全的基础块集合。
v3 是广泛提取的中间 catalog 产出物。
v3.1 是应用了可信度分离的当前推荐 RAG 产出物。
风险：
提取的 symbol 不能全部以相同的可信度使用。今天的工作不仅仅是创建了几个文件，而是多次转向了容易出错的方向。特别是恢复硬编码 API focus 块的判断、发现 broad v3 的噪声风险的判断，以及在 v3.1 中将 trusted/syntax/migration/mention/candidate/rejected 拆分的判断都很重要。
17. 接下来的工作
接下来的工作并不是直接进行 GitHub 代码标记。
首先要做的事：
- 基于
docs_chunks_v3_1.jsonl的search_text生成 embedding - 结合向量搜索 + 关键字搜索进行混合检索测试
- 基于
trusted_api_symbols、syntax_symbols、migration_mappings设计标签决定的 Python 流程 - 定义 GitHub 仓库结构化数据的输入格式
- 设计同时查看
.gd、.tscn、.tres、project.godot、README 的仓库级别判别流程 - 将 RAG 判别器结果与生成 8 类 JSONL 数据集的流水线连接
- 当远程 LLM endpoint 准备好后，连接用于修改代码/说明/SFT/DPO 候选生成的辅助
- 之后基于 Qwen 的 SFT/DPO 与 SWE Agent 轨迹学习进行扩展
今天的最终教训就是这些。
与其大量收集文档，
分离出对所收集知识的可信度并据此使用更为重要。