Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Semanttinen koodihaku

Oppitunti 6 / 18 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Koodin haku merkityksen perusteella
  2. Koodihakemiston indeksointi
  3. Koodaus ja indeksointi
  4. Haku luonnollisella kielellä
  5. Kielten välinen haku
  6. Haku funktiomerkinnän perusteella
  7. Keskeiset asiat

Koodin haku merkityksen perusteella

Perinteinen koodihaku perustuu avainsanoihin: syötät funktion nimen tai kommentissa esiintyvän sanan. Semanttinen koodihaku menee pidemmälle: se löytää koodia sen merkityksen tai tarkoituksen perusteella, vaikka täsmälliset termit eivät täsmäisi.

Codestral-embedin avulla voit hakea koodia luonnollisella kielellä. Kysely kuten “funktio, joka lajittelee listan” löytää quicksort-toteutuksen, vaikka sana “sort” ei esiintyisi koodissa lainkaan. Tämä heijastaa kehittäjän arkea liittyessään olemassa olevaan projektiin: tiedät mitä etsit, mutta sinulla ei ole hajuakaan, miten edellinen tiimi on sen nimennyt.

Koodihakemiston indeksointi

Ensimmäinen vaihe on purkaa ja koodata projektin jokainen tiedosto tai funktio. Alla oleva funktio käy läpi hakemistorakenteen ja suodattaa pois kansiot, jotka sotkisivat indeksiä. Pelkkä node_modules voi olla kymmenen kertaa suurempi kuin itse kirjoittamasi koodi, eikä sen tiedoista ole mitään hyötyä haussa.

import os
import numpy as np
from mistralai.client import Mistral

client = Mistral(api_key=api_key)

def extract_code_files(directory, extensions=(".py", ".js", ".ts")):
    """Extract all code files from a directory."""
    code_files = []
    for root, dirs, files in os.walk(directory):
        # Ignore irrelevant directories
        dirs[:] = [d for d in dirs if d not in ("node_modules", ".git", "__pycache__", "venv")]
        for f in files:
            if any(f.endswith(ext) for ext in extensions):
                filepath = os.path.join(root, f)
                with open(filepath, "r", encoding="utf-8", errors="ignore") as fh:
                    content = fh.read()
                if content.strip():
                    code_files.append({
                        "path": filepath,
                        "content": content[:4000],  # Truncate if too long
                    })
    return code_files

# Extract files
code_files = extract_code_files("./my-project/")
print(f"{len(code_files)} code files found")

Kaksi toteutusyksityiskohtaa ansaitsevat huomion. Muuttujan dirs[:] muokkaaminen paikan päällä ei ole pelkkä lyhenne; se on ainoa tapa estää os.walk:ia laskeutumasta kyseisiin hakemistoihin. Muuttujan uudelleenmäärittäminen ilman viipalointia ei vaikuttaisi mitään. Mitä tulee katkaisuun 4 000 merkin kohdalla, tämä suojaa sinua valtavilta tiedostoilta, jotka räjäyttäisivät pyynnön, pitäen samalla tallella tiedoston alun – tuonnit ja päämääritykset –, joka kantaa merkittävimmän signaalin.

Koodaus ja indeksointi

Koodaus tapahtuu kahdenkymmenen tiedoston erissä edistymisnäytön kera. Useiden satojen tiedostojen repositoriossa tämä silmukka pyörii useita minuutteja. Ilman laskuria et pysty erottamaan hidasta käsittelyä jumittuneesta kutsusta.

def index_code_files(code_files, batch_size=20):
    """Create embeddings for all code files."""
    all_embeddings = []

    for i in range(0, len(code_files), batch_size):
        batch = code_files[i:i + batch_size]
        inputs = [f["content"] for f in batch]

        response = client.embeddings.create(
            model="codestral-embed",
            inputs=inputs,
        )
        all_embeddings.extend([d.embedding for d in response.data])
        print(f"Encoded {min(i + batch_size, len(code_files))}/{len(code_files)}")

    return np.array(all_embeddings)

embeddings = index_code_files(code_files)
print(f"Index: {embeddings.shape}")

