Απόκριση και Χρήση
Σε αυτήν τη σελίδα
Κατανοήστε Τι Επιστρέφει το API
Οι περισσότεροι προγραμματιστές που ξεκινούν με το API διαβάζουν μόνο μία γραμμή της απόκρισης—το παραγόμενο κείμενο—και αγνοούν τα υπόλοιπα. Αυτό είναι λάθος. Κάθε κλήση στο /v1/chat/completions επιστρέφει ένα πλούσιο αντικείμενο JSON. Εδώ θα βρείτε τα δεδομένα που χρειάζεστε για να παρακολουθείτε το κόστος, να εντοπίζετε μια αποκομμένη απόκριση πριν φτάσει στον χρήστη και να προσδιορίζετε μια συγκεκριμένη κλήση όταν ανοίγετε ένα αίτημα υποστήριξης.
Πλήρης Ανατομία της Απόκρισης
Ας ξεκινήσουμε με τα μεταδεδομένα. Αυτά είναι τα πεδία που σπάνια ελέγχετε, αλλά θα ευχόσασταν να είχατε καταγράψει την ημέρα που συμβαίνει ένα περιστατικό:
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}")
Το πεδίο id είναι ένα μοναδικό αναγνωριστικό που εκχωρείται σε κάθε αίτημα. Αυτή είναι η αναφορά που θα παρέχετε στην τεχνική υποστήριξη και αυτή που σας επιτρέπει να συνδέσετε ένα παράπονο χρήστη με μια συγκεκριμένη κλήση στα αρχεία καταγραφής σας. Το πεδίο model επιβεβαιώνει ποιο μοντέλο χρησιμοποιήθηκε πραγματικά. Αυτό έχει μεγαλύτερη σημασία από ό,τι νομίζετε όταν καλείτε ένα ψευδώνυμο -latest και η συμπεριφορά αλλάζει μέσα σε μια νύχτα χωρίς καμία αλλαγή κώδικα από την πλευρά σας.
Ο Πίνακας choices
Η καρδιά της απόκρισης βρίσκεται στο choices. Από προεπιλογή, αυτός ο πίνακας περιέχει ένα μόνο στοιχείο. Από αυτό εξάγετε τόσο το κείμενο όσο και την ετυμηγορία για το πώς ολοκληρώθηκε η παραγωγή:
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"
Εάν ζητήσετε πολλαπλές αποκρίσεις χρησιμοποιώντας την παράμετρο n, την οποία θα καλύψουμε στο μάθημα 15, το choices θα περιέχει πολλαπλά στοιχεία και το ευρετήριο θα αποκτήσει ξανά νόημα.
Τιμές του finish_reason
Αυτό το πεδίο καθορίζει την αξιοπιστία της εφαρμογής σας. Υπάρχουν τρεις πιθανές τιμές. Το stop σηματοδοτεί ότι το μοντέλο ολοκλήρωσε την απόκρισή του φυσικά. Αυτή είναι η κανονική περίπτωση, όπου μπορείτε να εμφανίσετε το περιεχόμενο χωρίς επιφυλάξεις. Το length σημαίνει ότι η παραγωγή διακόπηκε λόγω του max_tokens, οπότε η απόκριση είναι ενδεχομένως ημιτελής—μια περίληψη χωρίς συμπέρασμα ή μια λίστα που σταματά στο έβδομο στοιχείο. Τέλος, το tool_calls υποδεικνύει ότι το μοντέλο ζητά την εκτέλεση ενός εξωτερικού εργαλείου ως μέρος της κλήσης συνάρτησης και τώρα η μπάλα βρίσκεται στο γήπεδό σας.
Κάθε μία από αυτές τις περιπτώσεις απαιτεί ξεχωριστό χειρισμό, τον οποίο πρέπει να γράψετε μια και καλή:
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}")
Παρατηρήστε ότι ο κλάδος length δεν αφήνει απλώς το κείμενο να περάσει. Είτε κάνετε επανάληψη με υψηλότερο όριο, ζητάτε από το μοντέλο να συνεχίσει, είτε προειδοποιείτε τον χρήστη. Αυτό που δεν πρέπει ποτέ να κάνετε είναι να εμφανίζετε αποκομμένο κείμενο σαν να ήταν ολοκληρωμένο.
Το Αντικείμενο usage — Παρακολουθήστε το Κόστος Σας
Το πεδίο usage μετρά τα tokens που καταναλώθηκαν από το αίτημα, διαχωρίζοντας την είσοδο από την έξοδο:
usage = response.usage
print(f"Input tokens : {usage.prompt_tokens}")
print(f"Output tokens : {usage.completion_tokens}")
print(f"Total : {usage.total_tokens}")
Αυτή η διάκριση δεν είναι καλλωπιστική. Τα μοντέλα Mistral έχουν διαφορετικές χρεώσεις για είσοδο και έξοδο. Μια λειτουργία που στέλνει ένα μεγάλο πλαίσιο συμφραζομένων για να λάβει τρεις λέξεις πίσω έχει εντελώς διαφορετικό προφίλ κόστους από ένα μεγάλο προσχέδιο που παράγεται από μια σύντομη προτροπή. Ο υπολογισμός απαιτεί μόνο λίγες γραμμές:
# 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}")
Μια μεμονωμένη κλήση κοστίζει ένα κλάσμα του σεντ, κάτι που είναι ψευδώς καθησυχαστικό. Πολλαπλασιάστε το με την πραγματική κίνηση μιας εφαρμογής και το ερώτημα γίνεται: ποια λειτουργία καταναλώνει τι; Για να απαντήσετε σε αυτό, συγκεντρώστε μετρικές χρήσης από την πρώτη σας ανάπτυξη. Καταγράψτε κάθε κλήση μαζί με το όνομα της λειτουργίας που την προκάλεσε:
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")
Ένα αρχείο JSONL όπως αυτό, αν αναθεωρηθεί μετά από δύο εβδομάδες, θα σας πει χωρίς ασάφεια ποια οθόνη στο προϊόν σας επιβαρύνει περισσότερο τον λογαριασμό—και πόσες κλήσεις τελειώνουν με length.
Περιεχόμενο Απόκρισης
Το πεδίο content του μηνύματος του βοηθού μπορεί να λάβει δύο μορφές, ακριβώς όπως στην πλευρά του αιτήματος:
# 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": "..."}]
Στην πράξη, για τυπικές κλήσεις Chat Completions, το content είναι πάντα μια συμβολοσειρά. Η δομημένη μορφή προορίζεται για πολυτροπικές αποκρίσεις.
Εφαρμογή στην Πράξη
Ας τα συνδυάσουμε όλα αυτά σε μια συνάρτηση χρησιμότητας—αυτήν που θα αντιγράφετε από έργο σε έργο. Συνθέτει τα μηνύματα, πραγματοποιεί την κλήση και επιστρέφει ένα λεξικό που εκθέτει τόσο τις μετρικές όσο και το κείμενο:
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
}
Το βασικό σημείο είναι τι επιστρέφει η συνάρτηση: ποτέ μόνο το κείμενο. Αναβιβάζοντας το finish_reason, τους αριθμούς tokens και το αναγνωριστικό αιτήματος στον καλούντα, καθιστάτε το πιο κοινό σφάλμα αδύνατο—την αντιμετώπιση μιας αποκομμένης απόκρισης ως έγκυρης.
Βασικά σημεία
- Η απόκριση περιέχει
choices(περιεχόμενο),usage(tokens) και μεταδεδομένα (id,model) - Πάντα να ελέγχετε το
finish_reason— τοlengthσημαίνει ημιτελή απόκριση - Το
usageμετρά ξεχωριστά τα tokens εισόδου και εξόδου για ακριβή παρακολούθηση κόστους - Ρυθμίστε την καταγραφή μετρικών από την πρώτη σας ανάπτυξη σε παραγωγή
- Το πεδίο
idείναι απαραίτητο για την αποσφαλμάτωση και την τεχνική υποστήριξη