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

Exemplos Específicos Utilizando Modelos de Linguagem Pensantes

Conteúdo da página

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

Vamos cobrir tanto chamadas de chat quanto de geração, e depois discutir como usar os “modelos de pensamento” de forma eficaz.

ollama and python

Ollama se tornou rapidamente uma das maneiras mais convenientes de executar grandes modelos de linguagem (LLMs) localmente. 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 incorporar capacidades de IA diretamente em 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 se 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 máximo 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 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 (semelhante à API de transmissão da OpenAI). Você pode acumular o conteúdo ou exibir em tempo real para chatbots ou ferramentas 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 a 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 único — 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 ficar 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 lista todos os arquivos em um diretório."}
    ]
)

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

Isso retorna a mensagem final como um dicionário. Se você quiser transmissão, pode iterar sobre o fluxo de 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 Pensamento”

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

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

Isso os torna úteis para:

  • Depuração do raciocínio do modelo
  • Pesquisa sobre interpretabilidade
  • Construção de ferramentas que separam 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, extraia a parte "de pensamento"
import re
thinking = re.findall(r"<think>(.*?)</think>", content, re.DOTALL)
answer = re.sub(r"<think>.*?</think>", "", 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 Visualiza traços de raciocínio
Aplicações sensíveis ao desempenho modo não pensante do qwen3 Mais rápido, menos verboso
Educacional / Explicativo qwen3 Mostra lógica passo a passo

✅ Resumo

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

O design local-first do Ollama o torna ideal para aplicações de IA seguras, offline ou sensíveis à privacidade. Seja você está construindo um chatbot interativo ou um serviço de enriquecimento de dados em segundo plano, pode integrar LLMs perfeitamente ao seu fluxo de trabalho Python — com controle total sobre modelos, latência e dados.