Przejdź do głównej treści
Polski— Wybierz język
Menu

API Codestral w Pythonie

Lekcja 3 z 14 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Wywoływanie Codestral z poziomu Pythona
  2. Instalacja i konfiguracja
  3. Pełne wywołanie FIM
  4. Wywołanie czatu do generowania kodu
  5. Parametry zaawansowane
  6. Dwa wzorce do skopiowania
  7. Obsługa błędów
  8. Kluczowe wnioski

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 mistralai udostępnia client.fim.complete() dla FIM oraz client.chat.complete() dla czatu
  • Parametry prompt i suffix są specyficzne dla punktu końcowego FIM
  • Używaj temperature=0 do autouzupełniania, a 0.2-0.7 do generowania kreatywnego
  • stop ogranicza generowanie do spójnego bloku kodu
  • min_tokens i max_tokens kontrolują długość wyjścia
  • Zawsze obsługuj błędy HTTP w kodzie produkcyjnym