Nyereség:
- Le tudja írni egy LLM API kérés alapvető struktúráját (végpont, modell, üzenetek, max_tokens)
- Megérti a különbséget a rendszer-, felhasználói és asszisztensi szerepkörök és az állapot nélküli beszélgetési előzmények között
- El tudja olvasni és értelmezni tudja a visszaadott válasz mezőit (tartalomblokkok, stop_ok, használat).
A korábbi modulokban mesterséges intelligenciát használtunk chat ablakból. De ha saját termékébe, automatizálásába vagy munkafolyamatába szeretné beágyazni a mesterséges intelligenciát, a csevegési felület nem fogja megvágni; A modellhez programozottan kell csatlakozni, azaz kóddal vagy automatizálási eszközzel. Ennek a hídnak a neve API (Application Programming Interface, az a szerződés, amely lehetővé teszi, hogy két szoftver bizonyos szabályok szerint kommunikáljon). Ha befejezi ezt az egységet, tudni fogja, hogy mi minősül LLM (nagy nyelvi modell) API-kérésnek, milyen üzenetszerepeket töltenek be, és hogyan kell elolvasni a választ. Ez az az alap, amelyre a modul többi része épül.
Hogyan működik az API?
Az API alapfolyamata a következő: elküld egy kérést egy bizonyos formátumban; A szerver adott formátumban ad vissza választ. Az LLM-ekben ez általában egy HTTP-hívás (HTTP: szabványos protokoll a kérés-válasz továbbítására a weben) egyetlen címre (végpont, a kérést kezelő szerver rögzített címe). Például egy üzenetküldő API-ban minden kérés egyetlen címre érkezik, és a törzsben JSON-ként (JavaScript Object Notation – olyan kulcs/érték párokból álló szövegformátum, amelyet emberek és gépek is olvashatnak) továbbítanak.
Egy kérésben legalább három dolgot ad meg:
- Modell: Melyik modellt fogja használni (pl. gyors és olcsó modell vagy erős modell).
- max_tokens: A tokenek maximális száma (az a legkisebb egység, amelyben a szöveg feldolgozásra kerül, amelyet a következő egységben részletesen feldolgozunk), amelyet a modell képes előállítani; azaz kimeneti korlát.
- üzenetek: A beszélgetést alkotó üzenetek listája.
Lépésről lépésre: Hogyan állítsunk be egy kérést
- Készítse elő a végpontot és a hitelesítő adatokat. Az API-kulcsot (az Ön személyazonosságát igazoló titkos karakterláncot) egy fejlécben adja hozzá a kéréshez. Soha nem ágyazod be a kulcsot a kódba; A biztonságos tárolást a 9-es blokkban fedezzük.
- Válassza ki a modellt és a kimeneti korlátot. Könnyű modell + kis max_token egy egyszerű feladathoz; Erőteljes modell + nagyobb korlát egy összetett feladathoz.
- Állítsa be az üzenetlistát. List the system instruction, user message, and past rounds (if any).
- Küldje el a kérést, és elemezze a választ. Olvassa el a szöveges tartalmat, a leállás okát és a jogkivonat használatát a visszaküldött JSON-ból.
Üzenetszerepek: rendszer, felhasználó, asszisztens
Egy beszélgetés sorozatba rendezett üzenetekből áll, és minden üzenetnek megvan a maga szerepe. A szerep határozza meg, hogy a modell hogyan kezeli a szöveget.
Szerep
Aki ír
Cél
rendszer
Fejlesztő/üzemeltető
Állandó utasítások, személyiség és szabályok, amelyek az egész beszélgetés során érvényesek
felhasználó
végfelhasználó
A felhasználó aktuális kérdése vagy bevitele
asszisztens
modell
A modell által készített válasz (és a korábbi válaszok)
A rendszerszerep a legtöbb szolgáltatónál külön rendszermezőként érhető el a kérelem törzsében; A felhasználó és az asszisztens egymás után szerepel az üzenetlistában. 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": "Ön vállalati támogatási asszisztens. Adjon rövid, formális és ellenőrzött választ. Ne találjon ki olyan információkat, amelyekben nem biztos.", "üzenetek": [ { "role": "user", "content": "Hogyan kezdjem el a visszaküldési folyamatot?" } ]}
A beszéd hontalan
Íme a leggyakoribb tévhit: az LLM API-hívások állapot nélküliek – a szerver nem tart meg memóriát két kérés között. A modell nem emlékszik az előző kérésére. Ha többfordulós csevegést állít be, minden új kéréssel újra el kell küldenie a korábbi köröket. A modell „memóriája” az Ön által elküldött üzenetek listájából áll.
{ "model": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "role": "user", "content": "Hello, a nevem Deniz." }, { "role": "asszisztens", "content": "Szia Deniz, hogyan segíthetek?" }, { "role": "user", "content": "Most mondtam a nevem, emlékszel?" } ]}
A harmadik üzenet helyes megválaszolása attól függ, hogy mindkét előző üzenetet elküldte-e. Ha nem küldi el, a modell nem fogja tudni, hogy "Tenger", és hibásan válaszol. Ez közvetlenül befolyásolja a költségeket is: minél hosszabb a beszélgetés, annál nagyobb a lista, minden kérés több tokent fogyaszt.
Tipp: Hosszú beszélgetések során a régi körök összegzése és áthelyezése (összefoglaló + utolsó néhány kör) a teljes előzmény elküldése helyett csökkenti a költségeket és megőrzi a kontextusablakot. Ezt a 6. és 11. egységben elmélyítjük.
Olvassa el a választ
Amikor a modell választ ad, strukturált objektumot kap, nem egyszerű szöveget. Tipikus területek:
{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "assistant", "content": [ { "type": "text", "text": "Visszaküldés kezdeményezéséhez lépjen fiókja "Megrendeléseim" oldalára..." } ], "stop_reason": "usage_turn": "usage" "input_tokens": 47, "output_tokens": 88 }}
- tartalom: Maga a válasz; Ez a tartalomblokkok listája. A szövegblokk szövegmezője a tényleges válasz.
- stop_reason: Miért állt le a modell. end_turn = természetes vég; max_tokens = elakadt a kimeneti korlátnál (a válasz hiányos lehet); elutasítás = biztonsági okokból elutasítva. A kódnak mindig először a stop_reason-t kell néznie.
- használat: Bemeneti és kimeneti token számok. Ez a költség- és limitkövetés alapja.
Figyelem: Ha a stop_reason értéke max_tokens, a válasz nem fejeződik be. Ennek "sikeres válaszként" kezelése és a fél szöveg megjelenítése a felhasználónak az egyik leggyakoribb hiba a gyártás során. Vagy növelje a max_tokens értéket, vagy használja a streaminget.
Gyenge felszólítás / Erős felszólítás
Ugyanaz a feladat két különböző rendszerprompttal:
# GYENGE Ön asszisztens. Válaszoljon a kérdésekre.
# STRONGÖn vállalati támogatási asszisztens. Szabályok: - Kizárólag a megadott irányelv dokumentumban szereplő információkra hagyatkozzon; Ha ez nem szerepel a dokumentumban, mondja azt, hogy "Nem rendelkezem ezzel az információval, az illetékes egységhez irányítom." - A válaszok nem haladhatják meg a 3 mondatot, legyenek formálisak és egyértelműek. - Ne kérjen személyes adatokat (TC azonosítószám, kártyaszám), és ne ismételje meg. - Ne találgasson, ha nem vagy biztos benne.
Erőteljes változat; Meghatározza a hatókört, formát, biztonsági határt és viselkedést a bizonytalanságban. A modell kimenetének konzisztenciája közvetlenül ebből az egyértelműségből fakad.
Három mini tok
1. eset – Support bot (hontalansági csapda). Egy e-kereskedelmi csapat élesben vette a botot; Amikor a felhasználó azt mondta, hogy "törölje az előző rendelést", a bot "elfelejtette" a rendelés számát. Ok: minden kérést csak az utolsó üzenettel küldtek. Megoldás: az utolsó 6 kört hozzáadták az üzenetlistához. Eredmény: a kontextus megmaradt, de a kérésenkénti bevitel 40 tokenről ~600 tokenre nőtt – a költségleckét a 2. egységben fedezzük.
2. eset – Hiányos szerződés-összefoglaló. Egy jogi csapat 10 oldalas szerződéseket vázolt fel; max_tokens: 300 maradt alacsonyan, az összefoglalók a mondat közepét levágták. A stop_reason minden alkalommal max_tokens volt, de senki sem kereste. növelte a max_tokens értéket 1500-ra, és hozzáadta a stop_reason ellenőrzést; A csonka összesítő ráta 18%-ról 0%-ra csökkent.
3. eset – Szerepek keverése. Egy marketingcsapat az összes utasítást beleírta a felhasználói üzenetbe, így a rendszer üresen maradt. Ha a felhasználói bevitelt utasításokkal keverik, a modell néha megfelel a felhasználó „elfelejteni az előző szabályokat” parancsának. Állandó szabályokat helyeztek át a rendszerbe; A felhasználói bevitel és az utasítások elkülönítésével a szabálysértések jelentősen csökkentek.
Gyakori hibák
- Elfelejti elküldeni a múltat: Úgy gondolják, hogy a modell "nem emlékszik"; míg hontalan. Te hordozod a kontextust.
- Nem nézi a "stop_reason"-t: A max_tokens-el leállított válasz teljesnek tekinthető.
- Az utasítás beágyazása a `user'-be: Állandó szabályok a rendszerbe; Az azonnali bevitel a felhasználóhoz kerül. A keverés biztonsági réseket okoz.
- A "content" összetévesztése egy egyszerű karakterlánccal: A válasz blokkok listája; olvassa el az első szövegblokk szövegmezőjét, ellenőrizze a típusát, mielőtt a tartalom[0] beszerzése vakindexszel.
- A kulcs beágyazása a kódba: Használjon környezeti változót (9. egység).
Deeper: Tartalomblokkok és többrészes válaszok
Annak megértése, hogy a válaszban szereplő tartalommező miért egy lista, alapvető fontosságú a későbbiekben előforduló speciális szolgáltatások szempontjából. Néha a modell nem egyetlen szövegblokkot, hanem több blokkot ad vissza: egy gondolkodási blokkot, majd egy szövegblokkot; vagy egy szövegblokk, amelyet egy eszközhasználati blokk követ. Ez az oka annak, hogy a tartalom[0] vakon „válaszként” való számítása törékeny. A helyes megközelítés az, hogy végigmegyünk a listán, és típus szerint rendezzük: összegyűjtjük azon blokkok szövegtartalmát, amelyek típusmezője szöveg, a többi típust (gondolkodás, eszköz) pedig külön kezeljük.
Ez a különbségtétel a gyakorlatban az, hogy naplózhatja a modell okfejtését (ha van ilyen) anélkül, hogy felfedné a felhasználó számára, az eszközhívásokat külön logikára irányíthatja át, és csak a tényleges választ nyomtathatja ki a képernyőre. A modul előrehaladtával (különösen a 4-es és 11-es egységekben) látni fogja, mennyire hasznos ez a blokkstruktúra a kimenet érvényesítéséhez és irányításához.
Egy másik gyakorlati szempont: ugyanazt a modellt különböző szolgáltatói platformokról érheti el (közvetlen API, felhőszolgáltatón keresztül). Bár a végpont címe és a hitelesítési formátum változhat, az alapvető fogalmak, például az üzenet szerepei, az állapottalanság és a válaszstruktúra változatlanok maradnak. Tehát az egység alapjai érvényesek, függetlenül attól, hogy milyen platformot használ.
Összefoglalva
Az LLM API kérés a modellből, a kimeneti korlátból és az üzenetlistából áll; szerepek (rendszer, felhasználó, asszisztens) határozzák meg a modell viselkedését. A hívások állapot nélküliek: minden kéréssel együtt hordozza a kontextust. A válasz egy strukturált objektum; A tartalom, a stop_reason és a használati mezők olvasása és értelmezése a tartósság alapja a gyártásban.
Pályázati feladat
Válasszon egy feladatot a saját szakmájából (pl. bejövő e-mailek rendezése, rövid összefoglalók készítése). Egy darab papírra: (1) írja fel a rendszer promptot 4-5 szabállyal, (2) állítson be egy minta felhasználói üzenetet és egy 2 körös előzményt, ha van ilyen, (3) határozzon meg egy ésszerű értéket a max_tokens számára, és írja be az indoklást, (4) sorolja fel, mely stop_reason értékeket fogja kezelni a visszaadott válaszban, és hogyan.
ellenőrző lista
- [ ] Meg tudom számolni egy kérés három kötelező részét (modell, max_tokens, üzenetek).
- [ ] Meg tudom magyarázni a különbséget a rendszer-, a felhasználói és az asszisztensi szerepek között.
- [ ] Tudom, hogy a hívások hontalanok, és cipelnem kell a múltat.
- El tudom olvasni és hozzászólni tudok [ ] tartalmakhoz, stop_reason és használati mezőkhöz.
- [ ] A max_tokens segítségével tudom észrevenni és kezelni a csonka választ.