Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Instalar o SDK Python da Mistral

Aula 4 de 14 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Pré-requisitos
  2. Isole o seu projeto antes de instalar qualquer coisa
  3. Instalar o SDK oficial
  4. Verificar a instalação com uma chamada real à API
  5. Tornar o ambiente reproduzível
  6. Quatro falhas comuns e como diagnosticá-las
  7. Pontos-chave

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 Mistral desde 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 mistralai dentro 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.txt para reprodutibilidade
  • É necessário o Python 3.10 ou superior