Como Usar o Ollama: Guia Completo para Iniciantes sobre LLMs Locais com Ollama

O cenário da inteligência artificial está em constante evolução, com os Grandes Modelos de Linguagem (LLMs) se tornando cada vez mais poderosos e acessíveis. Embora muitos interajam com esses modelos através de serviços baseados na nuvem, há um movimento crescente focado em executá-los diretamente em computadores pessoais. É aqui que entra o Ollama. O Ollama é uma ferramenta potente, porém fácil de usar, projetada para simplificar drasticamente o complexo processo de baixar, configurar e executar LLMs de ponta como Llama 3, Mistral, Gemma, Phi e muitos outros, localmente.

Este guia abrangente serve como seu ponto de partida para dominar o Ollama. Percorreremos desde os passos iniciais de instalação e interações básicas com modelos até técnicas de personalização mais avançadas, uso da API e solução de problemas essenciais. Seja você um desenvolvedor buscando integrar IA local em suas aplicações, um pesquisador interessado em experimentar diversas arquiteturas de modelos, ou simplesmente um entusiasta de IA ansioso por explorar o potencial de executar modelos poderosos offline, o Ollama fornece um portal excepcionalmente otimizado e eficiente.

💡

Quer uma ótima ferramenta de Teste de API que gera documentação de API bonita?

Quer uma plataforma integrada, tudo-em-um para sua equipe de desenvolvedores trabalhar em conjunto com máxima produtividade?

Apidog atende todas as suas demandas, e substitui o Postman a um preço muito mais acessível!

botão

Por que escolher o Ollama para Execução Local de LLM?

Antes de mergulhar nos detalhes técnicos, é crucial entender as vantagens convincentes de usar o Ollama para operação local de LLM. Por que optar por essa abordagem em vez de depender unicamente das APIs na nuvem prontamente disponíveis?

Privacidade e Segurança Incomparáveis com o Ollama: Quando você executa um LLM usando o Ollama em sua máquina, cada pedaço de dado – seus prompts, os documentos que você fornece e o texto gerado pelo modelo – permanece confinado inteiramente ao seu sistema local. Ele nunca sai do seu hardware. Isso garante o mais alto nível de privacidade e controle de dados, um fator crítico ao lidar com informações pessoais sensíveis, dados comerciais confidenciais ou pesquisa proprietária.
Economia de Custos Significativa através do Ollama: APIs de LLM baseadas na nuvem frequentemente operam em modelos de pagamento por uso ou exigem taxas de assinatura contínuas. Esses custos podem acumular rapidamente, especialmente com uso intensivo. O Ollama elimina essas despesas recorrentes. Além do investimento inicial em hardware adequado (que você já pode possuir), executar modelos localmente é efetivamente gratuito, permitindo experimentação e geração ilimitadas sem a preocupação iminente das contas de API.
Verdadeira Capacidade Offline com o Ollama: Uma vez que um modelo Ollama é baixado para seu armazenamento local, ele é seu para usar a qualquer hora, em qualquer lugar, completamente independente de uma conexão com a internet. Este acesso offline é inestimável para desenvolvedores trabalhando em ambientes com conectividade restrita, pesquisadores em campo, ou qualquer pessoa que precise de acesso confiável à IA em movimento.
Personalização Profunda e Experimentação via Modelfiles do Ollama: O Ollama se distingue por seu poderoso sistema Modelfile. Isso permite aos usuários modificar facilmente o comportamento do modelo ajustando parâmetros (como níveis de criatividade ou comprimento da saída), definindo prompts de sistema personalizados para moldar a persona da IA, ou até mesmo integrando adaptadores especializados afinados (LoRAs). Você também pode importar pesos de modelos diretamente de formatos padrão como GGUF ou Safetensors. Este nível granular de controle e flexibilidade raramente é oferecido por provedores de API na nuvem de código fechado.
Vantagens Potenciais de Desempenho com o Ollama: Dependendo da configuração do seu hardware local, particularmente a presença de uma Unidade de Processamento Gráfico (GPU) capaz, o Ollama pode entregar tempos de resposta (velocidade de inferência) significativamente mais rápidos em comparação com serviços na nuvem, que podem estar sujeitos à latência da rede, limitação de taxa ou carga variável em recursos compartilhados. Aproveitar seu hardware dedicado pode levar a uma experiência muito mais fluida e interativa.
Engajamento com o Vibrante Ecossistema Open Source do Ollama: O Ollama em si é um projeto de código aberto, fomentando a transparência e a contribuição da comunidade. Além disso, serve principalmente como um portal para uma vasta e rapidamente expansível biblioteca de LLMs abertamente acessíveis. Ao usar o Ollama, você se torna parte deste ecossistema dinâmico, beneficiando-se do conhecimento compartilhado, suporte da comunidade e da constante inovação impulsionada pela colaboração aberta.

A principal conquista do Ollama é mascarar as complexidades inerentes envolvidas na configuração dos ambientes de software necessários, gerenciamento de dependências e configuração dos intrincados ajustes necessários para executar esses sofisticados modelos de IA. Ele utiliza habilmente motores de inferência de backend altamente otimizados, notavelmente a renomada biblioteca llama.cpp, para garantir uma execução eficiente em hardware de consumidor padrão, suportando aceleração tanto por CPU quanto por GPU.

Entendendo Ollama vs. Llama.cpp

É benéfico esclarecer a relação entre Ollama e llama.cpp, pois estão intimamente relacionados, mas servem a propósitos diferentes.

llama.cpp: Esta é a biblioteca C/C++ fundamental e de alto desempenho responsável pela tarefa central de inferência de LLM. Ela lida com o carregamento de pesos do modelo, processamento de tokens de entrada e geração eficiente de tokens de saída, com otimizações para diversas arquiteturas de hardware (conjuntos de instruções de CPU como AVX, aceleração de GPU via CUDA, Metal, ROCm). É o motor potente que realiza o trabalho pesado computacional.
Ollama: Esta é uma aplicação abrangente construída em torno do llama.cpp (e potencialmente outros backends futuros). O Ollama fornece uma camada amigável por cima, oferecendo:
Uma Interface de Linha de Comando (CLI) simples para fácil interação (ollama run, ollama pull, etc.).
Um servidor API REST embutido para integração programática.
Gerenciamento de modelos otimizado (download de uma biblioteca, armazenamento local, atualizações).
O sistema Modelfile para personalização e criação de variantes de modelos.
Instaladores multiplataforma (macOS, Windows, Linux) e imagens Docker.
Detecção e configuração automática de hardware (CPU/GPU).

Em essência, embora tecnicamente você pudesse usar llama.cpp diretamente compilando-o e executando suas ferramentas de linha de comando, isso requer um esforço técnico significativamente maior em relação à configuração, conversão de modelos e gerenciamento de parâmetros. O Ollama empacota essa potência em uma aplicação acessível e fácil de usar, tornando os LLMs locais práticos para um público muito mais amplo, especialmente para iniciantes. Pense no llama.cpp como os componentes do motor de alto desempenho, e no Ollama como o veículo totalmente montado e amigável, pronto para dirigir.

Instalando o Ollama em seu Sistema

O Ollama é projetado para acessibilidade, oferecendo procedimentos de instalação diretos para macOS, Windows, Linux e ambientes Docker.

Requisitos Gerais do Sistema para o Ollama:

RAM (Memória): Este é frequentemente o fator mais crítico.
Mínimo 8 GB: Suficiente para modelos menores (ex., 1B, 3B, 7B parâmetros), embora o desempenho possa ser lento.
Recomendado 16 GB: Um bom ponto de partida para executar modelos de 7B e 13B confortavelmente.
Ideal 32 GB ou mais: Necessário para modelos maiores (30B, 40B, 70B+) e permite janelas de contexto maiores. Mais RAM geralmente leva a um melhor desempenho e à capacidade de executar modelos maiores e mais capazes.
Espaço em Disco: A aplicação Ollama em si é relativamente pequena (algumas centenas de MB). No entanto, os LLMs que você baixa exigem espaço considerável. Os tamanhos dos modelos variam enormemente:
Modelos Quantizados Pequenos (ex., ~3B Q4): ~2 GB
Modelos Quantizados Médios (ex., 7B/8B Q4): 4-5 GB
Modelos Quantizados Grandes (ex., 70B Q4): ~40 GB
Modelos Muito Grandes (ex., 405B): Mais de 200 GB!
Certifique-se de ter espaço livre suficiente na unidade onde o Ollama armazena os modelos (veja a seção abaixo).
Sistema Operacional:
macOS: Versão 11 Big Sur ou posterior. Apple Silicon (M1/M2/M3/M4) é recomendado para aceleração de GPU.
Windows: Windows 10 versão 22H2 ou posterior, ou Windows 11. Ambas as edições Home e Pro são suportadas.
Linux: Uma distribuição moderna (ex., Ubuntu 20.04+, Fedora 38+, Debian 11+). Requisitos do kernel podem ser aplicáveis, especialmente para suporte de GPU AMD.

Instalando o Ollama no macOS

Download: Obtenha o arquivo DMG da aplicação Ollama para macOS diretamente do site oficial do Ollama.
Montar: Dê um duplo clique no arquivo .dmg baixado para abri-lo.
Instalar: Arraste o ícone Ollama.app para sua pasta de Aplicativos.
Executar: Abra a aplicação Ollama da sua pasta de Aplicativos. Pode ser necessário conceder permissão para executá-la na primeira vez.
Serviço em Segundo Plano: O Ollama começará a ser executado como um serviço em segundo plano, indicado por um ícone na sua barra de menus. Clicar neste ícone fornece opções para sair da aplicação ou visualizar os logs.

Ao iniciar a aplicação, o processo do servidor Ollama é iniciado automaticamente e a ferramenta de linha de comando ollama é adicionada ao PATH do seu sistema, tornando-a imediatamente disponível na aplicação Terminal (Terminal.app, iTerm2, etc.). Em Macs equipados com Apple Silicon (chips M1, M2, M3, M4), o Ollama utiliza perfeitamente a GPU integrada para aceleração via API gráfica Metal da Apple sem requerer nenhuma configuração manual.

Instalando o Ollama no Windows

Download: Obtenha o arquivo instalador OllamaSetup.exe do site do Ollama.
Executar Instalador: Dê um duplo clique no arquivo .exe baixado para iniciar o assistente de configuração. Certifique-se de atender ao requisito mínimo de versão do Windows (10 22H2+ ou 11).
Seguir Instruções: Prossiga pelas etapas de instalação, aceitando o contrato de licença e escolhendo o local de instalação, se desejado (embora o padrão geralmente esteja bom).

