API Codestral v Pythonu
Na tej strani
Klicanje Codestrala iz Pythona
V tej lekciji preideš od teorije k izvršljivi kodi. Uporabil boš Python SDK Mistral AI za poizvedbe pri Codestralu na njegovih dveh končnih točkah, prilagodil napredne parametre, ki ločijo uporaben predlog od preveč zgovornega, in implementiral vzorce, ki jih najdeš v večini integracij v realnem svetu.
Namestitev in konfiguracija
SDK namestiš z enim samim ukazom:
pip install mistralai
Svoj API ključ pridobiš na console.mistral.ai in ga prebereš iz okolja, namesto da bi ga trdo kodiral v svojo datoteko:
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Codestral strežeta dve platformi, med katerima izbereš ob ustvarjanju ključa. api.mistral.ai deluje na podlagi plačila po uporabi z obračunom glede na porabo: to je standardna pot, ko je Codestral ena od komponent v aplikaciji. codestral.mistral.ai je namenska končna točka, dostopna brezplačno ali prek naročnine, zasnovana za neposredno uporabo s strani razvijalca znotraj njihovega urejevalnika.
Popoln klic FIM
Tukaj je podroben klic FIM z vsemi pomembnimi parametri:
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)
Razčlenitev odgovora
Vrnjeni objekt vsebuje več kot le generirano besedilo. V proizvodnem okolju moraš sistematično preveriti tri dele informacij: samo dokončanje, porabo žetonov, ki določa tvoj račun, in razlog zaustavitve, ki ti pove, ali se je model naravno zaključil ali dosegel tvojo omejitev.
# Dostop do generiranega dokončanja
text = response.choices[0].message.content
# Preveri število uporabljenih žetonov
tokens_prompt = response.usage.prompt_tokens
tokens_completion = response.usage.completion_tokens
tokens_total = response.usage.total_tokens
# Preveri razlog zaustavitve
reason = response.choices[0].finish_reason # "stop", "length", itd.
Če je finish_reason enak "length" pri polovici tvojih klicev, je to jasen signal: tvoj max_tokens je prenizek in uporabnikom dostavljaš okrnjeno kodo.
Klic klepeta za generiranje kode
Kadar ni kazalke sredi datoteke – na primer pri popolnem generiranju, razlagi ali refaktoriranju – prevzame končna točka za klepet. Sistemska sporočila takrat določijo format izhoda, kar odpravi potrebo po naknadnem čiščenju odgovora:
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)
Napredni parametri
Par min_tokens / max_tokens določa dolžino izhoda. Spodnja meja je uporabna pri generiranju bloka, za katerega veš, da ne more biti krajši od določene prostornine, na primer funkcije z obravnavo napak.
# min_tokens: vsili najmanjšo dolžino izhoda
# max_tokens: omeji največjo dolžino
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
min_tokens=20,
max_tokens=300,
)
Žetoni za zaustavitev igrajo drugačno vlogo: generiranje ustavijo ob določenem vzorcu in tako ohranijo dokončanje znotraj okvira trenutne funkcije, namesto da bi modelu dovolili veriženje v naslednjo.
# Zaustavi generiranje ob določenih vzorcih
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
stop=["\n\n", "\nclass ", "\ndef "], # Zaustavi pred novo funkcijo/razredom
)
Temperatura nazadnje ureja variabilnost. Pri 0 isti vhod vedno da isti izhod, kar samodejno dokončevanje zahteva. Okoli 0.3 model predlaga variante, kar je zanimivo pri prikazu več predlogov. Pri 0.7 si v načinu možganske nevihte za kodo, kar je uporabno za raziskovanje pristopa, a neprimerno za tok urejanja.
# temperature=0: deterministično (samodejno dokončevanje)
# temperature=0.3: rahlo kreativno (več predlogov)
# temperature=0.7: kreativno (možganska nevihta za kodo)
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
temperature=0.3,
top_p=0.95,
)
Dva vzorca za kopiranje in lepljenje
Prvi reproducira vedenje IDE: vsebino datoteke razdeliš na položaju kazalke, obe polovici pa postaneta prompt in suffix.
def autocomplete_ide(file_content: str, cursor_position: int) -> str:
"""Simulira samodejno dokončevanje IDE s 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
Drugi avtomatizira dokumentacijo za obstoječi projekt: posreduješ funkcijo, pridobiš njen docstring, sistemska navodila pa uveljavijo enoten format, tako da se rezultat vstavi brez nadaljnjega urejanja.
def generate_docstring(function_code: str) -> str:
"""Generira docstring za funkcijo 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
Obravnava napak
Omrežni klic bo prej ali slej spodletel in razširitev urejevalnika, ki se zruši pri napaki validacije, je slabša od razširitve brez dokončanja. Zato svoje klice vedno ovij:
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}")
Ključne ugotovitve
- SDK
mistralaiizpostavljaclient.fim.complete()za FIM inclient.chat.complete()za klepet - Parametra
promptinsuffixsta specifična za končno točko FIM - Uporabi
temperature=0za samodejno dokončevanje,0.2-0.7za kreativno generiranje stopomeji generiranje na koherenten blok kodemin_tokensinmax_tokensnadzirata dolžino izhoda- V proizvodni kodi vedno obravnavaj napake HTTP