Ollama + Python: Automatizar os Teus Modelos IA com API

Chegou a hora de desbloquear o verdadeiro potencial dos teus modelos de linguagem locais! Se já instalaste o Ollama no teu computador e brincaste um pouco com ele na linha de comandos, sabes o quão poderoso pode ser ter LLMs a correr localmente. Mas e se quiseres ir além da interação manual? E se precisares de integrar estas capacidades de IA nos teus próprios scripts, aplicações ou fluxos de trabalho automatizados? É aqui que a API do Ollama entra em cena, e combiná-la com a flexibilidade do Python é uma fórmula vencedora.

Neste tutorial, vais aprender os fundamentos de como usar a Ollama Python API para interagir com os teus modelos locais de forma programática. Vais descobrir como enviar prompts, receber respostas e integrar a inteligência artificial diretamente nos teus projetos Python. Prepara-te para automatizar tarefas, criar ferramentas personalizadas e explorar novas possibilidades com LLMs locais, tudo com o poder da programação.

Vamos arregaçar as mangas e começar a programar com o Ollama em Python!

O Que é o Ollama e a Sua API?

Antes de mergulharmos no código, vamos solidificar o nosso entendimento do que é o Ollama e porquê a sua API é tão crucial para o desenvolvimento de aplicações com inteligência artificial local.

O Ollama: O Teu Servidor Local de LLMs

Imagina ter os modelos de linguagem grandes (LLMs) mais recentes a correr diretamente no teu computador, sem a necessidade de enviar os teus dados para a cloud. É exatamente isso que o Ollama te permite fazer. Ele simplifica o processo de descarregar, configurar e executar modelos como o Llama 2, Mistral, Gemma e muitos outros. Essencialmente, o Ollama funciona como um servidor local que gere os teus modelos de IA, tornando-os acessíveis no teu próprio ambiente.

Executar LLMs localmente oferece várias vantagens, incluindo privacidade de dados, menor latência (pois não dependes de uma ligação à internet constante para cada interação) e controlo total sobre os modelos que usas. É uma ferramenta fantástica para programadores, investigadores e entusiastas que querem experimentar com IA sem as complexidades da configuração manual ou os custos associados a serviços baseados na cloud.

A API do Ollama: A Porta para a Interação Programática

Embora a linha de comandos do Ollama seja ótima para testar e interagir manualmente, a verdadeira magia acontece quando podes comunicar com ele a partir de outros programas. É para isso que serve a API do Ollama. Uma API (Interface de Programação de Aplicações) é um conjunto de regras e protocolos que permite que diferentes aplicações de software comuniquem entre si.

A API do Ollama expõe várias funcionalidades do serviço local através de pontos de acesso HTTP (endpoints). Isto significa que podes enviar requisições (como enviar um prompt para um modelo) e receber respostas (como o texto gerado pelo modelo) usando protocolos web padrão. Ao usar a API Ollama tutorial, vais aprender a enviar requisições para o teu servidor Ollama local a partir dos teus scripts Python, permitindo-te automatizar interações, integrar funcionalidades de IA em aplicações maiores ou criar interfaces personalizadas para os teus modelos.

Com a API, a linha de comandos torna-se apenas uma das muitas formas de interagir com o Ollama. Python, com a sua vasta coleção de bibliotecas e facilidade de uso, torna-se uma ferramenta ideal para explorar e tirar partido desta API, abrindo um leundo de possibilidades para o desenvolvimento Ollama Python.

Pré-requisitos: Prepara o Teu Ambiente

Antes de começarmos a escrever código para usar a Ollama Python API, precisas de ter algumas coisas configuradas no teu sistema. Certifica-te de que tens os seguintes pré-requisitos cumpridos.

1. Instala o Python e o Pip

Python é a linguagem que vamos usar, e o pip é o seu gestor de pacotes padrão, essencial para instalar bibliotecas adicionais. A maioria dos sistemas operativos modernos já vem com Python pré-instalado, mas é uma boa ideia verificar se tens uma versão recente (recomendamos Python 3.8 ou superior).