O instalador configura o Ollama para ser executado automaticamente como um serviço em segundo plano quando o sistema inicia. Ele também adiciona o executável ollama.exe ao PATH do seu sistema, permitindo que você use o comando ollama em terminais padrão do Windows como o Prompt de Comando (cmd.exe), PowerShell ou o novo Terminal do Windows. O servidor API do Ollama inicia automaticamente e escuta em http://localhost:11434.

Aceleração de GPU do Ollama para Windows:

NVIDIA: Instale os drivers GeForce Game Ready ou NVIDIA Studio mais recentes do site da NVIDIA. É necessária a versão do driver 452.39 ou posterior. O Ollama deve detectar e utilizar automaticamente GPUs compatíveis.
AMD: Instale os drivers AMD Software: Adrenalin Edition mais recentes do site de suporte da AMD. GPUs Radeon compatíveis (geralmente série RX 6000 e posteriores) serão usadas automaticamente.

Instalando o Ollama no Linux

O método mais conveniente para a maioria das distribuições Linux é usar o script de instalação oficial:

curl -fsSL https://ollama.com/install.sh | sh

Este comando baixa o script e o executa usando sh. O script realiza as seguintes ações:

Detecta a arquitetura do seu sistema (x86_64, ARM64).
Baixa o binário apropriado do Ollama.
Instala o binário em /usr/local/bin/ollama.
Verifica os drivers de GPU necessários (NVIDIA CUDA, AMD ROCm) e instala dependências, se possível (esta parte pode variar por distribuição).
Cria um usuário e grupo do sistema ollama dedicados.
Configura um arquivo de serviço systemd (/etc/systemd/system/ollama.service) para gerenciar o processo do servidor Ollama.
Habilita e inicia o serviço ollama, para que ele seja executado automaticamente na inicialização e em segundo plano.

Instalação Manual do Ollama no Linux e Configuração do Systemd:
Se o script falhar, ou se você preferir controle manual (ex., instalar em um local diferente, gerenciar usuários de forma diferente, garantir versões específicas do ROCm), consulte o guia detalhado de instalação do Linux no repositório GitHub do Ollama. Os passos gerais envolvem:

Baixar o binário correto para sua arquitetura.
Tornar o binário executável (chmod +x ollama) e movê-lo para um local no seu PATH (ex., /usr/local/bin).
(Recomendado) Criar um usuário/grupo do sistema: sudo useradd -r -s /bin/false -m -d /usr/share/ollama ollama e sudo groupadd ollama, depois sudo usermod -a -G ollama ollama. Adicione seu próprio usuário ao grupo: sudo usermod -a -G ollama $USER.
Criar o arquivo de serviço systemd (/etc/systemd/system/ollama.service) com as configurações apropriadas (usuário, grupo, caminho do executável, variáveis de ambiente se necessário). Geralmente são fornecidos trechos de exemplo na documentação.
Recarregar o daemon systemd: sudo systemctl daemon-reload.
Habilitar o serviço para iniciar na inicialização: sudo systemctl enable ollama.
Iniciar o serviço imediatamente: sudo systemctl start ollama. Você pode verificar seu status com sudo systemctl status ollama.

Drivers Essenciais de GPU para o Ollama no Linux:
Para um desempenho ótimo, a instalação de drivers de GPU é altamente recomendada:

NVIDIA: Instale os drivers proprietários oficiais da NVIDIA para sua distribuição (ex., via gerenciador de pacotes como apt ou dnf, ou baixados do site da NVIDIA). Verifique a instalação usando o comando nvidia-smi.
AMD (ROCm): Instale o kit de ferramentas ROCm. A AMD fornece repositórios oficiais e guias de instalação para distribuições suportadas (como Ubuntu, RHEL/CentOS, SLES). Certifique-se de que a versão do seu kernel seja compatível. O script de instalação do Ollama pode lidar com algumas dependências do ROCm, mas a instalação manual garante a configuração correta. Verifique com rocminfo.

Usando a Imagem Docker Oficial do Ollama

O Docker oferece uma maneira agnóstica de plataforma para executar o Ollama em um contêiner isolado, simplificando o gerenciamento de dependências, especialmente para configurações complexas de GPU.

Contêiner Ollama Apenas CPU:

docker run -d \
  -v ollama_data:/root/.ollama \
  -p 127.0.0.1:11434:11434 \
  --name my_ollama \
  ollama/ollama

-d: Executa o contêiner em modo detached (segundo plano).
-v ollama_data:/root/.ollama: Cria um volume nomeado do Docker chamado ollama_data em seu sistema host e o mapeia para o diretório /root/.ollama dentro do contêiner. Isso é crucial para persistir seus modelos baixados. Se omitir isso, os modelos serão perdidos quando o contêiner for removido. Você pode escolher qualquer nome para o volume.
-p 127.0.0.1:11434:11434: Mapeia a porta 11434 na interface loopback da sua máquina host (127.0.0.1) para a porta 11434 dentro do contêiner. Use 0.0.0.0:11434:11434 se precisar acessar o contêiner Ollama de outras máquinas em sua rede.
--name my_ollama: Atribui um nome personalizado e memorável ao contêiner em execução.
ollama/ollama: Especifica a imagem oficial do Ollama do Docker Hub.

Contêiner Ollama com GPU NVIDIA:

Primeiro, certifique-se de que o NVIDIA Container Toolkit esteja corretamente instalado em sua máquina host e que o Docker esteja configurado para usar o runtime da NVIDIA.
Execute o contêiner, adicionando a flag --gpus=all:

docker run -d \
  --gpus=all \
  -v ollama_data:/root/.ollama \
  -p 127.0.0.1:11434:11434 \
  --name my_ollama_gpu \
  ollama/ollama

Esta flag concede ao contêiner acesso a todas as GPUs NVIDIA compatíveis detectadas pelo toolkit. Você pode especificar GPUs particulares se necessário (ex., --gpus '"device=0,1"').

Contêiner Ollama com GPU AMD (ROCm):

Use a tag de imagem específica do ROCm: ollama/ollama:rocm.
Mapeie os nós de dispositivo ROCm necessários do host para o contêiner:

docker run -d \
  --device /dev/kfd \
  --device /dev/dri \
  -v ollama_data:/root/.ollama \
  -p 127.0.0.1:11434:11434 \
  --name my_ollama_rocm \
  ollama/ollama:rocm

/dev/kfd: A interface do driver de fusão do kernel.
/dev/dri: Dispositivos de Infraestrutura de Renderização Direta (frequentemente inclui nós de renderização como /dev/dri/renderD128).
Certifique-se de que o usuário executando o comando docker no host tenha as permissões apropriadas para acessar esses arquivos de dispositivo (pode ser necessária a associação a grupos como render e video).

Uma vez que o contêiner Ollama esteja em execução, você pode interagir com ele usando o comando docker exec para executar comandos CLI do ollama dentro do contêiner:

docker exec -it my_ollama ollama list
docker exec -it my_ollama ollama pull llama3.2
docker exec -it my_ollama ollama run llama3.2

Alternativamente, se você mapeou a porta (-p), pode interagir com a API do Ollama diretamente da sua máquina host ou de outras aplicações que apontam para http://localhost:11434 (ou o IP/porta que você mapeou).

Onde o Ollama armazena modelos? Entendendo os Locais de Armazenamento do Ollama

Saber onde o Ollama guarda seus modelos baixados é essencial para gerenciar o espaço em disco e backups. O local padrão varia por sistema operacional e método de instalação:

Ollama no macOS: Os modelos residem dentro do diretório home do seu usuário em ~/.ollama/models. ~ representa /Users/<SeuNomeDeUsuario>.
Ollama no Windows: Os modelos são armazenados no diretório de perfil do seu usuário em C:\Users\<SeuNomeDeUsuario>\.ollama\models.
Ollama no Linux (Instalação de Usuário / Manual): Similar ao macOS, os modelos são tipicamente armazenados em ~/.ollama/models.
Ollama no Linux (Instalação de Serviço Systemd): Quando instalado via script ou configurado como um serviço para todo o sistema executando como usuário ollama, os modelos são frequentemente armazenados em /usr/share/ollama/.ollama/models. Verifique a configuração do serviço ou a documentação se você usou uma configuração não padrão.
Ollama via Docker: Dentro do contêiner, o caminho é /root/.ollama/models. No entanto, se você usou corretamente a flag -v para montar um volume Docker (ex., -v ollama_data:/root/.ollama), os arquivos reais do modelo são armazenados dentro da área de volumes gerenciados do Docker em sua máquina host. A localização exata dos volumes Docker depende da sua configuração do Docker, mas eles são projetados para persistir independentemente do contêiner.

Você pode redirecionar o local de armazenamento de modelos usando a variável de ambiente OLLAMA_MODELS, que cobriremos na seção de Configuração. Isso é útil se sua unidade primária tem pouco espaço e você prefere armazenar modelos grandes em um SSD dedicado ou unidade maior.

Seus Primeiros Passos com o Ollama: Executando um LLM

Agora que o Ollama está instalado e o servidor está ativo (executando via aplicativo de desktop, serviço systemd ou contêiner Docker), você pode começar a interagir com LLMs usando o comando direto ollama em seu terminal.

Baixando Modelos Ollama: O Comando `pull`

Antes de executar qualquer LLM específico, você deve primeiro baixar seus pesos e arquivos de configuração. O Ollama fornece uma biblioteca curada de modelos abertos populares, facilmente acessíveis através do comando ollama pull. Você pode navegar pelos modelos disponíveis na página da biblioteca do site do Ollama.

# Exemplo 1: Puxar o modelo mais recente Llama 3.2 8B Instruct
# Este é frequentemente marcado como 'latest' ou simplesmente pelo nome base.
ollama pull llama3.2

# Exemplo 2: Puxar uma versão específica do Mistral (7 Bilhões de parâmetros, modelo base)
ollama pull mistral:7b

# Exemplo 3: Puxar o modelo Gemma 3 4B do Google
ollama pull gemma3

# Exemplo 4: Puxar o modelo menor Phi-4 Mini da Microsoft (eficiente)
ollama pull phi4-mini

# Exemplo 5: Puxar um modelo de visão (pode processar imagens)
ollama pull llava

Entendendo as Tags de Modelo Ollama:
Os modelos na biblioteca Ollama utilizam uma convenção de nomenclatura nome_familia_modelo:tag. A tag especifica variações como:

