Biblioteca Python do Ollama: começando com LLMs localmente

As APIs de LLMs na nuvem são poderosas, mas trazem alguns trade-offs: cobrança por uso, limites de taxa e a incerteza constante sobre onde seus dados estão sendo processados. Para desenvolvedores que trabalham com dados sensíveis ou fazem muitos experimentos, essas restrições viram atrito rapidamente.

É aqui que as abordagens local-first se destacam. A biblioteca Python do Ollama elimina esse atrito ao permitir que você rode modelos de linguagem grandes localmente e interaja com eles usando um código limpo e nativo em Python. Isso dá controle total sobre desempenho, custo e privacidade.

Neste artigo, vou apresentar toda a API da biblioteca Python do Ollama, desde a geração de texto com generate() até tool calling e modelos de visão.

Também recomendo conferir nossos tutoriais mais recentes sobre o Ollama:

• Tutorial Gemma 4: construindo um agente local de código com Gradio e Ollama
• Tutorial Qwen 3.5 Small Models: crie um gerador de vídeo para jogo com Ollama
• Usando OpenClaw com Ollama: construindo um analista de dados local
• Usando Claude Code com modelos locais do Ollama

Pré‑requisitos para rodar o Ollama com Python

Antes de começar, garanta que você tem o seguinte configurado no seu dispositivo:

• Python 3.8 ou superior

• Ollama baixado do site, instalado e em execução (ollama serve)

• Pelo menos um modelo baixado (ex.: ollama pull llama3.2)

Esses pré‑requisitos importam porque o SDK em Python é apenas um cliente; a inferência acontece no runtime do Ollama. Se o runtime não estiver disponível ou se não houver um modelo adequado, as chamadas vão falhar.

Você também pode considerar usar Docker com Ollama para manter a consistência de versões.

O que é a biblioteca Python do Ollama?

A biblioteca Python do Ollama é o SDK oficial que encapsula a REST API do Ollama em uma interface simples e "pythônica". Em outras palavras, ela transforma requisições HTTP de baixo nível e payloads JSON em funções Python de alto nível, para você focar no objetivo e não nos detalhes de transporte.

À medida que seu aplicativo cresce, essa abstração evita a repetição na construção de requisições, padroniza o tratamento de respostas e centraliza o tratamento de erros em um só lugar.

Para comparar, uma requisição bruta poderia ser assim:

import requests

response = requests.post(
    "http://localhost:11434/api/generate",
    json={
        "model": "llama3.2",
        "prompt": "Explain recursion"
    }
)

Funciona, mas rapidamente fica verboso e sujeito a erros. Com o SDK, a mesma tarefa vira:

import ollama

response = ollama.generate(
    model='llama3.2',
    prompt='Explain recursion'
)

Como a biblioteca se comunica com o servidor do Ollama

Por baixo dos panos, cada chamada do SDK vira uma requisição HTTP ao servidor do Ollama em http://localhost:11434. Seu script Python atua como cliente, enquanto o runtime do Ollama funciona como servidor que hospeda e executa os modelos.

Essa separação é importante porque permite rodar o modelo como um serviço dedicado, tornando a gestão de recursos (CPU/GPU) mais eficiente e permitindo que múltiplos aplicativos compartilhem a mesma instância do modelo.

Se você precisar se conectar a outra máquina, pode configurar um client personalizado:

from ollama import Client

client = Client(host='http://remote-server:11434')
response = client.generate(model='llama3.2', prompt='Hello')

Instalação e configuração da biblioteca

A instalação é simples e requer poucas dependências:

pip install ollama

Depois de instalar, é uma boa prática verificar a conectividade listando os modelos disponíveis. 

Isso ajuda a confirmar que seu ambiente Python, o SDK e o runtime do Ollama estão conectados corretamente.

Para fazer isso, rode:

import ollama

print(ollama.list())

Gerando texto com generate()

A função generate() foi feita para tarefas sem estado, ou seja, cada requisição é tratada de forma independente, sem memória de interações anteriores. Isso a torna ideal para tarefas como sumarização, reescrita ou geração de código.

Como não há contexto mantido, a qualidade do resultado depende totalmente da clareza do seu prompt.

Geração de texto básica

O exemplo a seguir mostra o fluxo mais simples: enviar um prompt, receber a resposta e extrair o texto gerado.

import ollama

