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

RAG-arkkitehtuuri kokonaisuudessaan

Oppitunti 11 / 22 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Tavoitteet
  2. Mikä on RAG?
  3. Putken vaiheet
  4. Kokonaistoteutus
  5. Käyttö
  6. Optimointikohdat
  7. Keskeiset asiat

Oppitunti päivitetty 3. marraskuuta 2026 OpenAI:n dokumentaation perusteella: parametrit temperature ja top_p hyväksytään vain, jos päättelypyrkimys on none, kun taas GPT-5.6-mallit käyttävät oletusarvoisesti päättelyä (medium). Näitä parametreja asettavien kutsujen on siksi määritettävä reasoning={"effort": "none"} (API Responses) tai reasoning_effort="none" (Chat Completions). Lähteet: Using GPT-6 · GPT-5.6 Terra.

Tavoitteet

  • Ymmärtää RAG-arkkitehtuuri kokonaisuudessaan
  • Toteuttaa toimiva RAG-putki
  • Tunnistaa optimoitavat komponentit

Mikä on RAG?

RAG (Retrieval-Augmented Generation) yhdistää dokumenttihaut ja LLM:n tuottaman tekstin. Malli ei luota pelkästään sisäiseen tietämykseensä, vaan saa asiayhteydeksi relevantteja dokumentteja ja laatii vastauksensa niiden pohjalta. Kaikki, mitä olet rakentanut tämän kurssin alusta lähtien – upotukset, indeksointi, haku ja arviointi – muodostaa tässä vaiheessa完整的 järjestelmän ensimmäisen puoliskon.

Miksi RAG?

Neljä syytä tukevat sen käyttöä, ja ne vahvistavat toisiaan. Ensinnäkin omistusoikeudellinen data: etätyöpolitiikkasi, sisäiset menettelytavat ja tuoteluettelosi eivät ole koskaan olleet mallin koulutusdatassa, eikä mikään kehote saa niitä sinne. Toiseksi tuore tieto: kaikki koulutuksen jälkeinen aineisto on mallille näkymätöntä, kun taas indeksi päivittyy samana päivänä. Todennettavuus on yhtä tärkeää, sillä jokainen vastaus ankkuroituu tunnistettaviin lähteisiin, jotka käyttäjä voi avata ja tarkistaa – tämä muuttaa järjestelmään kohdistuvan luottamuksen luonnetta. Lopuksi kustannukset puoltavat sitä: tiedon lisääminen RAG:n kautta maksaa huomattavasti vähemmän kuin hienosäätö, ja korjaukset tehdään poistamalla dokumentti mallin uudelleenkouluttamisen sijaan.

Putken vaiheet

Tulkitse RAG kahtena erillisenä vaiheena, joita ei saa sekoittaa keskenään. Ingestointi tapahtuu offline-tilassa, kerran ja lopullisesti tai aina kun tietokanta päivittyy:

Dokumentit → Paloitelu → Upotukset → Vektorivarasto

Kysely tapahtuu online-tilassa jokaista kysymystä kohden, ja sen on pysyttävä nopeana:

Kysymys → Upotus → Haku → Asiayhteys + Kysymys → LLM → Vastaus

Tällä erottelulla on käytännön seuraus: ingestointikustannukset maksetaan kerran ja ne voivat olla raskaita, kun taas kyselykustannukset maksetaan jokaisesta kutsusta ja ne määräävät käyttäjäkokemuksen. Voit siis sallia monimutkaista ingestointikäsittelyä, mutta kyselypuolella sinun on pysyttävä kevyenä.

Kokonaistoteutus

Seuraava luokka konkretisoi kolme vaihetta kolmessa erillisessä metodissa sekä neljännen metodin, joka ketjuttaa ne yhteen. Tämä erottelu ei ole kosmeettista: se mahdollistaa haun testaamisen kuluttamatta generointitokeneita ja generoinnin toistamisen kiinteällä asiayhteydellä kahden kehotteen vertailemiseksi.

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

    # --- Ingestointivaihe ---

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

        # Luo upotukset erissä
        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"Ingestointi valmis: {len(self.chunks)} palaa indeksoitu")

    # --- Hakuvaihe ---

    def search(self, question: str, k: int = 5) -> list[dict]:
        """Etsii k relevantinta palaa."""
        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
        ]

    # --- Generointivaihe ---

    def generate(self, question: str, contexts: list[dict]) -> str:
        """Generoi vastauksen haettujen asiayhteyksien perusteella."""
        # Rakenna kehote
        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

    # --- Kokonainen putki ---

    def answer(self, question: str, k: int = 5) -> dict:
        """Täydellinen RAG-putki: haku → generointi."""
        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
            ]
        }

Kolme yksityiskohtaa generointivaiheessa vaikuttavat laatuun eniten. Järjestelmäviesti määrää vastaamaan vain annettujen dokumenttien perusteella ja myöntämään, jos tietoa puuttuu: ilman tätä ohjetta malli täyttää aukot yleisellä tietämyksellään, mikä tuottaa uskottavan mutta keksityn vastauksen. [Source: id]-etuliite ennen jokaista otetta antaa mallille jotain konkreettista lainattavaksi epämääräisen “dokumenttien mukaan” -sijaan. Lopuksi temperature-arvo 0.2 vähentää vaihtelua: faktuaalisissa kysymyksissä dokumenttikantaa vasten haluat johdonmukaisuutta, et luovuutta.

Käyttö

Testataan putkea minimaalisella liiketoimintatapauksella – kolme sisäistä käytäntöä ja kysymys, joka ei kopioi niiden tarkkaa sanamuotoa.

# Valmistele dokumentit
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"}
    },
]

# Luo putki
rag = PipelineRAG()
rag.ingest(documents)

# Esitä kysymys
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']}")

Vie harjoitusta pidemmälle kysymällä jotain, mihin mikään dokumentti ei vastaa, kuten yrityksen sairausvakuutussuunnitelmaa koskeva kysymys. Putki palauttaa silti kolme lähdettä – haku palauttaa aina k parasta ehdokasta – ja juuri järjestelmäviestin on estettävä mallia keksimästä vastausta. Tämän käyttäytymisen varmistaminen ennen tuotantoon viemistä on parempi kuin sen havaitseminen valituksen kautta.

Optimointikohdat

Jokainen putken vaihe voidaan parantaa itsenäisesti, mikä mahdollistaa edistymisen pienillä, mitattavissa olevilla säädöillä.

VaiheMahdolliset optimoinnit
PaloiteluPalan koko, päällekkäisyys, semanttinen paloitelu
UpotusMallin valinta, ulottuvuudet, tekstin rikastaminen
HakuHybridi, uudelleenjärjestely, metadata-suodattimet
KehoteJärjestelmäohjeet, asiayhteyden muotoilu, few-shot
GenerointiMalli, lämpötila, viittaukset

Seuraavat oppitunnit käsittelevät kutakin näistä optimoinneista yksityiskohtaisesti. Tartu niihin tässä järjestyksessä: paloitelu määrää sen, mitä voidaan hakea, eikä mikään uudelleenjärjestely korjaa huonosti paloiteltua dokumenttia.

Keskeiset asiat

  • RAG = Haku + Asiayhteys + LLM-generointi
  • Putki jakautuu ingestointiin (offline) ja kyselyyn (online)
  • Jokaista komponenttia (paloittelu, upotus, haku, kehote, generointi) voidaan optimoida itsenäisesti
  • RAG on joustavampi ja edullisempi tapa lisätä tietoa kuin hienosäätö