Ce este un API de LLM și cum funcționează (request, răspuns, tokeni)

Cei mai mulți dezvoltatori tratează un API de LLM ca pe orice alt serviciu web: trimiți o cerere, primești un răspuns „corect". Apoi se lovesc de primul răspuns care sună impecabil dar e fals, de primul document care taie brusc răspunsul la jumătate de propoziție, de prima factură surprinzător de mare — și își dau seama că modelul mental cu care au pornit era greșit. Un LLM nu caută răspunsuri într-o bază de date; el prezice, token cu token, cea mai plauzibilă continuare a textului. Din această singură idee decurg variabilitatea, halucinațiile, costul pe tokeni și limitele de context — tot ce trebuie să înțelegi înainte de a scrie prima linie de cod.

Vom învăța aici trei lucruri esențiale: (1) ce este un model de limbaj din perspectiva celui care îl folosește prin API, (2) ciclul fundamental request → model → răspuns și rolul tokenilor în acest ciclu, și (3) de ce folosim SDK-urile oficiale Python în loc de apeluri HTTP scrise de mână. Pe parcurs vom contura, doar cât e necesar pentru orientare, peisajul de provideri și modele al anului 2026.

Ce înseamnă „LLM" pentru un dezvoltator de API

LLM înseamnă Large Language Model — model de limbaj de mari dimensiuni. Pentru un cercetător în învățare automată, aceasta deschide o discuție despre arhitecturi, atenție și antrenament. Pentru noi, dezvoltatorii care construim aplicații, definiția practică este mult mai simplă și mai utilă:

Un LLM este un serviciu căruia îi trimiți un text (sau o conversație) și care îți returnează o continuare plauzibilă a acelui text, generată cuvânt cu cuvânt.

Mecanismul de bază, redus la esență, este predicția token-ului următor. Modelul a fost antrenat să răspundă la o întrebare aparent banală: „dat fiind textul de până acum, care este cea mai probabilă bucată de text care urmează?" Repetând această predicție de mii de ori, una după alta, modelul produce propoziții, paragrafe și răspunsuri întregi.

Este crucial să interiorizezi această idee: modelul nu caută răspunsuri într-o bază de date și nu „știe" lucruri în sensul în care le știe un index de căutare. El generează text statistic plauzibil pe baza tiparelor învățate. Aceasta explică direct două comportamente pe care le vei întâlni mereu:

• Variabilitate: la aceeași întrebare poți primi formulări ușor diferite, pentru că generarea implică o componentă probabilistică.
• Halucinații: modelul poate produce afirmații care sună corect, dar sunt false, pentru că obiectivul lui este plauzibilitatea, nu adevărul verificat.

Acest curs te va învăța tehnici concrete pentru a controla variabilitatea și a reduce riscul de halucinație (prompturi clare, parametri precum temperatura, ieșiri structurate), dar punctul de plecare este să accepți natura generativă a instrumentului.

Prompt și completare: cele două capete ale conversației

În jargonul API-urilor de LLM apar constant doi termeni:

• Prompt (sau input): textul pe care îl trimiți tu către model. Poate fi o întrebare, un set de instrucțiuni, o conversație întreagă sau un document care trebuie procesat.
• Completare (sau completion / output): textul pe care modelul îl generează ca răspuns.

În API-urile moderne de chat — atât la OpenAI, cât și la Anthropic — promptul nu este un singur șir de caractere monolitic, ci o listă de mesaje cu roluri. Cele mai frecvente roluri sunt:

La Anthropic, mesajul de tip system se transmite ca parametru separat (system), iar restul conversației ca listă de mesaje cu rolurile user și assistant. La OpenAI, în Chat Completions, toate mesajele (inclusiv cel system) intră în aceeași listă messages. Diferențele de formă le vom întâlni concret în modulul 1; deocamdată reține structura: o conversație este o secvență de mesaje cu roluri, iar modelul generează următorul mesaj assistant.

Tokenii: unitatea fundamentală de măsură

Aici se află conceptul care derutează cel mai des începătorii și care, totodată, guvernează costul și limitele oricărei aplicații AI: tokenul.

Modelele nu procesează text caracter cu caracter și nici, exact, cuvânt cu cuvânt. Ele lucrează cu tokeni — fragmente de text rezultate dintr-un proces numit tokenizare. Un token poate fi un cuvânt scurt întreg, o bucată dintr-un cuvânt mai lung, un semn de punctuație sau chiar un spațiu.

Câteva repere intuitive, valabile aproximativ pentru limba engleză:

