API Codestral în Python
Pe această pagină
Apelarea Codestral din Python
Această lecție trece de la teorie la cod executabil. Veți utiliza SDK-ul Python Mistral AI pentru a interoga Codestral pe cele două endpoint-uri ale sale, pentru a ajusta parametrii avansați care fac diferența dintre o sugestie utilă și una verbose și pentru a implementa tiparele întâlnite în majoritatea integrărilor din lumea reală.
Instalare și configurare
Instalați SDK-ul cu o singură comandă:
pip install mistralai
Recuperați cheia API de pe console.mistral.ai și citiți-o din variabilele de mediu, în loc să o codificați direct în fișier:
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Două platforme deservesc Codestral, iar dumneavoastră alegeți între ele la crearea cheii. api.mistral.ai funcționează pe baza unui sistem pay-per-use cu facturare în funcție de utilizare: aceasta este calea standard atunci când Codestral este doar o componentă printre altele într-o aplicație. codestral.mistral.ai este un endpoint dedicat, accesibil gratuit sau prin abonament, conceput pentru utilizarea directă de către un dezvoltator în interiorul editorului său.
Apel FIM complet
Iată un apel FIM detaliat cu toți parametrii importanți:
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)
Analiza răspunsului
Obiectul returnat conține mai mult decât textul generat. În producție, ar trebui să verificați sistematic trei elemente: completarea în sine, consumul de tokeni care determină factura și motivul opririi, care vă indică dacă modelul s-a oprit natural sau a atins limita impusă.
# Accesarea completării generate
text = response.choices[0].message.content
# Verificarea numărului de tokeni utilizați
tokens_prompt = response.usage.prompt_tokens
tokens_completion = response.usage.completion_tokens
tokens_total = response.usage.total_tokens
# Verificarea motivului opririi
reason = response.choices[0].finish_reason # "stop", "length", etc.
Un finish_reason de tip "length" la jumătate din apeluri este un semnal clar: max_tokens este prea mic și livrați cod trunchiat utilizatorilor dumneavoastră.
Apel Chat pentru generare de cod
Ori de câte ori nu există un cursor în mijlocul unui fișier — cum ar fi în cazul generării complete, al explicațiilor sau al refactorizării — endpoint-ul chat preia controlul. Mesajul de sistem încadrează apoi formatul de ieșire, ceea ce evită necesitatea curățării răspunsului ulterior:
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)
Parametri avansați
Perechea min_tokens / max_tokens încadrează lungimea ieșirii. Pragul inferior este util atunci când generați un bloc despre care știți că nu poate fi mai scurt decât un anumit volum, cum ar fi o funcție cu gestionarea erorilor sale.
# min_tokens: forțează o lungime minimă a ieșirii
# max_tokens: limitează lungimea maximă
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
min_tokens=20,
max_tokens=300,
)
Tokenii de oprire joacă un rol diferit: ei opresc generarea la un anumit model, menținând completarea în cadrul funcției curente, în loc să permită modelului să lanseze următoarea funcție.
# Oprirea generării la modele specifice
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
stop=["\n\n", "\nclass ", "\ndef "], # Oprire înainte de o nouă funcție/clasă
)
În final, temperatura guvernează variabilitatea. La 0, aceeași intrare produce întotdeauna aceeași ieșire, ceea ce este necesar pentru auto-completare. În jurul valorii de 0.3, modelul propune variante, ceea ce este interesant atunci când afișați mai multe sugestii. La 0.7, intrați în modul de brainstorming pentru cod, util pentru explorarea unei abordări, dar nepotrivit pentru un flux de editare.
# temperature=0: determinist (auto-completare)
# temperature=0.3: ușor creativ (mai multe sugestii)
# temperature=0.7: creativ (brainstorming cod)
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
temperature=0.3,
top_p=0.95,
)
Două tipare de copiat și lipit
Primul reproduce comportamentul IDE: divizați conținutul fișierului la poziția cursorului, iar cele două jumătăți devin prompt și suffix.
def autocomplete_ide(file_content: str, cursor_position: int) -> str:
"""Simulează auto-completarea IDE cu 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
Al doilea automatizează documentarea pentru un proiect existent: transmiteți o funcție, recuperați docstring-ul său, iar instrucțiunea de sistem impune un format unic, astfel încât rezultatul să poată fi inserat fără editări suplimentare.
def generate_docstring(function_code: str) -> str:
"""Generează un docstring pentru o funcție 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
Gestionarea erorilor
Un apel de rețea va eșua mai devreme sau mai târziu, iar o extensie de editor care se blochează la o eroare de validare este mai rea decât o extensie fără completare. Prin urmare, încadrați întotdeauna apelurile dumneavoastră:
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}")
Puncte cheie
- SDK-ul
mistralaiexpuneclient.fim.complete()pentru FIM șiclient.chat.complete()pentru chat - Parametrii
promptșisuffixsunt specifici endpoint-ului FIM - Utilizați
temperature=0pentru auto-completare și0.2-0.7pentru generare creativă stoplimitează generarea la un bloc de cod coerentmin_tokensșimax_tokenscontrolează lungimea ieșirii- Gestionați întotdeauna erorile HTTP în codul de producție