Voitot:
- Osaa kuvata LLM API -pyynnön perusrakenteen (päätepiste, malli, viestit, max_tokens)
- Ymmärtää eron järjestelmä-, käyttäjä- ja avustajaroolien ja tilattoman keskusteluhistorian välillä
- Osaa lukea ja tulkita palautetun vastauksen kenttiä (sisältölohkot, stop_reason, use).
Aiemmissa moduuleissa käytimme tekoälyä chat-ikkunasta. Mutta jos haluat upottaa tekoälyä omaan tuotteeseen, automaatioon tai työnkulkuun, chat-käyttöliittymä ei katkaise sitä. Sinun täytyy muodostaa yhteys malliin ohjelmallisesti, eli koodilla tai automaatiotyökalulla. Tämän sillan nimi on API (Application Programming Interface, sopimus, joka sallii kahden ohjelmiston keskustella tiettyjen sääntöjen mukaisesti). Kun lopetat tämän yksikön, tiedät, mitä LLM (Large Language Model) API-pyyntö muodostaa, mitä viestiroolit tekevät ja kuinka vastaus luetaan. Tämä on perusta, jolle muu moduuli rakennetaan.
Kuinka API toimii?
API:n peruskulku on seuraava: lähetät pyynnön tietyssä muodossa; Palvelin palauttaa vastauksen tietyssä muodossa. LLM:issä tämä on yleensä HTTP-puhelu (HTTP: standardiprotokolla pyyntö-vastauksen kuljettamiseen verkossa) yhteen osoitteeseen (päätepiste, pyyntöäsi käsittelevän palvelimen kiinteä osoite). Esimerkiksi viestintäsovellusliittymässä kaikki pyynnöt menevät yhteen osoitteeseen ja ne kuljetetaan rungossa JSON-muodossa (JavaScript Object Notation – tekstimuoto, joka koostuu avain/arvo-pareista, joita sekä ihmiset että koneet voivat lukea).
Pyynnössä määrität ainakin nämä kolme asiaa:
- Malli: Mitä mallia käytät (esim. nopea ja halpa malli tai tehokas malli).
- max_tokens: Tokenien enimmäismäärä (pienin yksikkö, jossa tekstiä käsitellään, joka käsitellään yksityiskohtaisesti seuraavassa yksikössä), jonka malli voi tuottaa; eli lähtöraja.
- viestit: Luettelo keskustelun muodostavista viesteistä.
Vaihe vaiheelta: Pyynnön määrittäminen
- Valmistele päätepiste ja tunnistetiedot. Lisäät API-avaimesi (salainen merkkijono, joka todistaa henkilöllisyytesi) pyyntöön otsikossa. Et koskaan upota avainta koodiin; Katamme turvallisen varastoinnin yksikössä 9.
- Valitse malli ja lähtöraja. Kevyt malli + pienet max_tokens yksinkertaiseen tehtävään; Tehokas malli + suurempi raja monimutkaiseen tehtävään.
- Aseta viestiluettelo. List the system instruction, user message, and past rounds (if any).
- Lähetä pyyntö ja jäsennä vastaus. Lue tekstisisältö, pysäytyssyy ja tunnuksen käyttö palautetusta JSONista.
Viesti Roolit: järjestelmä, käyttäjä, avustaja
Keskustelu koostuu viesteistä, jotka on järjestetty sarjaan, ja jokaisella viestillä on rooli. Rooli määrittää, kuinka malli käsittelee kyseistä tekstiä.
Rooli
Kuka kirjoittaa
Tarkoitus
järjestelmä
Kehittäjä/operaattori
Pysyvät ohjeet, persoonallisuus ja säännöt, jotka pätevät koko keskustelun ajan
käyttäjä
loppukäyttäjä
Käyttäjän nykyinen kysymys tai syöte
avustaja
malli
Mallin tuottama vastaus (ja aiemmat vastaukset)
Järjestelmärooli on saatavana erillisenä järjestelmäkenttänä pyynnön rungossa useimmilla palveluntarjoajilla; käyttäjä ja avustaja luetellaan peräkkäin viestiluettelossa. Critical point: the system instruction is the high-level instruction, the user message is the request to be answered at that moment.
{ "model": "claude-opus-4-8", "max_tokens": 1024, "system": "Olet yrityksen tukiassistentti. Anna lyhyt, virallinen ja vahvistettu vastaus. Älä keksi tietoja, joista et ole varma.", "viestit": [ { "role": "käyttäjä", "sisältö": "Kuinka aloitan palautusprosessini?" } ]}
Puhe on valtiotonta
Tässä on yleisin väärinkäsitys: LLM API -kutsut ovat tilattomia – palvelin ei säilytä muistia kahden pyynnön välillä. Malli ei muista edellistä pyyntöäsi. Jos olet perustamassa usean kierroksen keskustelua, sinun on lähetettävä aiemmat kierrokset uudelleen jokaisen uuden pyynnön yhteydessä. Mallin "muisti" koostuu luettelosta lähettämistäsi viesteistä.
{ "malli": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "role": "user", "content": "Hei, nimeni on Deniz." }, { "role": "assistant", "content": "Hei Deniz, kuinka voin auttaa sinua?" }, { "role": "user", "content": "Sanoin juuri nimeni, muistatko?" } ]}
Kolmanteen viestiin vastaaminen oikein riippuu siitä, oletko lähettänyt molemmat edelliset viestit. Jos et lähetä sitä, malli ei tiedä "Sea" ja vastaa väärin. Tämä vaikuttaa myös suoraan kustannuksiin: mitä pidempi keskustelu, sitä suurempi luettelo, ja jokainen pyyntö kuluttaa enemmän tunnuksia.
Vinkki: Pitkissä keskusteluissa vanhojen kierrosten yhteenveto ja siirtäminen (yhteenveto + viimeiset kierrokset) koko historian lähettämisen sijaan vähentää kustannuksia ja säilyttää kontekstiikkunan. Syvennämme tätä yksiköissä 6 ja 11.
Lue vastaus
Kun malli palauttaa vastauksen, saat strukturoidun objektin, ei pelkkää tekstiä. Tyypilliset alueet:
{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "assistant", "content": [ { "type": "text", "text": "Aloita palautus siirtymällä tilisi Omat tilaukset -sivulle..." } ], "stop_reason": "usage": "usage": "usage" "input_tokens": 47, "output_tokens": 88 }}
- sisältö: itse vastaus; Se on luettelo sisältölohkoista. Tekstilohkon tekstikenttä on varsinainen vastaus.
- stop_reason: Miksi malli pysähtyi. end_turn = luonnollinen loppu; max_tokens = jumissa lähtörajassa (vastaus voi olla epätäydellinen); kieltäytyminen = hylätty turvallisuussyistä. Koodisi tulee aina katsoa ensin stop_reason.
- käyttö: Syöttö- ja lähtötunnusnumerot. Se on kustannusten ja rajojen seurannan perusta.
Huomio: Jos stop_reason on max_tokens, vastausta ei suoriteta loppuun. Tämän käsitteleminen "onnistuneena vastauksena" ja puolitekstin näyttäminen käyttäjälle on yksi yleisimmistä tuotannon virheistä. Kasvata max_tokens-arvoa tai käytä suoratoistoa.
Heikko kehote / Vahva kehote
Sama tehtävä kahdella eri järjestelmäkehotteella:
# HEIKKO Olet avustaja. Vastaa kysymyksiin.
# STRONGOlet yrityksen tukiassistentti. Säännöt: - Luota yksinomaan toimitetun politiikka-asiakirjan tietoihin; Jos sitä ei ole asiakirjassa, sano "Minulla ei ole näitä tietoja, ohjaan ne asianomaiselle yksikölle." - Vastaukset eivät saa ylittää 3 lausetta, olla muodollisia ja selkeitä. - Älä pyydä henkilötietoja (TC ID numero, kortin numero) äläkä toista. - Älä arvaa, kun et ole varma.
Tehokas versio; Se määrittelee laajuuden, muodon, turvamarginaalin ja käyttäytymisen epävarmuudessa. Mallin tulosten johdonmukaisuus tulee suoraan tästä selkeydestä.
Kolme minikoteloa
Tapaus 1 — Tukibotti (kansalattomuuden ansa). Verkkokauppatiimi otti botin käyttöön; Kun käyttäjä sanoi "peruuta edellinen tilaus", botti "unohti" tilausnumeron. Syy: he lähettivät jokaisen pyynnön vain viimeisen viestin kanssa. Ratkaisu: he lisäsivät viimeiset 6 kierrosta viestiluetteloon. Tulos: konteksti säilytetty, mutta pyyntökohtainen syöttö lisääntyi 40 tunnuksesta ~ 600 tunnukseen – katamme yksikön 2 kustannusoppitunnin.
Tapaus 2 – Epätäydellinen sopimusyhteenveto. Lakityöryhmä laati 10-sivuisia sopimuksia; max_tokens: 300 pysyi alhaisena, yhteenvedot katkaisivat lauseen puolivälissä. stop_reason oli max_tokens joka kerta, mutta kukaan ei etsinyt. lisätty max_tokens arvoon 1500 ja lisätty stop_reason check; Lyhennetty yhteenvetoaste laski 18 prosentista 0 prosenttiin.
Tapaus 3 – Roolien sekoittuminen. Markkinointitiimi kirjoitti kaikki ohjeet käyttäjäviestiin jättäen järjestelmän tyhjäksi. Kun käyttäjä syöttää käskyä, malli noudattaa joskus käyttäjän komentoa "unohda aiemmat säännöt". He siirsivät pysyviä sääntöjä järjestelmään; Erottamalla käyttäjän syötteet ohjeista sääntörikkomukset vähenivät merkittävästi.
Yleisiä virheitä
- Unohtaminen lähettää menneisyyden: Mallin ajatellaan "ei muista"; kun taas se on valtioton. Kannat kontekstia.
- Ei katso `stop_reason`: Vastaus pysäytettiin max_tokensilla katsotaan valmiiksi.
- Ohjeen upottaminen "käyttäjään": Pysyvät säännöt järjestelmään; välitön syöttö menee käyttäjälle. Sekoittaminen luo tietoturva-aukkoja.
- Sisällön erehtyminen tavalliseksi merkkijonoksi: Vastaus on lohkoluettelo; lue ensimmäisen tekstilohkon tekstikenttä, tarkista sen tyyppi ennen sisällön[0] saamista sokkoindeksillä.
- Avaimen upottaminen koodiin: Käytä ympäristömuuttujaa (yksikkö 9).
Deeper: Sisältölohkot ja moniosaiset vastaukset
Sen ymmärtäminen, miksi vastauksen sisältökenttä on luettelo, on olennaista lisäominaisuuksien kannalta, joita kohtaat myöhemmin. Joskus malli ei palauta yhtä tekstilohkoa, vaan useita lohkoja: ajattelulohkon, jota seuraa tekstilohko; tai tekstilohko, jota seuraa työkalun käyttölohko. Tästä syystä sisällön[0] sokea laskeminen "vastaukseksi" on hauras. Oikea tapa on käydä lista läpi ja lajitella se tyypin mukaan: keräät tekstisisältöä lohkoista, joiden tyyppikenttä on teksti, ja käsittelet muita tyyppejä (ajattelu, työkalu) erikseen.
Käytännössä tämä ero tekee siitä, että voit kirjata mallin perustelut (jos sellaisia on) paljastamatta sitä käyttäjälle, ohjata työkalukutsut erilliseen logiikkaan ja tulostaa vain varsinaisen vastauksen näytölle. Moduulin edetessä (erityisesti yksiköissä 4 ja 11) näet kuinka hyödyllinen tämä lohkorakenne on lähdön validoinnissa ja ohjaamisessa.
Toinen käytännön seikka: voit käyttää samaa mallia eri palveluntarjoajan alustoista (suora API, pilvipalvelun kautta). Vaikka päätepisteen osoite ja todennusmuoto voivat muuttua, peruskäsitteet, kuten viestin roolit, tilattomuus ja vastausrakenne, pysyvät samoina. Joten tämän yksikön perusasiat pätevät riippumatta siitä, mitä alustaa käytät.
Yhteenvetona
LLM API -pyyntö koostuu mallista, lähtörajasta ja viestiluettelosta; roolit (järjestelmä, käyttäjä, avustaja) määräävät mallin käyttäytymisen. Puhelut ovat valtiottomia: kuljetat jokaisen pyynnön yhteydessä kontekstin. Vastaus on strukturoitu objekti; Sisällön, stop_reason- ja use-kenttien lukeminen ja tulkitseminen on tuotannon kestävyyden perusta.
Sovellustehtävä
Valitse tehtävä omasta ammatistasi (esim. saapuvien sähköpostien lajittelu, lyhyiden yhteenvetojen tekeminen). Paperille: (1) kirjoita järjestelmäkehote, jossa on 4-5 sääntöä, (2) aseta esimerkkikäyttäjäviesti ja 2-kierroshistoria, jos sellainen on, (3) määritä kohtuullinen arvo max_tokensille ja kirjoita perustelut, (4) listaa, mitä stop_reason-arvoja käsittelet palautetussa vastauksessa ja miten.
tarkistuslista
- [ ] Pystyn laskemaan pyynnön kolme pakollista osaa (malli, max_tokens, viestit).
- [ ] Osaan selittää eron järjestelmä-, käyttäjä- ja avustajan roolien välillä.
- [ ] Tiedän, että puhelut ovat valtiottomia ja että minun täytyy kantaa menneisyyttä.
- Pystyn lukemaan ja kommentoimaan [ ] sisältöä, stop_reason- ja käyttökenttiä.
- [ ] Max_tokensilla voin huomata ja käsitellä katkaistua vastausta.