API de Codestral en Python
En esta página
Llamada a Codestral desde Python
Esta lección pasa de la teoría al código ejecutable. Utilizarás el SDK de Python de Mistral AI para consultar Codestral en sus dos puntos de conexión, ajustar los parámetros avanzados que marcan la diferencia entre una sugerencia útil y una verbosa, e implementar los patrones presentes en la mayoría de las integraciones del mundo real.
Instalación y configuración
Instala el SDK con un único comando:
pip install mistralai
Recupera tu clave de API desde console.mistral.ai y léela desde el entorno en lugar de codificarla directamente en tu archivo:
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Dos plataformas sirven Codestral, y eliges entre ellas al crear tu clave. api.mistral.ai funciona bajo un modelo de pago por uso con facturación basada en el consumo: esta es la vía estándar cuando Codestral es un componente más entre muchos en una aplicación. codestral.mistral.ai es un punto de conexión dedicado, accesible de forma gratuita o mediante suscripción, diseñado para el uso directo por parte de un desarrollador dentro de su editor.
Llamada FIM completa
Aquí tienes una llamada FIM detallada con todos los 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)
Desglose de la respuesta
El objeto devuelto contiene algo más que el texto generado. En producción, debes comprobar sistemáticamente tres elementos: la finalización en sí misma, el consumo de tokens que determina tu factura y el motivo de parada, que indica si el modelo ha terminado de forma natural o ha alcanzado tu límite.
# Acceso a la finalización generada
text = response.choices[0].message.content
# Comprobación del número de tokens utilizados
tokens_prompt = response.usage.prompt_tokens
tokens_completion = response.usage.completion_tokens
tokens_total = response.usage.total_tokens
# Comprobación del motivo de parada
reason = response.choices[0].finish_reason # "stop", "length", etc.
Un finish_reason de "length" en la mitad de tus llamadas es una señal clara: tu max_tokens es demasiado bajo y estás entregando código truncado a tus usuarios.
Llamada chat para generación de código
Cuando no hay un cursor en medio de un archivo, como en el caso de una generación completa, una explicación o un refactorizado, el punto de conexión de chat toma el relevo. El mensaje del sistema enmarca entonces el formato de salida, lo que evita tener que limpiar la respuesta posteriormente:
response = client.chat.complete(
model="codestral-latest",
messages=[
{
"role": "system",
"content": "Eres un asistente experto en desarrollo Python. Responde solo con código, sin explicaciones."
},
{
"role": "user",
"content": "Escribe una función en Python que valide una dirección de correo electrónico usando expresiones regulares."
}
],
temperature=0.2,
max_tokens=500,
)
code = response.choices[0].message.content
print(code)
Parámetros avanzados
El par min_tokens / max_tokens delimita la longitud de la salida. El suelo es útil cuando generas un bloque del que sabes que no puede ser más corto que un cierto volumen, como una función con su gestión de errores.
# min_tokens: fuerza una longitud mínima de salida
# max_tokens: limita la longitud máxima
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
min_tokens=20,
max_tokens=300,
)
Los tokens de parada desempeñan un papel diferente: detienen la generación en un patrón específico, manteniendo la finalización dentro del ámbito de la función actual en lugar de permitir que el modelo encadene con la siguiente.
# Detener la generación en patrones específicos
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
stop=["\n\n", "\nclass ", "\ndef "], # Detener antes de una nueva función/clase
)
Por último, la temperatura gobierna la variabilidad. En 0, la misma entrada produce siempre la misma salida, algo que requiere la autocompletación. Alrededor de 0,3, el modelo propone variantes, lo cual es interesante al mostrar múltiples sugerencias. En 0,7, estás en modo de lluvia de ideas de código, útil para explorar un enfoque pero inadecuado para un flujo de edición.
# temperature=0: determinista (autocompletado)
# temperature=0.3: ligeramente creativo (múltiples sugerencias)
# temperature=0.7: creativo (lluvia de ideas de código)
response = client.fim.complete(
model="codestral-latest",
prompt=prompt,
suffix=suffix,
temperature=0.3,
top_p=0.95,
)
Dos patrones para copiar y pegar
El primero reproduce el comportamiento de un IDE: divides el contenido del archivo en la posición del cursor, y las dos mitades se convierten en el prompt y el suffix.
def autocomplete_ide(file_content: str, cursor_position: int) -> str:
"""Simula el autocompletado de un IDE con FIM de Codestral."""
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
El segundo automatiza la documentación de un proyecto existente: pasas una función, recuperas su docstring y la instrucción del sistema impone un único formato para que el resultado se inserte sin necesidad de edición adicional.
def generate_docstring(function_code: str) -> str:
"""Genera un docstring para una función de Python."""
response = client.chat.complete(
model="codestral-latest",
messages=[
{
"role": "system",
"content": "Genera un docstring estilo Google para la siguiente función. Devuelve SOLO el docstring entre triples comillas."
},
{
"role": "user",
"content": function_code
}
],
temperature=0,
max_tokens=300,
)
return response.choices[0].message.content
Gestión de errores
Una llamada de red fallará tarde o temprano, y una extensión de editor que se bloquea ante un error de validación es peor que una extensión sin autocompletado. Por tanto, envuelve siempre tus llamadas:
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"Error de validación: {e}")
except Exception as e:
print(f"Error inesperado: {e}")
Puntos clave
- El SDK
mistralaiexponeclient.fim.complete()para FIM yclient.chat.complete()para chat - Los parámetros
promptysuffixson específicos del punto de conexión FIM - Usa
temperature=0para autocompletado,0,2-0,7para generación creativa stoplimita la generación a un bloque de código coherentemin_tokensymax_tokenscontrolan la longitud de la salida- Gestiona siempre los errores HTTP en el código de producción