• Un cuvânt englezesc comun ≈ 1 token (uneori 1,3 tokeni).
• O regulă de buzunar des citată: aproximativ 4 caractere de text englezesc ≈ 1 token.
• Limbile cu diacritice și morfologie bogată, precum româna, tind să consume mai mulți tokeni per cuvânt decât engleza, pentru că tokenizatoarele au fost optimizate preponderent pe engleză. Practic, același mesaj scris în română poate costa sensibil mai mulți tokeni decât echivalentul lui în engleză.

De ce contează tokenii? Din două motive de business și inginerie:

1. Costul. Providerii facturează, în mod tipic, per token — separat pentru tokenii de intrare (promptul tău) și pentru tokenii de ieșire (răspunsul generat), de regulă ieșirea fiind mai scumpă. Mai mult text înseamnă mai mulți tokeni înseamnă cost mai mare. Notă importantă: prețurile API și numele modelelor se schimbă des; acest curs nu oferă nicio garanție de cost și nu citează tarife exacte, tocmai pentru că ele devin rapid perimate. Verifică întotdeauna pagina oficială de prețuri a providerului.
2. Limitele. Fiecare model are o limită maximă de tokeni pe care îi poate „ține în minte" simultan. Aceasta ne duce la distincția următoare, esențială.

Context window vs. max output tokens

Două limite separate sunt frecvent confundate, iar confuzia produce erori reale în producție.

• Context window (fereastra de context) este numărul total de tokeni pe care modelul îi poate procesa într-o singură cerere — intrarea plus ieșirea, însumate. Este capacitatea totală a „mesei de lucru" a modelului. În 2026, modele de top precum Claude Opus 4.8 sau familia GPT-5.5 oferă ferestre de context foarte mari (de ordinul a 1 milion de tokeni), ceea ce permite procesarea unor documente întregi într-un singur apel.
• Max output tokens (numărul maxim de tokeni de ieșire) este o limită pe care o setezi tu pentru fiecare cerere și care plafonează cât de lung poate fi răspunsul generat. La Anthropic, parametrul max_tokens este chiar obligatoriu în apelul de mesaje.

Relația dintre ele este de tip „buget comun":

tokeni_prompt + tokeni_raspuns_generat  ≤  context_window

Greșeala clasică: trimiți un document uriaș care aproape umple fereastra de context și apoi te miri că răspunsul se taie brusc — pur și simplu nu a mai rămas „buget" de tokeni pentru ieșire. Sau invers, setezi un max_tokens prea mic și răspunsul se oprește la jumătate de propoziție. A înțelege acest buget comun este una dintre cele mai valoroase deprinderi practice ale acestui modul.

Ciclul request → model → răspuns

Privind de sus, fiecare interacțiune cu un API de LLM urmează același tipar, indiferent de provider:

1. Request (cererea): aplicația ta trimite, peste rețea, o cerere care conține — în esență — ce model vrei să folosești, lista de mesaje (promptul) și parametri care controlează generarea (de exemplu max_tokens, temperature).
2. Model (procesarea): serverul providerului tokenizează intrarea, rulează modelul și generează ieșirea token cu token.
3. Response (răspunsul): primești înapoi textul generat, împreună cu metadate prețioase: câți tokeni de intrare și de ieșire s-au consumat (usage), motivul pentru care generarea s-a oprit (stop_reason / finish_reason), identificatori etc.

Acel câmp usage din răspuns este prietenul tău cel mai bun pentru a monitoriza consumul real, în loc să-l estimezi din burtă.

Sincron vs. streaming, la nivel conceptual

Există două moduri de a primi răspunsul:

• Sincron (non-streaming): trimiți cererea și aștepți până când întregul răspuns este gata; abia atunci îl primești, complet. Simplu de programat, dar utilizatorul așteaptă tăcut cât durează generarea.
• Streaming: răspunsul îți este trimis incremental, bucată cu bucată, pe măsură ce modelul îl generează. Este exact efectul de „text care apare cuvânt cu cuvânt" pe care l-ai văzut în interfețele de chat. Îmbunătățește percepția de viteză (utilizatorul vede primul cuvânt aproape imediat) și e potrivit pentru aplicații interactive.

Deocamdată e suficient să reții că există ambele moduri și la ce servesc. Implementarea concretă a streamingului o vom face mai târziu în curs; aici doar fixăm vocabularul.

De ce SDK oficial, nu HTTP manual

Tehnic, un API de LLM este un API web: ai putea construi singur cererile HTTP, cu anteturi, corp JSON și parsarea răspunsului. Ar funcționa. Dar în acest curs vom folosi SDK-urile oficiale Python, și iată de ce:

