Como usar Python com Ollama (biblioteca ollama e OpenAI SDK)

Instalação

pip install ollama

Confirme primeiro se o serviço Ollama está em execução e se você já baixou o modelo que pretende usar (por exemplo, ollama pull qwen3:8b).

Conversa básica

from ollama import chat

response = chat(
    model="qwen3:8b",
    messages=[
        {"role": "system", "content": "Responda em português brasileiro."},
        {"role": "user", "content": "Explique o que é aprendizado de máquina em três pontos."},
    ],
)

print(response.message.content)

Você também pode acessar o objeto de resposta como um dicionário: response["message"]["content"].

Saída em streaming

Exiba o texto enquanto ele é gerado:

from ollama import chat

stream = chat(
    model="qwen3:8b",
    messages=[{"role": "user", "content": "Escreva um exemplo de apresentação pessoal com 100 palavras"}],
    stream=True,
)

for chunk in stream:
    print(chunk.message.content, end="", flush=True)
print()

Conversa com várias mensagens: crie um chat no terminal

O modelo não guarda o histórico por conta própria. Você precisa armazenar todas as mensagens em uma lista:

from ollama import chat

messages = [{"role": "system", "content": "Você é um assistente simpático. Responda em português brasileiro."}]

while True:
    user_input = input("Você: ").strip()
    if user_input in {"exit", "quit", "sair"}:
        break
    messages.append({"role": "user", "content": user_input})

    reply = ""
    print("AI：", end="", flush=True)
    for chunk in chat(model="qwen3:8b", messages=messages, stream=True):
        piece = chunk.message.content
        reply += piece
        print(piece, end="", flush=True)
    print()

    messages.append({"role": "assistant", "content": reply})

Quanto mais longa a conversa, mais conteúdo você envia, e o limite de contexto pode ser excedido. Na prática, você pode manter apenas as mensagens das últimas rodadas ou resumir as conversas antigas.

Parâmetros e modo de raciocínio

response = chat(
    model="qwen3:8b",
    messages=[{"role": "user", "content": "Qual é a soma dos números de 1 a 100?"}],
    options={"temperature": 0.2, "num_ctx": 8192},
    think=True,
    keep_alive="30m",
)

print("Raciocínio: ", response.message.thinking)
print("Resposta: ", response.message.content)

Leitura de imagens

response = chat(
    model="gemma3",
    messages=[{
        "role": "user",
        "content": "O que há nesta imagem?",
        "images": ["./photo.jpg"],   # Você também pode passar bytes ou uma string em base64
    }],
)
print(response.message.content)

Outros recursos

import ollama

ollama.generate(model="qwen3:8b", prompt="Apresente Taipei em uma frase")  # Geração única
ollama.list()                                               # Modelos baixados
ollama.ps()                                                 # Modelos carregados
ollama.pull("nomic-embed-text")                             # Baixar um modelo
ollama.show("qwen3:8b")                                     # Informações do modelo
ollama.embed(model="nomic-embed-text", input="Olá")         # Embedding de texto

Conexão a outro host

from ollama import Client

client = Client(host="http://192.168.1.50:11434")
response = client.chat(model="qwen3:8b", messages=[{"role": "user", "content": "Olá"}])
print(response.message.content)

Você também pode definir a variável de ambiente OLLAMA_HOST. A função chat() padrão passará a usá-la.

Operações assíncronas

Use em frameworks assíncronos, como o FastAPI:

import asyncio
from ollama import AsyncClient


async def main():
    client = AsyncClient()
    response = await client.chat(
        model="qwen3:8b",
        messages=[{"role": "user", "content": "Olá"}],
    )
    print(response.message.content)


asyncio.run(main())

Tratamento de erros

import ollama

try:
    ollama.chat(model="not-exist", messages=[{"role": "user", "content": "hi"}])
except ollama.ResponseError as e:
    print("Erro: ", e.error, e.status_code)
    if e.status_code == 404:
        print("O modelo não existe. Execute ollama pull primeiro.")
except ConnectionError:
    print("Não foi possível conectar ao Ollama. Confirme se o serviço está em execução.")

Uso do OpenAI Python SDK

Se o seu programa já usa o OpenAI SDK, basta alterar base_url:

pip install openai

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1/",
    api_key="ollama",  # Obrigatório, mas o Ollama não verifica o valor
)

completion = client.chat.completions.create(
    model="qwen3:8b",
    messages=[{"role": "user", "content": "Olá, apresente-se"}],
)
print(completion.choices[0].message.content)

Assim, você pode alternar o mesmo programa entre modelos locais e APIs na nuvem. Frameworks como LangChain e LlamaIndex também podem se conectar ao Ollama dessa mesma forma.

Na próxima seção, você verá como usar JavaScript / Node.js.

Atualizado 12 de outubro de 2026