Matriisin vektorien järjestys vastaa täsmälleen code_files-listan järjestystä. Tämä implisiittinen vastaavuus on kaiken seuraavan kulmakivi: se mahdollistaa sen, että rankingin palauttama indeksi osoittaa tiettyyn tiedostopolkuun.

Haku luonnollisella kielellä

Codestral-embedin suurin etu on mahdollisuus hakea kysymyksellä ranskaksi tai englanniksi. Funktio koodaa kyselyn samalla mallilla, laskee samankaltaisuudet koko indeksiä vasten ja palauttaa top_k parasta tulosta sisältöesikatselun kera.

from sklearn.metrics.pairwise import cosine_similarity

def search_code(query, code_files, embeddings, top_k=5):
    """Search for code using natural language descriptions."""
    # Encode the query
    response = client.embeddings.create(
        model="codestral-embed",
        inputs=[query],
    )
    query_emb = np.array(response.data[0].embedding)

    # Calculate similarities
    sims = cosine_similarity([query_emb], embeddings)[0]

    # Top-k results
    top_indices = np.argsort(sims)[::-1][:top_k]

    results = []
    for idx in top_indices:
        results.append({
            "path": code_files[idx]["path"],
            "score": float(sims[idx]),
            "preview": code_files[idx]["content"][:200],
        })
    return results

# Natural language searches
queries = [
    "email validation function",
    "database connection",
    "HTTP error handling",
    "sorting algorithm",
]

for query in queries:
    print(f"\n--- Query: '{query}' ---")
    results = search_code(query, code_files, embeddings, top_k=3)
    for r in results:
        print(f"  [{r['score']:.3f}] {r['path']}")

Kentällä preview on välitön käytännön hyöty: se säästää sinut viiden tiedoston avaamiselta sen selvittämiseksi, mikä niistä todella vastaa hakua. Editori-integraatiossa nämä kaksi sataa merkkiä muodostavat esikatselurivin, joka näytetään kunkin tuloksen alla.

Kielten välinen haku

Codestral-embed ymmärtää logiikkaa riippumatta kielestä. Voit hakea Python-kuviota ja löytää vastaavan JavaScriptistä:

# Search using a code example in one language...
query_python = "def authenticate(username, password): check credentials and return token"

# ...and find the equivalent in another language
results = search_code(query_python, code_files, embeddings)
# May return a .js file with a similar function

Tämä kyky on korvaamaton sovelluksissa, jotka on jaettu Python-backendin ja TypeScript-frontendin kesken, joissa sama liiketoimintasääntö on joskus toteutettu molemmilla puolilla. Molempien toteutusten löytäminen yhdellä kyselyllä auttaa havaitsemaan eroavaisuudet ennen kuin bugi paljastaa ne tuotannossa.

Haku funktiomerkinnän perusteella

Voit hakea myös odotetun muodon eikä toiminnallisen domainin perusteella. Rakenteen kuvaaminen – asynkroninen funktio, luokka, middleware, testi – ohjaa haun kohti koodiobjektin tyyppiä eikä aihetta.

technical_queries = [
    "async function that fetches data from API and handles errors",
    "class with CRUD methods for database operations",
    "middleware that checks authentication token",
    "unit test for user registration",
]

for q in technical_queries:
    results = search_code(q, code_files, embeddings, top_k=2)
    print(f"\n{q}:")
    for r in results:
        print(f"  -> {r['path']} (score: {r['score']:.3f})")

Kokeile näitä neljää kyselyä omassa repositoriossasi ennen etenemistä. Huomaat, että tulokset heikkenevät merkittävästi hyvin pitkissä tiedostoissa, joissa 4 000 merkin katkaisu on leikannut pois hyödyllisen osan. Tämä on hetki päättää, indeksoitko kokonaisia tiedostoja vai – vielä parempi – funktioita yksitellen pilkottuna.

Keskeiset asiat

  • Codestral-embedin avulla voit hakea koodia luonnollisen kielen kuvauksilla
  • Indeksointi sisältää kaikkien kooditiedostojen koodauksen vektoreiksi
  • Kielten välinen haku toimii: Python-kuvio löytää JS-vastaavan
  • Suodata pois epäoleelliset hakemistot (node_modules, .git, venv) purkamisen aikana
  • Katkaise hyvin pitkät tiedostot pysyäksesi mallin rajoissa