Retriever 検索 代替 分解 文書

作成日: 2026年 6月 28日

このディレクトリは Retriever 検索 代替 ChatGPT 原文 メモ を見やすく再分割した文書束です。

原文メモはそのまま保存します。この README には共通コンテキスト、現在の方式、モデル候補、選択ガイドをまとめました。下位文書は代替別の文書だけを置きます。

総合比較表

これらの表はまだ最終選択肢ではなく、6月 28日 の比較対象となる検索代替を一画面で判断するための観察表です。基準は「コードチャンクをそのまま Retriever に入れたときにどの JSONL 候補が上がり、その候補が Qwen 検証段階で直接根拠として認められるか」です。

一目で分かる結論

PoC シミュレーション結果比較

デモ判定で明らかになった差異

候補返却傾向比較

False Positive / False Negative の比較

テーブル別適合度

ログで必ず見るべきこと

実装複雑度と運用コスト

Qwen をどこに置くか比較

選択優先順位

PoC チェックリスト

代替案ドキュメント

• 代替案 A: PostgreSQL full-text 維持
• 代替案 B: BM25 only
• 代替案 C: embedding only
• 代替案 D: BM25 + embedding 並列
• 代替案 E: Qwen query profile 作成
• 代替案 F: BM25 + embedding + reranker + validator

現在の前提

現在の基準は次のとおりである。

1. zip の中には markdown の原本、スキーマ、デバッガ、設計文書があります。  
2. ローカルにはすでに markdown → JSONL → DB 変換版が入っています。  
3. 今見ることができるのは変換前の markdown と DB スキーマ/検索フローです。  
4. PoC は zip 内の markdown を JSONL チャンクのように分割し、ローカル DB に入っていたであろう検索対象をシミュレートする必要があります。  
5. 必要なのはコードの骨格ではなく、チャンクが入ったときに各検索方式がどのようにスコアを作り、なぜ成功/失敗するかを追跡することです。

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

DBは JSONL の1行全体を 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 シグナルを必ず抽出して別のクエリに変換する方式は、基本設計の核心とはしない。必要であれば後で補助スコア程度に検討する。

現在の /api/retrieve 方法

現在のプロジェクトの /api/retrieve は BM25 ではない。

流れは次に近い。

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

PostgreSQLの ts_rank_cd は full-text ランキング関数です。BM25 のように term frequency、inverse document frequency、field length normalization を組み合わせた検索エンジン式 BM25 そのものとは異なるものとして考える必要があります。

plainto_tsquery(raw_chunk) は入力チャンクからトークンを抽出してクエリを作成します。基準となるチャンクは次のように長いクエリになることがあります。

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

この方式は1行にあまりにも多くのトークンを要求する可能性があります。

公式ドキュメントのチャンクが次のように分割されていると問題が生じます。

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

chunk B:
  AnimatedSprite2D の説明
  position.clamp
  screen_size

両方とも関連していますが、1つの行にすべてのトークンが同時に含まれていない可能性があります。

原文メモでは、strict raw AND 性質の検索が以下のように失敗する可能性があると考えられています。

strict raw AND hits: 0

現在の方式は PoC の基準線としては見ることができますが、最終的な検索戦略として維持するには弱いです。次のステップでは現在の方式と BM25 を分離して比較する必要があります。

モデル候補

voyage-code-3

現在のプロジェクトに最も適した埋め込み候補として言及されました。

理由：

queryが自然言語の質問ではなく、GDScriptコードチャンクです。  
検索対象のJSONLにもcode_blocks、API名、ドキュメント説明が混在しています。

利点:

• code retrieval に強い。
• 長いチャンクの処理に有利。
• code → docs 検索に適している。

欠点:

• 外部 API への依存がある。
• コストがかかる。
• Godot 特化モデルではない。

メモ基準の推奨:

voyage-code-3 1024 float

OpenAI text-embedding-3-large

汎用高品質埋め込み候補。

長所:

• 汎用セマンティック検索に強い。
• 文書説明検索が安定している。
• OpenAI エコシステムと結合しやすい。

短所:

• コード検索専用ではない。
• 基本次元が大きく、保存/インデックスコストが増加する可能性がある。
• GDScript チャンク → JSONL 検索は voyage-code-3 より直接的でない場合がある。

メモ基準の推奨度:

第2優先順位

Gemini Embedding

汎用/多言語セマンティック検索候補。

長所:

• 文書説明型検索に適している。
• 次元削減の選択肢がある。
• 多言語文書検索に強みがある可能性がある。

短所:

• コード検索専用の選択肢ではない。
• APIコードの正確性より意味的類似性に近い。
• Godot 移行の正確な判断には単独使用は危険がある。

Jina embeddings v4

複雑な文書、マルチモーダル、ビジュアルリッチな文書検索に強みがある候補。

長所:

• 文書検索の幅が広い。
• マルチモーダル/複合文書に強い。
• コードアダプタ系も検討可能。

短所:

• 現在のプロジェクトは markdown/コード中心である。
• 画像/表の検索が主目的ではない。
• 現段階では過剰な選択になる可能性がある。

メモ基準の推奨度:

今は優先度が低い

rerank-2.5

reranker 候補として言及された。

役割:

BM25とembeddingが取得した候補をraw chunkと共に再比較する。  
関連度スコアで候補を再順位付けする。

このプロジェクトで期待される効果:

• 2D movement と 3D movement の false positive を低減する。
• AnimatedSprite2D、Vector2、screen_size、position.clamp のような直接的文脈をよりよく反映させる。
• BM25 と embedding がそれぞれもたらした候補を最終候補として整理する。

注意:

• reranker は validator ではない。
• 直接根拠の検証は Qwen direct‑evidence validator が再度行う必要がある。

選択肢要約

現在の暫定判断

原文メモの結論は次に近い。

入力は chunkText を一つだけ保持する。

1次検索は BM25 で行う。  
  理由：コード/API 文字列検索に対して透明で強力であるため。

2次検索は voyage-code-3 埋め込みで行う。  
  理由：クエリがコードのチャンクであるため、コード検索モデルが適しているから。

3次ソートは rerank-2.5 で行う。  
  理由：BM25 と埋め込みがもたらした類似候補の中から、実際のチャンクに合致する JSONL を上位に持ってくるためである。

最後の検証は Qwen direct-evidence バリデータで行う。  
  理由：JSONL 内にチャンクと直接合致する文字列/パターンの根拠がなければ破棄しなければならないから。

一行要約：

raw chunk をそのまま入力
  -> BM25 + code embedding 並列候補生成
  -> reranker 再配置
  -> Qwen 直接根拠検証

次に実際に比較すること

• 現在の PostgreSQL フルテキスト方式が基準チャンクで何件返すか
• BM25 が first_2d_game を実際に上位に上げるか
• BM25 only で 3D movement の偽陽性がどれだけ混ざるか
• embedding only がどのような説明文書を追加で取得するか
• BM25 + embedding union で重複とスコアをどう合成するか
• reranker が 2D/3D 候補を適切に再順位付けするか
• Qwen direct-evidence validator が関係ない JSONL を実際に 아니오（いいえ）として捨てるか