Artikkeli

Miksi malli kirjoittaa työkalukutsunsa tekstinä

1.11.2026 · Todenta · 6 min lukuaika · Koostettu tekoälyllä, toimitettu ihmisen toimesta

Eräänä päivänä kirjanpitosovelluksen chat-kenttään kirjoitettiin kysymys liikevaihdosta. Vastaukseksi tuli SQL-kysely. Koko kysely — taulunimet, ehdot, kaikki — suoraan asiakkaan näkyviin.

Helppo selitys on että malli on huono. Se ei ollut se syy.

Mitä oikeasti tapahtui

Järjestelmä antaa mallille työkaluja: funktioita joita se voi kutsua hakeakseen dataa. Malli ei näe tietokantaa. Se näkee listan työkaluja ja niiden kuvaukset, ja jos se tarvitsee lukuja, sen pitäisi kutsua työkalua.

Työkalukutsu kulkee API:ssa rakenteellisena kenttänä — erillään tekstistä. Vastauksessa on kaksi kenttää:

{
  "choices": [{
    "message": {
      "content": null,               ← tekstivastaus
      "tool_calls": [{               ← rakenteellinen kutsu
        "function": { "name": "hae_luvut", "arguments": "{...}" }
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

Kun malli käyttää tool_calls-kenttää, sovellus näkee kutsun ja voi ajaa sen. Käyttäjä ei näe mitään — näkee vain lopullisen vastauksen.

Mutta malli voi myös tehdä jotain muuta: kirjoittaa saman asian tekstinä content-kenttään.

{
  "choices": [{
    "message": {
      "content": "[TOOL_CALL]{\"tool\":\"hae_luvut\",\"args\":{...}}[/TOOL_CALL]",
      "tool_calls": null             ← ei kutsua
    },
    "finish_reason": "stop"
  }]
}

Silloin sovellus näkee pelkkää tekstiä. Ei kutsuttavaa funktiota. Ja jos sovellus näyttää content-kentän sellaisenaan — kuten chat-ikkuna tekee — käyttäjä näkee raakatekstin.

Mitattu tästä järjestelmästä:

  • Lyhyt kysymys mallille suoraan → finish_reason: stop, ei tool_calls-avainta lainkaan
  • Pitkä järjestelmäkehote + työkalut mukana → [TOOL_CALL] tekstinä content-kentässä
  • API-loki kirjasi kutsun onnistuneeksi — virhettä ei ollut missään

Viimeinen kohta on se joka tekee tästä hankalan. Järjestelmä ei epäonnistunut. HTTP 200, kelvollinen JSON, kelvollinen vastaus. Ainoa outo asia oli sen sisältö — ja sisällön oikeellisuutta ei valvo mikään.

Miksi malli tekee niin

Työkalukutsujen tarkka muoto on API-sopimus, ei mallin ominaisuus. Malli on koulutettu tuottamaan sekä rakenteellisia kutsuja että tekstiä, ja kumpi tulee ulos riippuu siitä mitä kehotteessa on ja mitä API-versiota käytetään.

Kolme yleistä syytä, tässä tapauksessa todennäköisesti kaikki kolme:

1. Kehote kuvaa työkalun tekstinä

Jos järjestelmäkehotteessa lukee "sinulla on käytössäsi funktio hae_luvut jota kutsumalla saat luvut", malli voi tulkita että sen pitää kirjoittaa kutsu. Rakenteellinen kutsu vaatii että työkalut annetaan tools-parametrissa, ei tekstinä kehotteessa.

2. Pitkä kehote hukuttaa rakenteen

Kun kehotteessa on tuhat riviä sääntöjä, tools-määrittely jää suhteellisesti pieneksi osaksi kontekstia. Mitä pidempi kehote, sitä todennäköisemmin malli jäljittelee näkemäänsä tekstin muotoa rakenteen sijaan.

3. Työkaluvalinta ei ole pakollinen

Oletuksena malli saa valita: kutsua työkalua tai vastata suoraan. Jos se arvioi ettei osaa, se saattaa "näyttää yrityksen" kirjoittamalla kutsun tekstinä. Tämä on erityisen yleistä silloin kun malli ei tunne taulurakennetta — se keksii taulunimiä, ja keksitty taulu paljastaa että arvaus epäonnistui.

Tässä tapauksessa malli keksi tauluja joita ei ole olemassa: laskut, yritys_id, maara. Oikeat olivat tositteet, myyntilaskut, ostolaskut, tilikartta.

Kolme tapaa korjata — ja miksi kaksi niistä on huonoja

Vaihtoehto A: pakota työkalukutsu

Useimmat API:t tukevat tool_choice: "required" -asetusta, joka pakottaa mallin kutsumaan jotain työkalua. Se toimii — mutta rikkoo normaalin keskustelun. Kun käyttäjä kysyy "hei", malli ei voi vastata, koska sen on pakko kutsua työkalua.

Käyttökelpoinen vain silloin kun kaikki liikenne on työkaluvetoista. Chat-ikkunassa ei.

Vaihtoehto B: parsitaan teksti takaisin rakenteeksi

Etsitään vastauksesta [TOOL_CALL]-lohko ja tulkitaan se. Tämä on houkutteleva, koska se "korjaa" ongelman näkyvissä. Mutta se on myös sopimus jonka kanssa sinun on elettävä: mallin tekstimuoto ei ole dokumentoitu, ei versioitu eikä taattu. Se voi muuttua seuraavassa mallipäivityksessä.

Vaihtoehto C: siivotaan vastaus ennen näyttämistä

Hyväksytään että malli välillä vuotaa, ja siivotaan se pois ennen kuin käyttäjä näkee sen. Ei yritetä korjata mallin käytöstä — korjataan lopputulos.

Tämä on se mitä itse teimme, koska se on ainoa vaihtoehto joka ei riipu mallin sisäisestä logiikasta. Se ei ole kaunis, mutta se on deterministinen: sama syöte tuottaa aina saman tulosteen.

Mitä siivous käytännössä tarkoittaa

Muotoportti ei ole yksi sääntö vaan neljä, ja jokainen niistä vastaa eri vuototapaa:

VuotoMitä poistetaan
[TOOL_CALL]...[/TOOL_CALL]Koko lohko alusta loppuun
Koodiaita, jonka sisällä SQL tai JSONKoko aita sisältöineen
Rivin alussa [SQL] tai suoraan SELECTSe rivi
Rivin alussa "Haen…", "Tarkistan…", "Käytän työkalua…"Se rivi

Neljäs rivi on se jota en aluksi ymmärtänyt. Kun lohkot on poistettu, jäljelle jää usein lupaus siitä mitä mallin piti tehdä:

"Hakien liikevaihtoa Yritys 2:n kirjanpidosta."

Tämä ei ole vastaus eikä virhe. Se on aikeen kuvaus, joka jäi jäljelle kun varsinainen kutsu poistettiin. Käyttäjälle se näyttää siltä että järjestelmä aikoo tehdä jotain mutta ei saa aikaan.

Se osa joka meni ensin pieleen

Ensimmäinen versio siivouksesta käytti sääntöä: jos vastauksesta poistettiin yli puolet ja jäljelle jäi alle 40 merkkiä, vastaus hylätään kokonaan. Järkevän oloinen kynnysarvo.

Se rikkoi oikean vastauksen:

Tulos: 1 121 280 EUR       ← 19 merkkia, mutta taysin oikea vastaus

Lyhyt vastaus ei ole huono vastaus. Korjaus oli yksinkertainen mutta ei ilmeinen: numero yksin riittää sisällöksi. Jos jäljelle jäävässä tekstissä on numero, se on dataa. Pelkkä meta-teksti ei sisällä numeroa.

Tämä on se yksityiskohta jota mikään dokumentaatio ei kerro, ja jonka oppii vain kun näkee väärän hylkäyksen.

Mitä tästä jää käteen

  • HTTP 200 ei tarkoita onnistumista. Mallin vastaus voi olla muodollisesti oikein ja sisällöllisesti väärin.
  • Työkalukutsu on sopimus, ei itsestäänselvyys. Jos se ei kulje rakenteellisena, se kulkee tekstinä.
  • Pitkä kehote lisää vuotoriskiä. Mitä enemmän sääntöjä, sitä enemmän mallilla on jäljiteltävää tekstiä.
  • Kynnysarvot ovat vaarallisia. Jokainen "jos alle X merkkiä" -sääntö on väärä jossain tapauksessa.
  • Loki joka kirjaa vain onnistumisen ei näe tätä. Kriittinen tieto oli vastauksen sisältö, ei sen status.

Jos rakennat samaa: laita portti vastausputkeen, älä kehotteeseen. Kehote on toive, portti on tarkistus. Ja kirjaa mitä portti poisti — se luku kertoo enemmän kuin mikään hälytys.

Todenta tekee tämän osana AI-hallintakerrosta. Lue mitä se muuten tekee →

Todenta · Lennoware Oy · Etusivu · Yksi sivu · Tietosuojaseloste