Tamanho: 1b, 3b, 7b, 8b, 13b, 34b, 70b, 405b (indicando bilhões de parâmetros). Modelos maiores geralmente têm mais conhecimento, mas exigem mais recursos.
Quantização: q2_K, q3_K_S, q4_0, q4_K_M, q5_1, q5_K_M, q6_K, q8_0, f16 (float16), f32 (float32). A quantização reduz o tamanho do modelo e as necessidades computacionais, frequentemente com uma pequena perda de precisão. Números menores (ex., q4) significam mais compressão. Variantes K (_K_S, _K_M, _K_L) são geralmente consideradas um bom equilíbrio entre tamanho e qualidade. f16/f32 não são quantizados ou são minimamente comprimidos, oferecendo a maior fidelidade, mas exigindo mais recursos.
Variante: instruct (ajustado para seguir instruções), chat (ajustado para conversação), code (otimizado para tarefas de programação), vision (multimodal, lida com imagens), uncensored (menos filtragem de segurança, use com responsabilidade).
latest: Se você omitir uma tag (ex., ollama pull llama3.2), o Ollama normalmente assume a tag latest por padrão, que geralmente aponta para uma versão comumente usada e bem equilibrada (frequentemente um modelo de tamanho médio, quantizado e ajustado para instruções).

O comando pull baixa os arquivos necessários (que podem ter vários gigabytes) para o diretório de modelos Ollama designado. Você só precisa puxar uma combinação modelo:tag específica uma vez. O Ollama também pode atualizar modelos; executar pull novamente em um modelo existente baixará apenas as camadas alteradas (diferenças), tornando as atualizações eficientes.

Chat Interativo com Modelos Ollama: O Comando `run`

A maneira mais direta de conversar com um modelo baixado é usando o comando ollama run:

ollama run llama3.2

Se o modelo especificado (llama3.2:latest neste caso) ainda não foi puxado, ollama run convenientemente acionará ollama pull primeiro. Assim que o modelo estiver pronto e carregado na memória (o que pode levar alguns segundos, especialmente para modelos maiores), você será apresentado a um prompt interativo:

>>> Envie uma mensagem (/? para ajuda)

Agora, você pode simplesmente digitar sua pergunta ou instrução, pressionar Enter e esperar que a IA gere uma resposta. A saída normalmente flui token por token, proporcionando uma sensação responsiva.

>>> Explique o conceito de emaranhamento quântico em termos simples.
Ok, imagine que você tem duas moedas especiais que estão ligadas de uma forma mágica. Vamos chamá-las de Moeda A e Moeda B. Antes de olhar para elas, nenhuma moeda é cara ou coroa – elas estão em uma mistura nebulosa de ambas as possibilidades.

Agora, você dá a Moeda A para um amigo e viaja anos-luz de distância com a Moeda B. No instante em que você olha para sua Moeda B e vê que é, digamos, cara, você instantaneamente sabe *com certeza* que a Moeda A do seu amigo é coroa. E se você visse coroa, saberia que a deles é cara.

Isso é meio como o emaranhamento quântico! Duas partículas (como nossas moedas) ficam ligadas, e suas propriedades (como cara/coroa) permanecem correlacionadas, não importa o quão distantes estejam. Medir uma influencia instantaneamente a propriedade da outra, mais rápido do que a luz poderia viajar entre elas. É uma das partes mais estranhas e legais da física quântica!

>>> Envie uma mensagem (/? para ajuda)

Comandos Úteis dentro do Modo Interativo do Ollama:
Ao interagir com um modelo via ollama run, você pode usar comandos especiais prefixados com /:

/?: Exibe um menu de ajuda listando todos os comandos de barra disponíveis.
/set parameter <nome_parametro> <valor>: Modifica temporariamente um parâmetro de tempo de execução do modelo para a sessão de chat atual. Por exemplo, /set parameter temperature 0.9 aumenta a criatividade, enquanto /set parameter num_ctx 8192 aumenta a janela de contexto para esta sessão.
/show info: Imprime informações detalhadas sobre o modelo atualmente carregado, incluindo seus parâmetros, estrutura de template e licença.
/show modelfile: Exibe o conteúdo do Modelfile que foi usado para criar o modelo atualmente em execução. Isso é útil para entender seu modelo base, parâmetros e template de prompt.
/save <nome_sessao>: Salva o histórico de chat atual em um arquivo de sessão nomeado.
/load <nome_sessao>: Carrega uma sessão de chat previamente salva, restaurando o histórico da conversa.
/bye ou /exit: Sai graciosamente da sessão de chat interativa e descarrega o modelo da memória (se nenhuma outra sessão estiver usando). Você também pode geralmente sair usando Ctrl+D.

Gerenciando seus Modelos Ollama Locais

À medida que você baixa e cria modelos, precisará de maneiras de gerenciá-los:

Listando Modelos Ollama Baixados: Para ver todos os modelos atualmente armazenados localmente, use:

ollama list

Este comando exibe uma tabela mostrando o nome do modelo (NAME), ID único, tamanho em disco (SIZE) e tempo de modificação (MODIFIED).

Mostrando Informações Detalhadas do Modelo Ollama: Para inspecionar os detalhes de um modelo específico (seus parâmetros, prompt do sistema, template, etc.), use:

ollama show llama3.2:8b-instruct-q5_K_M

Isso imprimirá o conteúdo do Modelfile, configurações de parâmetros, detalhes do template e outros metadados associados a essa tag de modelo específica.

Removendo um Modelo Ollama: Se você não precisar mais de um modelo e quiser liberar espaço em disco, use:

ollama rm mistral:7b

Isso exclui permanentemente a combinação modelo:tag especificada do seu armazenamento. Use com cautela!

Copiando/Renomeando um Modelo Ollama: Para criar uma duplicata de um modelo existente, talvez como ponto de partida para personalização ou simplesmente para dar um nome diferente, use:

ollama cp llama3.2 minha-config-llama3.2-personalizada

Isso cria uma nova entrada de modelo chamada minha-config-llama3.2-personalizada baseada no llama3.2 original.

Verificando Modelos Ollama Atualmente Carregados: Para ver quais modelos estão ativamente carregados em sua RAM ou VRAM e prontos para inferência imediata, use:

ollama ps

Este comando mostra o nome do modelo, ID, tamanho, processador usado (CPU/GPU) e há quanto tempo foi acessado pela última vez. Os modelos geralmente permanecem carregados por um curto período após o uso (ex., 5 minutos) para acelerar solicitações subsequentes, depois descarregam automaticamente para liberar recursos.

Quais são os melhores modelos Ollama? Selecionando o LLM Certo

Esta é uma pergunta frequente e importante, mas a resposta é sutil. Não existe um único modelo Ollama "melhor" para todos ou para todas as tarefas. A escolha ideal depende de vários fatores:

Sua Tarefa Específica: O que você quer principalmente que a IA faça?
Chat/Assistência Geral: llama3.2, llama3.1, mistral, gemma3, qwq são fortes concorrentes.
Codificação/Programação: codellama, phi4, phi4-mini, starcoder2, deepseek-coder são especificamente ajustados para geração, explicação e depuração de código.
Escrita Criativa: Modelos com temperaturas padrão mais altas ou maior contagem de parâmetros (como modelos 70B) podem render resultados mais imaginativos. A experimentação é fundamental.
Sumarização/Análise: Modelos ajustados para instruções (tag :instruct) frequentemente se destacam aqui.
Multimodal (Entrada de Imagem): llava, moondream, llama3.2-vision.
Seus Recursos de Hardware (RAM e VRAM): Esta é uma grande restrição.
Recursos Baixos (8GB RAM, Sem/GPU Fraca): Atenha-se a modelos menores (parâmetros 1B-3B) ou versões fortemente quantizadas (ex., q2_K, q3_K_S) de modelos 7B. O desempenho será mais lento. Exemplos: gemma3:1b, llama3.2:1b, phi4-mini:q4_0.
Recursos de Médio Alcance (16GB RAM, GPU Básica): Você pode executar confortavelmente modelos 7B/8B (ex., llama3.2, mistral, gemma3) com boa quantização (q4_K_M, q5_K_M). Você pode conseguir executar modelos 13B (q4_0) lentamente.
Recursos de Ponta (32GB+ RAM, GPU Forte com 12GB+ VRAM): Você pode executar modelos maiores como 13B, 30B ou até 70B (quantização q4_K_M ou melhor como q5_K_M, q6_K). Estes oferecem raciocínio e conhecimento significativamente melhores. Exemplos: llama3.3, llama3.1:405b (exige recursos massivos), gemma3:27b, deepseek-r1:671b (requisitos extremos).
Compromisso Desejado Qualidade vs. Velocidade:
Maior Qualidade: Maior contagem de parâmetros e quantização menos agressiva (ex., q6_K, q8_0, f16) geralmente fornecem melhores resultados, mas são mais lentos e exigem mais recursos.
Maior Velocidade/Menor Uso de Recursos: Menor contagem de parâmetros e quantização mais agressiva (ex., q4_0, q4_K_M, q3_K_M) são mais rápidos e leves, mas podem exibir coerência ou precisão ligeiramente reduzidas. Quantizações K (_K_M, _K_S) frequentemente fornecem o melhor equilíbrio.
Ajuste e Alinhamento do Modelo: Alguns modelos são modelos base, enquanto outros são ajustados para instruções (instruct) ou ajustados para chat (chat). Modelos Instruct/chat geralmente são melhores em seguir direções e engajar em conversas. Modelos não censurados têm menos barreiras de segurança.

Recomendações para Iniciantes (Final de 2024):

Bom para Tudo (Hardware de Médio Alcance): llama3.2:8b-instruct-q5_K_M ou mistral:7b-instruct-v0.2-q5_K_M. Estes oferecem um ótimo equilíbrio de capacidade, velocidade e uso de recursos.
Opção Eficiente (Hardware de Baixa Gama): phi4-mini:q4_K_M ou gemma3:1b. Surpreendentemente capazes para seu tamanho.
Foco em Codificação: codellama:7b-instruct-q5_K_M.
Necessidades de Visão: llava:13b (se os recursos permitirem) ou moondream.

A melhor abordagem é empírica: Leia as descrições dos modelos na biblioteca Ollama, considere seu hardware, baixe alguns candidatos prováveis usando ollama pull, teste-os com seus prompts típicos usando ollama run, e veja qual deles tem o melhor desempenho para você. Não hesite em usar ollama rm em modelos que não atendam às suas necessidades para economizar espaço.

Desmistificando Conceitos de Modelos Ollama

Para usar e personalizar o Ollama eficazmente, ajuda entender alguns conceitos centrais de LLM.

Parâmetros de Modelo Ollama Explicados

LLMs têm configurações internas, ou parâmetros, que você pode ajustar para influenciar como eles geram texto. O Ollama permite controlar muitos destes:

