API Codestral w Pythonie
Na tej stronie
Wywoływanie Codestral z poziomu Pythona
Ta lekcja przenosi Cię od teorii do kodu wykonywalnego. Wykorzystasz Python SDK od Mistral AI, aby odpytywać Codestral przez jego dwa punkty końcowe, dostosować zaawansowane parametry odróżniające użyteczną sugestię od rozwlekłej odpowiedzi oraz wdrożyć wzorce spotykane w większości integracji rzeczywistych.
Instalacja i konfiguracja
Zainstaluj SDK jedną komendą:
pip install mistralai
Pobierz swój klucz API z console.mistral.ai i odczytuj go ze zmiennych środowiskowych, zamiast hardkodować go w pliku:
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Dwie platformy obsługują Codestral, a wybór między nimi następuje podczas tworzenia klucza. api.mistral.ai działa w modelu pay-per-use z rozliczeniem zależnym od użycia: to standardowa ścieżka, gdy Codestral jest jednym z wielu komponentów aplikacji. codestral.mistral.ai to dedykowany punkt końcowy, dostępny bezpłatnie lub w ramach subskrypcji, zaprojektowany do bezpośredniego użytku przez programistę w jego edytorze.
Pełne wywołanie FIM
Oto szczegółowe wywołanie FIM ze wszystkimi ważnymi 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)
Analiza odpowiedzi
Zwracany obiekt zawiera więcej niż tylko wygenerowany tekst. W środowisku produkcyjnym powinieneś systematycznie sprawdzać trzy elementy: samą uzupełnioną treść, zużycie tokenów determinujące koszt oraz powód zatrzymania, który informuje, czy model zakończył pracę naturalnie, czy osiągnął Twój limit.
# Dostęp do wygenerowanego uzupełnienia
text = response.choices[0].message.content
# Sprawdzenie liczby użytych tokenów
tokens_prompt = response.usage.prompt_tokens
tokens_completion = response.usage.completion_tokens
tokens_total = response.usage.total_tokens
# Sprawdzenie powodu zatrzymania
reason = response.choices[0].finish_reason # "stop", "length", itp.
Wartość finish_reason równa "length" w połowie wywołań to wyraźny sygnał: Twoje max_tokens jest zbyt niskie i dostarczasz użytkownikom ucięty kod.
Wywołanie czatu do generowania kodu
Gdy kursor nie znajduje się w środku pliku – np. przy pełnym generowaniu, wyjaśnianiu lub refaktoryzacji – przejmuję kontrolę punkt końcowy czatu. Wiadomość systemowa określa wtedy format wyjścia, co eliminuje konieczność późniejszego czyszczenia odpowiedzi:
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)
Parametry zaawansowane
Para min_tokens / max_tokens określa ramy długości wyjścia. Dolny próg jest przydatny przy generowaniu bloku, o którym wiesz, że nie może być krótszy niż określona objętość, np. funkcji wraz z obsługą błędów.
# min_tokens: wymusza minimalną długość wyjścia
# max_tokens: ogranicza maksymalną długość
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
min_tokens=20,
max_tokens=300,
)
Tokeny stop pełnią inną rolę: zatrzymują generowanie na konkretnym wzorcu, utrzymując uzupełnienie w zakresie bieżącej funkcji, zamiast pozwalać modelowi przechodzić do kolejnej.
# Zatrzymanie generowania na konkretnych wzorcach
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
stop=["\n\n", "\nclass ", "\ndef "], # Zatrzymaj przed nową funkcją/klasą
)
Na koniec temperatura steruje zmiennością. Przy wartości 0 to samo wejście zawsze daje to samo wyjście, czego wymaga automatyczne uzupełnianie. Około 0.3 model proponuje warianty, co jest interesujące przy wyświetlaniu wielu sugestii. Przy 0.7 znajdujesz się w trybie burzy mózgów nad kodem, przydatnym do eksploracji podejścia, ale nieodpowiednim dla przepływu edycji.
# temperature=0: deterministyczne (autouzupełnianie)
# temperature=0.3: lekko kreatywne (wiele sugestii)
# temperature=0.7: kreatywne (burza mózgów nad kodem)
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
temperature=0.3,
top_p=0.95,
)
Dwa wzorce do skopiowania
Pierwszy odwzorowuje zachowanie IDE: dzielisz zawartość pliku w pozycji kursora, a dwie połowy stają się odpowiednio prompt i suffix.
def autocomplete_ide(file_content: str, cursor_position: int) -> str:
"""Symuluje autouzupełnianie IDE z wykorzystaniem 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 automatyzuje dokumentację istniejącego projektu: przekazujesz funkcję, pobierasz jej docstring, a instrukcja systemowa wymusza jeden format, dzięki czemu wynik można wstawić bez dalszej edycji.
def generate_docstring(function_code: str) -> str:
"""Generuje docstring dla funkcji 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
Obsługa błędów
Połączenie sieciowe prędzej czy później ulegnie awarii, a rozszerzenie edytora, które crashuje się przy błędzie walidacji, jest gorsze niż rozszerzenie bez uzupełniania. Dlatego zawsze opakowuj swoje wywołania:
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"Błąd walidacji: {e}")
except Exception as e:
print(f"Niespodziewany błąd: {e}")
Kluczowe wnioski
- SDK
mistralaiudostępniaclient.fim.complete()dla FIM orazclient.chat.complete()dla czatu - Parametry
promptisuffixsą specyficzne dla punktu końcowego FIM - Używaj
temperature=0do autouzupełniania, a0.2-0.7do generowania kreatywnego stopogranicza generowanie do spójnego bloku kodumin_tokensimax_tokenskontrolują długość wyjścia- Zawsze obsługuj błędy HTTP w kodzie produkcyjnym