Dobici:
- Može opisati osnovnu strukturu LLM API zahtjeva (endpoint, model, messages, max_tokens)
- Razumije razliku između uloga sustava, korisnika i pomoćnika te povijesti razgovora bez statusa
- Može čitati i tumačiti polja (blokovi sadržaja, stop_reason, usage) vraćenog odgovora
U prethodnim modulima koristili smo umjetnu inteligenciju iz prozora za chat. Ali ako želite ugraditi AI u vlastiti proizvod, automatizaciju ili radni tijek, sučelje za chat vam neće pomoći; S modelom se trebate povezati programski, odnosno kodom ili alatom za automatizaciju. Naziv ovog mosta je API (Application Programming Interface, ugovor koji omogućuje da dva softvera razgovaraju s određenim pravilima). Kada završite ovu jedinicu, znat ćete što čini LLM (Large Language Model) API zahtjev, što rade uloge poruka i kako čitati odgovor. Ovo je temelj na kojem će se graditi ostatak modula.
Kako radi API?
Osnovni tijek u API-ju je sljedeći: šaljete zahtjev u određenom formatu; Poslužitelj vraća odgovor u određenom formatu. U LLM-u to je obično HTTP poziv (HTTP: standardni protokol za prijenos zahtjeva-odgovora na webu) na jednu adresu (krajnja točka, fiksna adresa na poslužitelju koji obrađuje vaš zahtjev). Na primjer, u API-ju za razmjenu poruka, svi zahtjevi idu na jednu adresu i nose se u tijelu kao JSON (JavaScript Object Notation — tekstualni format koji se sastoji od parova ključ/vrijednost koje mogu čitati i ljudi i strojevi).
U zahtjevu navodite najmanje ove tri stvari:
- Model: Koji model ćete koristiti (npr. brz i jeftin model ili moćan model).
- max_tokens: Maksimalan broj tokena (najmanja jedinica u kojoj se obrađuje tekst, koja će biti detaljno obrađena u sljedećoj jedinici) koje model može proizvesti; tj. granica izlaza.
- poruke: popis poruka koje čine razgovor.
Korak po korak: Kako postaviti zahtjev
- Pripremite krajnju točku i vjerodajnice. Svoj API ključ (tajni niz koji dokazuje vaš identitet) dodajete zahtjevu u zaglavlju. Nikada ne ugrađujete ključ u kod; Pokrivat ćemo sigurno skladištenje u jedinici 9.
- Odaberite model i izlaznu granicu. Lagani model + mali max_tokeni za jednostavan zadatak; Snažan model + veće ograničenje za složen zadatak.
- Postavite popis poruka. List the system instruction, user message, and past rounds (if any).
- Pošaljite zahtjev i analizirajte odgovor. Pročitajte tekstualni sadržaj, razlog zaustavljanja i upotrebu tokena iz vraćenog JSON-a.
Uloge poruka: sustav, korisnik, pomoćnik
Razgovor se sastoji od poruka poredanih u nizu, a svaka poruka ima svoju ulogu. Uloga određuje kako model tretira taj tekst.
uloga
Tko piše
Svrha
sustav
Programer/operater
Stalne upute, osobnost i pravila koja vrijede tijekom cijelog razgovora
korisnika
krajnji korisnik
Korisnikovo trenutno pitanje ili unos
asistent
model
Odgovor koji proizvodi model (i prethodni odgovori)
Uloga sustava dostupna je kao zasebno polje sustava u tijelu zahtjeva kod većine pružatelja usluga; korisnik i pomoćnik navedeni su redom na popisu poruka. 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": "Vi ste pomoćnik korporativne podrške. Dajte kratak, formalan i provjeren odgovor. Nemojte izmišljati informacije u koje niste sigurni.", "messages": [ { "role": "user", "content": "Kako mogu pokrenuti svoj proces povrata?" } ]}
Govor je bez državljanstva
Evo najčešće zablude: LLM API pozivi su bez statusa — poslužitelj ne zadržava memoriju između dva zahtjeva. Model se ne sjeća vašeg prethodnog zahtjeva. Ako postavljate više rundi chata, morat ćete ponovno poslati prethodne runde sa svakim novim zahtjevom. "Memorija" modela sastoji se od popisa poruka koje ste poslali.
{ "model": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "role": "user", "content": "Zdravo, moje ime je Deniz." }, { "role": "assistant", "content": "Zdravo Deniz, kako ti mogu pomoći?" }, { "role": "user", "content": "Upravo sam rekao svoje ime, sjećate li se?" } ]}
Točan odgovor na treću poruku ovisi o tome jeste li poslali obje prethodne poruke. Ako ga ne pošaljete, model neće znati "More" i krivo će odgovoriti. To također izravno utječe na trošak: što je razgovor dulji, to je lista veća, a svaki zahtjev troši više tokena.
Savjet: U dugim razgovorima, sažimanje i premještanje starih rundi (sažetak + zadnjih nekoliko rundi) umjesto slanja cijele povijesti smanjuje troškove i čuva kontekstni prozor. To ćemo produbiti u jedinicama 6 i 11.
Pročitajte odgovor
Kada model vrati odgovor, primate strukturirani objekt, a ne običan tekst. Tipična područja:
{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "assistant", "content": [ { "type": "text", "text": "Da biste pokrenuli povrat, idite na stranicu 'Moje narudžbe' na svom računu..." } ], "stop_reason": "end_turn", "usage": { "input_tokens": 47, "output_tokens": 88 }}
- sadržaj: sam odgovor; To je popis blokova sadržaja. Tekstualno polje tekstualnog bloka je stvarni odgovor.
- stop_reason: Zašto je model stao. end_turn = prirodan kraj; max_tokens = zapeo na granici izlaza (odgovor može biti nepotpun); odbijanje = odbijeno iz sigurnosnih razloga. Vaš kod bi uvijek trebao prvo pogledati stop_reason.
- upotreba: Unos i izlaz brojeva tokena. To je osnova praćenja troškova i ograničenja.
Pažnja: ako je stop_reason max_tokens, odgovor nije dovršen. Tretiranje ovoga kao "uspješnog odgovora" i prikazivanje pola teksta korisniku jedna je od najčešćih pogrešaka u proizvodnji. Ili povećajte max_tokens ili koristite streaming.
Slab upit / Jak upit
Isti zadatak s dva različita odziva sustava:
# SLABO Ti si asistent. Odgovori na pitanja.
# JAKO Vi ste pomoćnik korporativne podrške. Pravila: - Oslonite se isključivo na informacije u dostavljenom dokumentu o politici; Ako ga nema u dokumentu, recite "Nemam ove podatke, upućujem ih nadležnoj jedinici." - Odgovori ne smiju biti duži od 3 rečenice, moraju biti formalni i jasni. - Ne tražite osobne podatke (TC ID broj, broj kartice) i ne ponavljajte. - Ne pogađajte kada niste sigurni.
Snažna verzija; Definira opseg, oblik, sigurnosnu marginu i ponašanje u neizvjesnosti. Dosljednost rezultata modela dolazi izravno iz ove jasnoće.
Tri mini kućišta
Slučaj 1 — Bot za podršku (zamka apatridije). Tim za e-trgovinu preuzeo je bot uživo; Kada je korisnik rekao "otkaži prethodnu narudžbu", bot je "zaboravio" broj narudžbe. Razlog: slali su svaki zahtjev samo sa zadnjom porukom. Rješenje: dodali su zadnjih 6 rundi na listu poruka. Rezultat: sačuvan kontekst, ali je unos po zahtjevu povećan s 40 tokena na ~600 tokena — pokrit ćemo lekciju o troškovima u jedinici 2.
Slučaj 2 — Nepotpuni sažetak ugovora. Pravni tim imao je ugovore na 10 stranica; max_tokens: 300 je ostalo malo, sažeci su bili rezani usred rečenice. stop_reason je bio max_tokens svaki put, ali nitko nije gledao. povećao max_tokens na 1500 i dodao stop_reason provjeru; Skraćena sumarna stopa smanjila se s 18% na 0%.
Slučaj 3 — Miješanje uloga. Marketinški tim je upisivao sve upute u korisničku poruku, ostavljajući sustav prazan. Kad bi se korisnički unos pomiješao s uputama, model bi se ponekad povinovao korisnikovoj naredbi da "zaboravi prethodna pravila". Premjestili su stalna pravila u sustav; Odvajanjem korisničkog unosa od uputa, kršenja pravila značajno su se smanjila.
Uobičajene greške
- Zaboravljanje slanja prošlosti: Smatra se da se model "ne sjeća"; dok je bez državljanstva. Vi nosite kontekst.
- Ne gledajući `stop_reason`: Odgovor zaustavljen s max_tokens smatra se dovršenim.
- Ugradnja instrukcija u `korisnik`: Trajna pravila u sustav; trenutni unos ide korisniku. Miješanje stvara sigurnosne ranjivosti.
- Zamijeniti `sadržaj` za običan niz: Odgovor je popis blokova; pročitajte tekstualno polje prvog tekstualnog bloka, provjerite njegov tip prije dobivanja content[0] sa slijepim indeksom.
- Ugrađivanje ključa u kod: Koristite varijablu okruženja (jedinica 9).
Dublje: Blokovi sadržaja i odgovori iz više dijelova
Razumijevanje zašto je polje sadržaja u odgovoru popis temeljno je za napredne značajke s kojima ćete se susresti kasnije. Ponekad model ne vraća jedan blok teksta, već nekoliko blokova: blok razmišljanja, nakon kojeg slijedi blok teksta; ili blok teksta iza kojeg slijedi blok upotrebe alata. Zato je slijepo računanje sadržaja [0] kao "odgovora" krhko. Ispravan pristup je proći kroz popis i razvrstati ga po vrsti: skupljate tekstualni sadržaj blokova čije je polje tipa tekst, a druge vrste (razmišljanje, alat) tretirate odvojeno.
Ono što ova razlika radi u praksi jest da možete zabilježiti obrazloženje modela (ako ga ima) bez otkrivanja korisniku, preusmjeriti pozive alata na odvojenu logiku i ispisati samo stvarni odgovor na ekranu. Kako modul napreduje (osobito u jedinicama 4 i 11) vidjet ćete koliko je ova blok struktura korisna za provjeru valjanosti i usmjeravanje izlaza.
Još jedna praktična točka: istom modelu možete pristupiti s platformi različitih pružatelja (izravan API, putem pružatelja usluga u oblaku). Iako se adresa krajnje točke i format provjere autentičnosti mogu promijeniti, osnovni koncepti kao što su uloge poruka, apatridnost i struktura odgovora ostaju isti. Dakle, osnove u ovoj jedinici vrijede bez obzira koju platformu koristite.
Ukratko
LLM API zahtjev sastoji se od modela, ograničenja izlaza i popisa poruka; uloge (sustav, korisnik, pomoćnik) određuju ponašanje modela. Pozivi su bez statusa: nosite kontekst sa svakim zahtjevom. Odgovor je strukturirani objekt; Čitanje i tumačenje polja content, stop_reason i usage osnova je trajnosti u proizvodnji.
Zadatak aplikacije
Odaberite zadatak iz vlastite struke (npr. sortiranje pristigle e-pošte, izrada kratkih sažetaka). Na komad papira: (1) napišite upit sustava s 4-5 pravila, (2) postavite oglednu korisničku poruku i dvokružnu povijest ako postoji, (3) odredite razumnu vrijednost za max_tokens i napišite opravdanje, (4) navedite s kojim ćete stop_reason vrijednostima rukovati u vraćenom odgovoru i kako.
popis za provjeru
- [ ] Mogu prebrojati tri obavezna dijela zahtjeva (model, max_tokeni, poruke).
- [ ] Mogu objasniti razliku između uloga sustava, korisnika i pomoćnika.
- [ ] Znam da su pozivi bez statusa i da moram nositi prošlost.
- Mogu čitati i komentirati [ ] sadržaj, stop_reason i polja upotrebe.
- [ ] S max_tokens mogu primijetiti i obraditi skraćeni odgovor.