Abre o teu terminal ou linha de comandos e executa:

python --versionpip --version

Se os comandos não forem reconhecidos ou as versões forem muito antigas, descarrega e instala a versão mais recente do Python a partir do site oficial do Python. O pip geralmente vem incluído com as instalações mais recentes do Python.

2. Instala o Ollama e um Modelo LLM

Claro, precisas do próprio Ollama a correr! Se ainda não o fizeste, descarrega e instala o Ollama a partir do site oficial. Segue as instruções específicas para o teu sistema operativo (Windows, macOS ou Linux).

Depois de instalar o Ollama, precisas de descarregar pelo menos um modelo de linguagem para interagir. O Mistral é um bom modelo para começar, pois é rápido e capaz. Abre o teu terminal e executa:

ollama run mistral

Este comando irá descarregar o modelo Mistral se ainda não o tiveres. Podes digitar algo e interagir com o modelo para verificar se está a funcionar corretamente. Quando terminares, podes sair digitando /bye ou premindo Ctrl+C.

Ter o Ollama a correr com um modelo instalado é fundamental para que os teus scripts Python possam enviar requisições para ele.

3. Instala a Biblioteca requests

Para fazer requisições HTTP a partir de Python, a biblioteca mais popular e fácil de usar é a requests. Ela abstrai a complexidade de fazer pedidos web, tornando o nosso código muito mais limpo. Vais precisar dela para comunicar com a API do Ollama.

Abre o teu terminal e instala a biblioteca usando o pip:

pip install requests

Esta biblioteca será a nossa principal ferramenta para enviar dados para o servidor Ollama e receber as suas respostas. Com estes três passos concluídos, o teu ambiente está pronto para começarmos a usar a API do Ollama com Python!

Primeiros Passos com a API do Ollama

Agora que tens tudo configurado, vamos escrever o nosso primeiro script Python para interagir com o Ollama através da sua API. Vais ver como é simples enviar um prompt e obter uma resposta.

1. Importa as Bibliotecas Necessárias

Começa por abrir o teu editor de código favorito e cria um novo ficheiro Python (por exemplo, ollama_api_example.py). Precisamos de importar as bibliotecas requests para fazer as requisições HTTP e json para lidar com os dados que a API envia e recebe, que estão no formato JSON.

import requestsimport json

2. Define o URL da API do Ollama

Por padrão, quando instalas e executas o Ollama localmente, a sua API fica disponível no endereço http://localhost:11434. O endpoint específico para gerar texto a partir de um prompt é /api/generate. Vais definir isto como uma constante no teu script.

import requests
import json
API_URL = "http://localhost:11434/api/generate" # Endpoint para geração de texto

Certifica-te que o teu serviço Ollama está a correr em segundo plano para que este URL esteja acessível.

3. Cria uma Função para Enviar um Prompt

Vamos encapsular a lógica de interação com a API numa função. Esta função receberá o prompt que queres enviar e, opcionalmente, o nome do modelo a usar. Ela fará a requisição POST para o endpoint da API.

import requests
import json
API_URL = "http://localhost:11434/api/generate"

def generate_text(prompt, model="mistral"):
    """    Envia um prompt para a API do Ollama e devolve a resposta gerada.
    Args:
        prompt (str): O texto do prompt a enviar para o modelo.
        model (str): O nome do modelo Ollama a usar (p. ex., "mistral", "llama2").
    Returns:
        str: A resposta gerada pelo modelo ou uma mensagem de erro.
    """
    data = {
        "prompt": prompt,
        "model": model,
        "stream": False # Pedimos a resposta completa de uma vez
    }
    try:
        # Envia a requisição POST para a API
        response = requests.post(API_URL, data=json.dumps(data))
        # Verifica se a requisição foi bem sucedida (código 200)
        if response.status_code == 200:
            # Analisa a resposta JSON e extrai o texto gerado
            result = response.json()
            return result.get('response', 'Resposta inválida') # Usa .get para segurança
        else:
            # Devolve uma mensagem de erro se a requisição falhar
            return f"Erro na requisição: Código {response.status_code} - {response.text}"
    except requests.exceptions.ConnectionError:
        return "Erro: Não foi possível conectar à API do Ollama. Certifica-te que o Ollama está a correr."
    except Exception as e:
        return f"Ocorreu um erro inesperado: {e}"
