# Hallusinoinnin loppu dokumenttiprosesseissa: näin API-tason lähdeviittaukset sitovat AI-agentin jokaisen väitteen alkuperäiseen tekstikohtaan

> AI-agentin lähdeviittaukset ja hallusinoinnin esto API-tasolla: 15 % parempi lähdetarkkuus ja sivu- tai merkkikohtainen todennus ilman lainausten tokenikuluja.

- Julkaistu: 2026-10-17
- Kirjoittaja: Master Mind
- Alkuperäinen: https://aimaster.fi/artikkelit/hallusinoinnin-loppu-dokumenttiprosesseissa-nain-api-tason-lahdeviittaukset-sito

API-tason sisäänrakennettu lähdeviittausmekanismi parantaa lähteiden poimintatarkkuutta (recall) jopa 15 % verrattuna kehotteeseen rakennettuihin omiin toteutuksiin (Anthropic, 2025). Kun kasvuyritys automatisoi tarjouslaskentaa, sopimuskatselmointia tai teknistä asiakastukea, **AI-agentin lähdeviittaukset ja hallusinoinnin esto** ratkaisevat, uskaltaako asiantuntija luottaa agentin vastaukseen vai tarkistaako hän jokaisen rivin käsin. Pelkkä promptiin kirjoitettu pyyntö mainita lähteet on toive kielimallille; API-tason viittauspakko on deterministinen tarkistusmekanismi.

Vain 1 % suomalaisyrityksistä hyödyntää dataa uuden liiketoiminnan luomiseen (Sitra), ja asiantuntijatyössä suurin tulppa on harvoin dokumenttien puute. Yritykselläsi on jo tuhansia sivuja laitekäsikirjoja, laatustandardeja, toimitusehtoja ja asiakassopimuksia, mutta kukaan ei uskalla kytkeä AI-agenttia vastaamaan niistä, jos yksikin keksitty takuuehto tai väärä toleranssiluku voi maksaa kaupan.

## Miksi pelkkä kehotteeseen kirjoitettu lähdeviittaus pettää kasvuyrityksen dokumenttiprosesseissa?

Kehotteeseen kirjoitettu lähdeviittaus pettää tuotannossa siksi, että kielimalli generoi sekä väitteen että lähdeviitteen vapaana tekstinä. Malli voi mainita oikean dokumentin nimen, mutta muuttaa lainauksen sisällä olevaa lukua, yhdistää kaksi eri pykälää virheellisesti tai keksiä sivunumeron, jota PDF-tiedostossa ei ole.

Kun myynti-insinööri tai juristi huomaa agentin keksineen yhdenkin viitteen omasta päästään, luottamus järjestelmään loppuu siihen paikkaan. Sen sijaan, että agentti säästäisi aikaa, asiantuntija käyttää iltapäivän selaamalla 120-sivuista PDF-sopimusta varmistaakseen, sanooko kohta 4.2 oikeasti niin kuin agentti väittää. Silloin automaatiohankkeesta on tullut kallis oikolukuharjoitus — eikä sitä pelasta yksikään konsulttikalvo.

Perinteinen RAG-arkkitehtuuri (Retrieval-Augmented Generation, eli tiedonhaku, jossa kielimallille syötetään hakukoneen löytämiä tekstikappaleita) ratkaisee ongelmasta vain puolet. Vaikka haku löytäisi oikeat kappaleet, tavallisessa promptissa malli kirjoittaa lainauksen uudelleen token tokenilta ja voi silti vääristää yksityiskohtia.

## Miten AI-agentin lähdeviittaukset ja hallusinoinnin esto toimivat API-tasolla?

**AI-agentin lähdeviittaukset ja hallusinoinnin esto** API-tasolla perustuvat siihen, että alusta pilkkoo lähdedokumentit lauseiksi tai lohkoiksi ennen päättelyä ja pakottaa vastauksen palauttamaan eksaktit sijainti-indeksit. Kielimalli ei kirjoita lainausta ulkomuistista, vaan API-jäsennin poimii lainatun tekstin (`cited_text`) suoraan alkuperäisestä dokumentista.

