Libreria Python di Ollama: come iniziare con gli LLM in locale

Le API LLM nel cloud sono potenti, ma hanno dei compromessi: prezzi basati sull’uso, limiti di rate e l’incertezza costante su dove vengono elaborati i tuoi dati. Per chi lavora con dati sensibili o sperimenta molto, questi vincoli possono diventare presto un ostacolo.

È qui che si distinguono gli approcci local-first. La libreria Python di Ollama elimina questi attriti permettendoti di eseguire modelli linguistici di grandi dimensioni in locale interagendo con loro tramite codice pulito, nativo Python. In questo modo hai pieno controllo su prestazioni, costi e privacy.

In questo articolo ti guiderò attraverso l’intera API della libreria Python di Ollama, dalla semplice generazione di testo con generate() fino al tool calling e ai modelli vision.

Ti consiglio anche di dare un’occhiata agli altri nostri ultimi tutorial su Ollama:

• Tutorial Gemma 4: crea un agente AI di coding locale con Gradio e Ollama
• Tutorial Qwen 3.5 Small Models: crea un generatore Video-to-Game con Ollama
• Usare OpenClaw con Ollama: creare un data analyst locale
• Usare Claude Code con i modelli locali di Ollama

Prerequisiti per eseguire Ollama con Python

Prima di iniziare, assicurati di avere il seguente setup sul tuo dispositivo:

• Python 3.8 o superiore

• Ollama scaricato dal suo sito, installato e in esecuzione (ollama serve)

• Almeno un modello scaricato (ad es., ollama pull llama3.2)

Questi prerequisiti sono importanti perché l’SDK Python è solo un client; l’inferenza vera e propria avviene nel runtime di Ollama. Se il runtime non è disponibile o non è presente un modello adatto, le chiamate falliranno.

Puoi anche valutare l’uso di Docker con Ollama per garantire coerenza di versione.

Che cos’è la libreria Python di Ollama?

La libreria Python di Ollama è l’SDK ufficiale che incapsula la REST API di Ollama in un’interfaccia semplice e “pythonic”. In altre parole, trasforma richieste HTTP di basso livello e payload JSON in funzioni Python di alto livello, così puoi concentrarti sull’intento invece che sui dettagli di trasporto.

Man mano che l’app cresce, questa astrazione elimina la costruzione ripetitiva delle richieste, standardizza la gestione delle risposte e centralizza la gestione degli errori in un unico punto.

Per confronto, una richiesta grezza potrebbe essere così:

import requests

response = requests.post(
    "http://localhost:11434/api/generate",
    json={
        "model": "llama3.2",
        "prompt": "Explain recursion"
    }
)

Funziona, ma diventa presto prolissa e soggetta a errori. Con l’SDK, lo stesso compito diventa:

import ollama

response = ollama.generate(
    model='llama3.2',
    prompt='Explain recursion'
)

Come la libreria comunica con il server Ollama

Sotto il cofano, ogni chiamata dell’SDK diventa una richiesta HTTP al server Ollama su http://localhost:11434. Il tuo script Python funge da client, mentre il runtime di Ollama funge da server che ospita ed esegue i modelli.

Questa separazione è importante perché permette al modello di funzionare come un servizio dedicato, rendendo più efficiente la gestione delle risorse (CPU/GPU) e consentendo a più applicazioni di condividere la stessa istanza di modello.

Se devi connetterti a un’altra macchina, puoi configurare un client personalizzato:

from ollama import Client

client = Client(host='http://remote-server:11434')
response = client.generate(model='llama3.2', prompt='Hello')

Installazione e configurazione della libreria

L’installazione è semplice e richiede poche dipendenze:

pip install ollama

Dopo l’installazione, è buona norma verificare la connettività elencando i modelli disponibili. 

Questo ti aiuta a confermare che l’ambiente Python, l’SDK e il runtime di Ollama sono tutti correttamente collegati.

Per farlo, esegui quanto segue:

import ollama

print(ollama.list())

Generare testo con generate()

La funzione generate() è progettata per attività stateless, il che significa che ogni richiesta viene gestita in modo indipendente senza alcuna memoria delle interazioni precedenti. È quindi ideale per attività come riassunti, riscritture o generazione di codice.

Poiché non c’è contesto mantenuto, la qualità dell’output dipende interamente da quanto è chiaro il prompt.

Generazione di testo di base

L’esempio seguente mostra il workflow più semplice: inviare un prompt, ricevere una risposta ed estrarre il testo generato.

