Альтернатива C: только внедрение

Поток

raw chunkText
  -> embedding vector
  -> docs_chunks/api_mapping/label_prototypes embedding и cosine search
  -> 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

Ожидаемые сбои в базовом чанке

Эмбеддинги могут также высоко оценивать кандидатов со схожим смыслом.

Ожидаемый ложноположительный результат:

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 screen

embedding — вероятные кандидаты для поиска:

| first_3d_game / player_movement_code | движение игрока, ввод, нормализованное направление — значение близко | false positive | | Vector math / movement tutorial | скорость, вектор, нормализованный — значение близко | maybe | | Animation player docs | воспроизведение/остановка анимации — значение близко | maybe |

заметные проблемы в embedding only:

Строка проверяется не на точное совпадение, а на близость смысла.  
Поэтому такие критерии, как 2D/3D, Godot 3/Godot 4, необходимость миграции, могут стать размытыми.

Например, документы базового чанка и 3D‑движения оба делятся следующим смыслом.

keyboard input
movement direction
normalized velocity
player movement

Однако в базовом chunk есть следующие прямые подсказки.

AnimatedSprite2D
Vector2.ZERO
position.clamp
screen_size

embedding only может не объяснять эту прямую подсказку так же прозрачно, как BM25.

Логи, которые нужно проверить в PoC

В демонстрации PoC необходимо показать следующее.

1. query chunkText
2. Резюме заголовка/содержимого кандидата документа
3. косинусное сходство
4. Список строк, непосредственно совпадающих
5. Отображение кандидатов, близких по смыслу, если нет точно совпадающих строк

Видимый вывод:

embedding дополняет описательные документы, которые BM25 упустил.  
Однако он слаб в оценке прямых доказательств, поэтому не следует использовать его отдельно.

Преимущества

• Находит, даже если выражения различаются.
• Сильный в документальном описательном контенте.
• Легко вставлять raw chunk без изменений.
• Может служить резервом, когда BM25 возвращает 0 результатов.

Недостатки

• Трудно точно определить API.
• Может смешивать различия между версиями Godot 3 и Godot 4.
• Может смешивать контекст 2D/3D.
• Трудно объяснить, почему получен такой результат.
• api_mapping имеет высокий риск ложных срабатываний.

Оценка

Запрещено использовать отдельно  
Используется для дополнения кандидатов BM25