Esimerkiksi Anthropicin Claude Citations -rajapinnassa (2025–2026) dokumenttilohkolle asetettu `citations.enabled=true` muuttaa tavan, jolla malli käsittelee lähdeaineistoa. Rajapinta jakaa dokumentin automaattisesti lauseisiin ja liittää jokaiseen agentin esittämään väitteeseen rakenteisen viittauslohkon. Viittauksen tarkkuus määräytyy dokumenttityypin mukaan:

- **Pelkkä teksti (Plain text):** Rajapinta pilkkoo tekstin lauseiksi ja palauttaa 0-indeksoidun merkkivälin (`start_char_index` ja `end_char_index`), joka osoittaa merkin tarkkuudella oikeaan kohtaan lähdetekstissä.
- **PDF-dokumentit:** Rajapinta purkaa PDF:n tekstin, jakaa sen lauseiksi ja palauttaa 1-indeksoidun sivunumerovälin (`start_page_number` ja `end_page_number`). Skannattuja kuvamuotoisia PDF-tiedostoja ei voi viitata suoraan, minkä vuoksi pohjalle tarvitaan ensin [OCR- ja pilkkomisputken AI-agentin käyttöön](https://aimaster.fi/artikkelit/dokumenttidata-ei-ole-viela-tietoa-nain-kasvuyritys-rakentaa-ocr-ja-pilkkomisput) rakentava esikäsittely.
- **Räätälöidyt dokumenttilohkot (Custom content):** Jos syötät agentille valmiiksi pilkottuja taulukkorivejä, tuoteluetteloita tai puhelulitterointeja, rajapinta ei pilko niitä uudelleen vaan palauttaa 0-indeksoidun lohkovälin (`start_block_index` ja `end_block_index`).

Ratkaiseva taloudellinen ja tekninen etu piilee tokenilaskutuksessa. Anthropicin dokumentaation (2026) mukaan API-vastauksen palauttama suora lainaus (`cited_text`) ei kuluta lainkaan ulostulotokeneita (output tokens), eikä sitä laskuteta syötetokeneina keskustelun seuraavilla kierroksilla. Saat sanasta sanaan tarkistetut suorat lainaukset ilman, että pitkät sopimusotteet kasvattavat ulostulotokenien laskua.

| Ominaisuus | Prompt-pohjainen lähdeviittaus | Perinteinen RAG ilman API-viitteitä | API-tason lähdeviittaus (Citations API) |
| --- | --- | --- | --- |
| Osoittimen tarkkuus | Mallin kirjoittama vapaa teksti; voi keksiä sivunumeron | Tietää haetun tekstipalan, ei tarkkaa lausetta sen sisällä | Deterministinen merkki-, sivu- tai lohkoindeksi lähdetiedostoon |
| Lainauksen eheys | Malli voi muuttaa lukuja tai lyhentää ehtoja vapaasti | Malli generoi lainauksen uudelleen token tokenilta | API-jäsennin poimii `cited_text`-kentän suoraan alkuperäisestä datasta |
| Lainauksen ulostulotoken-hinta | Laskutetaan täysinä ulostulotokeneina jokaisesta sanasta | Laskutetaan täysinä ulostulotokeneina jokaisesta sanasta | `cited_text` ei kuluta lainkaan ulostulotokeneita (0 output tokenia) |
| Lähteiden poimintatarkkuus (recall) | Perustaso; heikkenee pitkissä monidokumenttikyselyissä | Riippuu palakoko- ja prompt-virityksestä | Jopa +15 % korkeampi poimintatarkkuus (Anthropic, 2025) |

## Miten API-lähdeviittaukset ja JSON Structured Outputs yhdistetään ERP- tai CRM-putkessa?

API-tason lähdeviittauksia ja pakotettua JSON-skeemaa (Structured Outputs) ei voi käyttää samassa API-kutsussa — molempien kytkeminen päälle yhtä aikaa palauttaa HTTP 400 -virheen (Anthropic, 2026). Tuotantojärjestelmissä tämä ratkaistaan kaksivaiheisella agenttiputkella, jossa ensimmäinen vaihe todentaa faktat lähdeviitteineen ja toinen vaihe muotoilee tietueen JSON-skeemaan.

Tekninen syy yhteensopimattomuudelle on selkeä: lähdeviittaukset vaativat tekstiväitteiden ja viittausmetadatan lomittamista vastausvirtaan, kun taas [structured outputs ja JSON-skeema tekoälyintegraatiossa](https://aimaster.fi/artikkelit/structured-outputs-ja-json-skeema-tekoalyintegraatiossa-estavat-rikkinaiset-erp-kutsut) lukitsevat koko ulostulon tiukkaan JSON-syntaksipuuhun. Jos kehittäjä yrittää lähettää samassa pyynnössä sekä `citations: {"enabled": true}` että `output_config.format`-parametrin, kutsu kaatuu välittömästi.

Me AIMASTERilla toteutamme tämän kaksivaiheisena arkkitehtuurina [Master OS](https://aimaster.fi/tuotteet/master-layer) -alustan päällä. **Master OS** on yrityksen AI Operating System: alusta, joka yhdistää yrityksen olemassa olevat järjestelmät (CRM, ERP, dokumentit), datan ja agentit turvallisesti tekoälyn käytettäväksi. Vaiheessa yksi lukija-agentti käy läpi välimuistiin (`cache_control: {"type": "ephemeral"}`) viedyt dokumentit lähdeviittaukset päällä ja tuottaa todennetun vastauksen sivu- ja merkki-indekseineen. Vaiheessa kaksi kevyt muotoilukutsu muuntaa todennetut väitteet ja niiden lähdeosoittimet tiukkaan JSON-skeemaan ERP- tai tikettijärjestelmää varten.

## Miten kasvuyritys ottaa lähdetodennetun dokumenttiagentin käyttöön 3 päivän sprinteissä?

Lähdetodennetun dokumenttiagentin käyttöönotto alkaa arvokkaimman dokumenttipullonkaulan kartoituksesta, lähdetiedostojen vakioinnista ja viittauspakotetun työnkulun rakentamisesta 3 päivän sprinteissä. Yrityksesi ei tarvitse vaihtaa dokumentinhallintaa, sillä agentti kytketään suoraan olemassa oleviin kansioihin ja järjestelmiin.

Vaikka 57 % suomalaisista pk-yrityksistä käyttää tekoälyä (2025), 43 % ei käytä lainkaan, ja suurin este käyttöönotolle on osaamisen puute (43 % ei-käyttäjistä). Moni kasvuyritys on kokeillut syöttää sopimuksia tai huoltokirjoja yleiseen keskustelutyökaluun, törmännyt keksittyyn lukuun ja todennut, ettei tekoälyyn voi luottaa. Ongelma ei ole tekoälyssä vaan siinä, että tuotantoarkkitehtuurista puuttuu API-tason lähdetodennus.

Me viemme dokumenttiagentit tuotantoon kolmessa vaiheessa ilman kuukausien esiselvityksiä:

- **[Master Plan](https://aimaster.fi/tuotteet/master-plan)** on tekoälystrategiasprintti, joka kartoittaa, missä tekoäly tuottaa yrityksellesi eniten arvoa — euroissa mitattuna. Tunnistamme, missä tarjous-, sopimus- tai tukiprosessissa asiantuntijoiden tunnit kuluvat nyt manuaaliseen pykälien tarkistamiseen.
- **Master OS** kytkee PDF-käsikirjat, sopimukset ja spesifikaatiot versioituun putkeen, jossa skannatut tiedostot ajetaan OCR-tekstintunnistuksen läpi, pysyvät dokumentit asetetaan prompt-välimuistiin ja `citations.enabled=true` pakotetaan jokaiseen kyselyyn.
- **[Master Mind](https://aimaster.fi/tuotteet/master-mind)** on AI-agenttien kokonaisuus, joka toimii Master OS:n päällä ja hoitaa liiketoimintaprosesseja itsenäisesti. **Räätälöidyt AI-ratkaisut** toteutetaan ketterällä sprinttimallilla: yksi sprintti on 3 kehityspäivää. Käyttöliittymässä jokainen agentin kirjoittama lause avaa klikkauksella täsmälleen sen PDF-sivun ja lauseen, johon väite perustuu.

Kuvitellaan anonymisoitu suomalainen kone- ja laitevalmistaja, jonka myynti-insinöörit vastaavat asiakkaiden 50-sivuisiin teknisiin vaatimuserittelyihin. Aiemmin hydrauliikka-, sähkö- ja turvallisuuskäsikirjojen ristiintarkistus vei kaksi työpäivää tarjousta kohden. Kun prosessiin kytketään Master OS:n päällä toimiva lähdetodennettu agentti, se luonnostelee vastaukset ja liittää jokaiseen lupaukseen käsikirjan nimen, sivunumeron ja suoran lainauksen (`cited_text`). Insinööri klikkaa viitettä, näkee korostetun lauseen alkuperäisellä PDF-sivulla ja hyväksyy tarjouksen 20 minuutissa. Samaa todennettavaa luotettavuutta hyödynnämme omissa portfolio-tuotteissamme, kuten Lyyli.ai:ssa ja VÖRKissä, sekä julkisille referenssiasiakkaillemme kuten Tagomolle ja Ainille (Jaajo Linnonmaa) rakennetuissa ratkaisuissa.

Haluatko nähdä, mikä yrityksesi dokumenttiprosessi voidaan automatisoida ilman pelkoa keksityistä vastauksista? Aloita tilaamalla [Ilmainen Master Mind -analyysi](https://aimaster.fi/analyysi), niin kartoitamme, missä lähdetodennetut AI-agentit tuottavat liiketoiminnallesi suurimman hyödyn euroissa.

## Usein kysytyt kysymykset

### Miten API-tason lähdeviittaus eroaa kehotteessa pyydetystä lähdeviittauksesta?

Kehotteeseen kirjoitettu pyyntö on vain tekstiohje kielimallille, joka voi silti keksiä sivunumeroita tai muuttaa lainauksen sanamuotoa. API-tason lähdeviittaus pilkkoo lähdedokumentin rakenteellisesti ennen vastausta ja palauttaa suoraan lähdetiedostosta poimitun merkki- tai sivunumerovälin.

### Kasvattavatko pitkät suorat lainaukset AI-agentin ulostulotokenien hintaa?

Ei maksa. Anthropicin Citations-rajapinnassa suoraa lainausta sisältävä cited_text-kenttä ei kuluta lainkaan ulostulotokeneita (output tokens). Sitä ei myöskään laskuteta syötetokeneina keskustelun seuraavilla kierroksilla.

### Mitä dokumenttityyppejä API-tason lähdeviittaukset tukevat?

Rajapinta tukee kolmea muotoa: pelkkää tekstiä (0-indeksoidut merkkivälit), tekstisisältöisiä PDF-tiedostoja (1-indeksoidut sivunumerovälit) ja valmiiksi lohkottuja custom content -dokumentteja (0-indeksoidut lohkovälit). Skannatut kuvamuotoiset PDF-tiedostot on ensin ajettava tekstintunnistuksen (OCR) läpi.

### Voiko API-tason lähdeviittauksia ja JSON Structured Outputs -muotoa käyttää samassa kutsussa?

Ei voi. Jos samassa API-pyynnössä ovat päällä sekä citations että JSON-skeemaan pakotettu ulostulo, rajapinta palauttaa 400-virheen. Tuotannossa tämä ratkaistaan kaksivaiheisella putkella, jossa ensimmäinen vaihe tuottaa todennetun vastauksen viitteineen ja toinen vaihe muotoilee datan JSON-skeemaan.