Instalar o SDK Python da Mistral
Nesta página
Pré-requisitos
Atualizado em 2 de novembro de 2026 — Mistral SDK 3. Esta lição cobria anteriormente a versão 2 do SDK e o Python 3.9. A versão atual é a 3.7.0 (lançada em 1 de novembro de 2026); requer Python 3.10 ou superior, e o cliente é importado através de
from mistralai.client import Mistraldesde a versão 2.0 (março de 2026). Fontes: mistralai no PyPI · notas de lançamento da v2.0.0 · notas de lançamento da v3.0.0.
A instalação do SDK requer três elementos: Python 3.10 ou superior, que pode verificar com python --version; um pip atualizado, obtido via pip install --upgrade pip; e a sua chave de API da Mistral já definida como variável de ambiente, conforme abordado na lição anterior. Se o Python ainda não estiver instalado na sua máquina, obtenha a última versão estável em python.org ou utilize o gestor de pacotes do seu sistema.
Isole o seu projeto antes de instalar qualquer coisa
Trabalhe sempre dentro de um ambiente virtual. Este hábito poupa-o de uma dor de cabeça comum: dois projetos na mesma máquina, onde um requer uma versão específica do SDK e o outro uma versão diferente, e um simples pip install quebra silenciosamente o primeiro projeto ao atualizar o segundo. Um ambiente virtual fornece a cada projeto as suas próprias dependências isoladas, separadas dos pacotes do sistema.
# Criar o ambiente virtual
python -m venv mistral-env
# Ativar no Linux / macOS
source mistral-env/bin/activate
# Ativar no Windows
mistral-env\Scripts\activate
Uma vez ativado, o seu terminal exibirá o nome do ambiente entre parênteses no início do prompt: (mistral-env). Este pequeno marcador garante que os comandos subsequentes se aplicam ao local correto; se não aparecer, não instale nada.
Instalar o SDK oficial
A instalação do SDK da Mistral requer apenas um comando:
pip install mistralai
Isto instala a versão mais recente do SDK: 3.7.0 a partir de 1 de novembro de 2026. A Geração 3 começou com a versão 3.0, lançada em 28 de setembro de 2026. Para confirmar que tudo está no lugar, execute pip show mistralai para exibir o nome do pacote, a versão e as dependências.
Por vezes, um projeto requer uma versão específica, por exemplo, para manter toda a equipa alinhada durante uma migração. Pode especificar restrições em dois níveis:
# Manter-se na geração 3
pip install "mistralai>=3,<4"
# Instalar uma versão exata
pip install "mistralai==3.7.0"
No processo, o pip instala algumas dependências que aparecem na lista. É útil reconhecê-las, particularmente o httpx2, o cliente HTTP que gere as chamadas de rede (o SDK utiliza este em vez do httpx a partir da versão 3.0), e o pydantic, que valida e serializa os dados trocados. Não irá interagir diretamente com estes, mas a sua presença explica por que razão uma instalação que parece pequena ocupa ainda assim alguns megabytes.
Verificar a instalação com uma chamada real à API
Executar pip show prova que o pacote existe, não que a sua configuração funciona. O teste real consulta a API. Crie um ficheiro chamado test_mistral.py:
import os
from mistralai.client import Mistral
api_key = os.environ.get("MISTRAL_API_KEY")
if not api_key:
print("Error: MISTRAL_API_KEY environment variable is not set.")
else:
client = Mistral(api_key=api_key)
print("Mistral client initialized successfully!")
# List available models
models = client.models.list()
print(f"Available models: {len(models.data)}")
for model in models.data[:5]:
print(f" - {model.id}")
Depois execute-o:
python test_mistral.py
Este script verifica duas coisas de uma vez. A verificação da api_key distingue imediatamente uma variável de ambiente em falta de um problema de rede genuíno; sem ela, poderia passar dez minutos a suspeitar da sua firewall quando o terminal foi simplesmente reaberto sem a variável. Se a lista de modelos for exibida, o SDK está instalado corretamente e a sua chave foi aceite pela API.
Tornar o ambiente reproduzível
Num projeto de equipa, a instalação deve ser reproduzível. Congele as suas dependências:
pip freeze > requirements.txt
Os seus colegas podem então reconstruir exatamente o mesmo ambiente com um único comando:
pip install -r requirements.txt
O seu servidor de implantação também lerá este ficheiro. Adote o hábito de o regenerar sempre que adicionar uma biblioteca; caso contrário, o código funcionará na sua máquina e em mais lado nenhum.
Quatro falhas comuns e como diagnosticá-las
O erro ModuleNotFoundError: No module named mistralai significa quase sempre que o terminal não está a usar o ambiente virtual correto. Verifique isto com which python, que deve apontar para o seu venv, e depois com pip list | grep mistralai.
O erro ImportError: cannot import name 'Mistral' from 'mistralai' indica código escrito para a versão 1 do SDK. Desde a versão 2.0, todas as importações passam por mistralai.client: escreva from mistralai.client import Mistral. A lição sobre versões do SDK detalha outras alterações.
Um erro de SSL ou de rede revela frequentemente um proxy corporativo situado entre si e o mundo exterior. Indique-o explicitamente ao pip:
pip install mistralai --proxy http://proxy.entreprise.com:8080
Finalmente, se a instalação rejeitar a sua versão do Python, lembre-se de que o SDK requer no mínimo o Python 3.10 desde a versão 2.0. Atualize o Python ou instale o pyenv para executar múltiplas versões lado a lado sem tocar no interpretador do sistema.
Pontos-chave
- Instale o SDK com
pip install mistralaidentro de um ambiente virtual - A versão atual é a 3.7.0 (1 de novembro de 2026); importe o cliente via
from mistralai.client import Mistral - Verifique a instalação listando os modelos disponíveis
- Congele as dependências em
requirements.txtpara reprodutibilidade - É necessário o Python 3.10 ou superior