💻 computer science

Improving BM25 Code Retrieval Under Fixed Generic Tokenization: Adaptive q-Log Odds as a Drop-In BM25 Fix

Dit artikel stelt een drop-in BM25-verbetering voor genaamd adaptieve q-log odds, die de standaard logaritmische IDF vervangt door een q-logaritme om de prestaties van code-retrieval onder vaste generieke tokenisatie aanzienlijk te verbeteren door het beter scheiden van identifier-uiteinden, terwijl de impact op tekst-retrieval verwaarloosbaar blijft en geen wijzigingen in query-latentie vereist worden.

Oorspronkelijke auteurs: Santosh Kumar Radha, Oktay Goktas

Gepubliceerd 2026-05-19

📖 5 min leestijd🧠 Diepgaand

CC BY 4.0

Oorspronkelijke auteurs: Santosh Kumar Radha, Oktay Goktas

Oorspronkelijk artikel gelicentieerd onder CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ Dit is een AI-gegenereerde uitleg van het onderstaande artikel. Het is niet geschreven of goedgekeurd door de auteurs. Raadpleeg het oorspronkelijke artikel voor technische nauwkeurigheid. Lees de volledige disclaimer

Het Probleem: De "Verloren in Vertaling"-Zoekopdracht

Stel je voor dat je een rechercheur bent (een coderende AI) die een misdaad probeert op te lossen. Je hebt een enorme bibliotheek met 50.000 bestanden, en je moet het ene specifieke bestand vinden dat de aanwijzing bevat: een functie genaamd handleWebSocketUpgrade.

Je huidige tool is een standaard bibliotheekzoekmachine (genaamd BM25). Deze tool is oorspronkelijk ontworpen om te zoeken naar natuurlijke taal, zoals nieuwsartikelen of boeken. Het werkt goed voor woorden als "de", "lopen" of "gelukkig". Maar code is anders. Code zit vol met unieke, specifieke namen (identifiers) die werken als geheime codes.

Het Probleem:
De standaardzoekmachine behandelt een unieke codenaam (zoals handleWebSocketUpgrade, die slechts in één bestand voorkomt) bijna hetzelfde als een iets minder zeldzame naam (zoals logger, die in 50 bestanden voorkomt).

Analogie: Stel je een bibliotheek voor waar de bibliothecaris een "relevantiescore" toekent aan boeken. Als je op zoek bent naar een boek met een zeer specifieke, unieke titel, zou de bibliothecaris moeten schreeuwen: "DIT IS HET!" Maar de huidige bibliothecaris fluistert: "Dit is een goed boek, maar dat andere ook."
Het Resultaat: De AI raakt afgeleid. Het leest de verkeerde bestanden, raakt in de war en faalt in het oplossen van de bug. Het artikel stelt dat het falen niet de schuld is van de AI; het is de schuld van de zoekmachine omdat het de unieke "codenamen" niet genoeg waardeert.

De Oorzaak: Een "Bevroren" Woordenboek

De auteurs leggen uit dat in veel bedrijven de zoekmachine wordt gebouwd door een infrastructuurteam met behulp van een "bevroren" woordenboek (tokenizer). Dit woordenboek breekt woorden op op basis van hoe mensen spreken, niet hoe code is geschreven.

De Beperking: De mensen die de zoekmachine gebruiken (de AI-ontwikkelaars) kunnen het woordenboek niet veranderen. Ze zitten vast aan de "bevroren" instelling. Ze hebben een oplossing nodig die werkt zonder de hele bibliotheek opnieuw te bouwen.

De Oplossing: De "Volumeknop" (q-Log)

De auteurs stellen een slimme, één-regelige wiskundige aanpassing voor aan het scoresysteem van de zoekmachine. Ze noemen dit Adaptive q-Log Odds.

De Analogie:
Stel je het scoresysteem van de zoekmachine voor als een volumeknop voor verschillende soorten woorden.

