Integração do Ollama com Python: Exemplos de API REST e Cliente Python

Neste post, exploraremos duas maneiras de conectar sua aplicação Python ao Ollama: 1. Via API REST HTTP; 2. Via a biblioteca oficial Python do Ollama.

Cobriremos chamadas de chat e geração, e em seguida discutiremos como usar os modelos de “raciocínio” de forma eficaz.

Ollama tornou-se rapidamente uma das formas mais convenientes de executar grandes modelos de linguagem (LLMs) localmente. Para ver como o Ollama se compara com vLLM, Docker Model Runner, LocalAI e provedores de nuvem — incluindo quando escolher cada um — veja Hospedagem de LLM: Infraestrutura Local, Auto-hospedada e em Nuvem Comparadas. Com sua interface simples e suporte para modelos abertos populares como Llama 3, Mistral, Qwen2.5 e até variantes de “raciocínio” como qwen3, é fácil integrar capacidades de IA diretamente nos seus projetos Python — sem depender de APIs de nuvem externas.

🧩 Pré-requisitos

Antes de começar, certifique-se de ter:

• Ollama instalado e rodando localmente (ollama serve)
• Python 3.9+
• Dependências necessárias:

pip install requests ollama

Confirme que o Ollama está rodando executando:

ollama list

Você deve ver modelos disponíveis como llama3, mistral ou qwen3.

⚙️ Opção 1: Usando a API REST do Ollama

A API REST é ideal quando você deseja controle máximo ou ao integrar com frameworks que já lidam com requisições HTTP.

Exemplo 1: API de Chat

import requests
import json

url = "http://localhost:11434/api/chat"

payload = {
    "model": "llama3.1",
    "messages": [
        {"role": "system", "content": "Você é um assistente Python."},
        {"role": "user", "content": "Escreva uma função que inverta uma string."}
    ]
}

response = requests.post(url, json=payload, stream=True)

for line in response.iter_lines():
    if line:
        data = json.loads(line)
        print(data.get("message", {}).get("content", ""), end="")

👉 A API REST do Ollama transmite respostas linha por linha (similar à API de streaming do OpenAI). Você pode acumular conteúdo ou exibi-lo em tempo real para chatbots ou ferramentas de CLI.

Exemplo 2: API de Geração

Se você não precisa de contexto de chat ou papéis, use o endpoint mais simples /api/generate:

import requests

url = "http://localhost:11434/api/generate"
payload = {
    "model": "llama3.1",
    "prompt": "Explique recursão em uma frase."
}

response = requests.post(url, json=payload, stream=True)
for line in response.iter_lines():
    if line:
        print(line.decode("utf-8"))

Este endpoint é ótimo para tarefas de geração de texto de única passagem — resumos, trechos de código, etc.

🐍 Opção 2: Usando a Biblioteca Python do Ollama

O cliente Python do Ollama oferece uma interface mais limpa para desenvolvedores que preferem permanecer totalmente em Python.

Exemplo 1: API de Chat

import ollama

response = ollama.chat(
    model="llama3.1",
    messages=[
        {"role": "system", "content": "Você é um assistente de código."},
        {"role": "user", "content": "Gere um script Python que liste todos os arquivos em um diretório."}
    ]
)

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

Isso retorna a mensagem final como um dicionário. Se você quiser streaming, pode iterar sobre o stream do chat:

stream = ollama.chat(
    model="llama3.1",
    messages=[
        {"role": "user", "content": "Escreva um haicai sobre recursão."}
    ],
    stream=True
)

for chunk in stream:
    print(chunk['message']['content'], end='', flush=True)

Exemplo 2: API de Geração

import ollama

output = ollama.generate(
    model="llama3.1",
    prompt="Resuma o conceito de decoradores em Python."
)

print(output['response'])

Ou transmita o resultado:

stream = ollama.generate(
    model="llama3.1",
    prompt="Liste três vantagens de usar Python para projetos de IA.",
    stream=True
)

for chunk in stream:
    print(chunk['response'], end='', flush=True)

🧠 Trabalhando com Modelos de “Raciocínio”

O Ollama suporta “modelos de raciocínio” como qwen3, projetados para mostrar seus passos intermediários de raciocínio. Esses modelos produzem saída estruturada, frequentemente em um formato como:

Resposta final aqui.

Isso os torna úteis para:

• Depurar o raciocínio do modelo
• Pesquisa em interpretabilidade
• Construir ferramentas que separam pensamento de saída

Exemplo: Usando um Modelo de Raciocínio

import ollama

response = ollama.chat(
    model="qwen3",
    messages=[
        {"role": "user", "content": "Qual é a capital da Austrália?"}
    ]
)

content = response['message']['content']

# Opcionalmente extraia a parte de "raciocínio"
import re
thinking = re.findall(r"", content, re.DOTALL)
answer = re.sub(r"", "", content, flags=re.DOTALL)

print("🧠 Processo de pensamento:\n", thinking[0].strip() if thinking else "N/A")
print("\n✅ Resposta final:\n", answer.strip())

Quando Usar Modelos de Raciocínio

✅ Resumo

O design local-first do Ollama o torna ideal para aplicações de IA seguras, offline ou sensíveis à privacidade. Seja construindo um chatbot interativo ou um serviço de enriquecimento de dados em segundo plano, você pode integrar LLMs de forma perfeita ao seu fluxo de trabalho Python — com controle total sobre modelos, latência e dados. Para uma comparação mais ampla do Ollama com outras infraestruturas de LLM locais e em nuvem, consulte nosso Hospedagem de LLM: Infraestrutura Local, Auto-hospedada e em Nuvem Comparadas.

Links úteis

• https://pypi.org/project/ollama/
• Ollama cheatsheet
• Python Cheatsheet
• Instalar e configurar Ollama
• Restringindo LLMs com Saída Estruturada: Ollama, Qwen3 & Python ou Go
• Comparação de saída estruturada entre provedores de LLM populares - OpenAI, Gemini, Anthropic, Mistral e AWS Bedrock
• Problemas de Saída Estruturada do Ollama GPT-OSS
• Como o Ollama Lida com Requisições Paralelas
• Teste: Alocação de memória e agendamento de modelos na nova versão do Ollama - v0.12.1