> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monostate.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Instalação

> Configure o AI Training no seu sistema

# Instalando o AI Training

Este guia vai te orientar na instalação do AI Training no seu computador. O processo leva cerca de 5-10 minutos.

## O Que Você Vai Obter

Quando você instala o AI Training com `pip` ou `uv`, você obtém:

* **Interface de Linha de Comando** - O comando `aitraining` para treinar modelos
* **Interface de Chat** - Teste e interaja com seus modelos treinados via navegador
* **API Python** - Importe e use em seus scripts Python

Todas as interfaces estão incluídas em uma única instalação de pacote.

## Pré-requisitos

Antes de instalar o AI Training, você precisa do Python no seu sistema. Python é uma linguagem de programação na qual o AI Training executa.

### Verificar se o Python Está Instalado

Abra seu terminal (Mac) ou Prompt de Comando (Windows) e digite:

```bash theme={null}
python --version
```

Se você ver um número de versão como `Python 3.8.0` ou superior, está tudo certo. O AI Training requer Python 3.8 ou mais recente (3.10+ recomendado).

Se você receber um erro ou tiver uma versão mais antiga, siga os passos de instalação abaixo.

## Instalando o Python

<Tabs>
  <Tab title="Windows">
    ### Instalação no Windows

    1. **Baixar Python**
       * Acesse [python.org/downloads](https://www.python.org/downloads/)
       * Clique no botão amarelo "Download Python"
       * Salve o instalador

    2. **Executar o Instalador**
       * Clique duas vezes no arquivo baixado
       * **Importante**: Marque "Add Python to PATH" na parte inferior
       * Clique em "Install Now"
       * Aguarde a instalação completar

    3. **Verificar Instalação**
       * Abra o Prompt de Comando (procure por "cmd" no menu Iniciar)
       * Digite: `python --version`
       * Você deve ver a versão do Python

    4. **Instalar pip (se necessário)**
       * pip geralmente vem com Python, mas verifique:
       ```bash theme={null}
       pip --version
       ```
       * Se não encontrado, execute:
       ```bash theme={null}
       python -m ensurepip --upgrade
       ```
  </Tab>

  <Tab title="Mac">
    ### Instalação no Mac

    1. **Usando Homebrew (Recomendado)**

       Se você não tem Homebrew, instale primeiro:

       ```bash theme={null}
       /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
       ```

       Então instale Python:

       ```bash theme={null}
       brew install python@3.11
       ```

    2. **Alternativa: Download Direto**
       * Acesse [python.org/downloads](https://www.python.org/downloads/)
       * Baixe o instalador macOS
       * Execute o instalador

    3. **Verificar Instalação**
       * Abra o Terminal (encontre em Applications > Utilities)
       * Digite: `python3 --version`
       * Você deve ver a versão do Python

    4. **Instalar pip (se necessário)**
       * pip geralmente vem com Python, mas verifique:
       ```bash theme={null}
       pip3 --version
       ```
  </Tab>

  <Tab title="Linux">
    ### Instalação no Linux

    A maioria das distribuições Linux vem com Python. Se não:

    **Ubuntu/Debian:**

    ```bash theme={null}
    sudo apt update
    sudo apt install python3 python3-pip
    ```

    **Fedora:**

    ```bash theme={null}
    sudo dnf install python3 python3-pip
    ```

    **Arch:**

    ```bash theme={null}
    sudo pacman -S python python-pip
    ```
  </Tab>
</Tabs>

## Instalando o AI Training

Uma vez que o Python está pronto, você tem duas opções para instalar o AI Training. Recomendamos usar `uv` para instalação mais rápida.

### Opção 1: Usando uv (Recomendado)

uv é um instalador de pacotes Python moderno que é muito mais rápido que pip e gerencia ambientes virtuais automaticamente.

#### Instale uv primeiro:

<Tabs>
  <Tab title="Windows">
    ```bash theme={null}
    # Using PowerShell (as administrator)
    powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
    ```
  </Tab>

  <Tab title="Mac/Linux">
    ```bash theme={null}
    curl -LsSf https://astral.sh/uv/install.sh | sh
    ```
  </Tab>
</Tabs>

#### Então instale o AI Training:

```bash theme={null}
# uv cria e gerencia automaticamente um ambiente virtual
uv pip install aitraining
```

Pronto! O uv gerencia o ambiente virtual para você automaticamente.

### Opção 2: Usando pip (Método tradicional)

Se você prefere a abordagem tradicional ou não consegue instalar uv:

#### Passo 1: Criar um Ambiente Virtual

Um ambiente virtual mantém os arquivos do AI Training separados de outros projetos Python.

<Tabs>
  <Tab title="Windows">
    ```bash theme={null}
    python -m venv aitraining-env
    aitraining-env\Scripts\activate
    ```
  </Tab>

  <Tab title="Mac/Linux">
    ```bash theme={null}
    python3 -m venv aitraining-env
    source aitraining-env/bin/activate
    ```
  </Tab>
</Tabs>

Você verá `(aitraining-env)` no seu terminal quando o ambiente estiver ativo.

#### Passo 2: Instalar o AI Training

```bash theme={null}
pip install aitraining
```

Isso baixa e instala o AI Training do PyPI com todas as suas dependências (incluindo PyTorch).

### Passo 3: Verificar Instalação

Verifique se tudo foi instalado corretamente:

```bash theme={null}
aitraining --version
```

Você deve ver o número da versão do AI Training.

## Escolha Sua Interface

O AI Training oferece três formas de trabalhar:

<CardGroup cols={3}>
  <Card title="Linha de Comando" icon="terminal" href="/cli/installation-setup">
    **Melhor para treinamento**

    Treine modelos com comandos. Bom para scripts e automação.

    Comece com: `aitraining --help`
  </Card>

  <Card title="Interface de Chat" icon="message" href="/chat/launching">
    **Melhor para testes**

    Teste seus modelos treinados interativamente em um navegador.

    Comece com: `aitraining chat`
  </Card>

  <Card title="API Python" icon="code" href="/api/introduction">
    **Melhor para desenvolvedores**

    Integre treinamento em suas aplicações Python.

    Comece com: `from autotrain.trainers.clm.params import LLMTrainingParams`
  </Card>
</CardGroup>

## Dependências Opcionais

Alguns recursos requerem pacotes adicionais:

| Recurso                      | Pacote         | Instalar                 | Plataforma                                    |
| ---------------------------- | -------------- | ------------------------ | --------------------------------------------- |
| Treinamento LoRA mais rápido | `unsloth`      | `pip install unsloth`    | Linux (apenas SFT, llama/mistral/gemma/qwen2) |
| Flash Attention 2            | `flash-attn`   | `pip install flash-attn` | Linux (CUDA)                                  |
| Treinamento distribuído      | `accelerate`   | Incluído                 | Linux/Mac/Windows                             |
| DeepSpeed Zero-3             | `deepspeed`    | `pip install deepspeed`  | Linux                                         |
| Quantização 4/8-bit          | `bitsandbytes` | Incluído                 | **Apenas Linux**                              |

<Note>
  **Accelerate é necessário** para treinamento multi-GPU e distribuído. Está incluído com o AITraining. DeepSpeed é opcional e fornece otimização de memória Zero-3 para modelos muito grandes.
</Note>

<Warning>
  **Quantização (int4/int8) funciona apenas no Linux.** A biblioteca `bitsandbytes` necessária para `--quantization int4` ou `--quantization int8` não está disponível no Windows ou macOS.
</Warning>

### Configuração de GPU (Opcional)

Para treinamento com GPU NVIDIA, você pode querer reinstalar PyTorch com sua versão específica de CUDA:

```bash theme={null}
# CUDA 11.8
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# CUDA 12.1
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
```

### Configuração Weights & Biases (Opcional)

O AITraining usa W\&B para logging por padrão. Para habilitar:

```bash theme={null}
pip install wandb
wandb login
```

Ou defina a variável de ambiente: `WANDB_API_KEY=your_key`

## Problemas Comuns

<AccordionGroup>
  <Accordion title="'python' não é reconhecido (Windows)">
    Python não está no PATH do seu sistema. Tente:

    * Use `python3` em vez de `python`
    * Reinstale Python e marque "Add Python to PATH"
    * Adicione Python manualmente ao PATH nas Variáveis de Ambiente do Sistema
  </Accordion>

  <Accordion title="Erros de permissão negada">
    No Mac/Linux, você pode precisar usar `sudo`:

    ```bash theme={null}
    sudo pip install aitraining
    ```

    Ou melhor, use um ambiente virtual (mostrado acima).
  </Accordion>

  <Accordion title="pip: comando não encontrado">
    pip não foi instalado com Python. Instale:

    ```bash theme={null}
    python -m ensurepip --upgrade
    ```

    Ou no Linux:

    ```bash theme={null}
    sudo apt install python3-pip
    ```
  </Accordion>

  <Accordion title="Instalação do PyTorch falha">
    * Certifique-se de ter espaço em disco suficiente (PyTorch é grande)
    * Tente atualizar pip primeiro: `pip install --upgrade pip`
    * Para suporte a GPU, certifique-se de que os drivers CUDA estão instalados
  </Accordion>
</AccordionGroup>

## Próximos Passos

Instalação completa! Agora você está pronto para treinar seu primeiro modelo:

<Card title="Tutorial de Início Rápido" icon="play" href="/foundations/quickstart">
  Treine seu primeiro modelo de IA em 10 minutos
</Card>

## Precisa de Ajuda?

* Junte-se à nossa [comunidade Discord](https://discord.gg/monostate) para suporte
* Verifique [problemas no GitHub](https://github.com/monostate/aitraining) para problemas conhecidos
* Envie um e-mail para [support@monostate.ai](mailto:support@monostate.ai) para ajuda direta