response = ollama.generate(
    model='llama3.2',
    prompt='Write a Python docstring for a function that calculates factorial'
)

print(response['response'])

A resposta também inclui metadados como tempo de execução e contagens de tokens, úteis para otimização de desempenho.

Personalizando a saída com parâmetros

O comportamento da geração pode ser ajustado com parâmetros de amostragem, que controlam como o modelo seleciona tokens.

Valores mais baixos de temperature produzem saídas mais determinísticas, enquanto valores altos trazem mais variabilidade. Você pode usar parâmetros como top_p e num_predict para refinar a diversidade e o tamanho da saída.

Aqui estão alguns parâmetros importantes que você pode usar: 

Aqui vai um exemplo usando os parâmetros top_p, temperature e num_predict:

response = ollama.generate(
    model='llama3.2',
    prompt='Explain machine learning in one paragraph',
    options={
        'temperature': 0.2,
        'top_p': 0.9,
        'num_predict': 100
    }
)

Construindo conversas com chat()

Diferente de generate(), a API chat() suporta interações com estado, trabalhando com uma sequência de mensagens. Isso permite que o modelo mantenha contexto ao longo de várias trocas.

Cada mensagem inclui um papel, como user, assistant ou system, o que ajuda a estruturar a conversa.

Requisições de chat de um único turno

Mesmo uma interação de um único turno usa o formato de mensagens, o que prepara o terreno para conversas mais complexas.

response = ollama.chat(
    model='llama3.2',
    messages=[
        {'role': 'user', 'content': 'Explain Python decorators'}
    ]
)

print(response['message']['content'])

Mantendo contexto em múltiplos turnos

Para manter o contexto, você armazena e reenvia explicitamente todo o histórico da conversa a cada requisição. Isso dá controle total sobre o que o modelo "lembra".

messages = [
    {'role': 'user', 'content': 'What is recursion?'}
]

response = ollama.chat(model='llama3.2', messages=messages)
messages.append(response['message'])

messages.append({'role': 'user', 'content': 'Give an example in Python'})
response = ollama.chat(model='llama3.2', messages=messages)

Usando prompts de system para moldar o comportamento

Um prompt de system define antecipadamente o comportamento do modelo, como tom, restrições ou papel.

messages = [
    {'role': 'system', 'content': 'You are a strict Python code reviewer.'},
    {'role': 'user', 'content': 'Review this code: def add(a,b): return a+b'}
]

Suporte a streaming e assíncrono na biblioteca Python do Ollama

Para apps interativos, responsividade é tão importante quanto correção. O Ollama oferece streaming e execução assíncrona para melhorar desempenho e experiência do usuário.

Respostas em streaming em tempo real

Com streaming, você processa a saída de forma incremental conforme ela é gerada, sem esperar pela resposta completa.

for chunk in ollama.chat(
    model='llama3.2',
    messages=[{'role': 'user', 'content': 'Write a story'}],
    stream=True
):
    print(chunk['message']['content'], end='', flush=True)

Usando AsyncClient em aplicações assíncronas

Execução assíncrona permite que seu app trate múltiplas requisições de forma concorrente sem bloquear. Você vai precisar usar a biblioteca asyncio do Python para implementar isso.

Veja um exemplo abaixo:

import asyncio
from ollama import AsyncClient

async def main():
    client = AsyncClient()
    async for chunk in await client.chat(
        model='llama3.2',
        messages=[{'role': 'user', 'content': 'Explain async programming'}],
        stream=True
    ):
        print(chunk['message']['content'], end='')

asyncio.run(main())

Gerenciando modelos do Ollama em Python

O SDK do Ollama também oferece ferramentas para gerenciar modelos programaticamente, o que é especialmente útil em ambientes automatizados.

Listando e inspecionando modelos locais

Você pode recuperar a lista de modelos disponíveis e inspecionar suas propriedades, como tamanho e configuração.

models = ollama.list()
print(models)

info = ollama.show('llama3.2')
print(info)

Baixando e excluindo modelos via código

Os modelos podem ser baixados ou removidos diretamente do Python, facilitando o gerenciamento dinâmico de dependências.

ollama.pull('llama3.2')
ollama.delete('llama3.2')

Gerando e usando embeddings com a biblioteca Python do Ollama

Embeddings representam textos como vetores numéricos que capturam significado semântico. Isso permite comparar textos por similaridade, e não por correspondência exata de palavras.

