Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Iġġenera embeddings għad-dejta tiegħek

Lezzjoni 3 / 22 Aġġornat 29 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Għanijiet
  2. Ipprepara d-dejta tiegħek
  3. Iġġenera embeddings f’lottijiet
  4. Aħżen l-embeddings
  5. Pipeline sħiħa: minn fajls tat-test għall-embeddings
  6. Stima tal-ispejjeż
  7. Punti Ewlenin

Għanijiet

  • Ipprepara d-dejta tat-test tiegħek għall-embedding
  • Iġġenera embeddings b’mod effiċjenti fuq skala kbira
  • Aħżen il-vetturi għal użu futur

Ipprepara d-dejta tiegħek

Il-kwalità tal-embedding tiegħek tiddependi direttament mill-kwalità tad-dejta tiegħek. Test mimli bi spazji stray, karattri ta’ kontroll minn esportazzjoni ħażina, jew mistrieħ ta’ linja erratiċi jipproduċi vettur kemxejn ‘il barra. Dak l-iżball jikkumula fuq kull tfittxija. It-tindif mhuwiex kożmetiku: hija l-ewwel u l-irħas ottimizzazzjoni tar-rilevanza.

import re

def nettoyer_texte(texte: str) -> str:
    """Prepares text for embedding."""
    # Remove multiple spaces
    texte = re.sub(r"\s+", " ", texte)
    # Remove control characters
    texte = re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f]", "", texte)
    # Trim
    texte = texte.strip()
    return texte

# Example
brut = "  Texte   avec   des   espaces\n\n\nen trop  "
propre = nettoyer_texte(brut)
print(propre)  # "Texte avec des espaces en trop"

Arrikkixxi l-kuntest

Estratt ta’ dokumentazzjoni iżolat jitlif parti mill-meaning tiegħu mingħajr it-titlu tiegħu. Ħu paragrafu li jibda b‘“Download the package from the official site”: barra mill-kuntest, xejn ma jindika li jirreferi għal PostgreSQL, u l-vettur li jirriżulta qatt ma jaqbel ma’ mistoqsija dwar PostgreSQL. Billi tpoġġi quddiem il-kontenut bit-titlu u s-sezzjoni tiegħu, terġa’ ddikjara dik l-informazzjoni fit-test li l-mudell jara.

def enrichir_document(titre: str, section: str, contenu: str) -> str:
    """Creates enriched text for better embedding."""
    return f"Titre : {titre}\nSection : {section}\n\n{contenu}"

texte_enrichi = enrichir_document(
    titre="Installation de PostgreSQL",
    section="Getting Started Guide",
    contenu="Download the package from the official site..."
)

Iġġenera embeddings f’lottijiet

Fuq corpus reali ta’ mijiet jew eluf ta’ dokumenti, l-ipproċessar irid ikun maqsum f’biċċiet u reżiljenti għal problemi fin-netwerk. Il-funzjoni hawn taħt tgħaddi mit-testijiet f’biċċiet, tordna sistematikament ir-risposta skont index biex tiżgura li l-vettur #7 jaqbel mad-dokument #7, u tipprova mill-ġdid darba wara pausa jekk iseħħ żball.

from openai import OpenAI
import time
import json

client = OpenAI()

def generer_embeddings(
    textes: list[str],
    model: str = "text-embedding-3-large",
    batch_size: int = 100
) -> list[list[float]]:
    """Generates embeddings in batches with error handling."""
    tous_les_embeddings = []

    for i in range(0, len(textes), batch_size):
        batch = textes[i:i + batch_size]
        print(f"Processing batch {i // batch_size + 1}/"
              f"{(len(textes) - 1) // batch_size + 1}")

        try:
            response = client.embeddings.create(
                input=batch,
                model=model
            )
            # Sort by index to guarantee order
            batch_embeddings = sorted(
                response.data, key=lambda x: x.index
            )
            tous_les_embeddings.extend(
                [item.embedding for item in batch_embeddings]
            )
        except Exception as e:
            print(f"Error on batch {i}: {e}")
            # Retry after a pause
            time.sleep(5)
            response = client.embeddings.create(
                input=batch,
                model=model
            )
            batch_embeddings = sorted(
                response.data, key=lambda x: x.index
            )
            tous_les_embeddings.extend(
                [item.embedding for item in batch_embeddings]
            )

    return tous_les_embeddings

L-ordni skont index hija prekawzjoni li qatt m’għandek taqbeż. Bidla silenzjuża ta’ ringiela waħda biżżejjed biex tassoċja kull dokument mal-vettur tal-ġar tiegħu. Is-sintomu li se tosserva huwa “it-tfittxija tirritorna żibel”, mingħajr l-ebda żball tekniku biex jindirik lejn id-direzzjoni t-tajba.

Aħżen l-embeddings