temperature: (Padrão: ~0.7-0.8) Controla a aleatoriedade ou "criatividade" da saída.
Valores mais baixos (ex., 0.2): Tornam a saída mais determinística, focada e previsível. Bom para respostas factuais ou geração de código.
Valores mais altos (ex., 1.0, 1.2): Aumentam a aleatoriedade, tornando a saída mais diversa e criativa, mas potencialmente menos coerente. Bom para brainstorming ou escrita de histórias.
top_p (Amostragem Nucleus): (Padrão: ~0.9) Define um limiar de probabilidade. O modelo considera apenas os próximos tokens mais prováveis cuja massa de probabilidade acumulada excede top_p. Diminuir top_p (ex., 0.5) restringe as escolhas a palavras mais prováveis, aumentando a coerência mas potencialmente reduzindo a novidade. Valores mais altos permitem escolhas mais diversas.
top_k: (Padrão: ~40) Limita as escolhas do modelo aos k próximos tokens mais prováveis. Um top_k mais baixo (ex., 10) torna a saída mais focada; um top_k mais alto permite mais variedade. top_p é frequentemente considerado mais eficaz que top_k. Geralmente, você define um ou outro, não ambos baixos.
num_predict: (Padrão: ~128, -1 para infinito) Número máximo de tokens (aproximadamente palavras/sub-palavras) que o modelo gerará em uma única resposta. Defina como -1 para geração ilimitada até que uma condição de parada seja atendida.
stop: Uma lista de sequências de texto específicas. Se o modelo gerar uma dessas sequências, ele imediatamente parará de produzir mais saídas. Útil para prevenir frases corridas ou garantir que o modelo pare após responder. Exemplo: ["\n", "User:", "<|eot_id|>"].
num_ctx: Define o tamanho da janela de contexto do modelo. Veja explicação detalhada abaixo.
Outros parâmetros: O Ollama expõe muitos outros parâmetros herdados do llama.cpp (como repeat_penalty, seed, mirostat, camadas de GPU num_gpu, etc.) para controle refinado. Consulte a documentação do Ollama e llama.cpp para detalhes.

Você pode definir estes temporariamente usando /set parameter em ollama run, permanentemente em um Modelfile usando a instrução PARAMETER, ou por requisição através do objeto options na API Ollama.

Comprimento de Contexto Ollama: O Parâmetro `num_ctx`

O comprimento de contexto, frequentemente referido como janela de contexto ou num_ctx nas configurações do Ollama e llama.cpp, é uma das limitações arquitetônicas mais críticas de um LLM.

O que representa: num_ctx define o número máximo de tokens que o modelo pode "ver" ou processar simultaneamente. Isso inclui tudo: o prompt inicial do sistema, todas as mensagens anteriores do usuário e respostas do assistente no histórico de chat atual, e o prompt de entrada mais recente do usuário.
Por que é crucial: A capacidade de um modelo gerar respostas relevantes, coerentes e contextualmente apropriadas depende fortemente de sua janela de contexto.
Conversas Longas: Uma janela de contexto maior permite que o modelo "lembre" informações de partes anteriores da conversa, evitando que perca o fio ou se repita.
Análise de Documentos: Ao processar documentos grandes (ex., para sumarização ou resposta a perguntas), a janela de contexto determina quanto do documento o modelo pode considerar de uma vez.
Instruções Complexas: Instruções que dependem de detalhes fornecidos muito antes no prompt exigem uma janela de contexto suficiente para serem entendidas corretamente.
Limites Inerentes do Modelo: Todo LLM é pré-treinado com um comprimento de contexto máximo específico (ex., 2048, 4096, 8192, 32k, 128k, ou até milhões para modelos de pesquisa de ponta). Embora você possa definir num_ctx no Ollama, defini-lo acima do limite de treinamento original do modelo pode levar a comportamento imprevisível, desempenho degradado (o modelo pode "esquecer" coisas fora de sua janela treinada) ou erros. Defini-lo mais baixo é sempre seguro, mas limita a capacidade do modelo.
Consumo de Recursos: Processar uma janela de contexto maior exige significativamente mais RAM e VRAM (memória da GPU) e leva mais tempo computacionalmente. Você precisa equilibrar a capacidade de contexto desejada com as limitações do seu hardware.
Encontrando o num_ctx Padrão para um Modelo Ollama: Use o comando ollama show <nome_modelo:tag> e procure a linha PARAMETER num_ctx na seção Modelfile exibida. Modelos Ollama geralmente vêm com um padrão razoável (ex., 4096 ou 8192).
Alterando o num_ctx para Ollama:
Temporariamente (durante ollama run): Use o comando de barra: /set parameter num_ctx 8192
Por Requisição API: Inclua-o no objeto JSON options: curl ... -d '{ "model": "...", "prompt": "...", "options": { "num_ctx": 8192 } }'
Persistentemente (Modelo Ollama Personalizado): Crie ou modifique um Modelfile e adicione ou altere a linha PARAMETER num_ctx <valor>, depois construa o modelo usando ollama create. Isso define o tamanho de contexto padrão para aquele modelo personalizado.

Escolha um valor num_ctx que se adapte às suas tarefas típicas. Para Q&A simples, uma janela menor (ex., 4096) pode ser suficiente. Para chats longos ou sumarização de documentos grandes, você se beneficiará da maior janela de contexto que seu hardware e o modelo podem suportar razoavelmente (ex., 8192, 16384, ou mais se disponível).

Ollama Avançado: Liberando a API e a Personalização

Enquanto a CLI ollama oferece fácil interação direta, o verdadeiro potencial para integrar o Ollama em fluxos de trabalho e aplicações reside em sua API REST embutida e no sistema de personalização Modelfile.

Interagindo Programaticamente com a API Ollama

Por padrão, o processo do servidor Ollama (seja executando via aplicativo de desktop, systemd ou Docker) escuta por requisições HTTP entrantes na porta 11434 de sua máquina local (http://localhost:11434 ou http://127.0.0.1:11434). Esta API permite que outros programas, scripts ou interfaces web executando na mesma máquina (ou outras na rede, se configurado) interajam com modelos Ollama programaticamente.

Pontos de Extremidade Chave da API Ollama:

POST /api/generate: Usado para gerar completudes de texto baseadas em um único prompt não conversacional. Adequado para tarefas como expansão de texto, tradução simples ou snippets de código rápidos. Requer um corpo JSON com model e prompt.
POST /api/chat: Projetado para interações conversacionais. Aceita uma lista de mensagens, cada uma com um role (system, user ou assistant) e content. Isso permite que o modelo mantenha o contexto ao longo de múltiplos turnos. Requer um corpo JSON com model e messages.
POST /api/embeddings: Gera representações vetoriais numéricas (embeddings) para texto de entrada. Estes vetores capturam significado semântico e são fundamentais para tarefas como Geração Aumentada por Recuperação (RAG), busca semântica, classificação de texto e agrupamento. Requer um corpo JSON com model e prompt.
GET /api/tags: Recupera uma lista de todos os modelos atualmente disponíveis em seu armazenamento local Ollama (equivalente a ollama list). Retorna um array JSON de objetos de modelo.
POST /api/show: Busca informações detalhadas sobre um modelo local específico, incluindo seus parâmetros, template, licença, etc. (equivalente a ollama show). Requer um corpo JSON com name (modelo:tag).
DELETE /api/delete: Remove um modelo especificado do armazenamento local (equivalente a ollama rm). Requer um corpo JSON com name (modelo:tag).
POST /api/pull: Inicia o download de um modelo da biblioteca Ollama (equivalente a ollama pull). Requer um corpo JSON com name (modelo:tag). Também pode transmitir informações de progresso.
POST /api/create: Cria um novo modelo personalizado baseado em um conteúdo de Modelfile fornecido (equivalente a ollama create -f). Requer um corpo JSON com name (novo nome do modelo) e modelfile (o conteúdo do Modelfile como uma string).
POST /api/copy: Duplica um modelo local existente sob um novo nome (equivalente a ollama cp). Requer um corpo JSON com source e destination.
POST /api/push: Envia um modelo local personalizado para sua conta no registro ollama.com (requer login/configuração prévia). Requer um corpo JSON com name (nome do modelo com namespace).

Formato de Requisição/Resposta API:
A maioria das requisições POST e DELETE espera uma carga útil JSON no corpo da requisição. Respostas são tipicamente retornadas como objetos JSON. Para os pontos de extremidade generate e chat, você pode controlar o formato da resposta:

"stream": false (Padrão): A API espera até que toda a resposta seja gerada e a retorna como um único objeto JSON contendo o texto completo, detalhes de completude e estatísticas de desempenho.
"stream": true: A API retorna um fluxo de objetos JSON, um para cada token gerado (ou pequeno bloco de tokens). Isso permite que aplicações exibam a resposta progressivamente, proporcionando uma experiência de usuário mais interativa. O último objeto JSON no fluxo contém as estatísticas gerais.

Exemplo de Interação API usando curl:

1. Requisição de Geração Simples (Não-Streaming):

curl http://localhost:11434/api/generate -d '{
  "model": "phi4-mini",
  "prompt": "Escreva uma função curta em Python para calcular o fatorial:",
  "stream": false,
  "options": {
    "temperature": 0.3,
    "num_predict": 80
  }
}'

2. Requisição de Chat Conversacional (Streaming):

# Nota: Saída de streaming aparecerá como múltiplas linhas JSON
curl http://localhost:11434/api/chat -d '{
  "model": "llama3.2:8b-instruct-q5_K_M",
  "messages": [
    { "role": "system", "content": "Você é um historiador experiente." },
    { "role": "user", "content": "Quais foram as principais causas da Primeira Guerra Mundial?" }
  ],
  "stream": true,
  "options": {
    "num_ctx": 4096
  }
}'

3. Requisição de Geração de Embedding:

curl http://localhost:11434/api/embeddings -d '{
  "model": "mxbai-embed-large",  # Ou outro modelo de embedding adequado
  "prompt": "Ollama facilita a execução local de LLMs."
}'

Esta API versátil forma a espinha dorsal para inúmeras integrações da comunidade, incluindo UIs web, ferramentas de desenvolvimento, serviços backend, scripts de automação e mais, tudo alimentado por sua instância local do Ollama.

Aproveitando a API de Compatibilidade OpenAI do Ollama

Reconhecendo a ampla adoção dos padrões API da OpenAI, o Ollama cuidadosamente inclui uma camada de compatibilidade experimental. Isso permite que muitas ferramentas, bibliotecas e aplicações projetadas para os serviços da OpenAI funcionem com sua instância local do Ollama com modificações mínimas, frequentemente triviais.