# --- Exemplo de uso da função ---
prompt = "Escreve um breve poema sobre Lisboa."
print(f"A enviar prompt: '{prompt}'")
response_text = generate_text(prompt, model="mistral") # Podes mudar o modelo aqui
print("\nResposta do Ollama:")
print(response_text)

Neste código, criamos um dicionário data com o prompt e o nome do modelo. Definimos "stream": False para receber a resposta completa de uma só vez. Usamos requests.post() para enviar os dados (convertidos para JSON com json.dumps()) para o URL da API.

4. Analisar a Resposta JSON

Quando a API responde com sucesso (código 200), ela envia um corpo de resposta em formato JSON. A biblioteca requests converte automaticamente esta resposta JSON num dicionário Python quando chamas response.json(). A resposta gerada pelo modelo está tipicamente na chave 'response'.

O nosso código de exemplo já faz esta análise: result = response.json() e depois result.get('response', 'Resposta inválida'). Usar .get() é uma boa prática, pois evita erros caso a chave 'response' não esteja presente na resposta por algum motivo.

5. Lidar com Erros da API

É fundamental que o teu código saiba lidar com situações em que a requisição não é bem sucedida. A API pode devolver códigos de estado HTTP diferentes de 200 (OK) se algo correr mal, como 404 (Não Encontrado), 500 (Erro Interno do Servidor), ou outros. Além disso, podem ocorrer erros de conexão se o servidor Ollama não estiver a correr.

O bloco try...except no nosso exemplo de código serve para capturar estes erros. Primeiro, verificamos response.status_code. Se não for 200, imprimimos o código de erro e o texto da resposta para ajudar na depuração. Capturamos também requests.exceptions.ConnectionError especificamente para dar uma mensagem útil se o Ollama não estiver acessível, e um Exception genérico para quaisquer outros problemas inesperados durante a requisição.

Executa este script no teu terminal (certifica-te que o Ollama está a correr em segundo plano) e deverás ver o prompt enviado e a resposta gerada pelo modelo Mistral!

python ollama_api_example.py

Parabéns! Acabaste de fazer a tua primeira interação programática com um LLM local usando a Ollama Python integração.

Parâmetros da API do Ollama

A API do Ollama para geração de texto (o endpoint /api/generate que usámos) aceita vários parâmetros que te permitem controlar o comportamento do modelo e a forma como ele gera a resposta. Compreender estes parâmetros é crucial para obter os resultados desejados.

Os parâmetros são enviados no corpo da requisição POST, dentro do objeto JSON que enviamos. Aqui estão alguns dos mais comuns e úteis:

model (Obrigatório)

Este parâmetro especifica o nome do modelo Ollama que queres usar para a geração. Por exemplo, "mistral", "llama2", "gemma:2b", etc. O modelo deve estar instalado no teu Ollama local.

"model": "mistral"

prompt (Obrigatório)

Este é o texto de entrada, a pergunta ou a instrução que dás ao modelo. É o coração da tua requisição.

"prompt": "Escreve um breve poema sobre Lisboa."

stream (Opcional, Padrão: true)

Define se a resposta deve ser transmitida (streamed) à medida que é gerada (true) ou se deves esperar pela resposta completa (false). Para o nosso exemplo inicial, definimos "stream": false para simplificar. Para interfaces de utilizador ou quando queres mostrar a resposta em tempo real, usar "stream": true é mais apropriado. Se usares stream: true, a resposta da API será uma série de objetos JSON separados por quebras de linha, e precisarás de processá-los iterativamente.

