API Ollama em Python, depois um endpoint hospedado

Configure o cliente Python

Instale o próprio Ollama primeiro, inicie-o e puxe um modelo de um terminal: ollama pull llama3. O servidor escuta em http://localhost:11434. Depois instale o pacote Python em um ambiente virtual:

Copypython -m venv .venv
source .venv/bin/activate
pip install ollama openai

O pacote ollama se comunica com as rotas nativas do Ollama em /api. O pacote openai é destinado à segunda metade deste tutorial, onde o destino é um endpoint hospedado. Se preferir uma ferramenta visual antes de codificar, consulte as notas sobre usar o Ollama com uma GUI.

Verifique a instalação executando ollama list no terminal. Se o seu modelo aparecer lá, o Python o encontrará. Se você receber um erro de conexão mais tarde, o servidor provavelmente não está em execução.

Sua primeira chamada de chat

Este é o básico da API Python Ollama em um trecho: uma mensagem de sistema, uma mensagem de usuário e duas opções.

Copyimport ollama

resp = ollama.chat(
    model="llama3",
    messages=[
        {"role": "system", "content": "Answer in one short paragraph."},
        {"role": "user", "content": "What is a context window?"},
    ],
    options={"temperature": 0.4, "num_ctx": 8192},
)
print(resp["message"]["content"])

A resposta é um objeto semelhante a dicionário; o texto está em message.content. Em options você pode definir parâmetros de geração. temperature controla a aleatoriedade e num_ctx define o comprimento da janela de contexto para essa chamada. A Ollama usa por padrão uma janela de contexto bastante pequena, a menos que você a aumente, o que surpreende quem cola documentos longos e recebe respostas que ignoram o início.

Para conversas multi-turno, mantenha uma lista de mensagens e adicione cada resposta manualmente. O Ollama, como a maioria das APIs de chat, é sem estado entre as chamadas.

Respostas em streaming

Sem streaming você espera pela resposta completa. Com stream=True a função retorna um gerador e você imprime os pedaços conforme chegam:

Copyimport ollama

for part in ollama.chat(
    model="llama3",
    messages=[{"role": "user", "content": "Explain recursion with a cooking analogy."}],
    stream=True,
):
    print(part["message"]["content"], end="", flush=True)

Cada parte contém um pequeno message.content. A última parte tem done definido como true e inclui tempo de processamento e contagem de tokens. Para aplicativos web, encaminhe esses fragmentos para o navegador por meio de eventos enviados pelo servidor ou websocket.

Erros que você realmente verá

Duas falhas cobrem a maioria dos problemas de iniciante.

Copyimport ollama

try:
    ollama.chat(model="llama3", messages=[{"role": "user", "content": "hi"}])
except ollama.ResponseError as exc:
    if exc.status_code == 404:
        print("Model missing. Run: ollama pull llama3")
    else:
        raise
except ConnectionError:
    print("Cannot reach Ollama. Is the server running on port 11434?")

Um 404 de ResponseError significa que o nome do modelo não corresponde a algo que você puxou. Os nomes incluem tags, então llama3 e llama3:70b são modelos diferentes. Um erro de conexão significa que o servidor não está ativo, ou você está dentro de um container onde localhost aponta para o container, não para o host. Nesse caso, passe um cliente com o host correto: ollama.Client(host="http://host.docker.internal:11434").

Mais padrões são coletados em erros comuns na API Ollama.

Mesmo programa, endpoint hospedado

Modelos locais são limitados pela sua memória e velocidade. Quando um script precisa ser executado em um servidor, lidar com muitos trabalhos em paralelo ou usar uma janela maior, um endpoint hospedado é mais fácil. O truque é escrever o programa contra o SDK OpenAI e tratar URL base, chave e modelo como configuração:

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("LLM_BASE_URL", "https://api.ollamansfw.com/v1"),
    api_key=os.environ["LLM_API_KEY"],
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")

def ask(prompt, history=None):
    messages = (history or []) + [{"role": "user", "content": prompt}]
    out = ""
    for chunk in client.chat.completions.create(model=MODEL, messages=messages, stream=True):
        if chunk.choices and chunk.choices[0].delta.content:
            piece = chunk.choices[0].delta.content
            out += piece
            print(piece, end="", flush=True)
    return out

ask("Explain recursion with a cooking analogy.")

Para Ollama local, defina LLM_BASE_URL=http://localhost:11434/v1, LLM_API_KEY=ollama (qualquer string não vazia é aceita lá) e LLM_MODEL=llama3. Para a API hospedada, use os padrões acima, sua chave real e o modelo uncensored. Nada mais no código muda.

Obtenha uma chave na página de chaves de API. Contas novas podem reivindicar um crédito de teste de $0,50 com um clique, sem pagamento, válido por 7 dias. O modelo é um modelo de pesos abertos de um provedor independente, ajustado para responder sem recusas de conteúdo para uso adulto legal. É apenas texto e não é uma API oficial de qualquer grande laboratório.

Executando muitos prompts em paralelo

Um modelo local em uma máquina geralmente processa uma requisição por vez, então os loops são sequenciais. Um endpoint hospedado permite concorrência, o que torna o trabalho em lote muito mais rápido. Mantenha a contagem de workers abaixo do limite da sua chave: 8 requisições simultâneas para uma chave completa, 2 para uma chave de teste.

Copyfrom concurrent.futures import ThreadPoolExecutor
from openai import OpenAI

client = OpenAI(base_url="https://api.ollamansfw.com/v1", api_key="YOUR_KEY")

def summarize(text):
    r = client.chat.completions.create(
        model="uncensored",
        messages=[{"role": "user", "content": "Summarize in one line: " + text}],
        max_tokens=60,
    )
    return r.choices[0].message.content

docs = ["first text", "second text", "third text"]
with ThreadPoolExecutor(max_workers=6) as pool:
    results = list(pool.map(summarize, docs))
print(results)

Seis workers deixam margem abaixo do limite de 8. Se um worker receber um 429, o SDK OpenAI tenta novamente algumas vezes por padrão, mas adicione seu próprio backoff para execuções longas. Lembre-se também que cada solicitação de streaming mantém seu slot até o fim do stream, então não misture um chat de streaming longo e um lote grande na mesma chave de teste.

Diferenças a planejar

• Sem opções apenas locais. num_ctx e keep_alive não têm significado no lado hospedado. A janela é de 100.000 tokens, incluindo prompt e resposta juntos.
• Limites de taxa. Uma chave completa permite 8 requisições simultâneas e 300 requisições por minuto; uma chave de teste permite 2 e 60. Passando disso você recebe 429 com rate_limited ou concurrency. Tente novamente após uma pausa; em sobrecarga temporária a resposta carrega Retry-After: 5.
• Custo. Entrada é $0,15 por 1M de tokens e saída é $0,50 por 1M. Um script que envia 2.000 prompts de 600 entrada e 400 saída de tokens gasta 2.000 x (600 x $0,15 + 400 x $0,50) / 1M = 2.000 x $0,00029 = $0,58.
• Faturamento. Crédito pré-pago, de $20 a $500, pago com cripto (USDT no TRC20 ou USDC na Base). Solicitações falhas ou recusadas não são cobradas.

Para uma comparação lado a lado dos endpoints, leia nossa nota de preços de API ou a documentação.

Mais guias

• API Ollama vs API OpenAI: Endpoints e Código
• Como usar o Ollama com uma GUI (e um fallback hospedado)