Lähe põhisisu juurde
Eesti— Vali keel
Menüü

RAG-i arhitektuur tervikuna

Õppetund 11 / 22 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Eesmärgid
  2. Mis on RAG?
  3. Torustiku etapid
  4. Täielik rakendus
  5. Kasutamine
  6. Optimeerimispunktid
  7. Peamised punktid

Tund uuendatud 3. novembril 2026 OpenAI dokumentatsiooni põhjal: parameetreid temperature ja top_p aktsepteeritakse ainult siis, kui arutluse jõupingutus (reasoning effort) on none, samas kui GPT-5.6 mudelid kasutavad vaikimisi arutlust (medium). Seetõttu peavad need parameetrid määravad päringud sisaldama reasoning={"effort": "none"} (API Responses) või reasoning_effort="none" (Chat Completions). Allikad: Using GPT-6 · GPT-5.6 Terra.

Eesmärgid

  • Mõista RAG-i arhitektuuri algusest lõpuni
  • Rakendada toimiv RAG-i torustik
  • Tuvastada optimeerimist vajavad komponendid

Mis on RAG?

RAG (Retrieval-Augmented Generation) ühendab dokumendipäringu LLM-i tekstiloomega. Mudel ei toetu ainult oma sisemistele teadmistele, vaid saab asjakohased dokumendid kontekstina ja koostab vastuse selle põhjal. Kõik, mida oled selle kursuse jooksul ehitanud – manused (embeddings), indekseerimine, otsing, hindamine – moodustab siin tervikliku süsteemi ülemise poole.

Miks RAG?

Seda õigustavad neli põhjust, mis toimivad koosmõjus. Esiteks, omandatud andmed: sinu kaugtöö poliitika, sisemised protseduurid ja tootekataloog ei ole kunagi olnud mudeli treeningandmetes ning ükski vihje (prompt) ei saa neid sinna tuua. Teiseks, värske info: kõik, mis on tekkinud pärast treeningut, on mudelile nähtamatu, samas kui indeksit saab uuendada samal päeval. Kontrollitavus on sama oluline, sest iga vastus on ankurdatud tuvastatavatesse allikatesse, mida kasutaja saab avada ja üle kontrollida – see muudab süsteemi usalduse olemust. Lõpuks, kulud mängivad selle kasuks: teadmiste lisamine RAG-i kaudu maksab palju vähem kui häälestamine (fine-tuning) ja parandused tehakse dokumendi kustutamisega, mitte mudeli ümberõppega.

Torustiku etapid

Loe RAG-i kahe eraldi faasina, mida ei tohi omavahel segi ajada. Sissevõtmine (Ingestion) toimub offline-režiimis, kas üks kord ja igaveseks või iga kord, kui andmekogu uueneb:

Dokumendid → Tükeldamine → Manused → Vektorhoidla

Päring toimub online-režiimis iga esitatud küsimuse korral ja peab jääma kiireks:

Küsimus → Manuse loomine → Otsing → Kontekst + Küsimus → LLM → Vastus

Sellel eraldatusel on praktiline tagajärg: sissevõtmise kulud kantakse üks kord ja need võivad olla suured, samas kui päringukulud tekivad iga kutse pealt ja määravad kasutajakogemuse. Seetõttu saad endale lubada keerukat sissevõtmise töötlemist, kuid päringupoolel pead jääma kergeks.

Täielik rakendus

Järgnev klass materialiseerib kolm faasi kolmes eraldi meetodis, lisades neljanda, mis need aheldab. See eraldatus pole kosmeetiline: see võimaldab testida otsingut ilma genereerimise tokeneid kulutamata ja korrata genereerimist fikseeritud kontekstil, et võrrelda kahte erinevat vihjet.

from openai import OpenAI
import numpy as np

client = OpenAI()

