Retrieval-Augmented Generation eli RAG on tuotanto-AI:n ehkä tärkein arkkitehtuuripala. Lähes jokainen sisäisen tiedon kysymys-vastaus-bot, dokumenttihakukone tai asiakaspalveluapuri rakentuu sen päälle. Tässä oppaassa rakennamme oman RAG-järjestelmäsi alusta loppuun PostgreSQL + pgvector -yhdistelmällä, ja generaattorina toimii Claude.
Tavoite on toimiva tuotantokelpoinen järjestelmä viikossa. Tämä on realistinen aikataulu, jos sinulla on perustiedot Postgresista ja Node.js:stä tai Pythonista. Opas ei käy läpi koodin yksityiskohtia rivi riviltä, mutta antaa selkeän rakenteen ja kuvaa kohdat, joissa kannattaa pysähtyä.
Miksi pgvector eikä erikoiskanta
pgvector on Postgresin laajennus, joka tuo vektorihaun samaan tietokantaan relaatiodatan kanssa. Suurin etu on yksinkertaisuus: et tarvitse kahta erillistä tietokantaa, transaktioita voi käyttää normaalisti, ja varmuuskopiointi sekä monitorointi tapahtuvat samoilla työkaluilla kuin Postgresissa muutenkin.
Erikoiskannat ovat parempia kahdessa tapauksessa: kun vektorimäärä ylittää 100 miljoonan tai kun tarvitaan erityisiä hybridihakuja, jotka yhdistävät vektori- ja tekstihakua eri tavalla kuin pgvector osaa. Useimmille suomalaisille yrityksille pgvector riittää helposti.
Vektorikantojen vertailu
Tilanteen hahmottamiseksi tässä viiden suosituimman vektorikannan vertailu samasta lähtötilanteesta: 1 miljoonan dokumentin korpus, 10 miljoonaa chunkia.
| Vektorikanta | Hinta (10 M vekt.) | Latency p95 | Pystytys | Sopii kun |
|---|---|---|---|---|
| pgvector | $50/kk (RDS) | 12 ms | Helppo | Postgres jo käytössä |
| Pinecone | $70/kk | 8 ms | Hyvin helppo | Skaalautuu yli 100 M |
| Weaviate | $120/kk | 10 ms | Kohtuu vaativa | Hybridihaku, monikriteeri |
| Qdrant | $45/kk (self) | 9 ms | Vaativa | On-premises pakollinen |
| Milvus | $110/kk | 11 ms | Vaativa | Skaalaus yli 1 B vekt. |
Tarvittavat työkalut
PostgreSQL 16+ (Supabase, AWS RDS tai self-hosted)
pgvector-laajennus, asennettavissa komennolla CREATE EXTENSION vector;
Node.js 22+ tai Python 3.11+
Anthropic API -avain Claude embeddings -laskentaa ja generaatiota varten
Dokumenttisetti syötettäväksi (PDF, DOCX, Markdown tai HTML)
Vaihe 1: tietokannan pystytys
Luo Postgres-instanssi (Supabase on yksinkertaisin aloitus), ota pgvector käyttöön ja luo dokumenttitaulu. Vektorisarake on tyyppiä VECTOR(1024), sillä Claude embeddings palauttaa 1024-ulotteisia vektoreita. Lisää myös HNSW-indeksi vektorisarakkeelle, sillä se nopeuttaa hakuja kymmenkertaisesti normaaliin sequential scaniin verrattuna.
Vaihe 2: dokumenttien chunkaus
Pilko dokumentit 500–800 sanan paloiksi ja säilytä 50–100 sanan overlap palojen välillä, jotta konteksti ei katkea kahden palan rajalla. Tallenna pala, metadata (lähdedokumentti, sivu, kappaleotsikko) ja embedding tietokantaan yhdellä INSERTilla. Käytä Claude Embedding API:n batch-toimintoa, joka käsittelee 100 chunkia per kutsu.
Vaihe 3: kysely ja generaatio
Kun käyttäjä esittää kysymyksen, hae 5–10 relevanttia chunkia pgvectorin ANN-hakulla, syötä ne Claudelle kontekstina ja pyydä vastausta. Hyvä prompt-pohja löytyy promptauksen perusperiaatteistamme. Jos haluat agenttipohjaisen ratkaisun, jossa malli voi tarvittaessa pyytää lisää chunkeja, MCP-serverin pystytys Claude Codeen antaa luonnollisemman työnkulun pitkille keskusteluille.
Vaihe 4: token-kustannukset
RAG-järjestelmän todelliset kustannukset eivät tule embedeistä vaan generaatiosta. Yhden vastauksen pituus kerrallaan moninkertaistuu kuukauden mittaan helposti tuhansiksi euroiksi, jos optimointia ei tehdä. Lue kattava token-kustannusten hallinta -oppaamme, jos suunnittelet tuotantokäyttöä. Pienillä optimoinneilla säästät helposti 60–80 prosenttia kuukausilaskusta.
Vaihe 5: tuotantoon vienti
Lisää välimuistitus (Claude tukee prompt cachea, käytä sitä), rate limiting ja monitorointi. Hyvä vinkki on käyttää Claude Opus 4.7:ää vaikeisiin kysymyksiin ja Haikua yksinkertaisiin. Reititys mallien välillä laskee kuluja merkittävästi. Opus 4.7:n parannukset tekevät tästä mahdollisen ilman laadun menetystä, sillä uudemman version osaaminen kompensoi sen, kun raskaita kyselyjä reititetään harvemmin.
Yleisimmät virheet
Listamme yleisimmät RAG-projekteissa kohdatut virheet, joita olemme nähneet kymmenissä toteutuksissa.
Liian iso chunk-koko: konteksti karkaa, mutta semantiikka heikkenee
Unohdettu metadata-suodatus: hakutulokset ovat liian väljiä, malli saa irrelevanttia kontekstia
Ei prompt cachea: kustannukset 3–4-kertaistuvat
Yli-pitkät kontekstit: malli alkaa hukata fokusta yli 500 000 tokenin jälkeen
Pelkkä top-K-haku ilman re-rankingia: tarkkuus jää 60–70 prosentin tasolle, vaikka voisi olla 85+
Suomalainen näkökulma
Suomenkielinen RAG-toteutus toimii Claudella erinomaisesti, sillä mallin tokenisaattori käsittelee suomea suhteellisen hyvin verrattuna esimerkiksi vanhempiin GPT-3.5-tasoisiin malleihin. Käytännön kokemus kuitenkin osoittaa, että parhaat tulokset saadaan, kun chunk-koko on suomen kielessä hieman pienempi (400–600 sanaa) ja metadata-kuvaukset ovat englanniksi.
Useat suomalaiset RAG-projektit ovat onnistuneet hyvin myös sääntelyalan dokumentaatiossa, kuten kuntien päätöksenteon arkistoissa ja vakuutusalan ehtopapereissa. Tieto on usein staattista, mutta sen volyymi tekee manuaalisesta hausta käytännössä mahdotonta.
RAG ei ole vain tekninen toteutus, vaan tuotekehityskysymys. Mitä paremmin tunnet käyttäjäkyselyt, sitä parempaa retrievalia saat. Aloita pienestä, mittaa, iteroi — älä yritä rakentaa täydellistä järjestelmää ensimmäisellä yrityksellä.
