idea_world_labDEV JOURNAL
dimanche 28 juin 2026

Retriever recherche alternatives décomposition de documents

Date de rédaction : 28 juin 2026

Ce répertoire est un ensemble de documents découpés pour rendre plus lisible le mémo original ChatGPT sur les alternatives de recherche Retriever.

Le mémo original est conservé tel quel. Ce README regroupe le contexte commun, la méthode actuelle, les candidats de modèle et le guide de sélection. Les sous‑documents contiennent uniquement les documents propres à chaque alternative.

Tableau comparatif global

Ces tableaux ne constituent pas encore une décision finale, mais servent d’observations pour juger, en une seule vue, les alternatives de recherche à comparer le 28 juin. Le critère est : « quand on injecte le chunk de code tel quel dans le Retriever, quel candidat JSONL apparaît, et ce candidat peut‑il être accepté comme preuve directe lors de l’étape de validation Qwen ? »

Conclusion d’un coup d’œil

Alternative Position Rôle attendu Niveau de maturité Atout principal Risque principal Jugement actuel
A. PostgreSQL full‑text maintenu Baseline /api/retrieve actuelle Vérifier jusqu’où va la recherche implémentée Élevé Déjà intégré, les logs sont immédiatement visibles Si un long chunk devient la requête, des documents pertinents peuvent être omis Conserver comme baseline, sans l’imposer comme solution finale
B. BM25 uniquement Candidat de première recherche Trouver les documents contenant directement les chaînes de code/API Moyen Fort sur les chaînes littérales comme KinematicBody2D, move_and_slide, AnimatedSprite2D Les mots larges (ex. 2D/3D) entraînent des faux positifs Bon point de départ pour le premier PoC
C. embedding uniquement Extension sémantique du rappel Trouver des documents explicatifs même si la chaîne n’est pas identique Moyen Capture le sens des phrases, les tutoriels, les contextes d’usage similaires Risque élevé d’utiliser seul pour juger version/API Utiliser comme rappel auxiliaire plutôt qu’unique
D. BM25 + embedding Compromis réaliste Combiner preuves textuelles et sémantiques Moyen Allie précision BM25 et rappel embedding Nécessite combinaison de scores, déduplication, critères de sélection supérieurs Proche de la solution minimale viable
E. Profil de requête Qwen Expérience d’assistance à la recherche Générer un JSON d’intention à partir du chunk de code Faible Le profil de requête est lisible par un humain L’LLM peut créer des API/intention inexistantes avant la recherche À garder comme expérimentation/assistant, pas comme cœur de première recherche
F. BM25 + embedding + reranker + validator Structure candidat finale Générer, ré‑ordonner et valider les preuves directement Faible Meilleure qualité et observabilité Coût, latence, nombre d’étapes Candidat final visé

Comparaison des résultats de simulation PoC

Alternative Chunk d’entrée Mode de génération des candidats Probabilité d’obtenir le JSONL pertinent Probabilité d’inclure des JSONL non pertinents État attendu avant validation Qwen État attendu après validation Qwen
A chunkText complet plainto_tsquery('simple', chunkText) crée une requête longue Faible ou instable Faible, mais s’il n’y a aucun résultat, aucun candidat à observer Aucun ou quelques candidats retournés Risque de perte avant la validation de preuve directe
B chunkText complet Classement BM25 par token Élevé Moyen Des documents comme Input.is_action_pressed, AnimatedSprite2D, clamp peuvent apparaître Écarté si la chaîne exacte manque
C chunkText complet Similarité d’embedding code/document Moyen Élevé Des docs sur “movement”, “2D”, “player” apparaissent largement Écarté si le JSONL ne contient pas la chaîne exacte
D chunkText complet Fusion des candidats BM25 et embedding Élevé Moyen On voit à la fois les candidats textuels et sémantiques Ne restent que les candidats avec preuve directe
E chunkText complet interprété par Qwen Recherche via le profil généré par Qwen Moyen si le profil correspond Élevé Des API absentes du profil peuvent se glisser Le profil doit être vérifié pour correspondre au code réel
F chunkText complet Reranker ré‑ordonne les candidats BM25 + embedding Élevé Faible Même si beaucoup de candidats, les meilleurs sont filtrés Qwen ne garde que les preuves “oui/non” directes

Différences révélées lors du jugement de démonstration

