Câștiguri:
- Poate descrie structura de bază a unei solicitări API LLM (punct final, model, mesaje, max_tokens)
- Înțelege diferența dintre rolurile de sistem, utilizator și asistent și istoricul conversațiilor fără stat
- Poate citi și interpreta câmpuri (blocuri de conținut, stop_reason, utilizare) ale răspunsului returnat
În modulele anterioare, am folosit inteligența artificială dintr-o fereastră de chat. Dar dacă doriți să încorporați AI în propriul produs, automatizare sau flux de lucru, o interfață de chat nu o va tăia; Trebuie să vă conectați la model în mod programatic, adică cu cod sau cu un instrument de automatizare. Numele acestui pod este API (Application Programming Interface, contractul care permite a două software-uri să vorbească cu anumite reguli). Când terminați această unitate, veți ști ce reprezintă o solicitare API LLM (Large Language Model), ce rol fac rolurile de mesaj și cum să citiți răspunsul. Aceasta este fundația pe care va fi construit restul modulului.
Cum funcționează API-ul?
Fluxul de bază în API este următorul: trimiteți o solicitare într-un anumit format; Serverul returnează un răspuns într-un format specific. În LLM, acesta este de obicei un apel HTTP (HTTP: protocol standard pentru transportul cererii-răspuns pe web) la o singură adresă (punct final, adresa fixă de pe serverul care gestionează cererea dvs.). De exemplu, într-un API de mesagerie, toate solicitările ajung la o singură adresă și sunt transportate în corp ca JSON (JavaScript Object Notation — un format text format din perechi cheie/valoare care pot fi citite atât de oameni, cât și de mașini).
Într-o cerere, specificați cel puțin aceste trei lucruri:
- Model: ce model veți folosi (de exemplu, un model rapid și ieftin sau un model puternic).
- max_tokens: Numărul maxim de jetoane (cea mai mică unitate în care este procesat textul, care vor fi procesate în detaliu în unitatea următoare) pe care modelul le poate produce; adică limita de ieșire.
- mesaje: Listă de mesaje care alcătuiesc conversația.
Pas cu pas: Cum să configurați o solicitare
- Pregătiți punctul final și acreditările. Adăugați cheia dvs. API (șirul secret care vă dovedește identitatea) la cerere într-un antet. Nu încorporați niciodată cheia în cod; Vom acoperi depozitarea în siguranță în unitatea 9.
- Selectați modelul și limita de ieșire. Model ușor + max_tokens mici pentru o sarcină simplă; Model puternic + limită mai mare pentru o sarcină complexă.
- Configurați lista de mesaje. List the system instruction, user message, and past rounds (if any).
- Trimiteți cererea și analizați răspunsul. Citiți conținutul textului, motivul opririi și utilizarea simbolului din JSON returnat.
Roluri de mesaje: sistem, utilizator, asistent
O conversație constă din mesaje aranjate într-o secvență, iar fiecare mesaj are un rol. Rolul determină modul în care modelul tratează acel text.
Rol
Cine scrie
Scop
sistem
Dezvoltator/operator
Instrucțiuni permanente, personalitate și reguli care se aplică pe parcursul întregii conversații
utilizator
utilizatorul final
Întrebarea sau intrarea curentă a utilizatorului
asistent
model
Răspunsul produs de model (și răspunsurile anterioare)
Rolul de sistem este disponibil ca un câmp de sistem separat în corpul cererii la majoritatea furnizorilor; utilizatorul și asistentul sunt listate secvenţial în lista de mesaje. 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": "Sunteți un asistent de asistență corporativă. Dați un răspuns scurt, formal și verificat. Nu inventați informații despre care nu sunteți sigur.", "messages": [ { "role": "user", "content": "Cum încep procesul de returnare?" } ]}
Vorbirea este apatridă
Iată cea mai comună concepție greșită: apelurile LLM API sunt apatride — serverul nu păstrează nicio memorie între două solicitări. Modelul nu își amintește cererea dumneavoastră anterioară. Dacă configurați un chat cu mai multe runde, va trebui să retrimiteți rundele anterioare cu fiecare solicitare nouă. „Memoria” modelului constă dintr-o listă de mesaje pe care le-ați trimis.
{ "model": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "role": "user", "content": "Bună ziua, mă numesc Deniz." }, { "rol": "assistant", "content": "Bună Deniz, cu ce te pot ajuta?" }, { "rol": "user", "content": "Tocmai mi-am spus numele, vă amintiți?" } ]}
Răspunsul corect la al treilea mesaj depinde de trimiterea ambelor mesaje anterioare. Daca nu il trimiti, modelul nu va sti "Sea" si va raspunde gresit. Acest lucru afectează, de asemenea, în mod direct costul: cu cât conversația este mai lungă, cu atât lista este mai mare, fiecare cerere consumând mai multe jetoane.
Sfat: în conversațiile lungi, rezumarea și mutarea rundelor vechi (rezumat + ultimele runde) în loc să trimiteți întregul istoric reduce costurile și păstrează fereastra de context. Vom aprofunda acest lucru în unitățile 6 și 11.
Citiți Răspunsul
Când modelul returnează un răspuns, primiți un obiect structurat, nu text simplu. Zone tipice:
{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "assistant", "content": [ { "type": "text", "text": "Pentru a iniția o retur, accesați pagina „Comenzile mele” din contul dvs...." } ], "stop_reason": "utilisation:_" {n:" 47, „output_tokens”: 88 }}
- conținut: răspunsul în sine; Este o listă de blocuri de conținut. Câmpul de text al blocului de text este răspunsul real.
- stop_reason: De ce sa oprit modelul. end_turn = final natural; max_tokens = blocat la limita de ieșire (răspunsul poate fi incomplet); refuz = refuzat din motive de securitate. Codul dvs. ar trebui să se uite întotdeauna la stop_reason mai întâi.
- utilizare: numere de jeton de intrare și ieșire. Este baza urmăririi costurilor și limitelor.
Atenție: Dacă stop_reason este max_tokens, răspunsul nu este finalizat. Tratând acest lucru ca un „răspuns de succes” și arătând jumătate de text utilizatorului este una dintre cele mai frecvente greșeli în producție. Fie crește max_tokens, fie folosește streaming.
Prompt slab / Prompt puternic
Aceeași sarcină cu două solicitări de sistem diferite:
# SLABEști un asistent. Răspunde la întrebările.
# STRONGSunteți un asistent de asistență corporativă. Reguli: - Bazați-vă numai pe informațiile din documentul de politică furnizat; Dacă nu este în document, spuneți „Nu dețin această informație, o direcționez către unitatea relevantă”. - Răspunsurile nu trebuie să depășească 3 propoziții, să fie formale și clare. - Nu solicitați date personale (număr ID TC, număr card) și nu repetați. - Nu ghici când nu ești sigur.
Versiune puternică; Acesta definește domeniul de aplicare, forma, marja de siguranță și comportamentul în incertitudine. Consecvența rezultatelor modelului provine direct din această claritate.
Trei mini carcase
Cazul 1 — Asistență bot (capcană pentru apatridie). O echipă de comerț electronic a preluat botul live; Când utilizatorul a spus „anulează comanda anterioară”, botul „a uitat” numărul comenzii. Motiv: trimiteau fiecare cerere doar cu ultimul mesaj. Soluție: au adăugat ultimele 6 runde la lista de mesaje. Rezultat: contextul a fost păstrat, dar intrarea pe solicitare a crescut de la 40 de jetoane la ~600 de jetoane — vom acoperi lecția de cost în unitatea 2.
Cazul 2 – Rezumatul contractului incomplet. O echipă juridică avea contracte de 10 pagini conturate; max_tokens: 300 au rămas scăzute, rezumatele au fost tăiate la mijlocul propoziției. stop_reason a fost max_tokens de fiecare dată, dar nimeni nu se uita. a crescut max_tokens la 1500 și a adăugat stop_reason check; Rata sumar trunchiată a scăzut de la 18% la 0%.
Cazul 3 — Amestecarea rolurilor. O echipă de marketing scria toate instrucțiunile în mesajul utilizatorului, lăsând sistemul gol. Când introducerea utilizatorului este amestecată cu instrucțiuni, modelul se conforma uneori cu comanda utilizatorului de a „uita regulile anterioare”. Au mutat reguli permanente în sistem; Separând intrarea utilizatorului de instrucțiuni, încălcările regulilor au scăzut semnificativ.
Greșeli comune
- Uitarea de a trimite trecutul: Se crede că modelul „nu-și amintește”; întrucât este apatrid. Tu porti contextul.
- Nu se uită la `stop_reason`: răspunsul oprit cu max_tokens este considerat complet.
- Încorporarea instrucțiunii în „utilizator”: reguli persistente în sistem; intrarea instantanee ajunge la utilizator. Amestecarea creează vulnerabilități de securitate.
- Confundarea „conținut” cu un șir simplu: răspunsul este o listă de blocuri; citiți câmpul de text al primului bloc de text, verificați tipul acestuia înainte de a obține conținut[0] cu un index orb.
- Încorporarea cheii în cod: Utilizați o variabilă de mediu (unitatea 9).
Mai profund: blocuri de conținut și răspunsuri în mai multe părți
Înțelegerea de ce câmpul de conținut din răspuns este o listă este fundamentală pentru funcțiile avansate pe care le veți întâlni mai târziu. Uneori, modelul returnează nu un singur bloc de text, ci mai multe blocuri: un bloc de gândire, urmat de un bloc de text; sau un bloc de text urmat de un bloc de utilizare a instrumentului. De aceea, numărarea orbește conținutul[0] ca „răspuns” este fragil. Abordarea corectă este să parcurgeți lista și să o sortați după tip: colectați conținutul text al blocurilor al căror câmp de tip este text și tratați alte tipuri (gândire, instrument) separat.
Ceea ce face această distincție în practică este că puteți înregistra raționamentul modelului (dacă există) fără a-l dezvălui utilizatorului, redirecționați apelurile instrumentului către o logică separată și imprimați doar răspunsul real pe ecran. Pe măsură ce modulul progresează (în special în unitățile 4 și 11) veți vedea cât de utilă este această structură de bloc pentru validarea și direcționarea ieșirii.
Un alt punct practic: puteți accesa același model de pe platforme diferite de furnizori (API direct, prin intermediul unui furnizor de cloud). Deși adresa punctului final și formatul de autentificare se pot schimba, conceptele de bază precum rolurile mesajelor, apatridia și structura răspunsului rămân aceleași. Deci elementele de bază din această unitate se aplică indiferent de platforma pe care o utilizați.
Pe scurt
O solicitare API LLM constă din model, limita de ieșire și lista de mesaje; rolurile (sistem, utilizator, asistent) determină comportamentul modelului. Apelurile sunt apatride: purtați contextul cu fiecare cerere. Răspunsul este un obiect structurat; Citirea și interpretarea câmpurilor de conținut, stop_reason și utilizare este baza durabilității în producție.
Sarcina de aplicare
Alegeți o sarcină din propria profesie (de exemplu, sortarea e-mail-urilor primite, crearea de rezumate scurte). Pe o bucată de hârtie: (1) scrieți promptul de sistem cu 4-5 reguli, (2) configurați un mesaj de exemplu de utilizator și un istoric de 2 runde, dacă este cazul, (3) determinați o valoare rezonabilă pentru max_tokens și scrieți justificarea, (4) enumerați ce valori stop_reason veți gestiona în răspunsul returnat și cum.
lista de verificare
- [ ] Pot număra cele trei părți obligatorii ale unei cereri (model, max_tokens, mesaje).
- [ ] Pot explica diferența dintre rolurile de sistem, utilizator și asistent.
- [ ] Știu că apelurile sunt apatride și că trebuie să duc trecutul.
- Pot citi și comenta câmpurile de conținut [ ], stop_reason și utilizare.
- [ ] Cu max_tokens pot observa și gestiona răspunsul trunchiat.