Primul dumneavoastră apel API în Python
Pe această pagină
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 naturallength: răspunsul a fost întrerupt deoarece a atins limitamax_tokensmodel_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.usagevă indică câți tokeni au fost consumați (util pentru urmărirea costurilor)temperaturecontrolează creativitatea;max_tokenslimitează lungimea- Începeți cu
mistral-small-latest: este rapid, economic și performant