API Codestral v Pythone
Na tejto strane
Volanie Codestral z Pythonu
Táto lekcia prechádza od teórie k spustiteľnému kódu. Použiješ Python SDK od Mistral AI na dopytovanie modelu Codestral cez jeho dva koncové body, doladíš pokročilé parametre, ktoré oddeľujú užitočný návrh od ukecaného, a implementuješ vzory bežné vo väčšine integrácií v reálnom svete.
Inštalácia a konfigurácia
Nainštaluj SDK jediným príkazom:
pip install mistralai
Získaj svoj API kľúč z console.mistral.ai a načítaj ho z prostredia namiesto toho, aby si ho natvrdo zakódoval priamo do súboru:
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Codestral obsluhujú dve platformy a medzi nimi si vyberáš pri vytváraní kľúča. api.mistral.ai funguje na báze platby za využitie s fakturáciou podľa spotreby: toto je štandardná cesta, keď je Codestral jednou zo zložiek aplikácie. codestral.mistral.ai je vyhradený koncový bod, dostupný zadarmo alebo cez predplatné, určený na priame použitie vývojárom v jeho editore.
Kompletné volanie FIM
Tu je podrobné volanie FIM so všetkými dôležitými parametrami:
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)
Rozbor odpovede
Vrátený objekt obsahuje viac než len vygenerovaný text. V produkčnom prostredí by si mal systematicky kontrolovať tri informácie: samotné doplnenie, spotrebu tokenov, ktorá určuje tvoju faktúru, a dôvod zastavenia, ktorý ti povie, či model skončil prirodzene, alebo narazil na tvoj limit.
# Prístup k vygenerovanému doplneniu
text = response.choices[0].message.content
# Kontrola počtu použitých tokenov
tokens_prompt = response.usage.prompt_tokens
tokens_completion = response.usage.completion_tokens
tokens_total = response.usage.total_tokens
# Kontrola dôvodu zastavenia
reason = response.choices[0].finish_reason # "stop", "length", atď.
Hodnota finish_reason rovnajúca sa "length" pri polovici tvojich volaní je jasným signálom: tvoje max_tokens je príliš nízke a používateľom doručuješ orezaný kód.
Volanie chatu na generovanie kódu
Vždy, keď nie je kurzor uprostred súboru – napríklad pri úplnom generovaní, vysvetľovaní alebo refaktoringu – preberá vedenie koncový bod chatu. Systémová správa potom rámec formát výstupu, čo eliminuje potrebu následného čistenia odpovede:
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)
Pokročilé parametre
Dvojica parametrov min_tokens / max_tokens ohraničuje dĺžku výstupu. Spodná hranica je užitočná pri generovaní bloku, o ktorom vieš, že nemôže byť kratší než určitý objem, napríklad funkcia s obsluhou chýb.
# min_tokens: vynúti minimálnu dĺžku výstupu
# max_tokens: obmedzí maximálnu dĺžku
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
min_tokens=20,
max_tokens=300,
)
Tokeny zastavenia (stop tokens) zohrávajú inú úlohu: zastavia generovanie na konkrétnom vzore, čím udržia doplnenie v rámci aktuálnej funkcie namiesto toho, aby model prešiel do ďalšej.
# Zastavenie generovania na špecifických vzoroch
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
stop=["\n\n", "\nclass ", "\ndef "], # Zastaviť pred novou funkciou/triedou
)
Nakoniec, teplota riadi variabilitu. Pri hodnote 0 vždy rovnaký vstup prináša rovnaký výstup, čo automatické dopĺňanie vyžaduje. Okolo hodnoty 0.3 model navrhuje varianty, čo je zaujímavé pri zobrazovaní viacerých návrhov. Pri hodnote 0.7 si v režime brainstormingu kódu, čo je užitočné na preskúmavanie prístupu, ale nevhodné pre editačný tok.
# temperature=0: deterministické (automatické dopĺňanie)
# temperature=0.3: mierne kreatívne (viacero návrhov)
# temperature=0.7: kreatívne (brainstorming kódu)
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
temperature=0.3,
top_p=0.95,
)
Dva vzory na kopírovanie
Prvý reprodukuje správanie IDE: rozdelíš obsah súboru na pozícii kurzora a tieto dve časti sa stanú promptom a suffixom.
def autocomplete_ide(file_content: str, cursor_position: int) -> str:
"""Simuluje automatické dopĺňanie v IDE pomocou 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
Druhý automatizuje dokumentáciu pre existujúci projekt: odovzdáš funkciu, získaš jej docstring a systémová inštrukcia vynúti jediný formát, aby sa výsledok vložil bez ďalších úprav.
def generate_docstring(function_code: str) -> str:
"""Generuje docstring pre Python funkciu."""
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
Obsluha chýb
Sieťové volanie skôr či neskôr zlyhá a rozšírenie editora, ktoré spadne pri chybe overenia, je horšie než rozšírenie bez dopĺňania. Preto vždy obaľuj svoje volania:
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"Chyba overenia: {e}")
except Exception as e:
print(f"Neočakávaná chyba: {e}")
Kľúčové poznatky
- SDK
mistralaiposkytujeclient.fim.complete()pre FIM aclient.chat.complete()pre chat - Parametre
promptasuffixsú špecifické pre koncový bod FIM - Použi
temperature=0pre automatické dopĺňanie,0.2-0.7pre kreatívne generovanie stopobmedzuje generovanie na súvislý blok kódumin_tokensamax_tokensriadia dĺžku výstupu- V produkčnom kóde vždy ošetruj HTTP chyby