"stream": false

Parâmetros de Geração (Opcionais)

Estes parâmetros influenciam diretamente o processo de inferência do modelo, afetando a criatividade, aleatoriedade e foco da resposta. São configurados dentro de um dicionário aninhado chamado options.

  • temperature (Padrão: 0.8): Controla a aleatoriedade da saída. Valores mais altos (p. ex., 1.0) tornam a saída mais aleatória e criativa, enquanto valores mais baixos (p. ex., 0.2) a tornam mais focada e determinística.
  • top_p (Padrão: 0.9): Controla a diversidade da saída, focando-se nos tokens mais prováveis cuja probabilidade cumulativa atinge top_p. Um valor mais baixo restringe a gama de tokens possíveis.
  • top_k (Padrão: 40): Limita a amostragem aos k tokens mais prováveis em cada passo.
  • num_predict (Padrão: 128): O número máximo de tokens a gerar na resposta.
  • repeat_penalty (Padrão: 1.1): Penaliza a repetição de tokens para evitar loops na geração.

Podes incluir estes parâmetros na tua requisição da seguinte forma:

data = {
    "prompt": prompt,
    "model": model,
    "stream": False,
    "options": {
        "temperature": 0.7,
        "top_p": 0.95,
        "num_predict": 500 # Gerar até 500 tokens
    }}

Experimentar com estes parâmetros permite-te ajustar a resposta do modelo às tuas necessidades específicas. Por exemplo, para tarefas criativas, podes aumentar a temperature; para resumos concisos, podes diminuir a num_predict.

A documentação oficial da API do Ollama lista todos os parâmetros disponíveis e as suas descrições detalhadas. Explorá-los é uma parte importante do desenvolvimento Ollama Python.

Exemplos de Uso da API

Agora que conheces os fundamentos e os parâmetros, vamos ver como podes usar a função generate_text que criámos para realizar diferentes tarefas comuns de processamento de linguagem natural (PNL). A beleza da API é que a mesma função básica pode ser usada para uma variedade de casos de uso, simplesmente mudando o prompt.

1. Gerar Texto a Partir de um Prompt

Já vimos um exemplo básico com um poema. Podes usar a mesma abordagem para gerar qualquer tipo de texto:

  • Histórias curtas
  • Descrições de produtos
  • E-mails
  • Conteúdo para redes sociais

Basta mudar a variável prompt:

# Exemplo: Gerar uma ideia para uma história
prompt_historia = "Escreve uma sinopse para uma história de ficção científica sobre um astronauta que descobre uma civilização perdida num planeta distante."
resposta_historia = generate_text(prompt_historia, model="mistral")
print("\nSinopse da História:")
print(resposta_historia)

2. Resumir um Texto

Para resumir um texto, a chave está em construir um prompt que instrua o modelo a realizar essa tarefa e incluir o texto que queres resumir.

# Exemplo: Resumir um texto
texto_longo = """A inteligência artificial (IA) é um campo da ciência da computação dedicado à criação de sistemas que podem realizar tarefas que normalmente exigiriam inteligência humana. Isso inclui aprendizagem, perceção, resolução de problemas e tomada de decisões. Os avanços recentes em IA, particularmente em aprendizagem automática e modelos de linguagem grandes (LLMs), impulsionaram a tecnologia para novas aplicações em áreas como saúde, finanças e transporte. A ética e a segurança da IA são tópicos de debate importantes à medida que a tecnologia continua a evoluir."""
prompt_resumo = f"Resume o seguinte texto em 3 frases:\n\n{texto_longo}"
resposta_resumo = generate_text(prompt_resumo, model="mistral")
print("\nResumo:")
print(resposta_resumo)

Ao construir o prompt, usa frases claras como “Resume o seguinte texto…” e inclui o texto a resumir. Podes até especificar o número de frases ou a extensão desejada para o resumo.

3. Traduzir um Texto

