Alternative C: Nur Einbetten

Ablauf

raw chunkText
  -> Einbettungsvektor
  -> docs_chunks/api_mapping/label_prototypes Einbettung und Kosinus‑Suche
  -> Top JSONL zurückgeben

Warum Einbettungen benötigt werden

BM25 ist stark bei genauen Zeichenketten, kann jedoch schwächer werden, wenn Beschreibungen und Code‑Darstellungen unterschiedlich sind.

Zum Beispiel enthält das Chunk den folgenden Code.

position = position.clamp(Vector2.ZERO, screen_size)

Im Dokument kann es wie folgt beschrieben sein.

prevent the player from leaving the screen
clamping a value means restricting it to a given range

In diesem Fall kann das Embedding die Bedeutungsverbindung erfassen.

Erwarteter Erfolg im Basis-Chunk

Das Embedding könnte das nächste Thema finden.

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

Erwartete Fehler im Standard‑Chunk

Embedding kann auch Kandidaten, die inhaltlich ähnlich sind, gleichzeitig hoch bewerten.

Erwartete Fehlalarm:

3D player movement
scripting player input
vector math
animation player docs

Das heißt, wenn die Bedeutung von „player movement“ ähnlich ist, kann der Unterschied zwischen 2D und 3D verwischt werden.

PoC‑Simulation

Konvertiere den Basis‑Chunk in einen Einbettungsvektor.

Eingabebedeutung:

2D player movement
keyboard input
velocity normalization
animation while moving
keep player inside screen

Mögliche Kandidaten, die das Embedding wahrscheinlich findet:

Kandidat	Warum erscheint es	Bewertung
`first_2d_game / coding_the_player`	2D-Spielerbewegung, Eingabe, Animation, Bildschirmbegrenzung Bedeutung ist ähnlich	accept
`first_2d_game / clamp explanation`	Bedeutet, dass der Spieler nicht aus dem Bildschirm herausgehen kann, Bedeutung ist ähnlich	accept
`first_3d_game / player_movement_code`	Spielerbewegung, Eingabe, normalisierte Richtung Bedeutung ist ähnlich	false positive
`Vector math / movement tutorial`	Geschwindigkeit, Vektor, normalisiert Bedeutung ist ähnlich	maybe
`Animation player docs`	Abspielen/Stoppen von Animationen Bedeutung ist ähnlich	maybe

Auffällige Probleme bei reinem Embedding:

Man prüft eher, ob die Bedeutung nahe liegt, als ob die Zeichenkette exakt übereinstimmt.  
Deshalb kann das Kriterium, das genau unterschieden werden muss, wie 2D/3D, Godot3/Godot4 oder ob eine Migration nötig ist, verschwimmen.

Zum Beispiel teilen das Referenz‑Chunk und das 3D‑Bewegungsdokument dieselbe Bedeutung.

keyboard input
movement direction
normalized velocity
player movement

Allerdings enthält der Referenz‑Chunk den folgenden direkten Hinweis.

AnimatedSprite2D
Vector2.ZERO
position.clamp
screen_size

embedding only kann diesen direkten Hinweis möglicherweise nicht so transparent wie BM25 erklären.

Protokolle, die im PoC zu überprüfen sind

Im Embedding-PoC muss Folgendes angezeigt werden.

1. Abfrage chunkText  
2. Zusammenfassung von Kandidatendokument Überschrift/Inhalt  
3. Kosinus‑Ähnlichkeit  
4. Liste der exakt übereinstimmenden Zeichenketten  
5. Anzeige von Kandidaten, die keine exakte Übereinstimmung haben, aber inhaltlich nahe liegen

Sichtbare Schlussfolgerung:

Embedding ergänzt erklärende Dokumente, die BM25 verpasst hat.  
Jedoch ist es schwach bei der direkten Evidenzbewertung, daher sollte es nicht allein verwendet werden.

Vorteile

Auch wenn die Formulierung unterschiedlich ist, wird gefunden.
Starke Leistung bei dokumentationsbeschreibendem Inhalt.
Roh‑Chunks können unverändert eingefügt werden.
Kann als Fallback dienen, wenn BM25 keine Treffer liefert.

Nachteile

Die genaue API‑Bestimmung ist schwach.
Unterschiede zwischen Godot 3‑ und Godot 4‑Versionen können vermischt werden.
2D‑/3D‑Kontexte können vermischt werden.
Es ist schwer zu erklären, warum dieses Ergebnis entstanden ist.
In api_mapping besteht ein hohes Risiko für Fehlalarme.

Einzelverwendung verboten  
Zur Ergänzung von BM25‑Kandidaten verwenden