Risposta u Użu
F'din il-paġna
Ifhem x’tirritorna l-API
Ħafna żviluppaturi ġodda għall-API jaqraw biss linja waħda tar-risposta—it-test iġġenerat—u jinjoraw kollox l-ieħor. Din hija żball. Kull sejħa lejn /v1/chat/completions tirritorna oġġett JSON rikk. Hawnhekk issib id-data li għandek bżonn biex issegwi l-ispejjeż, tiskopri risposta mqatgħa qabel ma tilħaq lill-utent, u tidentifika sejħa speċifika meta tiftaħ tikketta ta’ appoġġ.
L-Anatomija Sħiħa tar-Risposta
Ejja nibdew bil-metadejta. Dawn huma l-oqsma li rari tiċċekkja, iżda li tkun tixtieq li kont irreġistrajt il-jum li jseħħ inċident:
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "What is machine learning?"}],
max_tokens=500
)
# Access metadata
print(f"Request ID : {response.id}")
print(f"Model used : {response.model}")
print(f"Created at : {response.created}")
Il-qasam id huwa identifikatur uniku assenjat għal kull talba. Din hija r-referenza li tipprovdi lill-appoġġ tekniku, u dik li tippermettilek torbot ilment tal-utent ma’ sejħa speċifika fil-logs tiegħek. Il-qasam model jikkonferma liema mudell intuża attwalment. Dan jimpatta aktar milli taħseb meta ssejjaħ alias -latest u l-imġiba tinbidel f’daqqa waħda mingħajr ebda bidla fil-kodiċi tiegħek.
L-Array choices
Il-qalba tar-risposta tinsab f’choices. B’mod predefinit, dan l-array fih element wieħed biss. Minnu testratti kemm it-test kif ukoll il-verdett dwar kif intemmet il-ġenerazzjoni:
choice = response.choices[0]
# The generated message
print(choice.message.role) # "assistant"
print(choice.message.content) # The response text
# The index of this response in the array
print(choice.index) # 0
# The stop reason
print(choice.finish_reason) # "stop", "length", or "tool_calls"
Jekk titlob risposti multipli billi tuża l-parametru n, li se nkopru fil-lezzjoni 15, choices ikun fih elementi multipli, u l-indiċi jerġa’ jsir sinifikanti.
Valuri ta’ finish_reason
Dan il-qasam jiddetermina l-affidabbiltà tal-applikazzjoni tiegħek. Hemm tliet valuri possibbli. stop jindika li l-mudell temm ir-risposta tiegħu b’mod naturali. Dan huwa l-każ normali, fejn tista’ turi l-kontenut mingħajr riżervi. length ifisser li l-ġenerazzjoni nqatgħet minħabba max_tokens, allura r-risposta hija potenzjalment mhux kompluta—sommarju li jonqsu l-konklużjoni tiegħu, jew lista li tieqaf fis-seba’ oġġett. Fl-aħħar nett, tool_calls jindika li l-mudell qed jitlob l-eżekuzzjoni ta’ għodda esterna bħala parti mis-sejħa tal-funzjoni, u issa l-ballun huwa f’idejk.
Kull wieħed minn dawn il-każijiet jeħtieġ trattament distint, li għandek tikteb darba għal dejjem:
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Write a detailed report."}],
max_tokens=200
)
choice = response.choices[0]
if choice.finish_reason == "stop":
# Complete response — normal processing
result = choice.message.content
elif choice.finish_reason == "length":
# Truncated response — retry with more tokens or warn the user
print("Warning: The response was truncated.")
# Option: Retry with a higher max_tokens limit
# Option: Ask the model to continue
elif choice.finish_reason == "tool_calls":
# The model requests a tool call
for tool_call in choice.message.tool_calls:
print(f"Requested tool: {tool_call.function.name}")
Innota li l-fergħa length ma tħallix it-test jgħaddi biss hekk. Jew terġa’ tipprova b’limitu ogħla, titlob lill-mudell biex ikompli, jew twissi lill-utent. Dak li qatt m’għandek tagħmel huwa li turi test imqatta’ qisu kien komplet.
L-Oġġett usage — Segwi l-Ispejjeż Tiegħek
Il-qasam usage jgħodd it-tokens ikkunsmati mit-talba, u jissepara l-input mill-output:
usage = response.usage
print(f"Input tokens : {usage.prompt_tokens}")
print(f"Output tokens : {usage.completion_tokens}")
print(f"Total : {usage.total_tokens}")
Din id-distinzjoni mhix kożmetika. Il-mudelli ta’ Mistral għandhom rati differenti għall-input u l-output. Karatteristika li tibgħat kuntest twil biex tirċievi tliet kliem lura għandha profil ta’ spiża kompletament differenti minn abbozz twil iġġenerat minn prompt qasir. Il-kalkolu jieħu ftit linji biss:
# Hypothetical rates per million tokens (check current pricing)
RATE_INPUT = 2.0 # $/M tokens input
RATE_OUTPUT = 6.0 # $/M tokens output
cost_input = (usage.prompt_tokens / 1_000_000) * RATE_INPUT
cost_output = (usage.completion_tokens / 1_000_000) * RATE_OUTPUT
cost_total = cost_input + cost_output
print(f"Cost of this call: ${cost_total:.6f}")
Sejħa waħda tiswi frazzjoni ta’ ċenteżmu, li hija falzament rassiguranti. Immultiplika dan bit-traffiku reali ta’ applikazzjoni, u l-mistoqsija ssir: liema karatteristika tikkonsma x’biex? Biex twieġeb dan, aggrega metriċi ta’ użu mill-ewwel dispjegament tiegħek. Irreġistra kull sejħa flimkien mal-isem tal-karatteristika li ħarġitha:
import json
from datetime import datetime
def log_usage(response, endpoint_name: str):
"""Logs usage metrics for each API call."""
log_entry = {
"timestamp": datetime.utcnow().isoformat(),
"endpoint": endpoint_name,
"model": response.model,
"prompt_tokens": response.usage.prompt_tokens,
"completion_tokens": response.usage.completion_tokens,
"total_tokens": response.usage.total_tokens,
"finish_reason": response.choices[0].finish_reason,
"request_id": response.id
}
with open("api_usage.jsonl", "a") as f:
f.write(json.dumps(log_entry) + "\n")
# Usage
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Hello"}]
)
log_usage(response, "main_chatbot")
Fajl JSONL bħal dan, rivedut wara ġimagħtejn, jgħidlek mingħajr ambigwità liema skrin fil-prodott tiegħek jiżen l-aktar fuq il-kont—u kemm sejħa jispiċċaw b’length.
Kontenut tar-Risposta
Il-qasam content tal-messaġġ tal-assistent jista’ jieħu żewġ forom, eżattament bħal fuq in-naħa tat-talba:
# Simple form — string
content = response.choices[0].message.content
# "Machine learning is a branch of artificial intelligence..."
# Structured form — list of blocks (rare in standard chat)
# [{"type": "text", "text": "..."}]
Fil-prattika, għal sejħiet standard ta’ Chat Completions, content huwa dejjem stringa. Il-forma strutturata hija rriżervata għal risposti multimodali.
Poġġiha fil-Prattika
Ejja niġbru dan kollu f’funzjoni ta’ utilità—dik li se tikkopja minn proġett għal ieħor. Tgħaqqad il-messaġġi, tagħmel is-sejħa, u tirritorna dizzjunarju li jesponi kemm il-metriċi kif ukoll it-test:
from mistralai.client import Mistral
def chat_complete(
client: Mistral,
prompt: str,
system: str = "",
model: str = "mistral-large-latest",
max_tokens: int = 1000
) -> dict:
"""Chat Completions call with error handling and metrics."""
messages = []
if system:
messages.append({"role": "system", "content": system})
messages.append({"role": "user", "content": prompt})
response = client.chat.complete(
model=model,
messages=messages,
max_tokens=max_tokens
)
return {
"content": response.choices[0].message.content,
"finish_reason": response.choices[0].finish_reason,
"tokens_in": response.usage.prompt_tokens,
"tokens_out": response.usage.completion_tokens,
"model": response.model,
"id": response.id
}
Il-punt ewlieni huwa dak li tirritorna l-funzjoni: qatt biss it-test. Billi tgħolli finish_reason, il-għadd ta’ tokens, u l-ID tat-talba għal min sejjaħ, tagħmel l-iżball l-aktar komuni impossibbli—li tittratta risposta mqatgħa bħala waħda valida.
Punti Ewlenin
- Ir-risposta fiha
choices(kontenut),usage(tokens), u metadejta (id,model) - Dejjem iċċekkja
finish_reason—lengthtfisser risposta mhux kompluta usagejgħodd it-tokens tal-input u tal-output separatament għal traċċar preċiż tal-ispejjeż- Ippara logging tal-metriċi mill-ewwel dispjegament tal-produzzjoni tiegħek
- Il-qasam
idhuwa essenzjali għad-debugging u l-appoġġ tekniku