• Autentificare automată: SDK-ul citește cheia din variabila de mediu corespunzătoare și o atașează corect la fiecare cerere.
• Tipuri și autocompletare: lucrezi cu obiecte și metode bine definite, nu cu dicționare JSON brute predispuse la greșeli de tipar.
• Reîncercări și gestionarea erorilor: SDK-urile tratează automat reîncercări la erori tranzitorii și expun excepții clare.
• Streaming și funcționalități avansate: streamingul, apelarea de unelte (tool calling) și ieșirile structurate sunt mult mai ușor de folosit prin SDK decât reconstruite manual.
• Aliniere cu documentația: exemplele oficiale de pe docs.anthropic.com și platform.openai.com sunt scrise în termenii SDK-ului, deci urmărirea lor devine directă.

Pachetele pe care le vom folosi de-a lungul cursului sunt cele oficiale, publicate pe PyPI: anthropic (seria 0.105.x, de exemplu 0.105.2 din mai 2026) și openai (seria 2.41.x, de exemplu 2.41.0 din iunie 2026). O regulă de aur pe care o vom respecta riguros: fixăm explicit versiunile SDK-urilor în proiect, pentru că aceste biblioteci evoluează rapid, iar o versiune nefixată poate aduce schimbări incompatibile.

Peisajul 2026, doar cât să te orientezi

Nu vom transforma cursul într-un catalog de modele — numele și prețurile lor se schimbă des. Dar pentru orientare, iată reperele actuale ale anului 2026:

• OpenAI oferă familia GPT-5.5 (cu variante precum standard, Thinking și Pro, cu context de ordinul a 1M tokeni), alături de GPT-5.4 și GPT-5.3 Instant. SDK-ul Python openai și, complementar, OpenAI Agents SDK acoperă scenariile de la apeluri simple la agenți.
• Anthropic oferă familia Claude: Fable 5 (cel mai capabil model general), Opus 4.8 (top-ul familiei Opus), Opus 4.7 (generația anterioară, încă disponibilă), Sonnet 5 (echilibrul performanță/cost, succesorul lui Sonnet 4.6) și Haiku 4.5 (rapid și economic, context 200K), primele având context de până la 1M tokeni. SDK-ul este pachetul anthropic.
• Google propune familia Gemini 3.1 (Pro, Flash, Deep Think), pe care o menționăm doar ca punct de referință al peisajului.

Vom construi în acest curs cu OpenAI și Anthropic, dar principiile (mesaje, tokeni, context, streaming) sunt transferabile între provideri.

O resursă oficială și gratuită

Pe lângă documentația oficială, Anthropic Academy oferă materiale de învățare gratuite și oficiale despre lucrul cu API-ul Claude. Este o sursă excelentă de aprofundare, complementară acestui curs, și o recomandăm explicit pentru cei care vor să exploreze mai departe.

Unde se situează acest curs

Pentru a evita confuzia cu alte cursuri din ofertă, fixăm clar poziționarea:

• Acesta este cursul în care scrii cod Python care apelează API-uri de LLM, de la primul import până la o aplicație funcțională.
• Teoria profundă de învățare automată (cum funcționează transformerele, mecanismul de atenție, antrenamentul) nu este obiectul nostru — acela este teritoriul cursurilor conceptuale.
• Construirea de soluții fără cod (no-code) este, de asemenea, alt teritoriu. Aici miza este programarea reală.

Cu acest model mental — predicția token-ului, ciclul request→model→răspuns, tokenii ca unitate de cost și de limită, context window versus max output, sincron versus streaming și SDK-ul oficial ca instrument — nu mai privești API-ul ca pe o cutie neagră. Dar a înțelege cum funcționează nu este totuna cu a-l face să funcționeze la tine în terminal: lecția următoare construiește mediul Python curat în care vei scrie primul apel real, iar de acolo fiecare lecție adaugă câte o piesă până la o aplicație completă pe care o poți pune în mâna cuiva.

Rezumat

• Un LLM, pentru dezvoltatorul de API, este un serviciu care continuă text prin predicția token-ului următor; este generativ, deci variabil și predispus la halucinații, ceea ce vom controla prin tehnici concrete.
• O cerere este o listă de mesaje cu roluri (system, user, assistant); modelul generează următorul mesaj de tip assistant.
• Tokenii sunt unitatea de măsură pentru cost și pentru limite; româna consumă tipic mai mulți tokeni decât engleza.
• Context window = intrare + ieșire însumate; max output tokens = plafonul răspunsului, setat de tine. Ele împart un buget comun.
• Răspunsul vine sincron sau prin streaming; ambele au utilitatea lor.
• Folosim SDK-urile oficiale anthropic (0.105.x) și openai (2.41.x), cu versiuni fixate, ancorate în docs.anthropic.com și platform.openai.com.