import ollama

response = ollama.generate(
    model='llama3.2',
    prompt='Write a Python docstring for a function that calculates factorial'
)

print(response['response'])

La risposta include anche metadati come tempo di esecuzione e conteggio dei token, utili quando ottimizzi le prestazioni.

Personalizzare l’output con i parametri

Il comportamento di generazione può essere regolato usando i parametri di sampling, che controllano come il modello seleziona i token.

Valori di temperatura più bassi producono output più deterministici, mentre valori più alti introducono maggiore variabilità. Puoi usare parametri come top_p e num_predict per affinare ulteriormente la diversità e la lunghezza dell’output.

Ecco alcuni parametri importanti che puoi usare: 

Ecco un esempio di uso dei parametri top_p, temperature e num_predict:

response = ollama.generate(
    model='llama3.2',
    prompt='Explain machine learning in one paragraph',
    options={
        'temperature': 0.2,
        'top_p': 0.9,
        'num_predict': 100
    }
)

Creare conversazioni con chat()

A differenza di generate(), l’API chat() supporta interazioni stateful lavorando con una sequenza di messaggi. Questo permette al modello di mantenere il contesto su più turni.

Ogni messaggio include un ruolo, come user, assistant o system, che aiuta a strutturare la conversazione.

Richieste chat a singolo turno

Anche un’interazione a singolo turno usa il formato dei messaggi, che pone le basi per conversazioni più complesse.

response = ollama.chat(
    model='llama3.2',
    messages=[
        {'role': 'user', 'content': 'Explain Python decorators'}
    ]
)

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

Mantenere il contesto multi-turno

Per mantenere il contesto, archivi ed invii esplicitamente l’intera cronologia della conversazione con ogni richiesta. In questo modo controlli completamente ciò che il modello ricorda.

messages = [
    {'role': 'user', 'content': 'What is recursion?'}
]

response = ollama.chat(model='llama3.2', messages=messages)
messages.append(response['message'])

messages.append({'role': 'user', 'content': 'Give an example in Python'})
response = ollama.chat(model='llama3.2', messages=messages)

Usare i prompt di sistema per modellare il comportamento

Un prompt di sistema serve a definire in anticipo il comportamento del modello, come tono, vincoli o ruolo.

messages = [
    {'role': 'system', 'content': 'You are a strict Python code reviewer.'},
    {'role': 'user', 'content': 'Review this code: def add(a,b): return a+b'}
]

Supporto streaming e async nella libreria Python di Ollama

Per le applicazioni interattive, la reattività è importante quanto la correttezza. Ollama supporta sia lo streaming sia l’esecuzione asincrona per migliorare prestazioni ed esperienza utente.

Risposte in streaming in tempo reale

Lo streaming ti permette di elaborare l’output man mano che viene generato, invece di attendere la risposta completa.

for chunk in ollama.chat(
    model='llama3.2',
    messages=[{'role': 'user', 'content': 'Write a story'}],
    stream=True
):
    print(chunk['message']['content'], end='', flush=True)

Usare AsyncClient per app asincrone

L’esecuzione asincrona permette alla tua applicazione di gestire più richieste in concorrenza senza bloccare. Per implementarla dovrai usare la libreria asyncio di Python.

Vediamo un esempio qui sotto:

import asyncio
from ollama import AsyncClient

async def main():
    client = AsyncClient()
    async for chunk in await client.chat(
        model='llama3.2',
        messages=[{'role': 'user', 'content': 'Explain async programming'}],
        stream=True
    ):
        print(chunk['message']['content'], end='')

asyncio.run(main())

Gestire i modelli di Ollama da Python

L’SDK di Ollama fornisce anche strumenti per gestire i modelli in modo programmatico, particolarmente utile in ambienti automatizzati.

Elencare e ispezionare i modelli locali

Puoi recuperare l’elenco dei modelli disponibili e ispezionarne le proprietà, come dimensioni e configurazione.

models = ollama.list()
print(models)

info = ollama.show('llama3.2')
print(info)

Scaricare ed eliminare modelli in modo programmatico

I modelli possono essere scaricati o rimossi direttamente da Python, semplificando la gestione dinamica delle dipendenze.

ollama.pull('llama3.2')
ollama.delete('llama3.2')

Generare e usare embeddings con la libreria Python di Ollama

Le embeddings rappresentano il testo come vettori numerici che catturano il significato semantico. Questo ti permette di confrontare testi in base alla somiglianza invece che alle parole esatte.

