Codestral API Pythonban
Ezen az oldalon
A Codestral meghívása Pythonból
Ebben a leckében az elmélettől a futtatható kód felé lépünk. Használni fogod a Mistral AI Python SDK-t a Codestral két végpontjának lekérdezésére, hangolni fogod azokat a haladó paramétereket, amelyek megkülönböztetik a hasznos javaslatot a bőbeszédűtől, és megvalósítod a legtöbb valós integrációban előforduló mintázatokat.
Telepítés és konfiguráció
Telepítsd az SDK-t egyetlen paranccsal:
pip install mistralai
Szerezd be az API-kulcsodat a console.mistral.ai oldalról, és olvasd be a környezeti változókból, ahelyett, hogy közvetlenül a fájlba írnád:
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Két platform szolgálja ki a Codestralt, és ezek között a kulcs létrehozásakor választhatsz. Az api.mistral.ai használat alapú számlázással működik (pay-per-use): ez a szabványos út, ha a Codestral csak egy komponens a sok közül egy alkalmazásban. A codestral.mistral.ai egy dedikált végpont, amely ingyenesen vagy előfizetéssel érhető el, kifejezetten fejlesztők közvetlen használatára tervezték a szerkesztőjükön belül.
Teljes FIM hívás
Íme egy részletes FIM hívás az összes fontos paraméterrel:
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)
A válasz elemzése
A visszaadott objektum többet tartalmaz, mint csak a generált szöveget. Éles környezetben rendszeresen ellenőrizned kell három információt: magát a kiegészítést, a számládat meghatározó tokenfelhasználást és a leállási okot (stop reason), amely jelzi, hogy a modell természetesen fejezte-e be a generálást, vagy elérte-e a limitet.
# A generált kiegészítés elérése
text = response.choices[0].message.content
# A felhasznált tokenek számának ellenőrzése
tokens_prompt = response.usage.prompt_tokens
tokens_completion = response.usage.completion_tokens
tokens_total = response.usage.total_tokens
# A leállási ok ellenőrzése
reason = response.choices[0].finish_reason # "stop", "length", stb.
Ha a hívásaid felénél a finish_reason értéke "length", az egyértelmű jelzés: a max_tokens értéke túl alacsony, és csonka kódot szállítasz a felhasználóidnak.
Chat hívás kódgeneráláshoz
Valahányszor nincs kurzor a fájl közepén – például teljes generálás, magyarázat vagy refaktorálás esetén –, a chat végpont veszi át az irányítást. A rendszerüzenet (system message) ekkor keretezi a kimeneti formátumot, ami elkerülhetővé teszi a válasz utólagos tisztítását:
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)
Haladó paraméterek
A min_tokens / max_tokens pár keretezi a kimenet hosszát. Az alsó korlát (floor) akkor hasznos, ha olyan blokkot generálsz, amelyről tudod, hogy nem lehet rövidebb egy bizonyos volumennél, például egy függvény a hibakezelésével együtt.
# min_tokens: minimális kimeneti hosszt kényszerít ki
# max_tokens: korlátozza a maximális hosszt
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
min_tokens=20,
max_tokens=300,
)
A leállító tokenek (stop tokens) más szerepet játszanak: egy adott mintázatnál állítják le a generálást, így a kiegészítés a jelenlegi függvény keretein belül marad, ahelyett, hogy a modell átlépne a következőbe.
# Generálás leállítása specifikus mintázatoknál
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
stop=["\n\n", "\nclass ", "\ndef "], # Leállítás egy új függvény/osztály előtt
)
Végül a hőmérséklet (temperature) szabályozza a változékonyságot. 0 értéknél ugyanaz a bemenet mindig ugyanazt a kimenetet eredményezi, ami az automatikus kiegészítéshez szükséges. Körülbelül 0,3 értéknél a modell variánsokat javasol, ami akkor érdekes, ha több javaslatot jelenítesz meg. 0,7 értéknél kódötletelési módban vagy, ami hasznos egy megközelítés felderítésére, de szerkesztési folyamatba nem illik.
# temperature=0: determinisztikus (automatikus kiegészítés)
# temperature=0.3: enyhén kreatív (több javaslat)
# temperature=0.7: kreatív (kódötletelés)
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
temperature=0.3,
top_p=0.95,
)
Két másolható-beilleszthető minta
Az első az IDE viselkedését reprodukálja: a fájl tartalmát a kurzor pozíciójánál kettéválasztod, és a két fél lesz a prompt és a suffix.
def autocomplete_ide(file_content: str, cursor_position: int) -> str:
"""Szimulálja az IDE automatikus kiegészítését a Codestral FIM segítségével."""
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
A második egy meglévő projekt dokumentációjának automatizálása: átadsz egy függvényt, lekérdezed a docstringjét, és a rendszerutasítás egyetlen formátumot kényszerít ki, így az eredmény további szerkesztés nélkül beszúrható.
def generate_docstring(function_code: str) -> str:
"""Docstringet generál egy Python függvényhez."""
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
Hibakezelés
Egy hálózati hívás előbb-utóbb sikertelen lesz, és egy olyan szerkesztőbővítmény, amely érvényesítési hiba miatt összeomlik, rosszabb, mint egy olyan, amelyben nincs kiegészítés. Ezért mindig burkold be a hívásaidat:
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"Érvényesítési hiba: {e}")
except Exception as e:
print(f"Váratlan hiba: {e}")
Főbb megállapítások
- A
mistralaiSDK biztosítja aclient.fim.complete()függvényt a FIM-hez és aclient.chat.complete()függvényt a chathez - A
promptéssuffixparaméterek kifejezetten a FIM végpontra jellemzőek - Használj
temperature=0értéket az automatikus kiegészítéshez,0,2-0,7közöttit a kreatív generáláshoz - A
stopparaméter egy koherens kódblokkra korlátozza a generálást - A
min_tokensésmax_tokensparaméterek szabályozzák a kimenet hosszát - Éles kódban mindig kezeld a HTTP hibákat