Codestral API σε Python
Σε αυτήν τη σελίδα
Κλήση του Codestral από Python
Αυτό το μάθημα μεταβαίνει από τη θεωρία στον εκτελέσιμο κώδικα. Θα χρησιμοποιήσετε το Python SDK της Mistral AI για να κάνετε ερωτήματα στο Codestral στα δύο σημεία τελικού χρήστη (endpoints) του, θα ρυθμίσετε τις προηγμένες παραμέτρους που διαχωρίζουν μια χρήσιμη πρόταση από μια φλύαρη και θα υλοποιήσετε τα πρότυπα που συναντώνται στις περισσότερες ενσωματώσεις στον πραγματικό κόσμο.
Εγκατάσταση και διαμόρφωση
Εγκαταστήστε το SDK με μία μόνο εντολή:
pip install mistralai
Ανακτήστε το κλειδί API σας από το console.mistral.ai και διαβάστε το από το περιβάλλον συστήματος αντί να το κωδικοποιήσετε απευθείας στο αρχείο σας:
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Δύο πλατφόρμες εξυπηρετούν το Codestral και επιλέγετε ανάμεσά τους κατά τη δημιουργία του κλειδιού σας. Το api.mistral.ai λειτουργεί με βάση τη χρέωση ανά χρήση (pay-per-use): αυτή είναι η τυπική διαδρομή όταν το Codestral αποτελεί ένα μόνο συστατικό μεταξύ πολλών σε μια εφαρμογή. Το codestral.mistral.ai είναι ένα αφιερωμένο σημείο τελικού χρήστη, προσβάσιμο δωρεάν ή μέσω συνδρομής, σχεδιασμένο για άμεση χρήση από έναν προγραμματιστή μέσα στον επεξεργαστή κώδικά του.
Πλήρης κλήση FIM
Ακολουθεί μια λεπτομερής κλήση FIM με όλες τις σημαντικές παραμέτρους:
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
response = client.fim.complete(
model="codestral-latest",
prompt="def calculate_vat(price_excl: float, rate: float = 0.20) -> float:",
suffix="price = float(input('Price excl. VAT: '))\nprint(f'Price incl. VAT: {calculate_vat(price):.2f} EUR')",
temperature=0,
max_tokens=150,
stop=["\n\n"],
)
completion = response.choices[0].message.content
print(completion)
Ανάλυση της απόκρισης
Το αντικείμενο που επιστρέφεται περιέχει περισσότερα από απλώς το παραγόμενο κείμενο. Σε περιβάλλον παραγωγής, πρέπει να ελέγχετε συστηματικά τρία στοιχεία: την ίδια την ολοκλήρωση, την κατανάλωση tokens που καθορίζει τον λογαριασμό σας και τον λόγο διακοπής, ο οποίος σας ενημερώνει εάν το μοντέλο ολοκλήρωσε φυσικά τη διαδικασία ή αν έφτασε στο όριό σας.
# Πρόσβαση στην παραγόμενη ολοκλήρωση
text = response.choices[0].message.content
# Έλεγχος του αριθμού των tokens που χρησιμοποιήθηκαν
tokens_prompt = response.usage.prompt_tokens
tokens_completion = response.usage.completion_tokens
tokens_total = response.usage.total_tokens
# Έλεγχος του λόγου διακοπής
reason = response.choices[0].finish_reason # "stop", "length", κ.λπ.
Ένα finish_reason με τιμή "length" στις μισές κλήσεις σας είναι ένα σαφές σήμα: το max_tokens σας είναι πολύ χαμηλό και παραδίδετε κωδικοποιημένο κώδικα κομμένο στους χρήστες σας.
Κλήση Chat για παραγωγή κώδικα
Όποτε δεν υπάρχει δρομέας στη μέση ενός αρχείου—όπως συμβαίνει στην πλήρη παραγωγή, την εξήγηση ή την αναδιάρθρωση κώδικα—αναλαμβάνει το σημείο τελικού χρήστη chat. Το μήνυμα συστήματος ορίζει τότε τη μορφή εξόδου, αποφεύγοντας την ανάγκη καθαρισμού της απόκρισης εκ των υστέρων:
response = client.chat.complete(
model="codestral-latest",
messages=[
{
"role": "system",
"content": "You are an expert Python development assistant. Respond with code only, no explanations."
},
{
"role": "user",
"content": "Write a Python function that validates an email address using regex."
}
],
temperature=0.2,
max_tokens=500,
)
code = response.choices[0].message.content
print(code)
Προηγμένες παράμετροι
Το ζεύγος min_tokens / max_tokens ορίζει το μήκος της εξόδου. Το κατώτατο όριο είναι χρήσιμο όταν παράγετε ένα μπλοκ που γνωρίζετε ότι δεν μπορεί να είναι μικρότερο από έναν συγκεκριμένο όγκο, όπως μια συνάρτηση με τον χειρισμό σφαλμάτων της.
# min_tokens: επιβάλλει ένα ελάχιστο μήκος εξόδου
# max_tokens: περιορίζει το μέγιστο μήκος
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
min_tokens=20,
max_tokens=300,
)
Τα tokens διακοπής παίζουν διαφορετικό ρόλο: σταματούν τη δημιουργία σε ένα συγκεκριμένο μοτίβο, διατηρώντας την ολοκλήρωση εντός του πεδίου της τρέχουσας συνάρτησης αντί να επιτρέπουν στο μοντέλο να συνεχίσει στην επόμενη.
# Διακοπή δημιουργίας σε συγκεκριμένα μοτίβα
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
stop=["\n\n", "\nclass ", "\ndef "], # Διακοπή πριν από νέα συνάρτηση/κλάση
)
Τέλος, η θερμοκρασία (temperature) διέπει τη μεταβλητότητα. Στο 0, η ίδια είσοδος αποδίδει πάντα την ίδια έξοδο, κάτι που απαιτεί η αυτόματη ολοκλήρωση. Γύρω στο 0.3, το μοντέλο προτείνει παραλλαγές, γεγονός που είναι ενδιαφέρον όταν εμφανίζετε πολλαπλές προτάσεις. Στο 0.7, βρίσκεστε σε λειτουργία καταιγισμού ιδεών για κώδικα, χρήσιμη για την εξερεύνηση μιας προσέγγισης αλλά ακατάλληλη για ροή επεξεργασίας.
# temperature=0: ντετερμινιστική (αυτόματη ολοκλήρωση)
# temperature=0.3: ελαφρώς δημιουργική (πολλαπλές προτάσεις)
# temperature=0.7: δημιουργική (καταιγισμός ιδεών κώδικα)
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
temperature=0.3,
top_p=0.95,
)
Δύο πρότυπα για αντιγραφή-επικόλληση
Το πρώτο αναπαράγει τη συμπεριφορά ενός IDE: διαιρείτε το περιεχόμενο του αρχείου στη θέση του δρομέα και τα δύο μισά γίνονται το prompt και το suffix.
def autocomplete_ide(file_content: str, cursor_position: int) -> str:
"""Προσομοιώνει την αυτόματη ολοκλήρωση IDE με το Codestral FIM."""
prompt = file_content[:cursor_position]
suffix = file_content[cursor_position:]
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
temperature=0,
max_tokens=100,
stop=["\n\n", "\ndef ", "\nclass "],
)
return response.choices[0].message.content
Το δεύτερο αυτοματοποιεί την τεκμηρίωση για ένα υπάρχον έργο: περνάτε μια συνάρτηση, ανακτάτε το docstring της και η οδηγία συστήματος επιβάλλει μια ενιαία μορφή, ώστε το αποτέλεσμα να εισάγεται χωρίς περαιτέρω επεξεργασία.
def generate_docstring(function_code: str) -> str:
"""Δημιουργεί ένα docstring για μια συνάρτηση Python."""
response = client.chat.complete(
model="codestral-latest",
messages=[
{
"role": "system",
"content": "Generate a Google-style docstring for the following function. Return ONLY the docstring between triple quotes."
},
{
"role": "user",
"content": function_code
}
],
temperature=0,
max_tokens=300,
)
return response.choices[0].message.content
Διαχείριση σφαλμάτων
Μια κλήση δικτύου θα αποτύχει αργά ή γρήγορα και μια επέκταση επεξεργαστή που καταρρέει σε σφάλμα επικύρωσης είναι χειρότερη από μια επέκταση χωρίς ολοκλήρωση. Επομένως, τυλίγετε πάντα τις κλήσεις σας:
from mistralai.client import Mistral
from mistralai.client.errors import HTTPValidationError
try:
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
)
except HTTPValidationError as e:
print(f"Validation error: {e}")
except Exception as e:
print(f"Unexpected error: {e}")
Βασικά σημεία
- Το SDK
mistralaiεκθέτει τοclient.fim.complete()για FIM και τοclient.chat.complete()για chat - Οι παράμετροι
promptκαιsuffixείναι συγκεκριμένες για το σημείο τελικού χρήστη FIM - Χρησιμοποιήστε
temperature=0για αυτόματη ολοκλήρωση και0.2-0.7για δημιουργική παραγωγή - Το
stopπεριορίζει τη δημιουργία σε ένα συνεκτικό μπλοκ κώδικα - Τα
min_tokensκαιmax_tokensελέγχουν το μήκος της εξόδου - Να χειρίζεστε πάντα τα σφάλματα HTTP στον κώδικα παραγωγής