Situation observée Prompt simple initial Prompt direct avec preuve Signification pour la structure de recherche
Code Godot 3 + JSONL pertinent “Oui” peut apparaître “Oui” doit apparaître Passage si la preuve correspond réellement à la chaîne/API
Code Godot 3 + JSONL non pertinent Le mot large “Godot” peut produire “Oui” “Non” doit apparaître Risque si aucune validation de preuve directe n’est faite
Code KinematicBody2D + mapping 3D Spatial Peut être considéré pertinent sous le sens large “migration Godot” “Non” est correct Embedding seul ou jugement LLM lâche crée des faux positifs
Code yield(...) + prototype await “Oui” si le motif direct existe “Oui” label_prototypes peut servir de preuve de changement de motif global
Code AnimatedSprite2D.play() + docs d’animation généraux Peut sembler sémantiquement lié “Non” si le JSONL ne contient pas la chaîne/motif exact Même les chunks de docs nécessitent une validation de preuve directe

Comparaison des comportements de retour des candidats

Alternative Candidats qui remontent en haut Candidats souvent manqués Candidats fréquemment mélangés Points à vérifier visuellement
A Documents contenant de nombreux tokens de la requête dans une même ligne Quand les tokens pertinents sont répartis sur plusieurs documents Rare si la requête est trop stricte Pourquoi 0 résultat ? Quels tokens ont cassé le matching ?
B Lignes contenant directement le nom d’API, fonction ou nœud Docs descriptifs où le libellé a changé Docs d’autres systèmes partageant les mêmes mots Correspondance entre match_terms et la chaîne source du chunk
C Tutoriels ou explications sémantiquement proches Mapping API exact très court Docs où la version Godot ou 2D/3D diffère Le score cosinus est‑il accompagné d’une preuve textuelle directe ?
D Candidats exacts + sémantiques Candidats relégués par la combinaison de scores Candidats où les deux recherches sont faiblement alignées Provenance du candidat : BM25 ou embedding ?
E Candidats correspondant à l’intention extraite par Qwen Indices de code réels non inclus dans le profil API/intention imaginées par Qwen Chaque champ du profil apparaît‑t‑il réellement dans le chunk ?
F Candidats que le reranker estime pertinents pour le chunk Cas particuliers Godot inconnus du modèle de reranker Candidats avec haut score de rerank mais aucune preuve directe dans le JSONL Divergence entre le score de rerank et la décision du validator

Comparaison des faux positifs / faux négatifs

Alternative Exemple de faux positif Exemple de faux négatif Méthode de réduction
A Rarement, mais si la requête est trop large, des documents de mouvement généraux sont mélangés Si les documents pertinents sont répartis sur plusieurs lignes, aucun résultat Modifier la façon de générer la requête ou ajouter des candidats BM25
B movement, player, 2d entraînent le mélange d’autres documents de mouvement Si le nom de l’API n’apparaît que sous forme descriptive dans le document, il est omis Séparer les stop‑words / tokens faibles, pondérer directement les tokens d’API
C Des documents 3D ou d’autres versions au sens similaire sont mélangés Les lignes de renommage d’API courtes ne sont pas détectées Utiliser BM25 en parallèle et ajouter un validateur
D Des candidats faiblement correspondants apparaissent à la fois dans BM25 et l’embedding Si le critère de fusion est erroné, un côté des candidats est écrasé Conserver le drapeau de source d’union et le journal de preuves directes
E Qwen crée un migration_intent inexistant, contaminant les candidats Qwen omet les indices de code réels dans le profil Ne pas faire confiance au profil avant la recherche, l’utiliser seulement comme aide
F Le reranker surestime les explications plausibles Aucun document n’est récupéré à l’étape de génération des candidats Garantir un nombre suffisant de candidats et placer la validation Qwen en dernier

Pertinence par tableau

Alternative docs_chunks api_mapping label_prototypes Remarques
A Instable avec les documents très détaillés Si la ligne de correspondance exacte est courte, elle peut être manquée Si la ligne de motif est courte, elle peut être manquée Baseline pour identifier les limites de la méthode actuelle
B Bon pour la recherche API/titre/token Bon pour la recherche exacte d’API source/cible Bon pour la recherche de motifs source/cible Les trois tableaux sont utiles comme premiers candidats de recherche
C Bon pour le rappel des documents descriptifs Faible pour les lignes courtes comme les renommages d’API Peut être utilisé en complément si les motifs d’utilisation sont similaires Le support de docs_chunks est le plus naturel
D Récupère tous les candidats texte et chaîne Combine correspondance exacte et candidats sémantiques Large couverture des motifs d’utilisation complets Structure commune aux trois tableaux, la plus polyvalente
E Si le profil de requête est bon, recherche de documents descriptifs possible Risqué si des API hallucinated sont introduites Peut créer des prototypes d’intention mais risque de contamination Plus un test d’observation/complément que le cœur de la recherche
F Bon pour affiner les preuves descriptives finales Bon pour affiner les preuves de migration Bon pour affiner les preuves de changement d’utilisation Facile à traiter les trois tableaux dans le même pipeline

