API Ollama in Python, poi un endpoint ospitato

Configura il client Python

Installa prima Ollama stesso, avvialo e fai il pull di un modello da un terminale: ollama pull llama3. Il server ascolta su http://localhost:11434. Poi installa il pacchetto Python in un ambiente virtuale:

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

Il pacchetto ollama parla con gli endpoint nativi di Ollama sotto /api. Il pacchetto openai serve per la seconda parte del tutorial, dove il target è un endpoint ospitato. Per uno strumento visivo prima di programmare, vedi uso di Ollama con GUI.

Verifica l'installazione eseguendo ollama list nel terminale. Se il tuo modello appare lì, Python lo troverà. Se ottieni un errore di connessione in seguito, il server probabilmente non è in esecuzione.

La tua prima chiamata chat

Questa è la base dell'api python di ollama in un unico snippet: un messaggio di sistema, un messaggio utente e due opzioni.

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"])

La risposta è un oggetto simile a un dizionario; il testo si trova in message.content. In options puoi impostare i parametri di generazione. temperature controlla la casualità e num_ctx imposta la lunghezza del contesto per quella chiamata. Ollama utilizza un contesto piuttosto piccolo di default a meno che tu non lo aumenti, il che sorprende le persone che incollano documenti lunghi e ricevono risposte che ignorano l'inizio.

Per la chat multi-turno, mantieni un elenco di messaggi e aggiungi tu stesso ogni risposta. Ollama, come la maggior parte delle API chat, è stateless tra le chiamate.

Risposte in streaming

Senza streaming attendi la risposta completa. Con stream=True la funzione restituisce un generatore e stampi i pezzi man mano che arrivano:

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)

Ogni parte contiene un piccolo message.content. L'ultima parte ha done impostato su true e include i tempi e i conteggi dei token. Per le app web, inoltra questi pezzi al browser tramite eventi inviati dal server o un websocket.

Gli errori che vedrai davvero

Due failure coprono la maggior parte dei problemi dei principianti.

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?")

Un 404 da ResponseError significa che il nome del modello non corrisponde a un modello che hai scaricato con pull. I nomi includono tag, quindi llama3 e llama3:70b sono modelli diversi. Un errore di connessione significa che il server non è attivo, o che ti trovi all'interno di un container dove localhost punta al container, non all'host. In quel caso passa un client con l'host corretto: ollama.Client(host="http://host.docker.internal:11434").

Altri pattern sono raccolti in errori comuni dell'API Ollama.

Lo stesso programma, endpoint ospitato

I modelli locali sono limitati dalla tua memoria e velocità. Quando uno script deve essere eseguito su un server, gestire molti lavori paralleli o utilizzare una finestra più grande, un endpoint ospitato è più semplice. Il trucco è scrivere il programma contro l'SDK OpenAI e trattare l'URL di base, la chiave e il modello come configurazione:

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.")

Per Ollama locale, imposta LLM_BASE_URL=http://localhost:11434/v1, LLM_API_KEY=ollama (viene accettata qualsiasi stringa non vuota lì) e LLM_MODEL=llama3. Per l'API ospitata, usa i default sopra, la tua chiave reale e il modello uncensored. Nient'altro nel codice cambia.

Ottieni una chiave nella pagina delle chiavi API. I nuovi account possono richiedere un credito di prova da $0,50 con un solo clic, senza pagamento, valido per 7 giorni. Il modello è un modello a pesi aperti di un provider indipendente, ottimizzato per rispondere senza rifiuti di contenuti per un uso adulto lecito. È solo testo e non è un'API ufficiale di alcun grande laboratorio.

Esecuzione di molti prompt in parallelo

Un modello locale su una macchina di solito gestisce una richiesta alla volta, quindi i loop sono sequenziali. Un endpoint ospitato consente la concorrenza, il che rende il lavoro in batch molto più veloce. Mantieni il conteggio dei worker sotto il limite della tua chiave: 8 richieste concorrenti per una chiave completa, 2 per una chiave di prova.

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)

Sei worker lasciano margine sotto il limite di 8. Se un worker riceve un 429, l'SDK OpenAI riprova per un paio di volte per impostazione predefinita, ma aggiungi il tuo backoff per le esecuzioni lunghe. Ricorda anche che ogni richiesta streaming mantiene il suo slot fino alla fine dello stream, quindi non mescolare una chat streaming lunga e un batch grande sulla stessa chiave di prova.

Differenze da pianificare

• Nessuna opzione solo locale. num_ctx e keep_alive non hanno significato sul lato ospitato. La finestra è di 100.000 token, prompt e completamento insieme.
• Limiti di richieste. Una chiave completa permette 8 richieste concorrenti e 300 richieste al minuto; una chiave di prova ne permette 2 e 60. Superato questo limite ottieni un 429 con rate_limited o concurrency. Riprova dopo una pausa; in caso di sovraccarico temporaneo la risposta contiene Retry-After: 5.
• Costi. L'input è $0,15 per 1M di token e l'output è $0,50 per 1M. Uno script che invia 2.000 prompt di 600 token di input e 400 di output spende 2.000 x (600 x $0,15 + 400 x $0,50) / 1M = 2.000 x $0,00029 = $0,58.
• Fatturazione. Credito prepagato, da $20 a $500, pagato con cripto (USDT su TRC20 o USDC su Base). Le richieste fallite o rifiutate non vengono addebitate.

Per un confronto diretto degli endpoint, leggi la nostra nota sui prezzi API o la documentazione.

Altre guide

• API Ollama vs API OpenAI: Endpoint e Codice
• Come usare Ollama con un'interfaccia grafica (e un fallback ospitato)