Integrando o Ollama com Python: Exemplos de API REST e Cliente Python

+ Exemplos Específicos Utilizando LLMs de Pensamento

Conteúdo da página

Neste post, vamos explorar duas formas de conectar seu aplicativo Python ao Ollama: 1. Via HTTP REST API; 2. Via a biblioteca oficial do Ollama para Python.

Vamos abordar tanto as chamadas chat quanto as generate, e depois discutir como usar efetivamente os “modelos de pensamento”.

ollama e python

Ollama tornou-se rapidamente uma das formas mais convenientes de executar modelos de linguagem grandes (LLMs) localmente. Para ver como o Ollama se compara com o vLLM, Docker Model Runner, LocalAI e provedores de nuvem — incluindo quando escolher cada um — veja LLM Hosting: Local, Self-Hosted & Cloud Infrastructure Compared. Com sua interface simples e suporte a modelos abertos populares como Llama 3, Mistral, Qwen2.5, e até variantes de “pensamento” como qwen3, é fácil integrar capacidades de IA diretamente em seus projetos Python — sem depender de APIs de nuvem externas.

🧩 Pré-requisitos

Antes de mergulhar, certifique-se de ter:

  • Ollama instalado e em execução localmente (ollama serve)
  • Python 3.9+
  • Dependências necessárias:
pip install requests ollama

Confirme se o Ollama está em execução executando:

ollama list

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

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

A REST API é ideal quando você deseja o máximo de controle ou ao integrar com frameworks que já lidam com solicitaçõ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 de Python."},
        {"role": "user", "content": "Escreva uma função que inverte 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 as respostas linha por linha (similar à API de streaming do OpenAI). Você pode acumular o conteúdo ou exibi-lo em tempo real para chatbots ou ferramentas CLI.

Exemplo 2: API de Geração

Se você não precisar de contexto de chat ou de 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 em uma única etapa — resumos, snippets de código, etc.

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

A biblioteca Python do Ollama oferece uma interface mais limpa para desenvolvedores que preferem ficar totalmente no 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": "Gerar um script Python que lista todos os arquivos em um diretório."}
    ]
)

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

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

stream = ollama.chat(
    model="llama3.1",
    messages=[
        {"role": "user", "content": "Escreva um haiku 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 stream 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 “Pensamento”

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

🧠

  Passos de raciocínio aqui...
</think>

Resposta final aqui.

Isso os torna úteis para:

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

Exemplo: Usando um Modelo de Pensamento

import ollama

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

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

# Opcionalmente extrair a parte "pensamento"
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 Pensamento

Caso de Uso Modelo Recomendado Por quê
Interpretabilidade / Depuração qwen3 Visualizar rastreamento de raciocínio
Aplicações sensíveis a desempenho qwen3 modo não-pensamento Mais rápido, menos verboso
Educativo / Explicativo qwen3 Mostra lógica passo a passo

✅ Resumo

Tarefa REST API Cliente Python
Geração de texto simples /api/generate ollama.generate()
Chat conversacional /api/chat ollama.chat()
Suporte a streaming Sim Sim
Funciona com modelos de pensamento Sim Sim

O design local-first do Ollama torna-o ideal para aplicações de IA seguras, offline ou sensíveis à privacidade. Seja você construindo um chatbot interativo ou um serviço de enriquecimento de dados em segundo plano, você pode integrar LLMs de forma seamles no 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 locais e de nuvem LLM, consulte nosso LLM Hosting: Local, Self-Hosted & Cloud Infrastructure Compared.