Como Funciona:
O servidor Ollama expõe pontos de extremidade sob o caminho /v1/ (ex., http://localhost:11434/v1/) que espelham a estrutura e os formatos esperados de requisição/resposta dos pontos de extremidade chave da API OpenAI.

Pontos de Extremidade Compatíveis Chave:

/v1/chat/completions: Espelha o ponto de extremidade de completude de chat da OpenAI.
/v1/embeddings: Espelha o ponto de extremidade de embeddings da OpenAI.
/v1/models: Espelha o ponto de extremidade de listagem de modelos da OpenAI (retorna seus modelos locais Ollama).

Usando Bibliotecas Cliente OpenAI com Ollama:
A principal vantagem é que você pode usar bibliotecas cliente padrão da OpenAI (como openai-python, openai-node, etc.) simplesmente alterando dois parâmetros de configuração ao inicializar o cliente:

base_url (ou api_base): Defina isso para seu ponto de extremidade local Ollama v1: http://localhost:11434/v1/.
api_key: Forneça qualquer string não vazia. O ponto de extremidade /v1/ do Ollama na verdade não realiza autenticação e ignora o valor da chave, mas a maioria das bibliotecas cliente OpenAI exige que o parâmetro esteja presente. A prática comum é usar a string "ollama" ou "nokey".

Exemplo Python usando openai-python:

# Certifique-se de ter a biblioteca openai instalada: pip install openai
from openai import OpenAI
import os

# Defina o endpoint Ollama e uma chave API fictícia
OLLAMA_BASE_URL = "http://localhost:11434/v1"
OLLAMA_API_KEY = "ollama" # Placeholder, valor ignorado pelo Ollama

# Especifique o modelo local Ollama que você deseja usar
OLLAMA_MODEL = "llama3.2"

try:
    # Inicialize o cliente OpenAI, apontando-o para o servidor Ollama
    client = OpenAI(
        base_url=OLLAMA_BASE_URL,
        api_key=OLLAMA_API_KEY,
    )

    print(f"Enviando requisição para o modelo Ollama: {OLLAMA_MODEL} via camada de compatibilidade OpenAI...")

    # Faça uma requisição padrão de completude de chat
    chat_completion = client.chat.completions.create(
        model=OLLAMA_MODEL, # Use o nome do seu modelo local Ollama
        messages=[
            {"role": "system", "content": "Você é um assistente útil."},
            {"role": "user", "content": "Explique a diferença entre Ollama e llama.cpp."}
        ],
        temperature=0.7,
        max_tokens=250, # Nota: 'max_tokens' corresponde aproximadamente a 'num_predict' do Ollama
        stream=False # Defina como True para respostas em streaming
    )

    # Processe a resposta
    if chat_completion.choices:
        response_content = chat_completion.choices[0].message.content
        print("\nResposta Ollama:")
        print(response_content)
        print("\nEstatísticas de Uso:")
        print(f"  Tokens de Prompt: {chat_completion.usage.prompt_tokens}")
        print(f"  Tokens de Completude: {chat_completion.usage.completion_tokens}")
        print(f"  Tokens Totais: {chat_completion.usage.total_tokens}")
    else:
        print("Nenhuma opção de resposta recebida do Ollama.")

except Exception as e:
    print(f"\nOcorreu um erro:")
    print(f"  Tipo de Erro: {type(e).__name__}")
    print(f"  Detalhes do Erro: {e}")
    print(f"\nPor favor, certifique-se de que o servidor Ollama está executando e acessível em {OLLAMA_BASE_URL}.")
    print(f"Verifique também se o modelo '{OLLAMA_MODEL}' está disponível localmente ('ollama list').")

Esta compatibilidade simplifica significativamente a migração de projetos existentes baseados em OpenAI para usar modelos locais via Ollama ou a construção de novas aplicações que podem alternar flexivelmente entre backends na nuvem e locais. Embora nem todas as funcionalidades obscuras da OpenAI possam ser perfeitamente espelhadas, as funcionalidades principais de chat, embedding e listagem de modelos são bem suportadas.

Personalização Profunda do Ollama com Modelfiles

O Modelfile é a pedra angular das capacidades de personalização do Ollama. Ele atua como um blueprint ou receita, definindo precisamente como um modelo Ollama deve ser construído ou modificado. Ao criar e editar esses simples arquivos de texto, você ganha controle refinado sobre o comportamento, parâmetros e estrutura do modelo.

Instruções Principais do Modelfile Ollama:

FROM <referencia_modelo_base>: (Instrução Inicial Obrigatória) Especifica a fundação sobre a qual seu novo modelo é construído. A referência pode apontar para:
Um modelo existente em sua biblioteca local Ollama ou no registro oficial (ex., FROM llama3.2:8b-instruct-q5_K_M).
Um caminho relativo ou absoluto para um diretório local contendo pesos de modelo descompactados no formato Safetensors, junto com arquivos de configuração necessários (config.json, tokenizer.json, etc.). Exemplo: FROM /mnt/models/my_downloaded_llama/. O Ollama tentará carregar arquiteturas suportadas (Llama, Mistral, Phi, Gemma, etc.).
Um caminho relativo ou absoluto para um único arquivo de modelo no popular formato GGUF (que empacota pesos e metadados). Exemplo: FROM ./models/mistral-7b-instruct-v0.2.Q5_K_M.gguf.
PARAMETER <nome_parametro> <valor>: Define um valor de parâmetro de tempo de execução padrão para o modelo sendo criado. Estes padrões serão usados a menos que sejam sobrescritos durante ollama run (via /set parameter), através de opções de chamada API, ou por instruções PARAMETER subsequentes no mesmo Modelfile.
PARAMETER temperature 0.6
PARAMETER num_ctx 8192 (Define a janela de contexto padrão)
PARAMETER stop "<|user|>"
PARAMETER stop "<|end_of_turn|>" (Você pode ter múltiplos parâmetros de parada)
PARAMETER repeat_penalty 1.15
TEMPLATE "<string_template_prompt>": Define o formato específico que o Ollama deve usar para estruturar o prompt de entrada antes de alimentá-lo ao LLM subjacente. Isso é criticamente importante para modelos de chat e seguimento de instruções, pois eles são treinados para esperar tokens ou marcadores especiais delimitando mensagens do sistema, turnos do usuário e turnos do assistente. O template usa a sintaxe text/template do Go. Variáveis chave disponíveis dentro da string do template incluem:
{{ .System }}: Placeholder para a mensagem do sistema.
{{ .Prompt }}: Placeholder para a entrada atual do usuário (usado em /api/generate).
{{ .Response }}: Placeholder onde a saída gerada pelo modelo será anexada (frequentemente usado internamente ou para estruturas de template específicas).
{{ range .Messages }} ... {{ .Role }} ... {{ .Content }} ... {{ end }}: Usado em templates de chat (/api/chat) para iterar sobre todo o histórico de mensagens (turnos do sistema, usuário, assistente) e formatá-lo corretamente.
{{ .First }}: Um booleano indicando se a mensagem atual é a primeiríssima (útil para adicionar tokens especiais de início de sequência).
Exemplo (template ChatML simplificado):

TEMPLATE """{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>{{ end }}{{ range .Messages }}
<|im_start|>{{ .Role }}
{{ .Content }}<|im_end|>{{ end }}
<|im_start|>assistant
"""

Obter o template correto é essencial para fazer um modelo seguir instruções ou conversar naturalmente. Você pode visualizar o template padrão de um modelo usando ollama show --modelfile <nome_modelo>.

SYSTEM "<mensagem_sistema_padrao>": Fornece um prompt de sistema padrão que será usado se nenhuma outra mensagem do sistema for fornecida via API ou CLI. Isso é útil para definir uma persona consistente ou conjunto de instruções para o modelo.
SYSTEM "Você é um assistente de IA útil focado em fornecer respostas concisas."
ADAPTER </caminho/para/pesos_adaptador>: Aplica um adaptador LoRA (Low-Rank Adaptation) ou QLoRA ao modelo base especificado na instrução FROM. Adaptadores são pequenos conjuntos de pesos treinados para modificar ou especializar um LLM pré-treinado para uma tarefa, estilo ou domínio de conhecimento específico sem re-treinar todo o modelo massivo. O caminho pode apontar para:
Um único arquivo .gguf contendo o adaptador.
Um diretório contendo os pesos do adaptador no formato Safetensors (adapter_model.safetensors, adapter_config.json).
Importante: O modelo base (FROM) deve ser o mesmo em que o adaptador foi originalmente treinado para que funcione corretamente.
LICENSE "<detalhes_licenca>": Embuti informações de licença dentro dos metadados do modelo. Pode ser um identificador curto (como "MIT") ou um bloco de texto mais longo.
MESSAGE user "<mensagem_usuario_exemplo>" / MESSAGE assistant "<resposta_assistente_exemplo>": Define turnos de conversação de exemplo. Estes podem às vezes ajudar a guiar o tom, estilo ou formato de saída esperado do modelo, especialmente para cenários de prompting de poucos disparos, embora seu efeito varie entre modelos.

Construindo um Modelo Ollama a partir de um Modelfile:
Uma vez que você criou seu Modelfile (ex., salvo como MeuModeloPersonalizado.modelfile), você usa o comando ollama create para construir o modelo Ollama correspondente:

ollama create meu-novo-nome-modelo -f MeuModeloPersonalizado.modelfile

Ollama processa as instruções, potencialmente combina camadas, aplica adaptadores, define parâmetros e registra o novo modelo (meu-novo-nome-modelo) em sua biblioteca local. Você pode então executá-lo como qualquer outro modelo: ollama run meu-novo-nome-modelo.

Importando Modelos Externos para o Ollama (GGUF, Safetensors)

O sistema Modelfile do Ollama fornece uma maneira fluida de usar modelos obtidos de outras fontes (como Hugging Face, pesquisadores independentes, etc.) que são distribuídos em formatos padrão.

Importando Modelos GGUF para o Ollama: GGUF é um formato popular projetado especificamente para llama.cpp e motores de inferência similares. Ele empacota pesos de modelo (frequentemente pré-quantizados), informações do tokenizador e metadados em um único arquivo. Este é frequentemente o formato mais fácil de importar.

Baixe o arquivo .gguf (ex., zephyr-7b-beta.Q5_K_M.gguf).
Crie um Modelfile mínimo (ex., ZephyrImport.modelfile):

# ZephyrImport.modelfile
FROM ./zephyr-7b-beta.Q5_K_M.gguf

# Crucial: Adicione o template de prompt correto para este modelo!
# (Procure o formato de template exigido pelo modelo)
TEMPLATE """<|system|>
{{ .System }}</s>
<|user|>
{{ .Prompt }}</s>
<|assistant|>
{{ .Response }}</s>
"""
PARAMETER num_ctx 4096 # Defina um contexto padrão razoável
SYSTEM "Você é um chatbot amigável." # Prompt de sistema padrão opcional

Construa o modelo Ollama: ollama create meu-zephyr-gguf -f ZephyrImport.modelfile.

Importando Modelos Safetensors (Pesos Completos) para o Ollama: Safetensors é um formato seguro e rápido para armazenar tensores de modelos. Se você tem o conjunto completo de pesos e arquivos de configuração para um modelo neste formato:

Certifique-se de que todos os arquivos necessários (arquivos de peso *.safetensors, config.json, tokenizer.json, special_tokens_map.json, tokenizer_config.json, etc.) estejam localizados dentro de um único diretório (ex., /data/models/Mistral-7B-v0.1-full/).
Crie um Modelfile referenciando este diretório:

# MistralImport.modelfile
FROM /data/models/Mistral-7B-v0.1-full/

# Adicione as instruções TEMPLATE, PARAMETER, SYSTEM necessárias
TEMPLATE """[INST] {{ if .System }}{{ .System }} \n{{ end }}{{ .Prompt }} [/INST]
{{ .Response }}"""
PARAMETER num_ctx 4096
PARAMETER temperature 0.7

Construa o modelo: ollama create meu-mistral-safetensors -f MistralImport.modelfile. O Ollama tentará carregar arquiteturas compatíveis. Se o modelo não for quantizado (ex., FP16), você pode opcionalmente quantizá-lo durante a criação (veja abaixo).

Aplicando Adaptadores LoRA Safetensors via Modelfile Ollama:

Primeiro, certifique-se de ter o modelo Ollama base exato no qual o adaptador LoRA foi treinado. Puxe-o se necessário (ex., ollama pull llama3.2:8b).
Coloque os arquivos do adaptador LoRA (ex., adapter_model.safetensors, adapter_config.json) em seu próprio diretório (ex., /data/adapters/meu_llama3_lora/).
Crie um Modelfile especificando tanto a base quanto o adaptador:

# ApplyLora.modelfile
FROM llama3.2:8b # Deve corresponder à base do adaptador!

ADAPTER /data/adapters/meu_llama3_lora/

# Ajuste parâmetros ou template se o LoRA exigir
PARAMETER temperature 0.5
SYSTEM "Você agora responde no estilo ensinado pelo LoRA."

Construa o modelo adaptado: ollama create llama3-com-meu-lora -f ApplyLora.modelfile.

Quantizando Modelos com o Ollama

Quantização é o processo de reduzir a precisão numérica dos pesos de um modelo (ex., converter números de ponto flutuante de 16 bits para inteiros de 4 bits). Isso reduz significativamente o tamanho do arquivo do modelo e o uso de memória (uso de RAM/VRAM) e acelera a inferência, tornando possível executar modelos maiores e mais capazes em hardware de consumidor. A contrapartida é geralmente uma redução pequena, muitas vezes imperceptível, na qualidade da saída.

O Ollama pode realizar a quantização durante o processo de criação do modelo se a instrução FROM em seu Modelfile apontar para pesos de modelo não quantizados ou de maior precisão (tipicamente Safetensors FP16 ou FP32).

Como Quantizar usando ollama create:

Crie um Modelfile que aponte para o diretório contendo os pesos do modelo não quantizado:

# QuantizeMe.modelfile
FROM /caminho/para/meu/modelo_fp16_nao_quantizado/
# Adicione TEMPLATE, PARAMETER, SYSTEM conforme necessário

Execute o comando ollama create, adicionando a flag -q (ou --quantize) seguida pelo identificador de nível de quantização desejado:

# Quantizar para Q4_K_M (equilíbrio popular de tamanho/qualidade)
ollama create meu-modelo-quantizado-q4km -f QuantizeMe.modelfile -q q4_K_M

# Quantizar para Q5_K_M (ligeiramente maior, potencialmente melhor qualidade)
ollama create meu-modelo-quantizado-q5km -f QuantizeMe.modelfile -q q5_K_M

# Quantizar para Q8_0 (maior quantização comum, melhor qualidade entre quantizados)
ollama create meu-modelo-quantizado-q8 -f QuantizeMe.modelfile -q q8_0

# Quantizar para Q3_K_S (muito pequeno, mais perda de qualidade)
ollama create meu-modelo-quantizado-q3ks -f QuantizeMe.modelfile -q q3_K_S

Ollama usa as rotinas de quantização do llama.cpp para realizar a conversão e salva o modelo recém-quantizado com o nome especificado.

Níveis Comuns de Quantização:

q4_0, q4_1: Quantização básica de 4 bits.
q5_0, q5_1: Quantização básica de 5 bits.
q8_0: Quantização de 8 bits (tamanho de arquivo maior, mais próximo da qualidade original).
q3_K_S, q3_K_M, q3_K_L: Métodos "K-Quant" de 3 bits mais avançados (variações internas Pequeno/Médio/Grande). Muito pequeno, perda de qualidade perceptível.
q4_K_S, q4_K_M: K-Quants avançados de 4 bits. q4_K_M é frequentemente um ponto ideal recomendado.
q5_K_S, q5_K_M: K-Quants avançados de 5 bits. Bom equilíbrio, ligeiramente maior que Q4_K.
q6_K: K-Quant avançado de 6 bits. Tamanho maior, aproximando-se da qualidade Q8.

Escolher o nível de quantização correto depende das restrições do seu hardware e da tolerância à potencial redução de qualidade. Frequentemente vale a pena tentar q4_K_M ou q5_K_M primeiro.

Compartilhando seus Modelos Ollama Personalizados

Se você criou uma variante de modelo única usando um Modelfile – talvez aplicando um LoRA específico, definindo um prompt de sistema e template criativos, ou ajustando parâmetros finamente – você pode compartilhar sua criação com a comunidade Ollama mais ampla através do site oficial do registro de modelos Ollama.

Passos para Compartilhar um Modelo Ollama:

Criar uma Conta Ollama: Inscreva-se para uma conta gratuita no site Ollama (ollama.com). Seu nome de usuário escolhido se tornará o namespace para seus modelos compartilhados.
Vincular seu Ollama Local: Você precisa associar sua instalação local do Ollama à sua conta online. Isso envolve adicionar a chave pública Ollama da sua máquina local às configurações da sua conta no site. O site fornece instruções específicas sobre como encontrar seu arquivo de chave pública local (id_ed25519.pub) com base no seu sistema operacional.
Nomear seu Modelo Corretamente: Modelos compartilhados devem ter namespace com seu nome de usuário Ollama, seguindo o formato seu_nome_usuario/seu_nome_modelo. Se seu modelo personalizado local tiver um nome diferente (ex., mario), você primeiro precisa copiá-lo para o nome com namespace correto usando ollama cp:

# Assumindo que seu nome de usuário seja 'luigi' e o modelo local seja 'mario'
ollama cp mario luigi/mario

Enviar o Modelo para o Registro: Uma vez que o modelo esteja corretamente nomeado localmente e sua chave esteja vinculada, use o comando ollama push:

ollama push luigi/mario

Ollama enviará as camadas de modelo e metadados necessários para o registro.

Após a conclusão do envio, outros usuários Ollama em todo o mundo podem facilmente baixar e executar seu modelo compartilhado simplesmente usando seu nome com namespace:

ollama run luigi/mario

Este mecanismo de compartilhamento fomenta a colaboração e permite que a comunidade se beneficie de modelos especializados ou criativamente personalizados.

Otimizando o Desempenho do Ollama com Aceleração de GPU

Embora o Ollama possa executar modelos puramente na CPU do seu computador, aproveitar uma Unidade de Processamento Gráfico (GPU) compatível fornece um aumento drástico de desempenho, acelerando significativamente a velocidade com que os modelos geram texto (velocidade de inferência). O Ollama é projetado para detectar e utilizar automaticamente GPUs suportadas sempre que possível.

Ollama com GPUs NVIDIA: O Ollama oferece excelente suporte para GPUs NVIDIA, exigindo:

Uma GPU com Capacidade de Computação CUDA 5.0 ou superior (a maioria das placas GeForce GTX série 900 / Quadro série M e mais recentes). Verifique a lista de GPUs CUDA da NVIDIA para compatibilidade.
Os drivers proprietários oficiais da NVIDIA instalados corretamente em seu sistema host (Linux ou Windows).
No Linux com Docker, o NVIDIA Container Toolkit deve estar instalado e configurado.
O Ollama deve detectar automaticamente hardware e drivers compatíveis e descarregar a computação para a GPU.

Ollama com GPUs AMD Radeon: O suporte para GPUs AMD modernas está disponível tanto no Windows quanto no Linux:

Requer drivers AMD Radeon Software (Adrenalin Edition) recentes no Windows.
Requer a pilha de software ROCm (Radeon Open Compute platform) instalada no Linux (versão 5 ou 6+ recomendada). O instalador do Ollama para Linux ou a imagem Docker :rocm frequentemente ajudam com dependências, mas a instalação manual do ROCm pode ser necessária para compatibilidade total em certas distribuições.
GPUs suportadas geralmente incluem as séries RX 6000, RX 7000, PRO W6000/W7000 e alguns aceleradores Instinct. Consulte a documentação oficial de GPU do Ollama para uma lista detalhada.

Ollama com Apple Silicon (macOS): Em Macs equipados com chips das séries M1, M2, M3 ou M4, o Ollama utiliza automaticamente as capacidades de GPU incorporadas através da API gráfica Metal da Apple. Normalmente, não é necessária instalação adicional de drivers ou configuração; a aceleração de GPU funciona imediatamente.

Verificando o Uso da GPU Ollama:
A maneira mais fácil de verificar se o Ollama está realmente usando sua GPU é executar o comando ollama ps enquanto um modelo está carregado (ex., imediatamente após iniciar ollama run <modelo> em outro terminal, ou enquanto uma requisição API está sendo processada). Examine a coluna PROCESSOR na saída:

gpu: Indica que as camadas do modelo estão primariamente carregadas na GPU.
cpu: Indica que o modelo está executando unicamente na CPU. Isso pode significar que nenhuma GPU compatível foi detectada, os drivers estão ausentes ou incorretos, ou houve um problema ao inicializar o suporte à GPU. Verifique os logs do servidor Ollama para erros.

Selecionando GPUs Específicas em Configurações Multi-GPU Ollama:
Se seu sistema contém múltiplas GPUs compatíveis, você pode instruir o Ollama (e o llama.cpp subjacente) qual(is) dispositivo(s) específico(s) usar definindo variáveis de ambiente antes de iniciar o processo do servidor/aplicação Ollama:

NVIDIA (CUDA_VISIBLE_DEVICES): Defina esta variável para uma lista separada por vírgulas de índices de GPU (começando de 0) ou, preferencialmente, UUIDs de GPU.
export CUDA_VISIBLE_DEVICES=0 (Usa apenas a primeira GPU detectada pela NVIDIA).
export CUDA_VISIBLE_DEVICES=1 (Usa apenas a segunda GPU).
export CUDA_VISIBLE_DEVICES=GPU-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,GPU-yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy (Usa GPUs específicas identificadas por seus UUIDs, que você pode encontrar usando nvidia-smi -L).
AMD (ROCR_VISIBLE_DEVICES): Defina esta variável para uma lista separada por vírgulas de índices de GPU conforme relatado pelo comando rocminfo (geralmente começando de 0).
export ROCR_VISIBLE_DEVICES=0 (Usa a primeira GPU AMD detectada).
export ROCR_VISIBLE_DEVICES=1,2 (Usa a segunda e terceira GPUs AMD detectadas).

Definir um ID de dispositivo inválido (ex., export CUDA_VISIBLE_DEVICES=-1) é frequentemente usado como uma forma de forçar deliberadamente o Ollama a usar apenas a CPU, o que pode ser útil para depuração. Lembre-se de reiniciar o servidor/aplicação Ollama após definir essas variáveis de ambiente para que elas tenham efeito.

Configurando seu Ambiente Ollama

Além das configurações padrão, o comportamento do Ollama pode ser ajustado finamente usando várias variáveis de ambiente. Elas permitem personalizar configurações de rede, locais de armazenamento, níveis de log e mais.

Variáveis de Ambiente Chave do Ollama para Configuração

OLLAMA_HOST: Controla a interface de rede e a porta na qual o servidor API Ollama escuta.
Padrão: 127.0.0.1:11434 (Escuta apenas na interface loopback, acessível apenas da mesma máquina).
Exemplo: 0.0.0.0:11434 (Escuta em todas as interfaces de rede disponíveis, tornando o Ollama acessível de outros dispositivos em sua rede local. Aviso: Certifique-se de que regras de firewall apropriadas estejam implementadas se expor o Ollama externamente).
Exemplo: 192.168.1.100:11500 (Escuta apenas em um endereço IP local específico e uma porta personalizada).
OLLAMA_MODELS: Crucialmente, esta variável permite especificar um caminho de diretório personalizado onde o Ollama deve armazenar e procurar por modelos baixados. Isso é extremamente útil se sua unidade padrão (onde ~/.ollama ou C:\Users\<Usuário>\.ollama reside) tem pouco espaço ou se você prefere organizar modelos em um SSD dedicado ou unidade maior.
Exemplo (Linux/macOS): export OLLAMA_MODELS=/mnt/large_drive/my_ollama_models
Exemplo (Windows): Defina OLLAMA_MODELS como D:\OllamaData via Propriedades do Sistema.
Importante: Certifique-se de que o diretório exista e que a conta de usuário executando o processo do servidor Ollama tenha permissões completas de leitura e escrita para este caminho personalizado.
OLLAMA_ORIGINS: Gerencia o Compartilhamento de Recursos de Origem Cruzada (CORS) para a API Ollama. Por padrão, navegadores web restringem páginas web de fazer requisições API para domínios (origens) diferentes daquele de onde a página foi servida. Se você está executando uma UI web separada (como Open WebUI, Lobe Chat) servida de uma origem diferente (ex., http://localhost:3000) que precisa chamar sua API Ollama (em http://localhost:11434), você deve adicionar a origem da UI a esta variável.
Exemplo: export OLLAMA_ORIGINS=http://localhost:3000,http://192.168.1.50:8080 (Permite requisições destas duas origens específicas).
Exemplo: export OLLAMA_ORIGINS='*' (Permite requisições de qualquer origem. Use com cautela, especialmente se OLLAMA_HOST não for 127.0.0.1, pois isso poderia expor amplamente sua API). Pode incluir protocolos como chrome-extension://*.
OLLAMA_DEBUG: Defina como 1 para habilitar log de depuração verboso. Isso fornece informações muito mais detalhadas sobre as operações internas do Ollama, incluindo passos de detecção de GPU, detalhes de carregamento de modelo e erros potenciais, o que é inestimável para solução de problemas.
Exemplo: export OLLAMA_DEBUG=1
OLLAMA_KEEP_ALIVE: Controla por quanto tempo o Ollama mantém um modelo carregado na memória após sua última requisição. Por padrão, pode ser cerca de 5 minutos (5m). Definir como 0 descarrega o modelo imediatamente após o uso (economiza RAM/VRAM mas aumenta o tempo de carga para a próxima requisição). Definir para uma duração mais longa (ex., 30m) ou -1 (mantém carregado indefinidamente até o servidor parar) pode acelerar requisições frequentes ao mesmo modelo mas consome recursos constantemente.
Exemplo: export OLLAMA_KEEP_ALIVE=15m
HTTPS_PROXY / HTTP_PROXY / NO_PROXY: Variáveis de ambiente de rede padrão usadas se o Ollama precisar rotear suas requisições de internet de saída (ex., ao executar ollama pull para baixar modelos de ollama.com) através de um servidor proxy, comum em ambientes corporativos.
Exemplo: export HTTPS_PROXY=http://proxy.mycompany.com:8080

Métodos para Definir Variáveis de Ambiente Ollama

A maneira correta de definir estas variáveis depende de como você instalou e executa o Ollama:

Ollama no macOS (Usando o App): Variáveis de ambiente para aplicações GUI no macOS são melhor definidas usando launchctl. Abra o Terminal e use:

launchctl setenv OLLAMA_MODELS "/Volumes/ExternalSSD/OllamaStorage"
launchctl setenv OLLAMA_HOST "0.0.0.0:11434"
# Repita para outras variáveis

Após definir as variáveis, você deve Sair e reiniciar a aplicação Ollama do ícone da barra de menus para que as alterações tenham efeito.

Ollama no Linux (Usando Serviço Systemd): O método recomendado é criar um arquivo de sobrescrita para o serviço:

Execute sudo systemctl edit ollama.service. Isso abre um editor de texto vazio.
Adicione as seguintes linhas, modificando a variável e o valor conforme necessário:

[Service]
Environment="OLLAMA_MODELS=/caminho/para/diretorio/modelo/personalizado"
Environment="OLLAMA_HOST=0.0.0.0:11434"
Environment="OLLAMA_DEBUG=1"

Salve e feche o editor.
Aplique as alterações: sudo systemctl daemon-reload
Reinicie o serviço Ollama: sudo systemctl restart ollama

Ollama no Windows: Use o editor de Variáveis de Ambiente embutido:

Procure por "Editar as variáveis de ambiente do sistema" no menu Iniciar e abra-o.
Clique no botão "Variáveis de Ambiente...".
Você pode definir variáveis para seu usuário específico ("Variáveis de usuário") ou para todos os usuários ("Variáveis do sistema"). Variáveis do sistema geralmente requerem privilégios de administrador.
Clique em "Novo..." sob a seção desejada.
Digite o Nome da variável (ex., OLLAMA_MODELS) e o Valor da variável (ex., D:\OllamaData).
Clique em OK em todos os diálogos abertos.
Crucialmente, você deve reiniciar o processo em segundo plano do Ollama. Abra o Gerenciador de Tarefas (Ctrl+Shift+Esc), vá para a aba "Serviços", encontre "Ollama", clique com o botão direito e selecione "Reiniciar". Alternativamente, reinicie seu computador.

Ollama via Docker: Passe variáveis de ambiente diretamente no comando docker run usando a flag -e para cada variável:

docker run -d \
  --gpus=all \
  -v ollama_data:/root/.ollama \
  -p 127.0.0.1:11434:11434 \
  -e OLLAMA_HOST="0.0.0.0:11434" \
  -e OLLAMA_DEBUG="1" \
  -e OLLAMA_KEEP_ALIVE="10m" \
  --name my_ollama_configured \
  ollama/ollama

Ollama via ollama serve manual no Terminal: Simplesmente prefixe o comando com as atribuições de variáveis na mesma linha:

OLLAMA_DEBUG=1 OLLAMA_HOST=0.0.0.0:11434 OLLAMA_MODELS=/data/ollama ollama serve

Estas variáveis aplicar-se-ão apenas a essa instância específica do servidor.

Escolha o método apropriado para sua configuração e lembre-se de reiniciar o processo do servidor Ollama após fazer alterações para que elas se tornem ativas.

Solução de Problemas Comuns do Ollama

Mesmo com o foco do Ollama na simplicidade, você pode encontrar contratempos ocasionais. Veja como diagnosticar e resolver alguns problemas frequentes:

Consultando os Logs do Ollama

Sua principal ferramenta de diagnóstico é o arquivo de log do servidor Ollama. Ele registra informações de inicialização, tentativas de carregamento de modelos, resultados de detecção de GPU, requisições API e, mais importante, mensagens de erro detalhadas.

Locais Padrão do Arquivo de Log:

Ollama no macOS: ~/.ollama/logs/server.log
Ollama no Linux (Systemd): Use o comando de controle do journal: journalctl -u ollama. Adicione -f para seguir os logs em tempo real (journalctl -u ollama -f). Use -n 100 para ver as últimas 100 linhas (journalctl -u ollama -n 100).
Ollama no Windows: O arquivo de log é server.log localizado dentro de %LOCALAPPDATA%\Ollama. Você pode facilmente abrir esta pasta colando %LOCALAPPDATA%\Ollama na barra de endereço do Explorador de Arquivos ou na caixa de diálogo Executar (Win+R).
Ollama via Docker: Use o comando de logs do Docker: docker logs my_ollama (substitua my_ollama pelo nome do seu contêiner). Adicione -f para seguir (docker logs -f my_ollama).
Ollama via ollama serve manual: Logs são impressos diretamente na janela do terminal onde você lançou o comando.

Dica: Para solução de problemas mais detalhada, sempre habilite o log de depuração definindo a variável de ambiente OLLAMA_DEBUG=1 antes de iniciar o servidor Ollama, depois verifique os logs novamente.

Corrigindo o Erro Ollama: `listen tcp 127.0.0.1:11434: bind: address already in use`

Esta mensagem de erro específica é um dos problemas mais comuns que novos usuários encontram. Significa que o Ollama não pode iniciar seu servidor API porque outro processo já está ocupando a porta de rede (padrão 11434) que o Ollama precisa para escutar.

Causa Provável:
Outra instância do servidor Ollama já está executando em segundo plano (talvez de uma sessão anterior que não foi encerrada corretamente).
Uma aplicação completamente diferente em seu sistema está casualmente usando a porta 11434.
Solução 1: Identificar e Parar o Processo Conflitante: Você precisa descobrir qual processo está usando a porta e pará-lo (se for seguro fazê-lo).
Linux / macOS: Abra um terminal e execute sudo lsof -i :11434 ou sudo netstat -tulnp | grep 11434. Estes comandos devem mostrar o ID do Processo (PID) do programa usando a porta. Você pode então tentar pará-lo graciosamente ou usar sudo kill <PID>. Se for um processo Ollama antigo, matá-lo deve resolver o conflito.
Windows: Abra o Prompt de Comando como Administrador e execute netstat -ano | findstr "11434". Olhe na última coluna para o PID. Abra o Gerenciador de Tarefas (Ctrl+Shift+Esc), vá para a aba "Detalhes" (ou "Processos" e adicione a coluna PID), encontre o processo com esse PID e finalize-o se apropriado.
Solução 2: Mudar a Porta de Escuta do Ollama: Se você não puder parar o processo conflitante, ou se intencionalmente quiser que o Ollama execute em uma porta diferente, você pode configurar o Ollama para usar uma porta alternativa. Defina a variável de ambiente OLLAMA_HOST para incluir sua porta desejada antes de iniciar o Ollama.
Exemplo: Defina OLLAMA_HOST como 127.0.0.1:11435 (usando os métodos descritos na seção de Configuração).
Lembre-se de ajustar quaisquer configurações de cliente API, UIs web ou scripts para apontar para a nova porta (ex., http://localhost:11435) após fazer esta alteração.

Resolvendo Problemas de Detecção e Uso de GPU Ollama

Se ollama ps mostra cpu em vez de gpu, ou se você encontrar erros específicos relacionados à GPU nos logs (como CUDA error, ROCm error), siga estes passos:

Confirmar Compatibilidade da GPU: Verifique novamente se seu modelo específico de GPU está listado como suportado na documentação oficial de GPU do Ollama no GitHub.
Atualizar Drivers: Certifique-se de ter os drivers oficiais estáveis mais recentes instalados diretamente dos sites da NVIDIA ou AMD. Drivers genéricos incluídos com o SO são frequentemente insuficientes. Uma reinicialização completa do sistema após a instalação do driver é altamente recomendada.
Verificar Logs Ollama (Modo Debug): Defina OLLAMA_DEBUG=1, reinicie o servidor Ollama e examine cuidadosamente os logs de inicialização. Procure por mensagens relacionadas à detecção de GPU, carregamento de biblioteca (CUDA, ROCm) e quaisquer códigos de erro específicos.
Específicos NVIDIA (Linux):
Verifique se o comando nvidia-smi funciona e mostra sua GPU e versão do driver.
Se usando Docker, confirme se o NVIDIA Container Toolkit está instalado e funcional (docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi).
Verifique se os módulos do kernel necessários estão carregados (lsmod | grep nvidia). Às vezes, recarregá-los (sudo rmmod nvidia_uvm nvidia && sudo modprobe nvidia_uvm nvidia) pode ajudar.
Verifique os logs do sistema (dmesg | grep -iE 'nvidia|nvrm') para erros de hardware ou driver.
Específicos AMD (Linux):
Verifique se o comando rocminfo funciona e mostra sua GPU.
Certifique-se de que o usuário executando o Ollama (ou o contêiner Docker) tenha permissões corretas para os dispositivos /dev/kfd e /dev/dri/renderD* (frequentemente requer associação aos grupos render e video). Verifique a associação ao grupo com groups $USER ou groups ollama. Você pode precisar de --group-add render --group-add video em seu comando Docker.
Verifique os logs do sistema (dmesg | grep -iE 'amdgpu|kfd') para erros.
Forçar CPU (para teste): Como um passo de diagnóstico temporário, tente forçar o uso da CPU definindo CUDA_VISIBLE_DEVICES=-1 or ROCR_VISIBLE_DEVICES=-1. Se o Ollama executar corretamente na CPU, isso confirma que o problema está relacionado à configuração da GPU.

Abordando Outros Problemas Comuns do Ollama

Erros de Permissão (Diretório de Modelos): Especialmente no Linux com o serviço systemd, se o Ollama falhar ao puxar ou criar modelos, ele pode não ter permissões de escrita para o diretório de armazenamento de modelos (OLLAMA_MODELS ou o padrão). Certifique-se de que o diretório exista e seja propriedade ou gravável pelo usuário/grupo ollama (sudo chown -R ollama:ollama /caminho/para/modelos e sudo chmod -R 775 /caminho/para/modelos).
Downloads Lentos de Modelos (ollama pull):
Verifique a velocidade básica da sua conexão com a internet.
Se estiver atrás de um proxy, certifique-se de que HTTPS_PROXY esteja configurado corretamente.
Verifique regras de firewall que possam estar bloqueando ou limitando conexões a ollama.com.
No Windows com WSL2, o problema conhecido LSO (Large Send Offload) às vezes pode impactar o desempenho da rede dentro do WSL. Desabilitar LSOv2 para o adaptador de rede virtual WSL nas configurações do Adaptador de Rede do Windows pode ajudar, embora isso seja menos comum agora.
Saída de Terminal Corrompida (ollama run em Windows antigos): Se você vir caracteres estranhos como ←[?25h... no cmd.exe ou PowerShell em versões antigas do Windows 10, provavelmente é devido ao suporte deficiente a códigos de escape ANSI. As melhores soluções são:
Atualizar o Windows 10 para a versão 22H2 ou posterior.
Usar o Windows 11.
Usar a aplicação moderna Terminal do Windows, que tem excelente suporte ANSI.

Se você esgotou estes passos de solução de problemas e verificou os logs de depuração sem sucesso, a comunidade Ollama é um ótimo recurso. Prepare uma descrição clara do problema, inclua detalhes relevantes sobre seu SO, versão do Ollama, hardware (CPU/GPU/RAM), o modelo específico que você está usando, o comando que executou e crucialmente, as seções relevantes de seus logs de depuração. Poste sua pergunta no Discord do Ollama ou arquive um issue bem documentado no repositório GitHub do Ollama.

Como desinstalar o Ollama completamente

Se você precisar remover o Ollama do seu sistema, o processo varia com base no seu método de instalação inicial. Tipicamente envolve remover a aplicação/binário, o serviço em segundo plano (se aplicável) e os arquivos de modelos/configuração armazenados.

Desinstalando o Ollama no macOS (Instalado via .app):

Sair do Ollama: Clique no ícone do Ollama na barra de menus e selecione "Sair do Ollama".
Remover Aplicação: Arraste Ollama.app de sua pasta /Aplicativos para a Lixeira/Bin.
Remover Dados e Configuração: Abra o Terminal e execute rm -rf ~/.ollama. Aviso: Isso exclui permanentemente todos os modelos baixados e configuração. Verifique o comando duas vezes antes de executar.
(Opcional) Desdefinir Variáveis de Ambiente: Se você definiu variáveis manualmente usando launchctl setenv, pode desdefini-las: launchctl unsetenv OLLAMA_HOST, launchctl unsetenv OLLAMA_MODELS, etc.

Desinstalando o Ollama no Windows (Instalado via .exe):

Usar Desinstalador do Windows: Vá para "Configurações" > "Aplicativos" > "Aplicativos instalados". Localize "Ollama" na lista, clique nos três pontos (...) ao lado e selecione "Desinstalar". Siga as instruções de desinstalação.
Remover Dados e Configuração: Após o desinstalador terminar, exclua manualmente o diretório de dados do Ollama. Abra o Explorador de Arquivos, digite %USERPROFILE%\.ollama na barra de endereço, pressione Enter e exclua toda a pasta .ollama. Aviso: Isso exclui todos os modelos.
(Opcional) Remover Variáveis de Ambiente: Se você adicionou manualmente OLLAMA_HOST, OLLAMA_MODELS, etc., via Propriedades do Sistema, volte lá ("Editar as variáveis de ambiente do sistema") e exclua-as.

Desinstalando o Ollama no Linux (Instalado via Script ou Binário Manual):

Parar o Serviço: sudo systemctl stop ollama
Desabilitar o Serviço: sudo systemctl disable ollama
Remover Binário: sudo rm /usr/local/bin/ollama (ou o caminho onde você o instalou).
Remover Arquivo de Serviço: sudo rm /etc/systemd/system/ollama.service
Recarregar Systemd: sudo systemctl daemon-reload
(Opcional) Remover Usuário/Grupo: Se o usuário/grupo ollama foi criado: sudo userdel ollama, sudo groupdel ollama.
Remover Dados e Configuração: Exclua o diretório de armazenamento de modelos. Isso depende de onde foi armazenado:

Se executado como seu usuário: rm -rf ~/.ollama
Se executado como serviço do sistema (usuário ollama): sudo rm -rf /usr/share/ollama/.ollama (ou o caminho especificado por OLLAMA_MODELS no arquivo de serviço).
Aviso: Use sudo rm -rf com extrema cautela. Verifique se o caminho está correto antes de executar.

Desinstalando o Ollama via Docker:

Parar o Contêiner: docker stop my_ollama (use o nome do seu contêiner).
Remover o Contêiner: docker rm my_ollama.
Remover a Imagem: docker rmi ollama/ollama (e ollama/ollama:rocm se você usou).
(Opcional, Destrutivo) Remover o Volume: Se você quiser excluir todos os modelos baixados armazenados no volume Docker, execute docker volume rm ollama_data (use o nome do volume que você criou). Aviso: Isso é irreversível.

Conclusão: Abraçando o Poder da IA Local com o Ollama

O Ollama se destaca como uma ferramenta fundamental na democratização do acesso ao imenso poder dos modernos Grandes Modelos de Linguagem. Ao abstrair elegantemente as complexidades da configuração, ajuste e execução, ele capacita uma gama diversificada de usuários – de desenvolvedores e pesquisadores experientes a entusiastas curiosos – a executar IA sofisticada diretamente em seu próprio hardware. As vantagens são claras: privacidade incomparável, liberdade de custos recorrentes de API, operação offline confiável e a capacidade libertadora de personalizar e experimentar profundamente com modelos usando o sistema intuitivo Modelfile e a robusta API.

Seja seu objetivo construir a próxima geração de aplicações impulsionadas por IA, conduzir pesquisas de ponta mantendo a soberania dos dados, ou simplesmente explorar as fascinantes capacidades da geração de linguagem sem dependências externas, o Ollama fornece uma base estável, eficiente e amigável. Ele preenche com sucesso a lacuna entre o poder bruto de motores de inferência como llama.cpp e as necessidades práticas dos usuários, fomentando a inovação dentro do vibrante cenário da IA de código aberto.

A jornada ao mundo dos LLMs locais é acessível e profundamente recompensadora, graças ao Ollama. Baixe a aplicação, puxe seu primeiro modelo usando ollama pull, inicie uma conversa com ollama run e comece a desbloquear o vasto potencial da inteligência artificial, diretamente em sua própria máquina.

💡