Semelhante ao resumo, podes instruir o modelo a traduzir um texto para outro idioma.

# Exemplo: Traduzir um texto
texto_ingles = "Artificial intelligence is transforming industries worldwide."
prompt_traducao = f"Traduz o seguinte texto para Português de Portugal:\n\n{texto_ingles}"
resposta_traducao = generate_text(prompt_traducao, model="mistral")
print("\nTradução (PT-PT):")
print(resposta_traducao)

Especificar “Português de Portugal” no prompt ajuda a garantir que a tradução use a variante correta da língua.

4. Integrar com Outras Bibliotecas Python

A capacidade de chamar a API do Ollama a partir de Python abre portas para integrações mais complexas. Podes combinar a funcionalidade de geração de texto com outras bibliotecas Python para criar aplicações mais ricas:

  • Interfaces Web: Usa frameworks como Flask ou Streamlit para criar uma interface gráfica onde os utilizadores podem inserir prompts e ver as respostas do Ollama. O Streamlit é particularmente fácil para criar protótipos rápidos.
  • Automação de Tarefas: Integra a geração de texto em scripts que automatizam a criação de relatórios, a resposta a e-mails, ou a geração de conteúdo para um blog.
  • Análise de Dados: Processa grandes volumes de texto usando a API para tarefas como classificação, extração de entidades ou análise de sentimento, e depois usa bibliotecas de análise de dados como Pandas ou NLTK para processar os resultados.

Por exemplo, uma aplicação Streamlit simples poderia ter uma caixa de texto para o prompt, um botão para enviar, e uma área para mostrar a resposta, tudo usando a função generate_text nos bastidores.

Estes exemplos demonstram a versatilidade de usar a API Ollama para LLMs em Python. A tua imaginação é o limite para o tipo de aplicações que podes construir!

Dicas e Truques para Usar a API do Ollama em Python

Ao trabalhares com a API do Ollama nos teus projetos Python, algumas práticas recomendadas podem tornar o teu código mais robusto, eficiente e fácil de manter. Aqui ficam algumas dicas:

1. Usar Variáveis de Ambiente para Configurações

