Salt la conținutul principal
Română— Alege o limbă
Meniu

Primul dumneavoastră apel API în Python

Lecția 5 din 14 Actualizată 2 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Primul dumneavoastră schimb de date cu un model Mistral
  2. Inițializarea clientului
  3. Trimiterea unei cereri cu chat.complete()
  4. Citirea obiectului returnat
  5. Ajustarea comportamentului modelului
  6. Un apel pregătit pentru producție
  7. Puncte cheie

Primul dumneavoastră schimb de date cu un model Mistral

SDK-ul este instalat și cheia dumneavoastră API este gata de utilizare: a sosit momentul să trimiteți o cerere reală și, mai important, să înțelegeți ce se întoarce ca răspuns. Mulți dezvoltatori se opresc la prima linie a răspunsului și ignoră restul obiectului returnat. Aceasta este o greșeală, deoarece urmărirea costurilor și diagnosticarea răspunsurilor trunchiate se regăsesc exact în acele date rămase. Vom începe cu un cod minimal și vom avansa treptat către structura completă.

Inițializarea clientului

Clientul reprezintă punctul de intrare pentru toate interacțiunile dumneavoastră cu API-ul:

import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

Acesta gestionează conexiunile HTTP, reîncercările în cazul erorilor de rețea și serializarea cererilor. Instanțiați-l o singură dată la pornirea aplicației. Recrearea unui client pentru fiecare apel vă obligă să plătiți inutil pentru configurarea conexiunii și constituie una dintre cele mai subtile cauze ale latenței excesive.

Trimiterea unei cereri cu chat.complete()

Veți utiliza metoda chat.complete() cel mai frecvent. Aceasta trimite mesajele dumneavoastră și așteaptă răspunsul complet al modelului înainte de a returna controlul:

response = client.chat.complete(
    model="mistral-small-latest",
    messages=[
        {
            "role": "user",
            "content": "Explain the concept of tokenization in three sentences."
        }
    ]
)

print(response.choices[0].message.content)

Doi parametri sunt suficienți aici. model specifică ID-ul modelului: mistral-small-latest indică întotdeauna cea mai recentă versiune a Mistral Small, ceea ce îl face alegerea naturală pentru început, fiind rapid și economic. messages așteaptă o listă de mesaje structurate, fiecare având un role—system, user sau assistant—și un câmp content care conține textul. Această structură poate părea greoaie pentru o simplă întrebare, dar devine perfect logică odată ce ajungeți la lecția despre conversațiile multi-tur.

Citirea obiectului returnat

Obiectul response conține mult mai mult decât simplul text generat:

# Textul răspunsului
text = response.choices[0].message.content

# Rolul (întotdeauna "assistant" pentru un răspuns)
role = response.choices[0].message.role

# Motivul opririi
finish = response.choices[0].finish_reason  # "stop", "length", etc.

# Statistici privind tokenii
input_tokens = response.usage.prompt_tokens
output_tokens = response.usage.completion_tokens
total_tokens = response.usage.total_tokens

print(f"Response ({output_tokens} tokens): {text}")
print(f"Total tokens consumed: {total_tokens}")

Acordați o atenție deosebită câmpului usage încă de la început. Înregistrarea acestuia la fiecare apel vă indică exact ce funcționalitate a aplicației dumneavoastră consumă bugetul, fără a fi nevoie să reconstruiți factura la sfârșitul lunii.

Cât despre finish_reason, acesta indică motivul pentru care modelul s-a oprit și poate lua una dintre următoarele valori:

  • stop: modelul și-a finalizat răspunsul în mod natural
  • length: răspunsul a fost întrerupt deoarece a atins limita max_tokens
  • model_length: contextul total (intrare + ieșire) a atins limita modelului

Un răspuns care se termină la mijlocul unei propoziții nu este o eroare a modelului: este un finish_reason de tip length pe care nimeni nu l-a verificat. Verificați întotdeauna acest aspect înainte de a concluziona că există o problemă de calitate.

Ajustarea comportamentului modelului

Trei parametri suplimentari vă permit să direcționați generarea:

response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {
            "role": "user",
            "content": "Propose three names for an educational AI startup."
        }
    ],
    temperature=0.7,
    max_tokens=500,
    top_p=0.95,
)

Temperature controlează gradul de libertate al modelului. La 0.0, răspunsurile sunt deterministe: același prompt produce întotdeauna același text, ceea ce este necesar pentru extragere sau clasificare. Între 0.3 și 0.5, obțineți un echilibru bun pentru sarcini factuale. Între 0.7 și 1.0, răspunsurile devin mai creative și variate—acesta este intervalul utilizat în exemplul de mai sus, deoarece cerem idei de nume, iar repetarea aceleiași idei de trei ori ar fi inutilă. Peste 1.0, generarea devine extrem de aleatorie și rareori are utilitate practică.

max_tokens limitează lungimea răspunsului, ceea ce ajută la controlul costurilor și menține ieșirile gestionabile. Rețineți totuși că, dacă modelul este întrerupt, finish_reason va fi "length". top_p afectează diversitatea printr-un mecanism diferit: filtrează tokenii cu cea mai mică probabilitate. O valoare de 0.95 înseamnă că modelul ia în considerare doar tokenii care reprezintă 95% din probabilitatea cumulativă.

Un apel pregătit pentru producție

În condiții reale, rețeaua poate ceda, cheile pot expira, iar cotele se pot epuiza. Încadrați întotdeauna apelurile într-un bloc de gestionare a erorilor:

import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

try:
    response = client.chat.complete(
        model="mistral-small-latest",
        messages=[
            {"role": "user", "content": "What is the capital of France?"}
        ],
        max_tokens=100,
    )

    text = response.choices[0].message.content
    print(f"Response: {text}")
    print(f"Tokens used: {response.usage.total_tokens}")

except Exception as e:
    print(f"API call error: {e}")

Folosiți acest schelet pentru propriile dumneavoastră experimente, înlocuind pur și simplu conținutul mesajului. Acesta este punctul de plecare pentru tot ce urmează în acest curs.

Puncte cheie

  • client.chat.complete() este metoda principală pentru interacțiunea cu modelele
  • Textul răspunsului se află în response.choices[0].message.content
  • response.usage vă indică câți tokeni au fost consumați (util pentru urmărirea costurilor)
  • temperature controlează creativitatea; max_tokens limitează lungimea
  • Începeți cu mistral-small-latest: este rapid, economic și performant