Għal corpus żgħir ta’ ftit eluf ta’ dokumenti, fajl JSON sempliċi li fih it-testijiet, il-metadata, u l-vetturi jaħdem perfettament. Għandu l-vantaġġ li jkun leġibbli mill-bniedem meta jkollok bżonn tiddibuggja riżultat stramb.

import json

documents = [
    {"id": 1, "texte": "Premier document...", "metadata": {"source": "faq"}},
    {"id": 2, "texte": "Deuxième document...", "metadata": {"source": "docs"}},
]

# Generate embeddings
textes = [d["texte"] for d in documents]
embeddings = generer_embeddings(textes)

# Add vectors to documents
for doc, emb in zip(documents, embeddings):
    doc["embedding"] = emb

# Save
with open("corpus_embeddings.json", "w") as f:
    json.dump(documents, f)

Lil hinn minn dik l-iskala, isir collo d’bottla: kull numru huwa miktub bis-sħiħ, jintefaħ il-fajl u jimponi parsing għali fuq kull tagħbija. NumPy jaħżen l-istess valuri f’binarju fuq 4 bytes u jerġa’ jitgħabba minnufih.

import numpy as np

# Convert to NumPy matrix
matrice = np.array(embeddings, dtype=np.float32)
print(f"Shape : {matrice.shape}")  # (n_docs, 3072)

# Save in binary format
np.save("embeddings.npy", matrice)

# Load
matrice_chargee = np.load("embeddings.npy")

Pipeline sħiħa: minn fajls tat-test għall-embeddings

Ejja niġbru dawn l-elementi f’funzjoni li taqra folder, tnaddaf kull fajl, tiġġenera vetturi, u taqsam il-ħażna f’żewġ partijiet: il-metadata f’JSON (leġibbli u editjabbli) u l-matriċi f’NumPy (kompatta u mgħaġġla).

from openai import OpenAI
from pathlib import Path
import json
import numpy as np

client = OpenAI()

def pipeline_embeddings(dossier: str, model: str = "text-embedding-3-large"):
    """Complete pipeline: files → embeddings → storage."""
    dossier_path = Path(dossier)

    # 1. Read files
    documents = []
    for fichier in sorted(dossier_path.glob("*.txt")):
        contenu = fichier.read_text(encoding="utf-8")
        contenu = nettoyer_texte(contenu)
        if contenu:
            documents.append({
                "id": fichier.stem,
                "fichier": fichier.name,
                "texte": contenu
            })

    print(f"{len(documents)} documents found")

    # 2. Generate embeddings
    textes = [d["texte"] for d in documents]
    embeddings = generer_embeddings(textes, model=model)

    # 3. Save
    # Metadata in JSON
    meta = [{"id": d["id"], "fichier": d["fichier"]} for d in documents]
    with open("metadata.json", "w") as f:
        json.dump(meta, f, ensure_ascii=False, indent=2)

    # Vectors in NumPy
    np.save("embeddings.npy", np.array(embeddings, dtype=np.float32))

    print(f"Embeddings saved: {len(embeddings)} vectors "
          f"of {len(embeddings[0])} dimensions")

    return documents, embeddings

# Usage
documents, embeddings = pipeline_embeddings("./mes_documents/")

Innota s-sorted() fuq il-glob: mingħajru, l-ordni tal-fajls tiddependi mis-sistema tal-fajls, u ż-żewġ fajls tal-output tiegħek jistgħu joħorġu barra mis-sinkronizzazzjoni wara bidla sempliċi fil-magna.

Stima tal-ispejjeż

Qabel ma tniedi xogħol massiv, agħddi t-tokens lokalment b’tiktoken. L-operazzjoni tieħu ftit sekondi u ssalvak milli tiskopri tard wisq li corpus filtrat ħażin kien fih għaxar darbiet il-volum mistenni.

import tiktoken

encoder = tiktoken.get_encoding("cl100k_base")

def estimer_cout(textes: list[str], model: str = "text-embedding-3-large"):
    """Estimates embedding cost for a list of texts."""
    total_tokens = sum(len(encoder.encode(t)) for t in textes)

    # Approximate prices per million tokens (check current rates)
    prix = {
        "text-embedding-3-large": 0.13,
        "text-embedding-3-small": 0.02,
    }

    cout = total_tokens / 1_000_000 * prix.get(model, 0.13)
    print(f"Estimated tokens: {total_tokens:,}")
    print(f"Estimated cost: ${cout:.4f}")
    return total_tokens, cout

Il-prezzijiet fid-dizzjunarju huma indikattivi u jixjieħu malajr: dejjem iċċekkja r-rati attwali qabel ma tippreżenta kwotazzjoni lil klijent.

Punti Ewlenin

  • Naddaf u arrikkixxi t-testijiet tiegħek qabel ma tiġġenera l-embeddings
  • Uża l-ipproċessar f’lottijiet għal corpora kbar
  • Aħżen il-metadata f’JSON u l-vetturi f’NumPy
  • Stima l-ispejjeż tiegħek qabel ma tniedi xogħol massiv