Journaux à consulter impérativement

Alternative Journal avant recherche Journal pendant recherche Journal après recherche Points de vérification des causes d’échec
A chunkText brut, tsquery généré Nombre de hits search_tsv @@ query, ts_rank_cd Ligne retournée, score La requête est‑elle devenue trop longue ? Quels tokens manquent dans la ligne ?
B chunkText brut, liste de tokens Fréquence des termes, termes correspondants, score BM25 Top‑k par tableau Les tokens forts et faibles sont‑ils bien distingués ?
C chunkText brut, modèle d’embedding Distance vectorielle / score cosinus Top‑k sémantique Le candidat correspond‑il uniquement au sens sans texte réel ?
D Top‑k BM25, top‑k embedding Union, fusion des doublons, score fusionné Liste de candidats avec drapeaux source Pourquoi les candidats provenant d’une seule recherche ont‑ils survécu ?
E Chunk brut envoyé à Qwen Profil de requête Qwen au format JSON Résultats de recherche basés sur le profil Le champ de profil existe‑t‑il réellement dans la source ?
F Tous les candidats BM25/embedding Score de rerank, ordre de rerank Réponse Qwen « oui/non », raison du rejet Pourquoi les candidats passés par le reranker ont‑ils échoué à la validation de preuve directe ?

Complexité de mise en œuvre et coût opérationnel

Alternative Volume de mise en œuvre Modifications DB Coût du modèle externe Latence Difficulté de débogage Facilité de correction en cas d’échec
A Faible Pratiquement aucune Aucun Faible Faible Faible. Cependant, les limites de performance peuvent être structurelles
B Moyen Nécessite le choix du moteur/index BM25 Aucun ou faible Faible Faible Élevé. Ajustement possible des tokens/pondérations
C Moyen Colonnes/index d’embedding requis Présent Moyen Moyen Moyen. Nécessite réglage du modèle, des dimensions, du seuil
D Moyen à élevé Besoin à la fois de BM25 et de vecteur Présent Moyen Moyen Élevé. Possibilité de séparer le chemin de recherche qui a échoué
E Moyen Le stockage du profil est optionnel Présent Élevé Élevé Faible. Reproduire pourquoi le profil LLM était erroné peut être difficile
F Élevé Nécessite logs BM25 + vecteur + rerank Présent Élevé Élevé Élevé. La présence de logs à chaque étape indique où intervenir

Comparaison du placement de Qwen

Position Avantages Risques Mode d’utilisation actuel le plus adapté
Génération de requête avant recherche Permet de créer l’intention de recherche sans codage dur Peut créer des indices inexistants et contaminer la recherche Réservé aux expérimentations
Validation directe après génération de candidats Filtre les résultats pour vérifier la correspondance avec le code réel Coût d’appel supplémentaire Priorité maximale
Génération de réponse finale Produit des explications de code / réponses de migration Si les preuves sont fausses, la réponse le sera aussi Après les candidats JSONL validés
Intégration de la décision globale Produit une conclusion lisible par l’humain Peut masquer les échecs intermédiaires Après accumulation suffisante de logs, révision

Priorité de sélection

Priorité Option Raison Questions à vérifier à ce stade
1 Mesurer par rapport à la baseline A Identifier où l’implémentation actuelle échoue Combien de lignes le mode actuel renvoie‑t‑il réellement ?
2 Ajouter B comme PoC séparé La recherche de chaînes code/API est la plus explicable KinematicBody2D, yield, move_and_slide trouvent‑ils les bonnes lignes ?
3 Comparer C comme rappel complémentaire Peut élargir les candidats descriptifs de docs_chunks Dans quelle mesure les candidats sémantiques échouent‑ils à la validation directe ?
4 Générer des candidats en parallèle avec D Structure minimale réaliste La qualité s’améliore‑t‑elle en combinant BM25 et embedding ?
5 Ajouter reranker/validator avec F Vérification finale de la qualité Le jugement direct de Qwen élimine‑t‑il de façon fiable les JSONL non pertinents ?
En attente E Risque élevé de contamination par LLM avant recherche Le profil est‑il créé uniquement à partir des chaînes de code réelles ?

Checklist PoC

