Премини към основното съдържание
Български— Изберете език
Меню

Codestral API в Python

Урок 3 от 14 Обновен 2 ноември 2026 г. Програмист
На тази страница
  1. Извикване на Codestral от Python
  2. Инсталация и конфигурация
  3. Пълно FIM извикване
  4. Chat извикване за генериране на код
  5. Разширени параметри
  6. Два шаблона за копиране и поставяне
  7. Обработка на грешки
  8. Ключови изводи

Извикване на Codestral от Python

Този урок преминава от теория към изпълним код. Ще използвате Python SDK на Mistral AI, за да заявявате Codestral през неговите две крайни точки, да настроите разширените параметри, които отличават полезното предложение от многословното, и да приложите шаблоните, срещани в повечето интеграции в реални условия.

Инсталация и конфигурация

Инсталирайте SDK с една команда:

pip install mistralai

Вземете своя API ключ от console.mistral.ai и го прочетете от средата, вместо да го вграждате директно във файла си:

import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

Две платформи обслужват Codestral и Вие избирате между тях при създаването на ключа. api.mistral.ai работи на принципа „плащане според използването“ с таксуване базирано на потреблението: това е стандартният път, когато Codestral е един от многото компоненти в дадено приложение. codestral.mistral.ai е специализирана крайна точка, достъпна безплатно или чрез абонамент, предназначена за директна употреба от разработчик в неговия редактор.

Пълно FIM извикване

Ето подробно FIM извикване с всички важни параметри:

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)

Разбиване на отговора

Върнатият обект съдържа повече от просто генерирания текст. В производствена среда трябва систематично да проверявате три части от информацията: самото допълване, потреблението на токени, което определя сметката Ви, и причината за спиране, която Ви казва дали моделът е завършил естествено или е достигнал зададения лимит.

# Достъп до генерираното допълване
text = response.choices[0].message.content

# Проверка на броя използвани токени
tokens_prompt = response.usage.prompt_tokens
tokens_completion = response.usage.completion_tokens
tokens_total = response.usage.total_tokens

# Проверка на причината за спиране
reason = response.choices[0].finish_reason  # "stop", "length", и др.

Стойност finish_reason от "length" при половината от извикванията е ясен сигнал: Вашият max_tokens е твърде нисък и доставяте на потребителите си орязан код.

Chat извикване за генериране на код

Когато няма курсор в средата на файл – например при пълно генериране, обяснение или рефакторинг – крайната точка за чат поема инициативата. Системното съобщение тогава рамкира формата на изхода, което избягва необходимостта от последващо почистване на отговора:

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)

Разширени параметри

Двойката min_tokens / max_tokens рамкира дължината на изхода. Долната граница е полезна, когато генерирате блок, за който знаете, че не може да бъде по-къс от определен обем, като например функция с нейната обработка на грешки.

# min_tokens: налага минимална дължина на изхода
# max_tokens: ограничава максималната дължина
response = client.fim.complete(
    model="codestral-latest",
    prompt=prompt,
    suffix=suffix,
    min_tokens=20,
    max_tokens=300,
)

Стоповете (stop tokens) играят различна роля: те прекратяват генерирането при конкретен шаблон, задържайки допълването в рамките на текущата функция, вместо да позволят на модела да верижно премине към следващата.

# Спиране на генерирането при конкретни шаблони
response = client.fim.complete(
    model="codestral-latest",
    prompt=prompt,
    suffix=suffix,
    stop=["\n\n", "\nclass ", "\ndef "],  # Спиране преди нова функция/клас
)

Накрая, температурата управлява вариативността. При 0 един и същ вход винаги дава един и същ изход, което е задължително за автоматичното допълване. Около 0.3 моделът предлага варианти, което е интересно при показване на множество предложения. При 0.7 сте в режим на мозъчна атака за код, полезен за изследване на подход, но неподходящ за работен поток на редактиране.

# temperature=0: детерминирано (автоматично допълване)
# temperature=0.3: леко креативно (множество предложения)
# temperature=0.7: креативно (мозъчна атака за код)

response = client.fim.complete(
    model="codestral-latest",
    prompt=prompt,
    suffix=suffix,
    temperature=0.3,
    top_p=0.95,
)

Два шаблона за копиране и поставяне

Първият възпроизвежда поведението на IDE: разделяте съдържанието на файла на позицията на курсора и двете половини стават съответно prompt и suffix.

def autocomplete_ide(file_content: str, cursor_position: int) -> str:
    """Симулира автоматично допълване на IDE с 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

Вторият автоматизира документацията за съществуващ проект: подавате функция, извличате нейния docstring, а системната инструкция налага единен формат, така че резултатът да се вмъкне без допълнително редактиране.

def generate_docstring(function_code: str) -> str:
    """Генерира docstring за 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

Обработка на грешки

Мрежовото извикване рано или късно ще се провали, а разширение за редактор, което се срива при грешка във валидацията, е по-лошо от разширение без допълване. Затова винаги обгръщайте извикванията си:

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"Validation error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Ключови изводи

  • SDK mistralai излага client.fim.complete() за FIM и client.chat.complete() за чат
  • Параметрите prompt и suffix са специфични за крайната точка на FIM
  • Използвайте temperature=0 за автоматично допълване, 0.2-0.7 за креативно генериране
  • stop ограничава генерирането до смислен блок код
  • min_tokens и max_tokens контролират дължината на изхода
  • Винаги обработвайте HTTP грешки в производствения код