RAG-arkkitehtuuri kokonaisuudessaan
Tällä sivulla
Oppitunti päivitetty 3. marraskuuta 2026 OpenAI:n dokumentaation perusteella: parametrit
temperaturejatop_phyväksytään vain, jos päättelypyrkimys onnone, 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) taireasoning_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ä.
| Vaihe | Mahdolliset optimoinnit |
|---|---|
| Paloitelu | Palan koko, päällekkäisyys, semanttinen paloitelu |
| Upotus | Mallin valinta, ulottuvuudet, tekstin rikastaminen |
| Haku | Hybridi, uudelleenjärjestely, metadata-suodattimet |
| Kehote | Järjestelmäohjeet, asiayhteyden muotoilu, few-shot |
| Generointi | Malli, 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ö