Ir para o conteúdo principal
Português— Escolher um idioma
Menu

API Codestral em Python

Aula 3 de 14 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Chamar o Codestral a partir de Python
  2. Instalação e configuração
  3. Chamada FIM completa
  4. Chamada de chat para geração de código
  5. Parâmetros avançados
  6. Dois padrões para copiar e colar
  7. Tratamento de erros
  8. Pontos-chave

Chamar o Codestral a partir de Python

Esta lição transita da teoria para o código executável. Vai utilizar o SDK Python da Mistral AI para consultar o Codestral nos seus dois endpoints, ajustar os parâmetros avançados que distinguem uma sugestão útil de uma resposta prolixa e implementar os padrões encontrados na maioria das integrações no mundo real.

Instalação e configuração

Instale o SDK com um único comando:

pip install mistralai

Obtenha a sua chave de API em console.mistral.ai e leia-a a partir do ambiente, em vez de a codificar diretamente no seu ficheiro:

import os
from mistralai.client import Mistral

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

Duas plataformas servem o Codestral, e escolhe entre elas ao criar a sua chave. A api.mistral.ai opera num regime de pagamento por utilização com faturação baseada no consumo: este é o caminho padrão quando o Codestral é apenas um componente entre muitos numa aplicação. A codestral.mistral.ai é um endpoint dedicado, acessível gratuitamente ou via subscrição, concebido para utilização direta por um programador no seu editor.

Chamada FIM completa

Eis uma chamada FIM detalhada com todos os parâmetros importantes:

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)

Análise da resposta

O objeto devolvido contém mais do que apenas o texto gerado. Em produção, deve verificar sistematicamente três informações: a própria conclusão, o consumo de tokens que determina a sua fatura e o motivo de paragem, que indica se o modelo terminou naturalmente ou se atingiu o seu limite.

# Aceder à conclusão gerada
text = response.choices[0].message.content

# Verificar o número de tokens utilizados
tokens_prompt = response.usage.prompt_tokens
tokens_completion = response.usage.completion_tokens
tokens_total = response.usage.total_tokens

# Verificar o motivo de paragem
reason = response.choices[0].finish_reason  # "stop", "length", etc.

Um finish_reason de "length" em metade das suas chamadas é um sinal claro: o seu max_tokens é demasiado baixo e está a entregar código truncado aos seus utilizadores.

Chamada de chat para geração de código

Sempre que não exista um cursor no meio de um ficheiro — como é o caso da geração completa, explicação ou refatoração —, o endpoint de chat assume o controlo. A mensagem de sistema define então o formato de saída, o que evita a necessidade de limpar a resposta posteriormente:

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)

Parâmetros avançados

O par min_tokens / max_tokens define o comprimento da saída. O limite mínimo é útil ao gerar um bloco que sabe não poder ser mais curto do que um determinado volume, como uma função com o seu tratamento de erros.

# min_tokens: força um comprimento mínimo de saída
# max_tokens: limita o comprimento máximo
response = client.fim.complete(
    model="codestral-latest",
    prompt=prompt,
    suffix=suffix,
    min_tokens=20,
    max_tokens=300,
)

Os tokens de paragem desempenham um papel diferente: interrompem a geração num padrão específico, mantendo a conclusão no âmbito da função atual em vez de deixar o modelo encadear para a seguinte.

# Parar a geração em padrões específicos
response = client.fim.complete(
    model="codestral-latest",
    prompt=prompt,
    suffix=suffix,
    stop=["\n\n", "\nclass ", "\ndef "],  # Parar antes de uma nova função/classe
)

Por fim, a temperatura governa a variabilidade. Em 0, a mesma entrada produz sempre a mesma saída, o que a conclusão automática exige. Por volta de 0.3, o modelo propõe variantes, o que é interessante ao apresentar múltiplas sugestões. Em 0.7, entra no modo de brainstorming de código, útil para explorar uma abordagem, mas inadequado para um fluxo de edição.

# temperature=0: determinístico (conclusão automática)
# temperature=0.3: ligeiramente criativo (múltiplas sugestões)
# temperature=0.7: criativo (brainstorming de código)

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

Dois padrões para copiar e colar

O primeiro reproduz o comportamento de um IDE: divide o conteúdo do ficheiro na posição do cursor, e as duas metades tornam-se o prompt e o sufixo.

def autocomplete_ide(file_content: str, cursor_position: int) -> str:
    """Simula a conclusão automática de um IDE com o 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

O segundo automatiza a documentação de um projeto existente: passa uma função, recupera a sua docstring e a instrução do sistema impõe um formato único para que o resultado seja inserido sem necessidade de edição adicional.

def generate_docstring(function_code: str) -> str:
    """Gera uma docstring para uma função 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

Tratamento de erros

Uma chamada de rede falhará mais cedo ou mais tarde, e uma extensão de editor que falha num erro de validação é pior do que uma extensão sem conclusão. Por isso, envolva sempre as suas chamadas:

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}")

Pontos-chave

  • O SDK mistralai expõe client.fim.complete() para FIM e client.chat.complete() para chat
  • Os parâmetros prompt e suffix são específicos do endpoint FIM
  • Utilize temperature=0 para conclusão automática, 0.2-0.7 para geração criativa
  • stop limita a geração a um bloco de código coerente
  • min_tokens e max_tokens controlam o comprimento da saída
  • Trate sempre os erros HTTP em código de produção