Retriever 检索 替代 方案 拆解 文档

编写日期：2026年 6月 28日

此目录是为了更易阅读而重新划分的文档集合，来源于 Retriever 检索 替代 ChatGPT 原文 备注。

原文备注保持原样。此 README 汇总了共同上下文、当前方式、模型候选、选择指南。子文档仅包含各替代方案的文档。

综合比较表

这些表格并非最终选择，而是 6 月 28 日用于在同一页面判断需要比较的检索替代方案的观察表。标准是 “把代码 chunk 原样放入 Retriever 时，会出现哪些 JSONL 候选，以及这些候选能否在 Qwen 验证阶段直接被认可为依据”。

一目了然的结论

PoC 仿真结果比较

演示判定中显现的差异

候选返回情况比较

False Positive / False Negative 比较

各表适用度

必须通过日志查看的内容

实现复杂度与运营成本

Qwen 放置位置比较

选择优先级

PoC 检查清单

方案文档

• 方案 A：PostgreSQL 全文检索维护
• 方案 B：仅 BM25
• 方案 C：仅 embedding
• 方案 D：BM25 + embedding 并行
• 方案 E：生成 Qwen 查询配置文件
• 方案 F：BM25 + embedding + reranker + validator

当前前提

当前基准如下。

1. zip 中包含 markdown 原始文件、模式、调试器、设计文档。
2. 本地已经有 markdown → JSONL → DB 的转换版本。
3. 现在可以看到的是转换前的 markdown 和 DB 模式/搜索流程。
4. PoC 需要将 zip 中的 markdown 像 JSONL chunk 那样拆分，并模拟可能进入本地 DB 的搜索目标。
5. 所需的不是代码框架，而是追踪当 chunk 进入时，各种搜索方式如何生成分数以及为何成功/失败。

JSONL/DB 基准

文档基准产出如下。

work/godot_rag/jsonl/docs_chunks.jsonl
work/godot_rag/jsonl/api_mapping.jsonl
work/godot_rag/jsonl/label_prototypes.jsonl
work/godot_rag/jsonl/ingest_report.jsonl

数据库不是将整行 JSONL 放入 payload jsonb，而是将 JSONL 的字段展开为表的列来理解。

docs_chunks

chunk_id
doc_version
source_url
source_file
source_sha256
doc_type
symbol
section_path
heading
content
code_blocks
language_tags
godot_version_tags
api_symbols
token_count
metadata
embedding
search_tsv

api_mapping

mapping_id
source_api
target_api
change_type
godot_from
godot_to
confidence
evidence_chunk_ids
match_terms
notes
negative_patterns

label_prototypes

prototype_id
label
task_type
input_pattern
expected_finding
recommended_action
evidence_mapping_ids
evidence_chunk_ids
severity
validator_rules
embedding
search_tsv

基准块

在替代方案比较中作为基准的块是以下的 Godot 代码。

func _process(delta):
	var velocity = Vector2.ZERO
	if Input.is_action_pressed(&"move_right"):
		velocity.x += 1
	if Input.is_action_pressed(&"move_left"):
		velocity.x -= 1

	if velocity.length() > 0:
		velocity = velocity.normalized() * speed
		$AnimatedSprite2D.play()
	else:
		$AnimatedSprite2D.stop()

	position += velocity * delta
	position = position.clamp(Vector2.ZERO, screen_size)

强令牌:

animatedsprite2d
is_action_pressed
move_left
move_right
normalized
clamp
screen_size
vector2
zero

弱令牌：

func
var
if
else
velocity
position
delta
x
0
1

搜索输入保持为原始的 chunkText。在搜索之前必需提取 Godot API signal 并将其转换为单独的 query 的做法，并不是基本设计的核心。如果有需要，只在以后作为辅助评分进行审查。

当前 /api/retrieve 方式

当前项目的 /api/retrieve 并非 BM25。

流程接近如下。

chunkText
  -> plainto_tsquery('simple', chunkText)
  -> search_tsv @@ query
  -> ts_rank_cd(...)

PostgreSQL的 ts_rank_cd 是全文检索排名函数。它不同于像 BM25 那样将词频、逆文档频率、字段长度归一化组合在一起的搜索引擎式 BM25 本身，需要另作区分。

plainto_tsquery(raw_chunk) 会从输入的 chunk 中提取标记并生成 query。基准 chunk 可以像下面这样成为一个很长的 query。

func & process & delta & var & velocity & vector2 & zero
& input & is_action_pressed & move_right & move_left
& length & normalized & speed & animatedsprite2d
& play & stop & position & clamp & screen_size