Veelvoorkomende woorden (zoals "functie" of "return") staan laag omdat ze overal voorkomen.
Zeldzame woorden (de unieke codenamen) moeten hoog worden gezet.
Het Probleem: De standaard volumeknop (het logaritme) is kapot. Het zet het volume van zeldzame woorden wel omhoog, maar niet genoeg. Het behandelt een woord dat één keer voorkomt en een woord dat 50 keer voorkomt als bijna hetzelfde volume.

De Oplossing:
De auteurs vervangen de standaard volumeknop door een nieuwe die q-log heet.

Deze nieuwe knop heeft een speciale instelling (parameter q) die werkt als een "super-versterker" voor de zeldzaamste woorden.
Als je q = 1 zet, werkt het precies zoals de oude, kapotte knop (standaard BM25).
Als je q < 1 zet (zoals 0,05), schreeuwt het "DIT IS HET!" voor woorden die slechts één keer voorkomen. Het versterkt het verschil tussen een unieke identifier en een gemeenschappelijke met duizenden keren.

Hoe Het in de Praktijk Werkt

Het artikel testte dit op een enorme verzameling Go-code (182.000 bestanden).

Voorheen: De zoekmachine vond het juiste bestand slechts 25% van de tijd in de top 10 resultaten.
Na: Met de nieuwe "volumeknop" op de juiste instelling, vond het het juiste bestand 48% van de tijd.
De Magie: Dit is een verbetering van 89% in nauwkeurigheid. De AI kan nu bijna twee keer zo vaak het juiste bestand vinden, simpelweg door het volume van de unieke codenamen omhoog te draaien.

Het "Slimme" Deel: Auto-Tuning

Je zou kunnen vragen: "Hoe weten we welke instelling (q) we moeten gebruiken?"
De auteurs hebben een eenvoudige formule gemaakt die naar de bibliotheek zelf kijkt om de instelling automatisch te bepalen.

De Regel: Ze tellen hoeveel "unieke" woorden (hapaxes) er in de bibliotheek bestaan.
De Logica:
- Als de bibliotheek vol zit met unieke codenamen (zoals bij Go), zet de formule de volumeknop op "Super Versterken" (q = 0,05).
- Als de bibliotheek voornamelijk uit gemeenschappelijke woorden bestaat (zoals Python of gewone tekst), zet de formule de knop terug op "Normaal" (q = 1).
Waarom dit belangrijk is: Dit betekent dat de oplossing automatisch werkt. Het breekt tekstzoekopdrachten niet (waar unieke woorden minder belangrijk zijn) en het vereist geen menselijke experts om het voor elk nieuw project af te stemmen.

De Haken en Ogen: Tokenizers

Het artikel ontdekte ook een limiet. Als je het woordenboek (tokenizer) wel kunt veranderen om code beter te begrijpen (door handleWebSocketUpgrade op te splitsen in handle, web, socket, upgrade), dan werkt de standaardzoekmachine prima en is deze speciale "volumeknop" niet nodig.

De Conclusie: Deze oplossing is specifiek voor situaties waarin je het woordenboek niet kunt veranderen. Het is de "beste mogelijke oplossing" voor een afgesloten systeem.

Samenvatting

Het Probleem: Standaardzoekmachines negeren unieke codenamen, waardoor AI-coderingsagenten falen.
De Oplossing: Een wiskundige aanpassing die de belangrijkheid van woorden die slechts één keer voorkomen enorm versterkt.
Het Resultaat: Een enorme sprong in het vinden van de juiste codebestanden (van ~25% naar ~48% succespercentage in de topresultaten).
Het Voordeel: Het werkt automatisch, vereist geen wijzigingen aan de bestaande zoekinfrastructuur en is gratis te berekenen.

Kortom, het artikel leert ons hoe we het volume van de "geheime codes" in een bibliotheek omhoog kunnen draaien, zodat de rechercheur (de AI) ze duidelijk hoort en het juiste bestand vindt.

Technische Samenvatting: Verbetering van BM25-code-retrieval onder vaste generieke tokenisatie

1. Probleemstelling

In retrieval-verrijkte coderingssystemen treedt een kritiek faalpunt op wanneer het relevante bronbestand ontbreekt in de opgehaalde context. Dit gebeurt vaak in regimes met "bevroren generieke tokenisatie", waarbij een BM25-index wordt gebouwd door een zoekinfrastructuur (bijvoorbeeld Lucene, Elasticsearch, Tantivy) met behulp van een analyzer die is afgestemd op natuurlijke taal in plaats van code. Beoefenaars kunnen deze tokenisator vaak niet aanpassen.

Onder deze beperkingen faalt de standaard BM25 om unieke code-identifiers (bijvoorbeeld handleWebSocketUpgrade) voldoende te onderscheiden van veelvoorkomende, terugkerende tokens. De standaard Robertson–Spärck-Jones (RSJ) Inverse Document Frequency (IDF) maakt gebruik van een logaritmische functie: $\log((N - n_t + 0.5)/(n_t + 0.5))$ . Omdat de logaritme langzaam groeit, "onderscheidt" deze de staart van de verdeling onvoldoende. Een term die in één bestand voorkomt ($df=1$) en een term die in 50 bestanden voorkomt, ontvangen IDF-weights die slechts met een kleine constante verschillen in plaats van met een orde van grootte. Bijgevolg worden "gouden" bestanden met unieke identifiers vaak lager gerangschikt dan "afleidende" bestanden die een paar gemeenschappelijke, niet-unieke tokens delen, waardoor het contextvenster van de agent wordt gevuld met irrelevante code.

2. Methodologie: Adaptieve q-log Odds

Het artikel stelt een "drop-in"-oplossing voor die uitsluitend de buitenste logaritme van de BM25-IDF-berekening aanpast, waarbij term-frequentie-saturatie en tokenisatie onaangetast blijven.

De Transformatie: De auteurs vervangen de standaardlogaritme door de Tsallis q-logaritme (of $q$ -log), gedefinieerd als:
$\ln_q(x) = \frac{x^{1-q} - 1}{1 - q}$
De nieuwe IDF wordt:
$idf_{RSJ}^q(t) = \ln_q\left(\frac{N - n_t + \delta}{n_t + \delta}\right)$
waarbij $\delta = 0.5$ .
Wiskundige Eigenschappen:
- Herstel van BM25: Bij $q=1$ herstelt de transformatie de klassieke BM25-IDF exact via de regel van L'Hôpital ( $\lim_{q \to 1} \ln_q(x) = \log x$ ).
- Versterking volgens machtswet: Voor $q < 1$ werkt de transformatie als een Box-Cox-transformatie van de RSJ-odds met $\lambda = 1-q$ . In het regime van ultra-zeldzame tokens ( $n_t \ll N$ ) groeit de IDF volgens een machtswet ( $x^{1-q}$ ), waardoor het gewicht van $df=1$ hapaxen (unieke identifiers) aanzienlijk wordt versterkt ten opzichte van minder zeldzame tokens.
- Saturatie: Voor $q > 1$ saturert de IDF, waardoor discriminatie voor zeldzame tokens effectief wordt verworpen.
Implementatie: De methode vereist slechts één pass over de sparse score-matrix bij het laden van de index om de IDF-kolom te herschalen. De query-latentie blijft onveranderd.

3. Belangrijkste Bijdragen