Élément de vérification Écran/journal à vérifier Critère de succès
Mettre le même chunkText dans plusieurs alternatives Zone de saisie du chunk du débogueur web L'entrée ne change pas selon l'alternative
Bouton de recherche par table Boutons docs_chunks, api_mapping, label_prototypes Les candidats diffèrent par table même avec le même chunk
Vérification des candidats bruts Payload JSONL retourné Le champ correspond à la chaîne réelle du chunk source
Vérification Qwen Zone de débogage prompt + chunk + jsonl Les candidats pertinents affichent “Oui”, les non pertinents “Non”
Vérification du motif de rejet Journal des résultats du validateur Les candidats ne contenant que des mots généraux comme Godot, migration, 2D sont éliminés
Collecte de faux positifs Liste des candidats éliminés Peut être utilisée plus tard pour améliorer les règles de requête/jeton/validateur
Enregistrement de la comparaison par alternative Journal d’observation ou JSON de résultat Les différences A‑F pour la même entrée sont conservées

Documents d'alternative

Hypothèse actuelle

Les critères actuels sont les suivants.

1. Le zip contient le markdown original, le schéma, le débogueur et la documentation de conception.  
2. Le local possède déjà la version convertie markdown → JSONL → DB.  
3. Ce que l’on peut voir actuellement, c’est le markdown avant conversion et le schéma/flux de recherche de la base de données.  
4. Le PoC doit découper le markdown du zip en morceaux similaires à des chunks JSONL, puis simuler les cibles de recherche qui auraient pu être insérées dans la base de données locale.  
5. Ce qui est nécessaire, ce n’est pas le squelette du code, mais le suivi de la façon dont chaque méthode de recherche génère un score et pourquoi elle réussit ou échoue lorsqu’un chunk est inséré.

JSONL/DB critères

Les livrables basés sur le document sont les suivants.

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

La base de données n'est pas structurée pour insérer une ligne JSONL entière dans payload jsonb, mais plutôt pour déployer les champs JSONL en tant que colonnes de la table.

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

Chunk de référence

Le chunk utilisé comme référence dans la comparaison des alternatives est le code Godot suivant.

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)

Token fort :

animatedsprite2d
is_action_pressed
move_left
move_right
normalized
clamp
screen_size
vector2
zero

Token faible :

func
var
if
else
velocity
position
delta
x
0
1

La saisie de recherche reste telle quelle chunkText. Avant la recherche, extraire obligatoirement le signal de l’API Godot pour le transformer en requête séparée n’est pas considéré comme un élément central de la conception de base. Si nécessaire, on l’examinera plus tard uniquement comme un score auxiliaire.

Méthode actuelle /api/retrieve

Le /api/retrieve du projet actuel n’est pas BM25.

Le flux est proche de ce qui suit.

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

PostgreSQL ts_rank_cd est une fonction de classement en texte intégral. Contrairement à BM25, qui combine la fréquence des termes, la fréquence inverse des documents et la normalisation de la longueur du champ selon une approche typique des moteurs de recherche, il faut le considérer différemment.

plainto_tsquery(raw_chunk) extrait des jetons du fragment d’entrée pour créer une requête. Le fragment de référence peut devenir une requête longue comme suit.

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

Cette méthode peut exiger trop de jetons dans une seule ligne.

Il y a un problème si le chunk de la documentation officielle est divisé comme suit.

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

chunk B:
  Description d'AnimatedSprite2D
  position.clamp
  screen_size

Les deux sont liés, mais il se peut qu’une même ligne ne contienne pas tous les jetons simultanément.

Dans la note originale, on considère qu’une recherche de type strict raw AND peut échouer comme suit.

strict raw AND hits: 0

La méthode actuelle peut être considérée comme une ligne de base pour le PoC, mais elle est trop faible pour être maintenue comme stratégie de recherche finale. À l'étape suivante, il faut comparer séparément la méthode actuelle et BM25.

Candidats de modèle

voyage-code-3

Il a été mentionné comme le candidat d'embedding le mieux adapté au projet actuel.

Raison:

La requête n'est pas une question en langage naturel, mais un bloc de code GDScript.  
Le JSONL cible de recherche contient également des blocs de code, des noms d'API et des descriptions de documentation mélangés.

Avantages :

  • Est fort en récupération de code.
  • Est avantageux pour le traitement de gros morceaux.
  • Convient à la recherche code → docs.

Inconvénients :

  • Dépend d'une API externe.
  • Coûte cher.
  • Ce n'est pas un modèle spécialisé pour Godot.

Recommandation basée sur les notes :

voyage-code-3 1024 float

OpenAI text-embedding-3-large

Candidat d'embedding polyvalent de haute qualité.