Creare text embedding

L’esempio seguente converte del testo in una rappresentazione vettoriale utilizzabile per ricerca o clustering.

response = ollama.embed(
    model='nomic-embed-text',
    input='Ollama is a local LLM runtime'
)

embedding = response['embeddings'][0]

Costruire una ricerca per similarità di base

Una volta generate le embeddings, la similarità può essere misurata con la cosine similarity, che confronta l’angolo tra i vettori.

Ecco un semplice esempio della funzione di ricerca:

import numpy as np

def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

Tool calling e output strutturato nella libreria Python di Ollama

Per costruire applicazioni più avanzate, spesso i modelli devono interagire con funzioni esterne o restituire dati strutturati.

Implementare il tool calling con funzioni Python

Il tool calling consente al modello di invocare funzioni Python predefinite in base all’intento dell’utente.

Creiamo una funzione che usa questi strumenti:

def get_weather(city: str) -> str:
    """Get current weather for a city"""
    return f"Weather in {city} is sunny"
response = ollama.chat(
    model='llama3.2',
    messages=[{'role': 'user', 'content': 'What is the weather in Paris?'}],
    tools=[get_weather]
)

Ottenere risposte JSON strutturate

Gli output strutturati garantiscono che le risposte vengano restituite in un formato coerente e leggibile dalle macchine, come JSON.

response = ollama.chat(
    model='llama3.2',
    messages=[{'role': 'user', 'content': 'Review: Great product, 5 stars!'}],
    format='json'
)

Avanzato: modelli vision e Ollama Cloud in Python

Ollama supporta modelli multimodali e inferenza basata su cloud per casi d’uso più avanzati.

Inviare immagini ai modelli vision

I modelli vision possono elaborare sia testo sia immagini, abilitando attività come descrizione di immagini e analisi visiva.

response = ollama.chat(
    model='llama3.2-vision',
    messages=[{
        'role': 'user',
        'content': 'Describe this image',
        'images': ['image.jpg']
    }]
)

Eseguire modelli cloud da Python

Per modelli più grandi che non possono girare in locale, Ollama Cloud offre inferenza hosted.

ollama signin
ollama.chat(model='deepseek-v3.1:671b-cloud', messages=[...])
from ollama import Client

client = Client(
    host='https://ollama.com',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

Gestione degli errori: le insidie più comuni della libreria Python di Ollama

Quando costruisci applicazioni reali, gestire esplicitamente gli errori aiuta a prevenire failure silenziosi e migliora l’affidabilità.

Gestire eccezioni ResponseError

L’SDK di Ollama solleva eccezioni strutturate per gli errori lato server, permettendoti di ispezionare cosa è andato storto.

import ollama

try:
    ollama.generate(model='unknown', prompt='test')
except ollama.ResponseError as e:
    print(e.status_code, e.error)

Debug di problemi di connessione e di modello

I problemi più comuni includono il server non in esecuzione, modelli mancanti, memoria insufficiente o superamento dei limiti di contesto.

• Server non in esecuzione: Avvia con ollama serve

• Modello non trovato: Esegui ollama pull

• Memoria insufficiente: Usa modelli più piccoli o la quantizzazione

• Problemi di contesto: Regola num_ctx

num_ctx controlla il numero massimo di token che il modello può “vedere” in una volta, inclusi:

• il tuo prompt
• le istruzioni di sistema
• la cronologia della conversazione
• i documenti recuperati (RAG)
• e i token generati dal modello 

Gestire questo parametro aiuterà a evitare che l’LLM tronchi contenuti precedenti (di solito dall’inizio) o perda istruzioni o dati importanti in modo silenzioso.

Considerazioni finali

La libreria Python di Ollama offre un’interfaccia completa per lavorare con LLM locali e cloud, dalla semplice generazione di testo a funzionalità avanzate come embeddings, tool calling e input multimodali. Gli LLM diventano un servizio locale contro cui puoi fare scripting, testare e scalare come qualsiasi altro componente del tuo stack.

Dalla mia esperienza con Ollama, ho trovato che è una buona opzione da avere senza dover usare LLM nel cloud. Per esempio, posso usare i modelli open source con maggiore libertà. Se anche tu stai cercando più opzioni per passare da un modello all’altro, Ollama è un buon punto di accesso a tutto questo.

Se vuoi approfondire le tue competenze, ti consiglio il corso Developing LLM Applications with LangChain o la certificazione Associate AI Engineer for Developers.