Dobički:
- Lahko opiše osnovno strukturo zahteve API LLM (končna točka, model, sporočila, max_tokens)
- Razume razliko med vlogami sistema, uporabnika in pomočnika ter zgodovino pogovorov brez stanja
- Lahko bere in interpretira polja (bloki vsebine, stop_reason, uporaba) vrnjenega odgovora
V prejšnjih modulih smo uporabljali umetno inteligenco iz okna za klepet. Če pa želite umetno inteligenco vdelati v svoj izdelek, avtomatizacijo ali potek dela, vam vmesnik za klepet ne bo pomagal; Z modelom se morate povezati programsko, torej s kodo ali orodjem za avtomatizacijo. Ime tega mostu je API (Application Programming Interface, pogodba, ki omogoča, da se dve programski opremi pogovarjata z določenimi pravili). Ko končate to enoto, boste vedeli, kaj je zahteva API-ja LLM (Large Language Model), kaj počnejo vloge sporočil in kako brati odgovor. To je osnova, na kateri bo zgrajen preostali del modula.
Kako deluje API?
Osnovni tok v API-ju je naslednji: pošljete zahtevo v določenem formatu; Strežnik vrne odgovor v določeni obliki. V LLM je to običajno klic HTTP (HTTP: standardni protokol za prenos zahteve-odgovora v spletu) na en sam naslov (končna točka, fiksni naslov na strežniku, ki obravnava vašo zahtevo). Na primer, v API-ju za sporočanje gredo vse zahteve na en sam naslov in se prenesejo v telo kot JSON (JavaScript Object Notation – besedilni format, sestavljen iz parov ključ/vrednost, ki ga lahko berejo tako ljudje kot stroji).
V zahtevku navedete vsaj te tri stvari:
- Model: kateri model boste uporabili (npr. hiter in poceni model ali zmogljiv model).
- max_tokens: največje število žetonov (najmanjša enota, v kateri je obdelano besedilo, ki bo podrobno obdelano v naslednji enoti), ki jih lahko proizvede model; tj. meja izhoda.
- sporočila: seznam sporočil, ki sestavljajo pogovor.
Korak za korakom: Kako nastaviti zahtevo
- Pripravite končno točko in poverilnice. Zahtevi v glavi dodate svoj ključ API (tajni niz, ki dokazuje vašo identiteto). Ključa nikoli ne vdelate v kodo; Pokrivali bomo varno skladiščenje v enoti 9.
- Izberite model in omejitev izhoda. Lahek model + majhni max_tokeni za preprosto opravilo; Zmogljiv model + večja omejitev za kompleksno nalogo.
- Nastavite seznam sporočil. List the system instruction, user message, and past rounds (if any).
- Pošljite zahtevo in razčlenite odgovor. Preberite besedilno vsebino, razlog za zaustavitev in uporabo žetona iz vrnjenega JSON.
Vloge sporočil: sistem, uporabnik, pomočnik
Pogovor je sestavljen iz sporočil, razvrščenih v zaporedje, in vsako sporočilo ima svojo vlogo. Vloga določa, kako model obravnava to besedilo.
Vloga
Kdo piše
Namen
sistem
Razvijalec/operater
Stalna navodila, osebnost in pravila, ki veljajo skozi celoten pogovor
uporabnik
končnega uporabnika
Uporabnikovo trenutno vprašanje ali vnos
pomočnik
model
Odziv, ki ga ustvari model (in prejšnji odgovori)
Sistemska vloga je pri večini ponudnikov na voljo kot ločeno sistemsko polje v telesu zahteve; uporabnik in pomočnik sta navedena zaporedno na seznamu sporočil. 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": "Ste pomočnik pri podpori podjetja. Podajte kratek, uraden in preverjen odgovor. Ne izmišljujte informacij, o katerih niste prepričani.", "messages": [ { "role": "user", "content": "Kako začnem svoj postopek vračila?" } ]}
Govor je brez državljanstva
Tukaj je najpogostejša napačna predstava: klici LLM API so brez stanja – strežnik ne obdrži pomnilnika med dvema zahtevama. Model se ne spomni vaše prejšnje zahteve. Če nastavljate klepet z več krogi, boste morali z vsako novo zahtevo ponovno poslati prejšnje kroge. »Spomin« modela je sestavljen iz seznama sporočil, ki ste jih poslali.
{ "model": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "role": "user", "content": "Pozdravljeni, ime mi je Deniz." }, { "role": "asistent", "content": "Pozdravljeni Deniz, kako vam lahko pomagam?" }, { "role": "user", "content": "Pravkar sem povedal svoje ime, se spomniš?" } ]}
Pravilen odgovor na tretje sporočilo je odvisen od tega, ali ste poslali obe prejšnji sporočili. Če ga ne pošljete, model ne bo poznal "Morje" in bo odgovoril napačno. To neposredno vpliva tudi na stroške: daljši kot je pogovor, večji je seznam, vsaka zahteva porabi več žetonov.
Nasvet: V dolgih pogovorih povzemanje in premikanje starih krogov (povzetek + zadnjih nekaj krogov) namesto pošiljanja celotne zgodovine zmanjša stroške in ohrani kontekstno okno. To bomo poglobili v 6. in 11. enoti.
Preberite odgovor
Ko model vrne odgovor, prejmete strukturiran predmet in ne navadnega besedila. Tipična področja:
{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "assistant", "content": [ { "type": "text", "text": "Če želite sprožiti vračilo, pojdite na stran 'Moja naročila' v vašem računu ..." } ], "stop_reason": "end_turn", "usage": { "input_tokens": 47, "output_tokens": 88 }}
- vsebina: sam odgovor; Je seznam vsebinskih blokov. Besedilno polje besedilnega bloka je dejanski odgovor.
- stop_reason: Zakaj se je model ustavil. end_turn = naravni konec; max_tokens = obtičal na izhodni meji (odziv je lahko nepopoln); zavrnitev = zavrnjen iz varnostnih razlogov. Vaša koda mora vedno najprej pogledati stop_reason.
- uporaba: Vnos in izpis številk žetona. Je osnova za sledenje stroškov in omejitev.
Pozor: če je stop_reason max_tokens, odgovor ni dokončan. Obravnavanje tega kot "uspešnega odgovora" in prikaz polovice besedila uporabniku je ena najpogostejših napak v produkciji. Povečajte max_tokens ali uporabite pretakanje.
Šibek poziv/močan poziv
Ista naloga z dvema različnima sistemskima pozivoma:
# WEAKVi ste pomočnik. Odgovorite na vprašanja.
# MOČNO Ste pomočnik za podporo podjetju. Pravila:- Zanašajte se izključno na informacije v predloženem dokumentu politike; Če tega ni v dokumentu, recite "teh podatkov nimam, jih usmerjam na ustrezno enoto." - Odgovori naj ne presegajo 3 stavkov, naj bodo formalni in jasni. - Ne zahtevajte osebnih podatkov (TC ID številka, številka kartice) in ne ponavljajte. - Ne ugibajte, če niste prepričani.
Zmogljiva različica; Določa obseg, obliko, varnostno rezervo in obnašanje v negotovosti. Doslednost rezultatov modela izhaja neposredno iz te jasnosti.
Trije mini kovčki
1. primer – podporni bot (past brez državljanstva). Ekipa za e-trgovino je bota objavila v živo; Ko je uporabnik rekel "prekliči prejšnje naročilo", je bot "pozabil" številko naročila. Razlog: vsako zahtevo so pošiljali samo z zadnjim sporočilom. Rešitev: na seznam sporočil so dodali zadnjih 6 krogov. Rezultat: kontekst je ohranjen, vendar se je vnos na zahtevo povečal s 40 žetonov na ~600 žetonov — lekcijo o stroških bomo obravnavali v 2. enoti.
Primer 2 – nepopoln povzetek pogodbe. Pravna ekipa je imela 10-stranske pogodbe; max_tokens: 300 je ostalo nizko, povzetki so bili odrezani sredi stavka. stop_reason je bil vsakič max_tokens, vendar nihče ni gledal. povečal max_tokens na 1500 in dodal stop_reason preverjanje; Okrnjena sumarna stopnja se je znižala z 18 % na 0 %.
Primer 3 – Mešanje vlog. Tržna ekipa je vsa navodila zapisala v uporabniško sporočilo, sistem pa pustil prazen. Ko se uporabniški vnos pomeša z navodili, bi model včasih upošteval uporabnikov ukaz, naj "pozabi prejšnja pravila". V sistem so premaknili stalna pravila; Z ločevanjem uporabniškega vnosa od navodil so se kršitve pravil znatno zmanjšale.
Pogoste napake
- Pozabljanje poslati preteklost: model naj bi se "ne spomnil"; medtem ko je brez državljanstva. Ti nosiš kontekst.
- Ne gledam na `stop_reason`: odgovor, ustavljen z max_tokens, se šteje za dokončan.
- Vdelava navodil v `uporabnik`: Trajna pravila v sistem; takojšnji vnos gre uporabniku. Mešanje ustvarja varnostne ranljivosti.
- Zamenjajte `vsebino` za navaden niz: Odgovor je seznam blokov; preberi besedilno polje prvega besedilnega bloka, preveri njegovo vrsto, preden dobiš content[0] s slepim indeksom.
- Vdelava ključa v kodo: Uporabite spremenljivko okolja (enota 9).
Deeper: vsebinski bloki in večdelni odgovori
Razumevanje, zakaj je polje vsebine v odgovoru seznam, je bistveno za napredne funkcije, s katerimi se boste srečali pozneje. Včasih model ne vrne enega bloka besedila, temveč več blokov: blok razmišljanja, ki mu sledi blok besedila; ali blok besedila, ki mu sledi blok uporabe orodja. Zato je slepo štetje vsebine[0] kot "odgovor" krhko. Pravilen pristop je, da pregledate seznam in ga razvrstite po vrsti: zberete besedilno vsebino blokov, katerih polje tipa je besedilo, druge vrste (razmišljanje, orodje) pa obravnavate ločeno.
To razlikovanje v praksi pomeni, da lahko sklepanje modela (če obstaja) zabeležite, ne da bi ga razkrili uporabniku, preusmerite klice orodij na ločeno logiko in natisnete samo dejanski odgovor na zaslonu. Ko modul napreduje (zlasti v enotah 4 in 11), boste videli, kako uporabna je ta struktura blokov za preverjanje in usmerjanje izhoda.
Še ena praktična točka: do istega modela lahko dostopate z različnih platform ponudnikov (neposredni API, prek ponudnika v oblaku). Čeprav se naslov končne točke in format preverjanja pristnosti lahko spremenita, osnovni pojmi, kot so vloge sporočil, stanje brez državljanstva in struktura odziva, ostanejo enaki. Osnove v tej enoti veljajo ne glede na to, katero platformo uporabljate.
Če povzamem
Zahteva LLM API je sestavljena iz modela, izhodne omejitve in seznama sporočil; vloge (sistem, uporabnik, pomočnik) določajo obnašanje modela. Klici so brez stanja: kontekst nosite z vsako zahtevo. Odziv je strukturiran objekt; Branje in interpretacija polj vsebine, stop_reason in usage je osnova trajnosti v proizvodnji.
Aplikacijska naloga
Izberite nalogo iz svojega poklica (npr. razvrščanje dohodne e-pošte, ustvarjanje kratkih povzetkov). Na kos papirja: (1) napišite sistemski poziv s 4-5 pravili, (2) nastavite vzorčno uporabniško sporočilo in dvokrožno zgodovino, če obstaja, (3) določite razumno vrednost za max_tokens in napišite utemeljitev, (4) navedite, katere vrednosti stop_reason boste obdelali v vrnjenem odgovoru in kako.
kontrolni seznam
- [ ] Lahko preštejem tri obvezne dele zahteve (model, max_tokens, sporočila).
- [ ] Znam razložiti razliko med vlogami sistema, uporabnika in pomočnika.
- [ ] Vem, da so klici brez stanja in da moram nositi preteklost.
- Znam brati in komentirati [ ] vsebino, stop_reason in polja za uporabo.
- [ ] Z max_tokens lahko opazim in obravnavam okrnjen odgovor.