class PipelineRAG:
    def __init__(
        self,
        model_embedding: str = "text-embedding-3-large",
        model_generation: str = "gpt-5.6-terra"
    ):
        self.client = OpenAI()
        self.model_embedding = model_embedding
        self.model_generation = model_generation
        self.chunks: list[dict] = []
        self.embeddings: np.ndarray | None = None

    # --- Ingestion Phase ---

    def ingest(self, documents: list[dict]):
        """Ingests documents {id, text, metadata}."""
        self.chunks = documents
        texts = [d["text"] for d in documents]

        # Generate embeddings in batches
        all_emb = []
        for i in range(0, len(texts), 100):
            batch = texts[i:i + 100]
            resp = self.client.embeddings.create(
                input=batch, model=self.model_embedding
            )
            batch_emb = sorted(resp.data, key=lambda x: x.index)
            all_emb.extend([e.embedding for e in batch_emb])

        self.embeddings = np.array(all_emb, dtype=np.float32)
        print(f"Ingestion complete: {len(self.chunks)} chunks indexed")

    # --- Retrieval Phase ---

    def search(self, question: str, k: int = 5) -> list[dict]:
        """Finds the k most relevant chunks."""
        query_emb = self.client.embeddings.create(
            input=question, model=self.model_embedding
        ).data[0].embedding

        scores = self.embeddings @ np.array(query_emb)
        top_k = np.argsort(scores)[-k:][::-1]

        return [
            {**self.chunks[i], "score": float(scores[i])}
            for i in top_k
        ]

    # --- Generation Phase ---

    def generate(self, question: str, contexts: list[dict]) -> str:
        """Generates a response based on retrieved contexts."""
        # Build the prompt
        formatted_context = "\n\n---\n\n".join(
            f"[Source: {c.get('id', 'unknown')}]\n{c['text']}"
            for c in contexts
        )

        messages = [
            {
                "role": "system",
                "content": (
                    "You are an assistant that answers questions "
                    "based solely on the provided documents. "
                    "If the information is not in the documents, "
                    "state this clearly. Cite your sources."
                )
            },
            {
                "role": "user",
                "content": (
                    f"Reference documents:\n\n{formatted_context}\n\n"
                    f"---\n\nQuestion: {question}"
                )
            }
        ]

        response = self.client.chat.completions.create(
            model=self.model_generation,
            reasoning_effort="none",  # temperature requires effort none
            messages=messages,
            temperature=0.2
        )

        return response.choices[0].message.content

    # --- Complete Pipeline ---

    def answer(self, question: str, k: int = 5) -> dict:
        """Complete RAG pipeline: search → generation."""
        contexts = self.search(question, k=k)
        response = self.generate(question, contexts)

        return {
            "question": question,
            "response": response,
            "sources": [
                {"id": c["id"], "score": c["score"],
                 "excerpt": c["text"][:150]}
                for c in contexts
            ]
        }

Genereerimisfaasis määravad kvaliteeti kolm detaili. Süsteemi sõnum nõuab vastamist ainult esitatud dokumentide põhjal ja tunnistamist, kui info puudub: ilma selle juhendita täidab mudel lüngad oma üldteadmistega, luues usutava, kuid väljamõeldud vastuse. Prefiks [Source: id] enne iga väljavõtet annab mudelile konkreetse viite, mitte ebamäärase „dokumentide põhjal“. Lõpuks vähendab temperature väärtus 0.2 varieeruvust: faktiliste küsimuste korral dokumendibaasi vastu soovid järjepidevust, mitte loovust.

Kasutamine

Testime torustikku minimaalse ärijuhtumi peal – kolm sisemist poliitikat ja küsimus, mis ei kopeeri ühegi neist sõnasõnalist sõnastust.

# Prepare documents
documents = [
    {
        "id": "leave-policy",
        "text": "Employees receive 25 days of paid leave "
                 "per year. Leave must be requested at least 2 weeks "
                 "in advance via the HR portal.",
        "metadata": {"type": "hr", "date": "2026-01"}
    },
    {
        "id": "remote-work-policy",
        "text": "Remote work is authorized up to 3 days per week. "
                 "Tuesdays and Thursdays are mandatory office days. "
                 "Written agreement with the manager is required.",
        "metadata": {"type": "hr", "date": "2026-01"}
    },
    {
        "id": "reimbursement-procedure",
        "text": "Expense reports must be submitted within 30 days "
                 "of the expense. Attach the original receipt. "
                 "Validation by the direct supervisor required for amounts over 200 euros.",
        "metadata": {"type": "finance", "date": "2026-01"}
    },
]

# Create the pipeline
rag = PipelineRAG()
rag.ingest(documents)

# Ask a question
result = rag.answer("How many days of remote work per week?")
print(result["response"])
print("\nSources used:")
for s in result["sources"]:
    print(f"  [{s['score']:.3f}] {s['id']}: {s['excerpt']}")

Viige harjutust veelgi kaugemale, küsides midagi, millele ükski dokument ei vasta, näiteks ettevõtte tervisekindlustuse kohta. Torustik tagastab ikka kolm allikat – otsing leiab alati oma k parimat kandidaati – ja just süsteemi sõnum peab takistama mudelit vastust välja mõtlemast. Selle käitumise kontrollimine enne tootmisse viimist on parem kui selle avastamine kaebuse kaudu.

Optimeerimispunktid

Iga torustiku sammu saab parendada sõltumatult, võimaldades edusamme väikeste, mõõdetavate kohanduste kaudu.

SammVõimalikud optimeerimised
TükeldamineTüki suurus, kattumine, semantiline tükeldamine
ManusedMudeli valik, mõõtmed, teksti rikastamine
OtsingHübriidotsing, ümberjärjestamine (reranking), metaandmete filtrid
Vihje (Prompt)Süsteemi juhised, konteksti formaat, few-shot näited
GenereerimineMudel, temperatuur, viited

Järgmised tunnid detailselt kirjeldavad iga neist optimeerimistest. Lahenda need selles järjekorras: tükeldamine määrab, mida saab leida, ja ükski ümberjärjestamine ei paranda halvasti tükeldatud dokumenti.

Peamised punktid

  • RAG = Otsing + Kontekst + LLM-i genereerimine
  • Torustik jaguneb sissevõtmiseks (offline) ja päringuks (online)
  • Iga komponenti (tükeldamine, manused, otsing, vihje, genereerimine) saab optimeerida sõltumatult
  • RAG on teadmiste lisamisel paindlikum ja odavam kui häälestamine (fine-tuning)