zisky:
- Dokáže popsat základní strukturu požadavku LLM API (koncový bod, model, zprávy, max_tokens)
- Chápe rozdíl mezi systémovými, uživatelskými a asistentskými rolemi a bezstavovou historií konverzací
- Dokáže číst a interpretovat pole (bloky obsahu, stop_reason, využití) vrácené odpovědi
V předchozích modulech jsme používali umělou inteligenci z okna chatu. Ale pokud chcete začlenit umělou inteligenci do svého vlastního produktu, automatizace nebo pracovního postupu, chatovací rozhraní to nezvládne; K modelu se musíte připojit programově, tedy pomocí kódu nebo automatizačního nástroje. Název tohoto mostu je API (Application Programming Interface, smlouva, která umožňuje dvěma softwarem mluvit s určitými pravidly). Když dokončíte tuto jednotku, budete vědět, co tvoří požadavek LLM (Large Language Model) API, co dělají role zpráv a jak číst odpověď. To je základ, na kterém bude postaven zbytek modulu.
Jak funguje API?
Základní tok v API je tento: odešlete požadavek v určitém formátu; Server vrátí odpověď v určitém formátu. V LLM se obvykle jedná o HTTP volání (HTTP: standardní protokol pro přenos žádost-odpověď na webu) na jedinou adresu (koncový bod, pevná adresa na serveru, který zpracovává váš požadavek). Například v rozhraní API pro zasílání zpráv jdou všechny požadavky na jedinou adresu a jsou přenášeny v těle jako JSON (JavaScript Object Notation – textový formát skládající se z párů klíč/hodnota, které mohou číst lidé i stroje).
V žádosti uveďte alespoň tyto tři věci:
- Model: Jaký model budete používat (např. rychlý a levný model nebo výkonný model).
- max_tokens: Maximální počet tokenů (nejmenší jednotka, ve které se zpracovává text, která bude podrobně zpracována v další jednotce), které může model vyrobit; tj. výstupní limit.
- zprávy: Seznam zpráv, které tvoří konverzaci.
Krok za krokem: Jak nastavit žádost
- Připravte koncový bod a pověření. K požadavku v záhlaví přidáte svůj klíč API (tajný řetězec, který prokazuje vaši identitu). Nikdy nevložíte klíč do kódu; Zajistíme bezpečné skladování v jednotce 9.
- Vyberte model a limit výkonu. Lehký model + malé max_tokeny pro jednoduchý úkol; Výkonný model + větší limit pro komplexní úkol.
- Nastavte seznam zpráv. List the system instruction, user message, and past rounds (if any).
- Odešlete požadavek a analyzujte odpověď. Přečtěte si textový obsah, důvod zastavení a použití tokenu z vráceného JSON.
Role zpráv: systém, uživatel, asistent
Konverzace se skládá ze zpráv uspořádaných za sebou a každá zpráva má svou roli. Role určuje, jak model zachází s tímto textem.
Role
Kdo píše
Účel
systém
Vývojář/operátor
Trvalé pokyny, osobnost a pravidla, která platí po celou dobu konverzace
uživatel
koncový uživatel
Aktuální otázka nebo vstup uživatele
asistent
model
Odpověď vytvořená modelem (a předchozí odpovědi)
Systémová role je k dispozici jako samostatné systémové pole v těle požadavku u většiny poskytovatelů; uživatel a asistent jsou uvedeni postupně v seznamu zprá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": "Jste asistent podnikové podpory. Poskytněte krátkou, formální a ověřenou odpověď. Nevymýšlejte si informace, kterými si nejste jisti.", "messages": [ { "role": "user", "content": "Jak zahájím proces vrácení?" } ]}
Řeč je bez státní příslušnosti
Zde je nejběžnější mylná představa: volání LLM API jsou bezstavová – server si mezi dvěma požadavky neuchová žádnou paměť. Model si nepamatuje váš předchozí požadavek. Pokud nastavujete vícekolový chat, budete muset s každou novou žádostí znovu odeslat minulá kola. „Paměť“ modelu se skládá ze seznamu zpráv, které jste odeslali.
{ "model": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "role": "user", "content": "Dobrý den, jmenuji se Deniz." }, { "role": "asistent", "content": "Ahoj Deniz, jak ti mohu pomoci?" }, { "role": "user", "content": "Právě jsem řekl své jméno, pamatuješ?" } ]}
Správná odpověď na třetí zprávu závisí na odeslání obou předchozích zpráv. Pokud jej neodešlete, modelka nebude znát „Moře“ a odpoví špatně. To také přímo ovlivňuje náklady: čím delší je konverzace, tím větší je seznam a každý požadavek spotřebovává více tokenů.
Tip: V dlouhých rozhovorech sumarizace a přesouvání starých kol (souhrn + posledních pár kol) namísto zasílání celé historie snižuje náklady a zachovává kontextové okno. To prohloubíme v 6. a 11. bloku.
Přečtěte si odpověď
Když model vrátí odpověď, obdržíte strukturovaný objekt, nikoli prostý text. Typické oblasti:
{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "asistent", "content": [ { "type": "text", "text": "Chcete-li zahájit vrácení, přejděte na stránku 'Moje objednávky' ve svém účtu..." } ], "stop_reason": "input_7", "input_7", "input_7" "output_tokens": 88 }}
- obsah: Vlastní odpověď; Je to seznam bloků obsahu. Textové pole textového bloku je skutečnou odpovědí.
- stop_reason: Proč se model zastavil. end_turn = přirozený konec; max_tokens = uvízl na výstupním limitu (odpověď může být neúplná); odmítnutí = odmítnuto z bezpečnostních důvodů. Váš kód by se měl vždy nejprve podívat na stop_reason.
- použití: Vstupní a výstupní čísla tokenů. Je to základ sledování nákladů a limitů.
Upozornění: Pokud je stop_reason max_tokens, odpověď není dokončena. Považovat to za „úspěšnou odpověď“ a zobrazovat uživateli poloviční text je jednou z nejčastějších chyb ve výrobě. Buď zvyšte max_tokens, nebo použijte streamování.
Slabá výzva / Silná výzva
Stejná úloha se dvěma různými systémovými výzvami:
# SLABÝ Jste asistent. Odpovězte na otázky.
# STRONGJste asistent podnikové podpory. Pravidla:- Spolehněte se pouze na informace v poskytnutém dokumentu o zásadách; Pokud to v dokumentu není, řekněte „Tyto informace nemám, směřuji je příslušnému útvaru“. - Odpovědi by neměly přesáhnout 3 věty, být formální a jasné. - Nevyžadujte osobní údaje (TC ID číslo, číslo karty) a neopakujte. - Nehádejte, když si nejste jisti.
Výkonná verze; Definuje rozsah, formu, bezpečnostní rezervu a chování v nejistotě. Konzistence výstupu modelu vychází přímo z této přehlednosti.
Tři mini pouzdra
Případ 1 – Support bot (past bez státní příslušnosti). Tým e-commerce uvedl robota naživo; Když uživatel řekl „zrušit předchozí objednávku“, bot „zapomněl“ číslo objednávky. Důvod: každý požadavek posílali pouze s poslední zprávou. Řešení: do seznamu zpráv přidali posledních 6 kol. Výsledek: kontext zachován, ale vstup na požadavek se zvýšil ze 40 tokenů na ~600 tokenů – lekci o nákladech probereme v lekci 2.
Případ 2 – Neúplné shrnutí smlouvy. Právní tým měl nastíněné desetistránkové smlouvy; max_tokens: 300 zůstalo málo, souhrny byly odříznuty uprostřed věty. stop_reason byl pokaždé max_tokens, ale nikdo se nedíval. zvýšen max_tokens na 1500 a přidána kontrola stop_reason; Míra zkráceného souhrnu se snížila z 18 % na 0 %.
Případ 3 – Míchání rolí. Marketingový tým zapisoval všechny pokyny do uživatelské zprávy a ponechal systém prázdný. Když se uživatelský vstup smíchal s instrukcemi, model někdy vyhověl příkazu uživatele „zapomenout na předchozí pravidla“. Přesunuli do systému trvalá pravidla; Oddělením uživatelského vstupu od pokynů se výrazně snížilo porušování pravidel.
Časté chyby
- Zapomenutí poslat minulost: Předpokládá se, že model si „nepamatuje“; zatímco je bez státní příslušnosti. Vy nesete kontext.
- Nesleduje `stop_reason`: Odpověď zastavená s max_tokens je považována za dokončenou.
- Vložení instrukce do `user`: Trvalá pravidla do systému; okamžitý vstup jde k uživateli. Míchání vytváří zranitelnosti zabezpečení.
- Záměna „obsahu“ za prostý řetězec: Odpovědí je seznam bloků; přečtěte textové pole prvního textového bloku, ověřte jeho typ před získáním obsahu[0] pomocí slepého indexu.
- Vložení klíče do kódu: Použijte proměnnou prostředí (jednotka 9).
Deeper: Obsahové bloky a vícedílné odpovědi
Pochopení toho, proč je pole obsahu v odpovědi seznam, je základem pokročilých funkcí, se kterými se později setkáte. Někdy model nevrátí jeden blok textu, ale několik bloků: blok myšlení, následovaný blokem textu; nebo blok textu následovaný blokem použití nástroje. Proto je slepé počítat obsah[0] jako „odpověď“ křehké. Správný přístup je procházet seznam a třídit jej podle typu: shromažďujete textový obsah bloků, jejichž pole typu je text, a ostatní typy (myšlení, nástroj) zpracováváte samostatně.
V praxi toto rozlišení dělá to, že můžete zaznamenat zdůvodnění modelu (pokud existuje), aniž byste je odhalili uživateli, přesměrovat volání nástrojů na samostatnou logiku a pouze vytisknout skutečnou odpověď na obrazovku. Jak modul postupuje (zejména v jednotkách 4 a 11), uvidíte, jak užitečná je tato bloková struktura pro ověřování a směrování výstupu.
Další praktický bod: ke stejnému modelu můžete přistupovat z různých platforem poskytovatelů (přímé API, prostřednictvím poskytovatele cloudu). Ačkoli se může změnit adresa koncového bodu a formát autentizace, základní pojmy jako role zpráv, stav bez stavu a struktura odpovědí zůstávají stejné. Takže základy této jednotky platí bez ohledu na to, jakou platformu používáte.
V souhrnu
Požadavek LLM API se skládá z modelu, výstupního limitu a seznamu zpráv; role (systém, uživatel, asistent) určují chování modelu. Hovory jsou bezstavové: s každým požadavkem nesete kontext. Odpověď je strukturovaný objekt; Čtení a interpretace polí content, stop_reason a use je základem trvanlivosti ve výrobě.
Aplikační úkol
Vyberte si úkol z vlastní profese (např. třídění příchozích e-mailů, vytváření stručných přehledů). Na kus papíru: (1) napište systémovou výzvu se 4-5 pravidly, (2) nastavte vzorovou uživatelskou zprávu a 2kolovou historii, pokud existuje, (3) určete přiměřenou hodnotu pro max_tokens a napište odůvodnění, (4) uveďte, které hodnoty stop_reason budete v vrácené odpovědi zpracovávat a jak.
kontrolní seznam
- [ ] Dokážu spočítat tři povinné části požadavku (model, max_tokens, zprávy).
- [ ] Umím vysvětlit rozdíl mezi systémovou, uživatelskou a asistentskou rolí.
- [ ] Vím, že hovory jsou bez státní příslušnosti a že musím nést minulost.
- Mohu číst a komentovat [ ] obsah, stop_reason a pole použití.
- [ ] S max_tokens si mohu všimnout a zpracovat zkrácenou odpověď.