Em vez de codificar o URL da API (http://localhost:11434) diretamente no teu script, considera usar variáveis de ambiente. Isto torna o teu código mais flexível, permitindo-te mudar o endereço da API (por exemplo, se estiveres a executar o Ollama num servidor diferente) sem modificar o código fonte. A biblioteca Python os pode ajudar-te com isto.

import os
API_URL = os.getenv("OLLAMA_API_URL", "http://localhost:11434/api/generate")
# Agora usa API_URL no teu código 
requests.post()

Podes definir a variável de ambiente antes de executar o script, por exemplo, no Linux/macOS:

export OLLAMA_API_URL="http://192.168.1.100:11434/api/generate"
python your_script.py

2. Implementar Tratamento de Erros Robusto

Já incluímos um tratamento básico de erros na nossa função generate_text, mas podes torná-lo mais sofisticado. Por exemplo, podes adicionar lógica para tentar novamente a requisição após um curto período de espera se receberes um erro de conexão ou um código de estado de servidor (5xx). Podes também registar (log) os erros para depuração.

Considera também validar os dados de entrada (o prompt, o nome do modelo) antes de enviar a requisição para evitar erros desnecessários.

3. Otimizar o Código para Desempenho

Para aplicações que precisam de alta performance ou que lidam com muitas requisições, considera:

  • Reutilizar a Conexão: Se estiveres a fazer muitas requisições para o mesmo endpoint, usar uma sessão requests.Session pode ser mais eficiente, pois reutiliza a conexão TCP subjacente.
  • Processamento Assíncrono: Para evitar bloquear o teu programa enquanto esperas pela resposta do Ollama, especialmente se usares stream: true ou fizeres várias requisições em paralelo, explora bibliotecas assíncronas como asyncio e aiohttp em conjunto com a API do Ollama.
  • Gerir Modelos: Certifica-te que o modelo que precisas está carregado no Ollama antes de fazer a requisição. Podes até usar outros endpoints da API do Ollama (como /api/show ou /api/pull) nos teus scripts para verificar ou descarregar modelos programaticamente.

Estas otimizações são mais relevantes para aplicações em produção ou com requisitos de desempenho rigorosos, mas são boas práticas a ter em mente à medida que te tornas mais proficiente com a Ollama Python API.

Conclusão

Chegaste ao fim deste tutorial básico sobre como usar a Ollama Python API! Explorámos o que é o Ollama, como a sua API te permite interagir programaticamente com modelos locais e, mais importante, escrevemos código Python para enviar prompts e receber respostas. Viste como configurar o teu ambiente, usar a biblioteca requests e entender a estrutura das requisições e respostas.

Dominar a API do Ollama com Python abre um leque vasto de possibilidades. Podes agora ir além da linha de comandos e integrar as capacidades de modelos de linguagem grandes nos teus próprios projetos. Automatiza tarefas, cria assistentes virtuais personalizados, desenvolve ferramentas de processamento de texto ou experimenta novas ideias de aplicações baseadas em LLMs, tudo a correr no teu próprio hardware.

Este tutorial cobriu os fundamentos do endpoint /api/generate, mas a API do Ollama oferece mais (como gestão de modelos, embeddings, etc.). Encorajamos-te vivamente a consultar a documentação oficial e experimentar os outros endpoints e parâmetros. Continua a praticar, adapta os exemplos de código às tuas necessidades e começa a construir as tuas próprias aplicações com a integração Python LLMs local.

Não hesites em modificar o código fornecido, experimentar diferentes modelos e explorar os vários parâmetros da API. O desenvolvimento com LLMs locais é um campo empolgante, e com o Ollama e Python, tens as ferramentas necessárias para inovar!

FAQs (Perguntas Frequentes)

O que é a API do Ollama e para que serve?

A API do Ollama é uma interface que permite que programas externos comuniquem e interajam com o serviço Ollama a correr localmente. Serve para enviar prompts para modelos de linguagem grandes (LLMs) geridos pelo Ollama, receber as suas respostas e gerir os modelos programaticamente. É essencial para integrar LLMs locais em scripts e aplicações personalizadas.

Quais são os pré-requisitos para usar a API do Ollama com Python?

Precisas de ter o Python instalado (com o gestor de pacotes pip), o Ollama instalado e a correr no teu sistema com pelo menos um modelo descarregado (como o Mistral), e a biblioteca Python requests instalada (pip install requests).

Como enviar um prompt ao modelo e receber a resposta usando a API?

Usas a biblioteca requests em Python para fazer uma requisição POST para o endpoint http://localhost:11434/api/generate (ou o endereço onde o teu Ollama está a correr). O corpo da requisição deve ser um objeto JSON contendo o "prompt" e o nome do "model". A resposta da API, também em JSON, conterá o texto gerado pelo modelo na chave "response".

Quais são os parâmetros da API e como usá-los?

Os parâmetros como model e prompt são obrigatórios. Parâmetros opcionais como stream, temperature, top_p, num_predict, entre outros, permitem controlar o processo de geração. Estes parâmetros opcionais são geralmente incluídos num dicionário aninhado chamado options dentro do corpo da requisição POST. Ajustar estes parâmetros permite influenciar a criatividade, o foco e a extensão da resposta do modelo.

Quais são alguns exemplos práticos de uso da API?

Podes usar a API para gerar diversos tipos de texto (histórias, e-mails, descrições), resumir textos longos, traduzir conteúdo entre idiomas, classificar texto, extrair informações, e integrar estas funcionalidades em aplicações web (usando Flask, Streamlit), scripts de automação, ou ferramentas de análise de dados. A flexibilidade do Python permite combinar a API do Ollama com muitas outras bibliotecas para criar soluções poderosas.

Pode fazer uma doação para ajudar a mater o site, Obrigado!