方案 C：仅嵌入
流程
raw chunkText
-> embedding vector
-> docs_chunks/api_mapping/label_prototypes embedding 与余弦搜索
-> 返回 top JSONL为什么需要 embedding
BM25 对精确字符串很强，但如果说明文字和代码表示不同，效果可能会变差。
例如，chunk 中包含以下代码。
position = position.clamp(Vector2.ZERO, screen_size)文档中可能会有如下说明。
prevent the player from leaving the screen
clamping a value means restricting it to a given range在这种情况下，embedding 可以捕获语义关联。
在基准块中预期的成功
embedding 有可能找到以下主题。
2D player movement
moving inside screen
animation based on movement
player movement tutorial基准块中预期的失败
embedding 可以同时给出意义相似的候选项较高的分数。
预期的误报：
3D player movement
scripting player input
vector math
animation player docs即如果“player movement”意义相似，就可以模糊2D/3D的区别。
PoC 模拟
将基准 chunk 转换为 embedding 向量。
输入意义：
2D player movement
keyboard input
velocity normalization
animation while moving
keep player inside screenembedding可能找到的高概率候选：
| 候选 | 为何出现 | 判断 |
|---|---|---|
first_2d_game / coding_the_player |
2D玩家移动、输入、动画、屏幕限制的含义相近 | accept |
first_2d_game / clamp explanation |
防止玩家离开屏幕的含义相近 | accept |
first_3d_game / player_movement_code |
玩家移动、输入、归一化方向的含义相近 | false positive |
Vector math / movement tutorial |
速度、向量、归一化的含义相近 | maybe |
Animation player docs |
播放/停止动画的含义相近 | maybe |
仅在embedding中显著的问题：
更关注字符串的意义是否接近，而不是是否完全匹配。
因此，像 2D/3D、Godot3/Godot4、是否迁移等需要精确区分的标准可能会变得模糊。例如，基准块和 3D movement 文档共享以下含义。
keyboard input
movement direction
normalized velocity
player movement但是基准块有以下直接线索。
AnimatedSprite2D
Vector2.ZERO
position.clamp
screen_sizeembedding only可能无法像 BM25 那样透明地解释这个直接线索。
PoC中需要确认的日志
在 embedding PoC 中应当显示如下。
1. query chunkText
2. 候选文档 标题/内容 摘要
3. 余弦相似度
4. 直接匹配的字符串列表
5. 没有直接匹配的字符串，但显示意义相近的候选项眼前的结论：
embedding是对BM25遗漏的说明性文档的补充。
但是在直接依据判定方面较弱，不能单独使用。优点
- 表达不同也能找到。
- 对文档说明型内容强大。
- 可以直接放入原始块。
- 当 BM25 为 0 条时可以作为 fallback。
缺点
- 对准确的 API 判断较弱。
- 可能混淆 Godot 3 与 Godot 4 版本差异。
- 可能混合 2D/3D 上下文。
- 难以解释为何得到该结果。
- 在
api_mapping中存在较大的误报风险。
判定
禁止单独使用
用于补充 BM25 候选