这种方式可能在一行中要求太多的标记。

如果官方文档的块被划分成如下所示，就会出现问题。

chunk A:
  Input.is_action_pressed
  velocity.normalized
  AnimatedSprite2D.play/stop

chunk B:
  AnimatedSprite2D 说明
  position.clamp
  screen_size

两者都相关，但可能并非所有令牌同时出现在同一行中。

在原始备注中，认为严格原始 AND 性质的搜索可能会像下面这样失败。

strict raw AND hits: 0

当前方式可以作为 PoC 的基准线，但作为最终搜索策略维持下来较为薄弱。下一阶段需要将当前方式与 BM25 分离后进行比较。

模型候选

voyage-code-3

被提及为最符合当前项目的 embedding 候选。

原因：

query 不是自然语言问题，而是 GDScript 代码块。  
搜索目标 JSONL 中也混杂了 code_blocks、API 名称、文档说明。

优点

• 对代码检索能力强。
• 适合处理长块（chunk）。
• 适用于 code → docs 的搜索。

缺点

• 依赖外部 API。
• 成本较高。
• 不是专门针对 Godot 的模型。

基于内存的推荐

voyage-code-3 1024 float

OpenAI text-embedding-3-large

通用高质量 embedding 候选。

优点：

• 在通用语义检索方面表现强劲。
• 对文档说明搜索稳定可靠。
• 易于与 OpenAI 生态系统集成。

缺点：

• 并非专用于代码检索。
• 基础维度较大，可能导致存储/索引成本上升。
• 对于 GDScript 块 → JSONL 的搜索，可能不如 voyage-code-3 直接。

基于内存的推荐度：

第二优先级

Gemini Embedding

通用/多语言语义检索候选。

优点：

• 适用于文档说明型检索。
• 有维度缩减的选项。
• 在多语言文档搜索方面可能具有优势。

缺点：

• 不是专用于代码检索的选项。
• 更侧重语义相似性，而非 API 代码的准确性。
• 在判断 Godot 迁移是否精确时，单独使用存在风险。

Jina embeddings v4

在复杂文档、跨模态、视觉丰富的文档检索方面具有优势的候选。

优点：

• 文档搜索范围广泛。
• 对跨模态/复合文档表现出色。
• 也可以考虑代码适配器系列。

缺点：

• 当前项目以 markdown/代码为中心。
• 图像/表格检索不是核心需求。
• 在现阶段可能是过度的选择。

基于备注的推荐度：

目前优先级较低

rerank-2.5

reranker 候选人被提及。

角色：

BM25和 embedding 带来的候选项会与原始块再次比较。  
根据相关度得分对候选项重新排序。

在此项目中预期的效果：

• 降低 2D movement 和 3D movement 的误报率。
• 更好地反映 AnimatedSprite2D、Vector2、screen_size、position.clamp 等直接上下文。
• 将 BM25 和 embedding 各自得到的候选项整理为最终候选。

注意：

• reranker 不是 validator。
• 直接依据的验证需要由 Qwen direct‑evidence validator 重新进行。

选项摘要

当前临时判断

原始备忘的结论接近于以下内容。

输入仅保留一个 chunkText。

第一次搜索使用 BM25。
  原因：在代码/API 字符串搜索中透明且强大。

第二次搜索使用 voyage-code-3 嵌入。
  原因：因为查询是代码块，适合代码检索模型。

第三次排序使用 rerank-2.5。
  原因：在 BM25 和嵌入得到的相似候选中，将真正的 chunk 对应的 JSONL 提升到上方。

最后验证使用 Qwen direct-evidence validator。
  原因：如果 JSONL 中没有与 chunk 直接匹配的字符串/模式依据，就必须舍弃。

一行摘要：

raw chunk 原样输入  
  -> BM25 + code embedding 并行候选生成  
  -> reranker 重新排序  
  -> Qwen 直接依据验证

接下来实际比较的内容

• 当前 PostgreSQL 全文检索方式在基准 chunk 中返回多少条记录
• BM25 是否真的把 first_2d_game 排到前面
• 在仅使用 BM25 时，3D movement 的误报会混入多少
• 仅使用 embedding 时会额外检索到哪些说明性文档
• 在 BM25 + embedding 联合时，如何合并重复项和分数
• reranker 是否能正确重新排序 2D/3D 候选项
• Qwen direct-evidence 验证器是否会把无关的 JSONL 实际上标记为 아니오 并丢弃