Blog
Ponto de vista

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

Audrey Lopez

Audrey Lopez

28 abril 2025

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?

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.

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:

Instalando o Ollama no macOS

  1. Download: Obtenha o arquivo DMG da aplicação Ollama para macOS diretamente do site oficial do Ollama.
  2. Montar: Dê um duplo clique no arquivo .dmg baixado para abri-lo.
  3. Instalar: Arraste o ícone Ollama.app para sua pasta de Aplicativos.
  4. Executar: Abra a aplicação Ollama da sua pasta de Aplicativos. Pode ser necessário conceder permissão para executá-la na primeira vez.
  5. 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

  1. Download: Obtenha o arquivo instalador OllamaSetup.exe do site do Ollama.
  2. 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).
  3. 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:

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:

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:

  1. Baixar o binário correto para sua arquitetura.
  2. Tornar o binário executável (chmod +x ollama) e movê-lo para um local no seu PATH (ex., /usr/local/bin).
  3. (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.
  4. 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.
  5. Recarregar o daemon systemd: sudo systemctl daemon-reload.
  6. Habilitar o serviço para iniciar na inicialização: sudo systemctl enable ollama.
  7. 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:

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

Contêiner Ollama com GPU NVIDIA:

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):

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

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:

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:

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 /:

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:

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

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:

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.

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:

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:

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:

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:

  1. base_url (ou api_base): Defina isso para seu ponto de extremidade local Ollama v1: http://localhost:11434/v1/.
  2. 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:

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>.

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.

  1. Baixe o arquivo .gguf (ex., zephyr-7b-beta.Q5_K_M.gguf).
  2. 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
  1. 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:

  1. 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/).
  2. 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
  1. 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:

  1. 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).
  2. 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/).
  3. 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."
  1. 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:

  1. 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
  1. 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:

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:

  1. 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.
  2. 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.
  3. 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
  1. 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:

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

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:

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:

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

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:

  1. Execute sudo systemctl edit ollama.service. Isso abre um editor de texto vazio.
  2. 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"
  1. Salve e feche o editor.
  2. Aplique as alterações: sudo systemctl daemon-reload
  3. Reinicie o serviço Ollama: sudo systemctl restart ollama

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

  1. Procure por "Editar as variáveis de ambiente do sistema" no menu Iniciar e abra-o.
  2. Clique no botão "Variáveis de Ambiente...".
  3. 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.
  4. Clique em "Novo..." sob a seção desejada.
  5. Digite o Nome da variável (ex., OLLAMA_MODELS) e o Valor da variável (ex., D:\OllamaData).
  6. Clique em OK em todos os diálogos abertos.
  7. 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:

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.

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:

Abordando Outros Problemas Comuns do Ollama

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):

  1. Sair do Ollama: Clique no ícone do Ollama na barra de menus e selecione "Sair do Ollama".
  2. Remover Aplicação: Arraste Ollama.app de sua pasta /Aplicativos para a Lixeira/Bin.
  3. 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.
  4. (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):

  1. 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.
  2. 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.
  3. (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):

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

Desinstalando o Ollama via Docker:

  1. Parar o Contêiner: docker stop my_ollama (use o nome do seu contêiner).
  2. Remover o Contêiner: docker rm my_ollama.
  3. Remover a Imagem: docker rmi ollama/ollama (e ollama/ollama:rocm se você usou).
  4. (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.

💡
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

Explore more

Onde Baixar Swagger UI em Português Grátis

Onde Baixar Swagger UI em Português Grátis

Explore a dificuldade de obter uma interface em português para o Swagger UI e saiba por que o Apidog é uma alternativa de plataforma poderosa para o desenvolvimento de APIs.

23 abril 2025

Onde Baixar o Postman em Português Grátis

Onde Baixar o Postman em Português Grátis

No mundo do desenvolvimento de software, especialmente ao trabalhar com APIs, ferramentas eficientes são essenciais. Postman se tornou um nome conhecido, uma plataforma popular usada por milhões de desenvolvedores para criar, testar e gerenciar APIs. No entanto, para muitos usuários de língua portuguesa, uma pergunta comum surge: é possível ter o Postman em português? A resposta curta é que Postman não oferece atualmente suporte nativo em português para sua interface de usuário. Mas não se preo

21 abril 2025

Desvendando Testes de API: Guia Completo do Postman para Iniciantes

Desvendando Testes de API: Guia Completo do Postman para Iniciantes

Este artigo introduz o uso básico do Postman, incluindo instalação, teste de APIs e envio de requisições HTTP, destacando suas funções convenientes e limitações, sugerindo soluções como o Apidog.

27 março 2025

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar