Alternative C : intégration uniquement

Flux

raw chunkText
  -> embedding vector
  -> docs_chunks/api_mapping/label_prototypes embedding et recherche cosinus
  -> top JSONL retourné

Pourquoi un embedding est‑il nécessaire

BM25 est robuste pour les correspondances exactes, mais il peut devenir faible lorsque la description et la représentation du code diffèrent.

Par exemple, le chunk contient le code suivant.

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

Le document peut être décrit comme suit.

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

Dans ce cas, l'embedding peut saisir les connexions sémantiques.

Succès attendu à partir du chunk de référence

L'embedding a la possibilité de trouver le sujet suivant.

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

Échec attendu dans le chunk de référence

l'embedding peut également attribuer un score élevé à des candidats dont le sens est similaire.

Faux positif prévu :

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

En d'autres termes, si le sens de « player movement » est similaire, on peut estomper la différence entre 2D et 3D.

Simulation PoC

Convertir le chunk de référence en vecteur d'embedding.

Signification de l'entrée:

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

Candidats les plus susceptibles d'être trouvés par l'embedding :

| first_3d_game / player_movement_code | mouvement du joueur, entrée, direction normalisée, signification proche | false positive | | Vector math / movement tutorial | vélocité, vecteur, normalisé, signification proche | maybe | | Animation player docs | lecture/arrêt d'animation, signification proche | maybe |

Problèmes remarquables dans embedding only:

On regarde si le sens est proche plutôt que si la chaîne correspond exactement.  
Ainsi, des critères qui doivent être clairement séparés, comme 2D/3D, Godot3/Godot4, ou la nécessité de migration, peuvent devenir flous.

Par exemple, le chunk de référence et le document de mouvement 3D partagent tous les deux la même signification.

keyboard input
movement direction
normalized velocity
player movement

Cependant, le chunk de référence contient les indices directs suivants.

AnimatedSprite2D
Vector2.ZERO
position.clamp
screen_size

embedding only ne peut pas expliquer directement cet indice aussi clairement que BM25.

Journaux à vérifier dans le PoC

Dans le PoC d'embedding, il faut afficher les éléments suivants.

1. query chunkText  
2. Résumé du titre/contenu du document candidat  
3. similarité cosinus  
4. Liste des chaînes correspondantes exactes  
5. Afficher les candidats proches en sens lorsqu'aucune chaîne exacte ne correspond

Conclusion visible :

Les embeddings complètent les documents descriptifs que BM25 a manqués.  
Cependant, ils sont faibles pour le jugement de preuves directes, il ne faut donc pas les utiliser seuls.

Avantages

• Même si l'expression diffère, il trouve.
• Il est fort pour le contenu de type description de documentation.
• Il est facile d'insérer le chunk brut tel quel.
• Peut servir de secours lorsque BM25 renvoie 0 résultat.

Inconvénients

• Le jugement d'API précis est faible.
• Les différences entre les versions Godot 3/Godot 4 peuvent être mélangées.
• Le contexte 2D/3D peut être mélangé.
• Il est difficile d'expliquer pourquoi ce résultat est apparu.
• Dans api_mapping, le risque de faux positifs est élevé.

Jugement

**Interdiction d’utilisation exclusive**  
Utilisé pour compléter les candidats BM25