zisky:
- Dokáže opísať základnú štruktúru požiadavky LLM API (koncový bod, model, správy, max_tokens)
- Chápe rozdiel medzi rolami systému, používateľa a asistenta a bezstavovou históriou konverzácií
- Dokáže čítať a interpretovať polia (bloky obsahu, stop_reason, využitie) vrátenej odpovede
V predchádzajúcich moduloch sme využívali umelú inteligenciu z okna chatu. Ak však chcete začleniť AI do svojho vlastného produktu, automatizácie alebo pracovného postupu, rozhranie chatu to nepreruší; K modelu sa musíte pripojiť programovo, teda pomocou kódu alebo automatizačného nástroja. Názov tohto mosta je API (Application Programming Interface, zmluva, ktorá umožňuje dvom softvérom komunikovať s určitými pravidlami). Keď dokončíte túto jednotku, budete vedieť, čo predstavuje požiadavku LLM (Large Language Model) API, aké úlohy robia správy a ako čítať odpoveď. Toto je základ, na ktorom bude postavený zvyšok modulu.
Ako funguje rozhranie API?
Základný tok v API je tento: odošlete požiadavku v určitom formáte; Server vráti odpoveď v špecifickom formáte. V LLM je to zvyčajne volanie HTTP (HTTP: štandardný protokol na prenos žiadosti a odpovede na webe) na jednu adresu (koncový bod, pevná adresa na serveri, ktorý spracováva vašu požiadavku). Napríklad v rozhraní API na odosielanie správ idú všetky požiadavky na jedinú adresu a v tele sa prenášajú ako JSON (JavaScript Object Notation – textový formát pozostávajúci z párov kľúč/hodnota, ktoré môžu čítať ľudia aj stroje).
V žiadosti uveďte aspoň tieto tri veci:
- Model: Ktorý model budete používať (napr. rýchly a lacný model alebo výkonný model).
- max_tokens: Maximálny počet tokenov (najmenšia jednotka, v ktorej je spracovaný text, ktorá bude podrobne spracovaná v ďalšej jednotke), ktoré dokáže model vyrobiť; t.j. výstupný limit.
- správy: Zoznam správ, ktoré tvoria konverzáciu.
Krok za krokom: Ako nastaviť požiadavku
- Pripravte koncový bod a poverenia. Svoj API kľúč (tajný reťazec, ktorý dokazuje vašu identitu) pridáte do požiadavky v hlavičke. Nikdy nevložíte kľúč do kódu; Pokryjeme bezpečné skladovanie v bloku 9.
- Vyberte model a výstupný limit. Ľahký model + malé max_tokeny pre jednoduchú úlohu; Výkonný model + väčší limit pre komplexnú úlohu.
- Nastavte zoznam správ. List the system instruction, user message, and past rounds (if any).
- Pošlite žiadosť a analyzujte odpoveď. Prečítajte si textový obsah, dôvod zastavenia a použitie tokenu z vráteného JSON.
Roly správ: systém, používateľ, asistent
Konverzácia pozostáva zo správ usporiadaných v poradí a každá správa má svoju úlohu. Rola určuje, ako model zaobchádza s textom.
Role
Kto píše
Účel
systém
Vývojár/operátor
Trvalé pokyny, osobnosť a pravidlá, ktoré platia počas celého rozhovoru
užívateľ
koncového užívateľa
Aktuálna otázka alebo vstup používateľa
asistent
model
Odpoveď vytvorená modelom (a predchádzajúce odpovede)
Systémová rola je u väčšiny poskytovateľov dostupná ako samostatné systémové pole v tele žiadosti; používateľ a asistent sú uvedené postupne v zozname správ. 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 asistentom podnikovej podpory. Poskytnite krátku, formálnu a overenú odpoveď. Nevymýšľajte si informácie, ktorými si nie ste istý.", "messages": [ { "role": "user", "content": "Ako začnem proces vrátenia?" } ]}
Reč je bez štátnej príslušnosti
Tu je najbežnejšia mylná predstava: Volania LLM API sú bezstavové – server si medzi dvoma požiadavkami neuchováva žiadnu pamäť. Model si nepamätá vašu predchádzajúcu požiadavku. Ak nastavujete viackolový čet, budete musieť pri každej novej žiadosti znova odoslať predchádzajúce kolá. „Pamäť“ modelu pozostáva zo zoznamu správ, ktoré ste odoslali.
{ "model": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "role": "user", "content": "Dobrý deň, volám sa Deniz." }, { "role": "asistent", "content": "Ahoj Deniz, ako ti môžem pomôcť?" }, { "role": "user", "content": "Práve som povedal svoje meno, pamätáš?" } ]}
Správna odpoveď na tretiu správu závisí od odoslania oboch predchádzajúcich správ. Ak ho nepošlete, modelka nebude poznať „More“ a odpovie nesprávne. To tiež priamo ovplyvňuje náklady: čím dlhšia je konverzácia, tým väčší je zoznam, pričom každá požiadavka spotrebuje viac tokenov.
Tip: Pri dlhých rozhovoroch sumarizácia a presúvanie starých kôl (súhrn + posledných pár kôl) namiesto odosielania celej histórie znižuje náklady a zachováva kontextové okno. Prehĺbime to v 6. a 11. bloku.
Prečítajte si odpoveď
Keď model vráti odpoveď, dostanete štruktúrovaný objekt, nie obyčajný text. Typické oblasti:
{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "asistent", "content": [ { "type": "text", "text": "Ak chcete začať vrátenie, prejdite na stránku 'Moje objednávky' vo svojom účte..." } ], "stop_reason": "input_7", "input_7", "input_7" "output_tokens": 88 }}
- obsah: Samotná odpoveď; Je to zoznam blokov obsahu. Skutočnou odpoveďou je textové pole textového bloku.
- stop_reason: Prečo sa model zastavil. end_turn = prirodzený koniec; max_tokens = zaseknutý na výstupnom limite (odpoveď môže byť neúplná); odmietnutie = odmietnutie z bezpečnostných dôvodov. Váš kód by sa mal vždy najprv pozrieť na stop_reason.
- použitie: Vstupné a výstupné čísla tokenov. Je základom sledovania nákladov a limitov.
Upozornenie: Ak stop_reason je max_tokens, odpoveď nie je dokončená. Považovať to za „úspešnú odpoveď“ a zobraziť používateľovi polovičný text je jednou z najčastejších chýb vo výrobe. Zvýšte max_tokens alebo použite streamovanie.
Slabá výzva / Silná výzva
Rovnaká úloha s dvoma rôznymi systémovými výzvami:
# SLABÝSte asistent. Odpovedzte na otázky.
# STRONGSte asistent podnikovej podpory. Pravidlá:- Spoliehajte sa výlučne na informácie v poskytnutom dokumente o politike; Ak to v dokumente nie je, povedzte: „Túto informáciu nemám, smerujem ju na príslušný útvar.“ - Odpovede by nemali presiahnuť 3 vety, byť formálne a jasné. - Nevyžadujte osobné údaje (IČO, číslo karty) a neopakujte. - Nehádajte, keď si nie ste istý.
Výkonná verzia; Definuje rozsah, formu, bezpečnostnú rezervu a správanie v neistote. Konzistentnosť výstupu modelu vychádza priamo z tejto prehľadnosti.
Tri mini puzdrá
Prípad 1 – Podporný robot (pasca bez štátnej príslušnosti). Tím elektronického obchodu uviedol robota do prevádzky; Keď používateľ povedal „zrušiť predchádzajúcu objednávku“, robot „zabudol“ číslo objednávky. Dôvod: každú požiadavku posielali len s poslednou správou. Riešenie: do zoznamu správ pridali posledných 6 kôl. Výsledok: kontext sa zachoval, ale vstup na požiadavku sa zvýšil zo 40 tokenov na ~600 tokenov – lekciu o nákladoch preberieme v 2. bloku.
Prípad 2 – Neúplné zhrnutie zmluvy. Právny tím mal načrtnuté 10-stranové zmluvy; max_tokens: 300 zostalo nízke, súhrny boli odrezané od polovice vety. stop_reason bol zakaždým max_tokens, ale nikto sa nepozeral. zvýšený max_tokens na 1500 a pridaná kontrola stop_reason; Skrátená súhrnná miera sa znížila z 18 % na 0 %.
Prípad 3 – Miešanie rolí. Marketingový tím písal všetky pokyny do používateľskej správy, pričom systém nechal prázdny. Keď sa používateľský vstup zmiešal s pokynmi, model niekedy vyhovoval príkazu používateľa „zabudnúť na predchádzajúce pravidlá“. Do systému presunuli trvalé pravidlá; Oddelením používateľských vstupov od pokynov sa počet porušení pravidiel výrazne znížil.
Časté chyby
- Zabudnutie poslať minulosť: Predpokladá sa, že model si „nepamätá“; keďže je bez štátnej príslušnosti. Nosíte kontext.
- Nepozerá sa na `stop_reason`: Odpoveď zastavená s max_tokens sa považuje za dokončenú.
- Vloženie inštrukcie do `user`: Trvalé pravidlá do systému; okamžitý vstup ide používateľovi. Miešaním vznikajú bezpečnostné chyby.
- Zámena „obsahu“ za obyčajný reťazec: Odpoveďou je zoznam blokov; prečítajte si textové pole prvého textového bloku, overte jeho typ pred získaním obsahu[0] pomocou slepého indexu.
- Vloženie kľúča do kódu: Použite premennú prostredia (jednotka 9).
Deeper: Obsahové bloky a viacdielne odpovede
Pochopenie, prečo je obsahové pole v odpovedi zoznam, je základom pokročilých funkcií, s ktorými sa neskôr stretnete. Niekedy model nevracia jeden blok textu, ale niekoľko blokov: blok myslenia, po ktorom nasleduje blok textu; alebo blok textu, za ktorým nasleduje blok použitia nástroja. Preto je slepé počítať obsah[0] ako „odpoveď“ krehké. Správny prístup je prejsť zoznam a zoradiť ho podľa typu: zhromažďujete textový obsah blokov, ktorých typové pole je text, a ostatné typy (myslenie, nástroj) spracovávate oddelene.
Toto rozlíšenie v praxi robí to, že môžete zaznamenať zdôvodnenie modelu (ak existuje) bez toho, aby ste ho odhalili používateľovi, presmerovať volania nástrojov na oddelenú logiku a vytlačiť iba skutočnú odpoveď na obrazovku. Ako modul postupuje (najmä v blokoch 4 a 11), uvidíte, aká užitočná je táto bloková štruktúra na overenie a riadenie výstupu.
Ďalší praktický bod: k rovnakému modelu môžete pristupovať z rôznych platforiem poskytovateľa (priame rozhranie API, prostredníctvom poskytovateľa cloudu). Aj keď sa adresa koncového bodu a formát autentifikácie môžu zmeniť, základné pojmy ako roly správ, stav bez stavu a štruktúra odpovede zostávajú rovnaké. Takže základy v tejto jednotke platia bez ohľadu na to, akú platformu používate.
V súhrne
Požiadavka LLM API pozostáva z modelu, limitu výstupu a zoznamu správ; roly (systém, používateľ, asistent) určujú správanie modelu. Hovory sú bez stavu: nesiete kontext s každou požiadavkou. Odpoveď je štruktúrovaný objekt; Čítanie a interpretácia polí content, stop_reason a use je základom trvanlivosti vo výrobe.
Aplikačná úloha
Vyberte si úlohu z vlastnej profesie (napr. triedenie prichádzajúcich e-mailov, vytváranie stručných súhrnov). Na kus papiera: (1) napíšte systémovú výzvu so 4-5 pravidlami, (2) nastavte vzorovú správu používateľa a 2-kolovú históriu, ak existuje, (3) určte primeranú hodnotu pre max_tokens a napíšte odôvodnenie, (4) uveďte, ktoré hodnoty stop_reason budete spracovať v vrátenej odpovedi a ako.
kontrolný zoznam
- [ ] Viem spočítať tri povinné časti požiadavky (model, max_tokens, správy).
- [ ] Viem vysvetliť rozdiel medzi rolou systému, používateľa a asistenta.
- [ ] Viem, že hovory sú bez štátnej príslušnosti a že musím niesť minulosť.
- Môžem čítať a komentovať obsah [ ], polia stop_reason a use.
- [ ] Pomocou max_tokens si môžem všimnúť a spracovať skrátenú odpoveď.