Migración entre versiones del SDK de Mistral
En esta página
- Por qué importa esta lección
- Cuatro generaciones en dos años
- De 0.x a 1.x: el cliente Mistral y los métodos encadenados
- De 1.x a 2.x: todo se mueve bajo mistralai.client
- De 2.x a 3.x: httpx2 y herramientas integradas
- ¿Y qué pasa con TypeScript?
- Cómo llevar a cabo la migración
- Si no puedes migrar de inmediato
- Puntos clave
Lección reescrita el 2 de noviembre de 2026. La versión anterior hablaba de «pasar de V1 a V2», lo cual correspondía en realidad a la transición del cliente heredado 0.x a la versión 1.0 en agosto de 2024. Desde entonces, el SDK de Python ha tenido dos lanzamientos mayores más: la 2.0 en marzo de 2026 y la 3.0 en septiembre de 2026. Esta lección reconstruye la historia completa basándose en las guías de migración oficiales y las notas de lanzamiento. Actualizado el 3 de noviembre de 2026: se ha corregido el bucle de streaming en TypeScript, que anteriormente pasaba contenido
string | ContentChunk[]directamente aprocess.stdout.write, lo que causaba fallos en modo estricto.
Por qué importa esta lección
Te encontrarás con este material en dos escenarios: estás retomando un proyecto escrito hace tiempo que se niega a arrancar tras una actualización de dependencias, o estás siguiendo un tutorial en línea cuyos ejemplos ya no funcionan. En ambos casos, hazte la misma primera pregunta: ¿para qué generación del SDK se escribió este código? Casi siempre, una sola línea te lo dice: la sentencia de importación.
Cuatro generaciones en dos años
| Generación | Python (mistralai) | TypeScript (@mistralai/mistralai) | Característica de código distintiva |
|---|---|---|---|
| 0.x | hasta 0.4.2 (julio de 2024) | hasta 0.5.0 (junio de 2024) | MistralClient, métodos planos: client.chat(...) |
| 1.x | 1.0.0 (7 de ago de 2024) → 1.9.11 (oct de 2025) | desde ago de 2024 | from mistralai import Mistral, métodos encadenados: client.chat.complete(...) |
| 2.x | 2.0.0 (10 de mar de 2026) | 2.0.0 (18 de mar de 2026) | Python: from mistralai.client import Mistral; TypeScript: solo módulos ES |
| 3.x | 3.0.0 (28 de sep de 2026), 3.7.0 a fecha de 1 de nov de 2026 | 3.0 (oct de 2026), 3.5.0 hoy | Python: cliente HTTP httpx2 |
En TypeScript, la importación import { Mistral } from '@mistralai/mistralai' no ha cambiado desde la 1.x. En Python, ha cambiado dos veces: ahí es donde se producen la mayoría de las roturas.
De 0.x a 1.x: el cliente Mistral y los métodos encadenados
La versión 1.0 sustituyó los dos clientes, MistralClient (síncrono) y MistralAsyncClient (asíncrono), por una única clase, Mistral. También reemplazó los métodos planos por espacios de nombres: chat agrupa las operaciones de conversación y hay que bajar un nivel más para llegar a complete(). Los mensajes, que antes se escribían usando la clase ChatMessage, ahora se escriben como diccionarios o utilizando las clases UserMessage, SystemMessage, AssistantMessage y ToolMessage.
# 0.x (heredado)
from mistralai.client import MistralClient
from mistralai.models.chat_completion import ChatMessage
client = MistralClient(api_key="...")
response = client.chat(
model="mistral-small-latest",
messages=[ChatMessage(role="user", content="Hello")],
)
# 1.x
from mistralai import Mistral
client = Mistral(api_key="...")
response = client.chat.complete(
model="mistral-small-latest",
messages=[{"role": "user", "content": "Hello"}],
)
El streaming sigue la misma lógica, con una trampa que suele costar media hora de depuración: el fragmento recibido ahora está envuelto y su contenido se lee a través de un nivel intermedio .data. El código heredado 0.x copiado tal cual lanza un AttributeError en el primer fragmento.
# 0.x
for chunk in client.chat_stream(model=..., messages=...):
print(chunk.choices[0].delta.content)
# 1.x y posteriores
for chunk in client.chat.stream(model=..., messages=...):
print(chunk.data.choices[0].delta.content)
La guía oficial de la 1.0 proporciona la tabla completa. Las correspondencias más frecuentes son:
| 0.x | 1.x y posteriores |
|---|---|
client.chat / client.chat_stream | client.chat.complete / client.chat.stream |
client.completions (FIM) | client.fim.complete |
client.embeddings(model=..., input=[...]) | client.embeddings.create(model=..., inputs=[...]) |
client.list_models() | client.models.list() |
client.files.create(...) | client.files.upload(...) |
client.jobs.create(...) | client.fine_tuning.jobs.create(...) |
MistralAsyncClient y sus métodos | Variantes _async: client.chat.complete_async, client.chat.stream_async… |
De 1.x a 2.x: todo se mueve bajo mistralai.client
La versión 2.0 no tocó los nombres de los métodos: client.chat.complete sigue siendo client.chat.complete. Cambió la dirección de todo lo demás. El SDK se convirtió en un paquete de espacio de nombres (PEP 420) y todas las importaciones migraron de mistralai a mistralai.client:
# 1.x
from mistralai import Mistral
from mistralai.models import UserMessage, SDKError
# 2.x y posteriores
from mistralai.client import Mistral
from mistralai.client.models import UserMessage
from mistralai.client.errors import SDKError
Observa la tercera línea: las clases de error ya no viven entre los modelos, sino en mistralai.client.errors, con MistralError como base común (de la que heredan SDKError y HTTPValidationError).
Los clientes de proveedores de nube se unieron al mismo espacio de nombres. En la 1.x, se distribuían con el paquete mistralai pero en módulos separados, mistralai_azure y mistralai_gcp:
# 1.x
from mistralai_azure import MistralAzure
client = MistralAzure(azure_endpoint="https://your-endpoint.inference.ai.azure.com", azure_api_key="your-azure-key")
from mistralai_gcp import MistralGoogleCloud
client = MistralGoogleCloud(region="europe-west4", project_id="my-project")
# 2.x y posteriores
from mistralai.azure.client import MistralAzure
client = MistralAzure(server_url="https://your-endpoint.inference.ai.azure.com", api_key="your-azure-key")
from mistralai.gcp.client import MistralGCP # pip install "mistralai[gcp]"
client = MistralGCP(region="europe-west4", project_id="my-project")
Otros tres cambios en la 2.0 pueden afectarte. La versión mínima es ahora Python 3.10 (la 1.9.11 aceptaba Python 3.9). Se renombraron 42 tipos según una convención regular: {Verbo}{Entidad}Request para solicitudes y {Verbo}{Entidad}Response para respuestas. El único renombrado visible en el código habitual es Tools, que pasó a ser ConversationRequestTool. Por último, las enumeraciones ahora aceptan valores desconocidos, por lo que un nuevo valor añadido por la API ya no hace colapsar una versión antigua del SDK.
De 2.x a 3.x: httpx2 y herramientas integradas
La versión 3.0, lanzada el 28 de septiembre de 2026, no cambia ni las importaciones ni los métodos comunes. Sin embargo, tres puntos pueden romper un proyecto:
- El cliente HTTP pasa a ser
httpx2. Si pasas tu propio cliente al SDK (parámetrosclient=oasync_client=, por ejemplo para un proxy o cabeceras comunes), debe ser un clientehttpx2; las solicitudes, respuestas y errores de transporte brutos también son tiposhttpx2. - Las herramientas integradas abandonan las completaciones de chat.
client.chat.completeyclient.agents.completeya no aceptan las herramientasweb_search,web_search_premiumycode_interpreter: se usan a través de la API de Conversaciones (client.beta.conversations) o un agente. La documentación de Mistral explica por qué: las respuestas de completado de chat no pueden llevar las referencias que devuelven estas herramientas. - Los extras
mcpyagentsdependen ahora de MCP 2.2.
La versión 3.0 también añade autenticación mediante token de cuenta de servicio: Mistral() lee el token del archivo especificado por la variable de entorno MISTRAL_SA_TOKEN_PATH.
¿Y qué pasa con TypeScript?
Pasar del cliente JavaScript heredado 0.x al SDK de TypeScript 1.x refleja casi exactamente la transición de Python. La importación cambia de una exportación por defecto a una con nombre, el constructor toma un objeto de configuración y los métodos se vuelven encadenados:
// 0.x (heredado)
import MistralClient from '@mistralai/mistralai';
const client = new MistralClient(process.env.MISTRAL_API_KEY);
const response = await client.chat({
model: 'mistral-small-latest',
messages: [{ role: 'user', content: 'Hello' }],
});
// 1.x y posteriores
import { Mistral } from '@mistralai/mistralai';
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
const response = await client.chat.complete({
model: 'mistral-small-latest',
messages: [{ role: 'user', content: 'Hello' }],
});
El streaming pasa de client.chatStream(...) a client.chat.stream(...), y, al igual que en Python, el contenido se lee mediante chunk.data:
const stream = await client.chat.stream({
model: 'mistral-small-latest',
messages: [{ role: 'user', content: 'Hello' }],
});
for await (const chunk of stream) {
const content = chunk.data.choices[0]?.delta.content;
// content también puede ser una lista de fragmentos: solo escribimos texto
if (typeof content === 'string') process.stdout.write(content);
}
TypeScript 2.0 (18 de marzo de 2026) mantuvo estas importaciones, pero el SDK se publica ahora solo como módulos ES: un require('@mistralai/mistralai') en CommonJS ya no funciona. La validación en tiempo de ejecución pasa a Zod v4, lo que solo afecta a los proyectos que importan esquemas directamente desde el SDK. Y los clientes de nube viven en paquetes separados: @mistralai/mistralai-azure (MistralAzure) y @mistralai/mistralai-gcp (MistralGCP, anteriormente MistralGoogleCloud).
Cómo llevar a cabo la migración
En un proyecto real, procede en un orden definido en lugar de corregir errores según aparecen. Empieza identificando la generación del código mediante sus importaciones y luego actualiza el paquete (pip install --upgrade mistralai o npm install @mistralai/mistralai@latest): mientras la versión antigua esté instalada, estás arreglando cosas a ciegas. A continuación, procede así:
- Busca las importaciones antiguas:
MistralClient,from mistralai import,from mistralai.models import,mistralai_azure,mistralai_gcp,require('@mistralai/mistralai') - Sustitúyelas según las correspondencias de esta lección; no olvides los errores, que se mueven a
mistralai.client.errors - Actualiza las llamadas: métodos encadenados,
inputsen plural para embeddings,.dataen los bucles de streaming - Mueve las herramientas integradas (
web_search,code_interpreter) de las completaciones de chat a la API de Conversaciones
Por último, prueba cada punto final que uses, uno por uno: chat, embeddings y streaming tienen cada uno sus propios cambios, y que un proyecto arranque no significa necesariamente que llame correctamente a los tres.
Si no puedes migrar de inmediato
Ninguna de estas versiones ofrece un modo de transición ni alias de compatibilidad. Si una congelación de producción te impide migrar, fija explícitamente la versión en tus dependencias; de lo contrario, la siguiente instalación traerá la última versión y romperá la aplicación:
# Python: permanecer en 1.x
pip install "mistralai<2"
# Python: permanecer en 2.x
pip install "mistralai>=2,<3"
# npm: permanecer en 1.x
npm install @mistralai/mistralai@1
Trata esta fijación como un respiro: las nuevas funcionalidades llegan solo a la versión actual.
Fuentes oficiales: Guía de migración 0.x → 1.0 · Notas de lanzamiento de Python 2.0.0 · Notas de lanzamiento de Python 3.0.0 · Notas de lanzamiento de TypeScript 2.0.0 · Historial de versiones en PyPI · Websearch — herramientas integradas
Puntos clave
- Identifica la generación del código por su importación:
MistralClient(0.x),from mistralai import Mistral(1.x),from mistralai.client import Mistral(2.x y 3.x) - La 1.0 (ago de 2024) introdujo el cliente
Mistral, los métodos encadenados y el nivel.dataen streaming - La 2.0 (mar de 2026) movió todas las importaciones de Python bajo
mistralai.client, los errores bajomistralai.client.errorsy subió el mínimo a Python 3.10 - La 3.0 (sep de 2026) cambia a
httpx2y reservaweb_searchycode_interpreterpara la API de Conversaciones y los agentes - En TypeScript, la importación no ha cambiado desde la 1.x, pero la 2.0 solo acepta módulos ES