Criando embeddings de texto

O exemplo a seguir converte um texto em uma representação vetorial que pode ser usada em busca ou clusterização.

response = ollama.embed(
    model='nomic-embed-text',
    input='Ollama is a local LLM runtime'
)

embedding = response['embeddings'][0]

Construindo uma busca por similaridade básica

Depois de gerar embeddings, a similaridade pode ser medida com cosseno, que compara o ângulo entre vetores.

Aqui está um exemplo simples da função de busca:

import numpy as np

def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

Tool calling e saída estruturada na biblioteca Python do Ollama

Para apps mais avançados, os modelos muitas vezes precisam interagir com funções externas ou retornar dados estruturados.

Implementando tool calling com funções Python

Tool calling permite que o modelo invoque funções Python pré-definidas com base na intenção do usuário.

Vamos criar uma função que usa essas ferramentas:

def get_weather(city: str) -> str:
    """Get current weather for a city"""
    return f"Weather in {city} is sunny"
response = ollama.chat(
    model='llama3.2',
    messages=[{'role': 'user', 'content': 'What is the weather in Paris?'}],
    tools=[get_weather]
)

Obtendo respostas JSON estruturadas

Saídas estruturadas garantem que as respostas sejam retornadas em um formato consistente e legível por máquinas, como JSON.

response = ollama.chat(
    model='llama3.2',
    messages=[{'role': 'user', 'content': 'Review: Great product, 5 stars!'}],
    format='json'
)

Avançado: modelos de visão e Ollama Cloud em Python

O Ollama suporta modelos multimodais e inferência em nuvem para casos de uso mais avançados.

Enviando imagens para modelos de visão

Modelos de visão processam texto e imagens, possibilitando tarefas como descrição de imagens e análise visual.

response = ollama.chat(
    model='llama3.2-vision',
    messages=[{
        'role': 'user',
        'content': 'Describe this image',
        'images': ['image.jpg']
    }]
)

Rodando modelos em nuvem a partir do Python

Para modelos maiores que não rodam localmente, o Ollama Cloud oferece inferência hospedada.

ollama signin
ollama.chat(model='deepseek-v3.1:671b-cloud', messages=[...])
from ollama import Client

client = Client(
    host='https://ollama.com',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

Tratamento de erros: armadilhas mais comuns no Ollama Python

Ao construir aplicativos reais, tratar erros explicitamente ajuda a evitar falhas silenciosas e melhora a confiabilidade.

Tratando exceções ResponseError

O SDK do Ollama lança exceções estruturadas para erros do lado do servidor, permitindo inspecionar o que deu errado.

import ollama

try:
    ollama.generate(model='unknown', prompt='test')
except ollama.ResponseError as e:
    print(e.status_code, e.error)

Depurando problemas de conexão e de modelos

Os problemas mais comuns incluem servidor parado, modelos ausentes, memória insuficiente ou estouro do limite de contexto.

• Servidor não está rodando: Inicie com ollama serve

• Modelo não encontrado: Rode ollama pull

• Falta de memória: Use modelos menores ou quantização

• Problemas de contexto: Ajuste num_ctx

num_ctx controla o número máximo de tokens que o modelo consegue “ver” ao mesmo tempo, incluindo:

• seu prompt
• instruções de system
• histórico da conversa
• documentos recuperados (RAG)
• e os próprios tokens gerados pelo modelo 

Gerenciar esse parâmetro ajuda a evitar que o LLM trunque conteúdos anteriores (geralmente do começo) ou perca instruções/dados importantes sem aviso.

Considerações finais

A biblioteca Python do Ollama oferece uma interface completa para trabalhar com LLMs locais e em nuvem, desde a geração simples de texto até recursos avançados como embeddings, tool calling e entradas multimodais. Os LLMs viram um serviço local com o qual você pode scriptar, testar e escalar como qualquer outro componente do seu stack.

Na minha experiência usando o Ollama, senti que é uma boa alternativa sem depender de LLMs na nuvem. Por exemplo, posso usar modelos open source com mais liberdade. Se você também busca mais opções para alternar entre modelos, o Ollama é uma boa porta de entrada para acessar tudo isso.

Se quiser aprofundar suas habilidades, recomendo o nosso curso Developing LLM Applications with LangChain ou a certificação Associate AI Engineer for Developers.