API Codestral em Python
Nesta página
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
mistralaiexpõeclient.fim.complete()para FIM eclient.chat.complete()para chat - Os parâmetros
promptesuffixsão específicos do endpoint FIM - Utilize
temperature=0para conclusão automática,0.2-0.7para geração criativa stoplimita a geração a um bloco de código coerentemin_tokensemax_tokenscontrolam o comprimento da saída- Trate sempre os erros HTTP em código de produção