Ir al contenido principal
Español— Elegir un idioma
Menú

Instalación del SDK de Python de Mistral

Lección 4 de 14 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. Prerrequisitos
  2. Aísla tu proyecto antes de instalar nada
  3. Instalación del SDK oficial
  4. Verifica la instalación con una llamada real a la API
  5. Haz reproducible el entorno
  6. Cuatro fallos comunes y cómo diagnosticarlos
  7. Puntos clave

Prerrequisitos

Actualizado el 2 de noviembre de 2026 — SDK de Mistral 3. Esta lección cubría anteriormente la versión 2 del SDK y Python 3.9. La versión actual es la 3.7.0 (lanzada el 1 de noviembre de 2026); requiere Python 3.10 o superior, y el cliente se importa mediante from mistralai.client import Mistral desde la versión 2.0 (marzo de 2026). Fuentes: mistralai en PyPI · notas de la versión v2.0.0 · notas de la versión v3.0.0.

La instalación del SDK requiere tres elementos: Python 3.10 o superior, que puedes verificar con python --version; un pip actualizado, que obtendrás con pip install --upgrade pip; y tu clave de API de Mistral ya configurada como variable de entorno, tal como se explicó en la lección anterior. Si aún no tienes Python instalado en tu máquina, descarga la última versión estable desde python.org o utiliza el gestor de paquetes de tu sistema.

Aísla tu proyecto antes de instalar nada

Trabaja siempre dentro de un entorno virtual. Este hábito te ahorrará un dolor de cabeza muy común: tener dos proyectos en la misma máquina, donde uno requiere una versión específica del SDK y el otra una diferente, y que un único pip install rompa silenciosamente el primer proyecto al actualizar el segundo. Un entorno virtual proporciona a cada proyecto sus propias dependencias aisladas, separadas de los paquetes globales del sistema.

# Crear el entorno virtual
python -m venv mistral-env

# Activar en Linux / macOS
source mistral-env/bin/activate

# Activar en Windows
mistral-env\Scripts\activate

Una vez activado, el indicador de tu terminal llevará el prefijo del nombre del entorno entre paréntesis: (mistral-env). Este pequeño marcador garantiza que los comandos posteriores se apliquen en la ubicación correcta; si no aparece, no instales nada.

Instalación del SDK oficial

Instalar el SDK de Mistral requiere un solo comando:

pip install mistralai

Esto instala la última versión del SDK: la 3.7.0 a fecha de 1 de noviembre de 2026. La generación 3 comenzó con la versión 3.0, lanzada el 28 de septiembre de 2026. Para confirmar que todo está en su sitio, ejecuta pip show mistralai para mostrar el nombre del paquete, la versión y las dependencias.

A veces un proyecto requiere una versión concreta, por ejemplo, para mantener a todo un equipo alineado durante una migración. Puedes especificar restricciones en dos niveles:

# Mantenerse dentro de la generación 3
pip install "mistralai>=3,<4"

# Instalar una versión exacta
pip install "mistralai==3.7.0"

Durante el proceso, pip descarga algunas dependencias que aparecen en la lista. Es útil reconocerlas, especialmente httpx2, el cliente HTTP que gestiona las llamadas de red (el SDK utiliza este en lugar de httpx a partir de la versión 3.0), y pydantic, que valida y serializa los datos intercambiados. No interactuarás directamente con ellas, pero su presencia explica por qué una instalación que parece pequeña ocupa aún así unos pocos megabytes.

Verifica la instalación con una llamada real a la API

Ejecutar pip show demuestra que el paquete existe, no que tu configuración funcione. La prueba real consulta la API. Crea un archivo llamado test_mistral.py:

import os
from mistralai.client import Mistral

api_key = os.environ.get("MISTRAL_API_KEY")

if not api_key:
    print("Error: La variable de entorno MISTRAL_API_KEY no está configurada.")
else:
    client = Mistral(api_key=api_key)
    print("¡Cliente de Mistral inicializado correctamente!")

    # Listar modelos disponibles
    models = client.models.list()
    print(f"Modelos disponibles: {len(models.data)}")
    for model in models.data[:5]:
        print(f"  - {model.id}")

Luego ejecútalo:

python test_mistral.py

Este script verifica dos cosas a la vez. La comprobación de api_key distingue inmediatamente una variable de entorno faltante de un problema de red genuino; sin ella, podrías pasar diez minutos sospechando de tu cortafuegos cuando lo único que ocurrió es que se reabrió el terminal sin la variable. Si se muestra la lista de modelos, el SDK está instalado correctamente y tu clave es aceptada por la API.

Haz reproducible el entorno

En un proyecto de equipo, la instalación debe ser reproducible. Congela tus dependencias:

pip freeze > requirements.txt

Tus compañeros podrán entonces reconstruir exactamente el mismo entorno con un solo comando:

pip install -r requirements.txt

Tu servidor de despliegue también leerá este archivo. Adquiere el hábito de regenerarlo cada vez que añadas una biblioteca; de lo contrario, el código funcionará en tu máquina y en ninguna otra.

Cuatro fallos comunes y cómo diagnosticarlos

El error ModuleNotFoundError: No module named mistralai casi siempre significa que el terminal no está usando el entorno virtual correcto. Verifícalo con which python, que debería apuntar a tu venv, y luego con pip list | grep mistralai.

El error ImportError: cannot import name 'Mistral' from 'mistralai' indica código escrito para la versión 1 del SDK. Desde la versión 2.0, todas las importaciones se realizan a través de mistralai.client: escribe from mistralai.client import Mistral. La lección sobre versiones del SDK detalla otros cambios.

Un error de SSL o de red a menudo revela la presencia de un proxy corporativo entre tú y el exterior. Indica explícitamente a pip dónde está:

pip install mistralai --proxy http://proxy.entreprise.com:8080

Por último, si la instalación rechaza tu versión de Python, recuerda que el SDK requiere como mínimo Python 3.10 desde la versión 2.0. Actualiza Python o instala pyenv para ejecutar múltiples versiones simultáneamente sin tocar el intérprete del sistema.

Puntos clave

  • Instala el SDK con pip install mistralai dentro de un entorno virtual
  • La versión actual es la 3.7.0 (1 de noviembre de 2026); importa el cliente mediante from mistralai.client import Mistral
  • Verifica la instalación listando los modelos disponibles
  • Congela las dependencias en requirements.txt para garantizar la reproducibilidad
  • Se requiere Python 3.10 o superior