Avantages :

  • Fort pour la recherche sémantique polyvalente.
  • Stable pour la recherche de descriptions de documents.
  • Facile à intégrer avec l'écosystème OpenAI.

Inconvénients :

  • Ce n'est pas dédié uniquement à la récupération de code.
  • La dimension de base est grande, ce qui peut augmenter les coûts de stockage/indice.
  • La recherche de chunks GDScript → JSONL peut être moins directe que voyage-code-3.

Recommandation basée sur la mémoire :

2e priorité

Gemini Embedding

Candidat de récupération sémantique universel/multilingue.

Avantages :

  • Idéal pour la récupération de type description de documents.
  • Offre des options de réduction de dimension.
  • Peut présenter des points forts pour la recherche de documents multilingues.

Inconvénients :

  • Ce n’est pas une option dédiée uniquement à la récupération de code.
  • Priorise la similarité sémantique plutôt que la précision du code API.
  • L’utilisation exclusive comporte des risques pour le jugement exact de la migration Godot.

Jina embeddings v4

Candidat avec des points forts pour la récupération de documents complexes, multimodaux et visuellement riches.

Avantages :

  • Large éventail de recherche de documents.
  • Performant pour les documents multimodaux/combinés.
  • La gamme d’adaptateurs de code peut également être examinée.

Inconvénients :

  • Le projet actuel est centré sur le markdown/le code.
  • La récupération d’images/tableaux n’est pas l’objectif principal.
  • À ce stade, cela pourrait être un choix excessif.

Recommandation basée sur les notes :

Pour le moment, priorité basse

rerank-2.5

Mentionné comme candidat au reranker.

Rôle :

Comparer à nouveau les candidats obtenus par BM25 et l'embedding avec le raw chunk.  
Réordonner les candidats selon le score de pertinence.

Ce projet vise les effets suivants :

  • Réduire les faux positifs du mouvement 2D et du mouvement 3D.
  • Mieux refléter le contexte direct tel que AnimatedSprite2D, Vector2, screen_size, position.clamp.
  • Organiser les candidats fournis par BM25 et l’embedding en candidats finaux.

Attention :

  • Le reranker n’est pas un validateur.
  • La validation des preuves directes doit être refaite par le validateur Qwen direct‑evidence.

Résumé des options

Alternative Flux Avantages Risques
A Maintien du texte intégral PostgreSQL Déjà implémenté Possibilité de 0 résultat sur de longs fragments, pas BM25
B BM25 uniquement Transparence, robuste aux chaînes/API Faux positifs comme le mouvement 3D
C Embedding uniquement Recherche sémantique possible Précision de l’API/versions faible
D BM25 + embedding Équilibre réaliste Nécessité d’ajuster la combinaison des scores
E Profil de requête Qwen Réduction du code dur, résumé d’intention possible Hallucination, coût, contamination avant recherche
F BM25 + embedding + reranker + validator Qualité prioritaire Coût, latence, nombreuses étapes

Jugement provisoire actuel

La conclusion de la note originale se rapproche de ce qui suit.

Conservez uniquement un chunkText en entrée.

La première recherche se fait avec BM25.  
  Raison : transparent et puissant pour la recherche de chaînes de code/API.

La deuxième recherche se fait avec l'embedding voyage-code-3.  
  Raison : la requête étant un chunk de code, le modèle de récupération de code est approprié.

Le troisième tri se fait avec rerank-2.5.  
  Raison : pour faire remonter en haut le JSONL correspondant au vrai chunk parmi les candidats similaires obtenus par BM25 et l'embedding.

La validation finale se fait avec le validateur Qwen direct-evidence.  
  Raison : si le JSONL ne contient pas de preuve directe sous forme de chaîne/pattern correspondant au chunk, il doit être rejeté.

Résumé en une ligne :

raw chunk telle quelle entrée
  -> Génération de candidats parallèles avec BM25 + intégration de code
  -> Réordonnancement du reranker
  -> Vérification directe des preuves par Qwen

À comparer réellement ensuite

  • Vérifier combien d’enregistrements la méthode full‑text de PostgreSQL renvoie à partir du chunk de référence
  • Vérifier si BM25 place réellement first_2d_game en haut de la liste
  • Mesurer à quel point les faux positifs de mouvement 3D se mélangent dans BM25 only
  • Voir quels documents descriptifs supplémentaires sont récupérés par embedding only
  • Déterminer comment fusionner les doublons et les scores dans l’union BM25 + embedding
  • Vérifier que le reranker réordonne correctement les candidats 2D/3D
  • Vérifier que le validateur Qwen direct‑evidence rejette réellement les JSONL non pertinents avec non