q-log RSJ-odds IDF: Een één-parameter deformatie van de BM25-IDF die bij $q=1$ exact BM25 herstelt en bij $q < 1$ fungeert als een versterker volgens de machtswet voor zeldzame tokens.
Oracle-prestatiegrenzen: Op het CoIR CodeSearchNet Go-corpus (182K documenten) met bevroren generieke tokenisatie verbetert het afstemmen van $q$ naar 0,05 de NDCG@10 van 0,2575 naar 0,4874 (+89,3% relatieve winst). Dit resultaat is statistisch significant ( $p \le 10^{-4}$ ) met nul tekenomkeringen in 10.000 gepaarde bootstrap-resamples.
Corpus-adaptieve predictor: Een gesloten-formule, label-vrije predictor $q_{pred} = 1 - 7.28 \cdot h_{tok}$ (waarbij $h_{tok}$ de hapax-dichtheid is) die de optimale $q$ schat uitsluitend op basis van corpusstatistieken. Deze predictor bereikt een recovery van 0,72 bij "leave-one-language-out" en defaultt correct naar $q \approx 1$ voor corpora waar BM25 al optimaal is (bijvoorbeeld Python).
Tokenizer-ablatie: Het onderzoek toont aan dat de prestatiewinst door $q$ -IDF grotendeels afhankelijk is van de tokenisator. Wanneer een identifier-bewuste tokenisator (die handleWebSocketUpgrade splitst in sub-tokens) wordt gebruikt, stort de incrementele winst van $q$ -IDF in. Dit bevestigt dat de waarde van de methode specifiek is voor het regime van "bevroren tokenisatie".
Agent-relevante proxies: De methode toont aanzienlijke winst in Recall@K-tokens (contextvensterefficiëntie), waardoor de kans dat het gouden bestand binnen een budget van 8K tokens verschijnt, op Go stijgt van 48,1% naar 68,8%.

4. Experimentele Resultaten

Code versus tekst: De methode levert enorme winsten op voor code-corpora met zware identifier-staarten (Go, Java, Ruby), maar bijna nul winst voor natuurlijke taaltekst (BEIR-datasets) en Python.
- Go: $q_{opt} = 0,05$ , +89,3% NDCG@10-winst.
- Java/Ruby: Aanzienlijke positieve winsten ( $q_{opt} \approx 0,70-0,90$ ).
- Python: $q_{opt} = 1,00$ . Python-identifiers zijn vaak woorden die op woordenlijst lijken en over bestanden worden hergebruikt; het signaal zit in de bins met een gemiddelde $df$, die de standaard log-IDF al optimaal behandelt. Afwijken van $q=1$ vervormt deze bins.
- BEIR (tekst): Geen significante winst; de methode stort in tot BM25 omdat de oracle $q$ op of boven 1 ligt.
Schaling: De prestatiewinst schaalt monotoon met de corpusgrootte. Op Go neemt de absolute winst toe van +0,061 bij 1K documenten naar +0,227 bij 182K documenten.
Baselines: De $q$ -log-methode presteert beter dan eenvoudige herschalingen van IDF volgens de machtswet ( $idf_\gamma$ ) en Divergence-from-Randomness (DFR-DPH)-modellen, die op code falen door slecht gekalibreerde term-frequentienormalisatie.

5. Betekenis en Reikwijdte

Het artikel positioneert dit werk niet als vervanging voor adequate tokenisatie, maar als een noodzakelijke interventie wanneer infrastructuurbeperkingen dit verhinderen.

Praktische bruikbaarheid: Voor beoefenaars die beheerde zoekclusters gebruiken (Elasticsearch, OpenSearch) waar de analyzer vaststaat, biedt deze methode een "één-regelige" wijziging in de IDF-berekening die de retrieval-effectiviteit voor codesoekopdrachten bijna kan verdubbelen.
Mechanisme: De verbetering wordt gedreven door de versterking van $df=1$ hapaxen (unieke identifiers zoals handleWebSocketUpgrade), die de primaire discriminators zijn in code-retrieval maar worden afgevlakt door standaard logaritmische weging.
Beperkingen: De auteurs stellen expliciet dat als een operator de tokenisator beheerst, de beste aanpak is om een identifier-bewuste analyzer te gebruiken en $q=1$ aan te houden. Het stapelen van $q$ -IDF bovenop identifier-bewuste tokenisatie levert verwaarloosbare of negatieve resultaten op. De methode is ook taalafhankelijk; ze biedt geen voordeel (en mogelijk een lichte degradatie) voor talen met een lage hapax-dichtheid zoals Python of PHP op volledige schaal.

Kortom, het artikel identificeert een specifiek faalpunt in code-retrieval onder bevroren tokenisatie en biedt een wiskundig onderbouwde, goedkope en adaptieve oplossing die het onderscheidend vermogen van unieke identifiers herstelt zonder herindexering of wijzigingen aan de tokenisator te vereisen.