Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Risposta u Użu

Lezzjoni 4 / 16 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Ifhem x’tirritorna l-API
  2. L-Anatomija Sħiħa tar-Risposta
  3. L-Array choices
  4. Valuri ta’ finish_reason
  5. L-Oġġett usage — Segwi l-Ispejjeż Tiegħek
  6. Kontenut tar-Risposta
  7. Poġġiha fil-Prattika
  8. Punti Ewlenin

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 — length tfisser risposta mhux kompluta
  • usage jgħ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 id huwa essenzjali għad-debugging u l-appoġġ tekniku