API Codestral v Pythonu
Na této stránce
Volání Codestralu z Pythonu
Tato lekce přechází od teorie ke spustitelnému kódu. Použiješ Python SDK od Mistral AI k dotazování na Codestral přes jeho dva endpointy, doladíš pokročilé parametry, které oddělují užitečný návrh od ukecaného, a implementuješ vzory běžné ve většině reálných integrací.
Instalace a konfigurace
Nainstaluj SDK jediným příkazem:
pip install mistralai
Získej svůj API klíč z console.mistral.ai a načti jej z prostředí místo toho, abys jej hardcodedoval přímo do souboru:
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Codestral obsluhují dvě platformy a mezi nimi si vybíráš při vytváření klíče. api.mistral.ai funguje na bázi pay-per-use s fakturací podle využití: toto je standardní cesta, když je Codestral jednou z mnoha komponent v aplikaci. codestral.mistral.ai je vyhrazený endpoint, dostupný zdarma nebo prostřednictvím předplatného, navržený pro přímé použití vývojářem v jeho editoru.
Kompletní volání FIM
Zde je podrobné volání FIM se všemi důležitými parametry:
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 odpovědi
Vrácený objekt obsahuje více než jen vygenerovaný text. V produkci bys měl systematicky kontrolovat tři informace: samotné dokončení, spotřebu tokenů, která určuje tvou fakturu, a důvod zastavení, který ti říká, zda model přirozeně skončil, nebo narazil na tvůj limit.
# Přístup k vygenerovanému dokončení
text = response.choices[0].message.content
# Kontrola počtu použitých tokenů
tokens_prompt = response.usage.prompt_tokens
tokens_completion = response.usage.completion_tokens
tokens_total = response.usage.total_tokens
# Kontrola důvodu zastavení
reason = response.choices[0].finish_reason # "stop", "length", atd.
Hodnota finish_reason rovna "length" u poloviny tvých volání je jasným signálem: tvé max_tokens je příliš nízké a uživatelům dodáváš useknutý kód.
Volání chatu pro generování kódu
Když není kurzor uprostřed souboru – například při úplném generování, vysvětlování nebo refaktoringu – přebírá řízení chatový endpoint. Systémová zpráva pak rámcuje formát výstupu, což eliminuje potřebu následného čištění odpovědi:
response = client.chat.complete(
model="codestral-latest",
messages=[
{
"role": "system",
"content": "Jsi expertní asistent pro vývoj v Pythonu. Odpovídej pouze kódem, bez vysvětlování."
},
{
"role": "user",
"content": "Napiš funkci v Pythonu, která validuje e-mailovou adresu pomocí regexu."
}
],
temperature=0.2,
max_tokens=500,
)
code = response.choices[0].message.content
print(code)
Pokročilé parametry
Dvojice min_tokens / max_tokens vymezuje délku výstupu. Spodní hranice je užitečná při generování bloku, o kterém víš, že nemůže být kratší než určitý objem, například funkce s obsluhou chyb.
# min_tokens: vynucuje minimální délku výstupu
# max_tokens: omezuje maximální délku
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
min_tokens=20,
max_tokens=300,
)
Stop tokeny hrají jinou roli: zastaví generování na konkrétním vzoru, čímž udrží dokončení v rámci aktuální funkce, místo aby model pokračoval řetězením do další funkce.
# Zastavení generování na specifických vzorech
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
stop=["\n\n", "\nclass ", "\ndef "], # Zastavit před novou funkcí/třídou
)
Nakonec teplota řídí variabilitu. Při hodnotě 0 vždy stejný vstupyielduje stejný výstup, což automatické doplňování vyžaduje. Kolem 0,3 model navrhuje varianty, což je zajímavé při zobrazování více návrhů. Při 0,7 jsi v režimu brainstormingu kódu, což je užitečné pro zkoumání přístupu, ale nevhodné pro editační tok.
# temperature=0: deterministické (automatické doplňování)
# temperature=0.3: mírně kreativní (více návrhů)
# temperature=0.7: kreativní (brainstorming kódu)
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
temperature=0.3,
top_p=0.95,
)
Dva vzory ke zkopírování
První reprodukuje chování IDE: rozdělíš obsah souboru na pozici kurzoru a obě poloviny se stanou promptem a suffixem.
def autocomplete_ide(file_content: str, cursor_position: int) -> str:
"""Simuluje automatické doplňování v IDE pomocí 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 dokumentaci pro existující projekt: předáš funkci, získáš její docstring a systémová instrukce vynutí jediný formát, takže výsledek lze vložit bez další úpravy.
def generate_docstring(function_code: str) -> str:
"""Generuje docstring pro funkci v Pythonu."""
response = client.chat.complete(
model="codestral-latest",
messages=[
{
"role": "system",
"content": "Vygeneruj docstring ve stylu Google pro následující funkci. Vrati POUZE docstring mezi trojitými uvozovkami."
},
{
"role": "user",
"content": function_code
}
],
temperature=0,
max_tokens=300,
)
return response.choices[0].message.content
Obsluha chyb
Síťové volání dříve či později selže a rozšíření editoru, které spadne na chybu validace, je horší než rozšíření bez doplňování. Proto vždy obal svá volání:
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 validace: {e}")
except Exception as e:
print(f"Neočekávaná chyba: {e}")
Klíčové poznatky
- SDK
mistralaizpřístupňujeclient.fim.complete()pro FIM aclient.chat.complete()pro chat - Parametry
promptasuffixjsou specifické pro endpoint FIM - Pro automatické doplňování použij
temperature=0, pro kreativní generování0,2–0,7 stopomezuje generování na soudržný blok kódumin_tokensamax_tokensřídí délku výstupu- V produkčním kódu vždy ošetři HTTP chyby