대안 D: BM25 + embedding 병렬

흐름

raw chunkText
  -> BM25 top 50
  -> embedding top 50
  -> 후보 union
  -> 점수 섞기
  -> JSONL 반환
  -> Qwen direct-evidence 검증

역할 분담

BM25가 잡는 것:

Input.is_action_pressed
AnimatedSprite2D
position.clamp
screen_size
Vector2.ZERO

embedding이 잡는 것:

player movement
2D movement tutorial
moving inside screen
animation based on movement

Qwen direct-evidence validator가 하는 것:

retrieved JSONL 안에 현재 chunk와 직접 맞는 문자열/패턴 근거가 있는지 확인
관련 없는 JSONL 폐기

장점

문자열 검색과 의미 검색의 약점을 서로 보완한다.
Qwen 없이도 1차 후보 품질이 좋아진다.
raw chunk 조건을 유지한다.
하드코딩된 Godot API signal extractor 없이도 시작할 수 있다.

단점

점수 결합 튜닝이 필요하다.
BM25 score와 vector score scale이 다르다.
reranker가 없으면 ranking이 흔들릴 수 있다.
false positive를 완전히 막지는 못한다.

기준 chunk에서 기대되는 결과

상위 후보:

first_2d_game / coding_the_player
same page / clamp section

낮추거나 검증에서 폐기해야 할 후보:

first_3d_game / player_movement_code
unrelated api_mapping
unrelated label_prototypes

PoC 시뮬레이션

기준 chunk를 두 경로로 동시에 검색한다.

raw chunkText
  -> BM25 top 50
  -> embedding top 50
  -> 후보 union
  -> 중복 병합
  -> Qwen direct-evidence 검증

BM25 top 후보 예시:

후보	BM25가 잡은 이유
`first_2d_game / coding_the_player`	`Input.is_action_pressed`, `move_left`, `move_right`, `AnimatedSprite2D.play/stop` 직접 일치
`first_2d_game / clamp section`	`position.clamp`, `Vector2.ZERO`, `screen_size` 직접 일치
`first_3d_game / player_movement_code`	입력 처리와 normalized 이동 토큰이 겹침

embedding top 후보 예시:

후보	embedding이 잡은 이유
`first_2d_game / coding_the_player`	2D player movement와 animation 의미가 가까움
`first_2d_game / clamp explanation`	player를 화면 안에 제한하는 의미가 가까움
`first_3d_game / player_movement_code`	player movement 의미가 가까움
`animation docs`	moving 상태에서 animation play/stop 의미가 가까움

후보 union 뒤에는 다음처럼 보인다.

candidate A:
  source: BM25 + embedding
  evidence: Input.is_action_pressed, AnimatedSprite2D.play/stop
  expected: accept

candidate B:
  source: BM25 + embedding
  evidence: position.clamp, Vector2.ZERO, screen_size
  expected: accept

candidate C:
  source: BM25 + embedding
  evidence: Input.is_action_pressed, move_left, move_right, normalized
  missing: AnimatedSprite2D, Vector2, screen_size
  expected: lower or reject

candidate D:
  source: embedding only
  evidence: semantic movement/animation similarity
  direct string match: weak
  expected: validator decision needed

Qwen direct-evidence validator에 넘길 때는 다음 기준으로 판단시킨다.

SOURCE_CODE 안의 실제 문자열/API 호출과
JSONL의 source_api, source_pattern, match_terms, required_when_seen_in_code, before_code,
또는 docs_chunks의 content/code_blocks/api_symbols가 직접 맞는가?

PoC에서 확인할 로그

이 대안은 union 과정이 중요하므로 다음을 보여줘야 한다.

1. BM25 후보 목록
2. embedding 후보 목록
3. union 후 중복 제거 결과
4. 각 후보가 BM25에서 왔는지 embedding에서 왔는지
5. 직접 문자열 근거 목록
6. Qwen validator의 예/아니오

눈에 보이는 결론:

BM25는 직접 API 근거를 올리고,
embedding은 설명형 후보를 보완한다.
하지만 union만으로는 false positive가 남으므로 validator가 필요하다.

판정

현실적인 중간 단계
실전 최소 권장선

reranker까지 바로 붙이기 부담스럽다면 이 대안부터 비교할 수 있다.