Libreria Python di Ollama: iniziare con gli LLM in locale

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

È qui che spiccano gli approcci local-first. La libreria Python di Ollama elimina questi attriti permettendoti di eseguire grandi modelli linguistici in locale, interagendo con loro tramite codice pulito e 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 di visione.

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

• Tutorial Gemma 4: crea un agente di coding locale con Gradio e Ollama
• Tutorial Qwen 3.5 Small Models: genera videogiochi da video 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 quanto segue 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 manca un modello adatto, le chiamate falliranno.

Puoi anche valutare l’uso di Docker con Ollama per mantenere 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 incline 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 fa da server che ospita ed esegue i modelli.

Questa separazione è importante perché permette al modello di girare come 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 dipendenze minime:

pip install ollama

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

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

Per farlo, esegui quanto segue:

import ollama

print(ollama.list())

Generare testo con generate()

La funzione generate() è progettata per compiti stateless, cioè ogni richiesta viene gestita in modo indipendente senza memoria delle interazioni precedenti. È ideale per attività come sintesi, riscrittura 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 flusso 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 conteggi di token, utili per ottimizzare le prestazioni.

Personalizzare l’output con i parametri

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

Valori di temperatura 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 utilizzo 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 turno singolo

Anche un’interazione a turno singolo usa il formato a 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, memorizzi ed invii esplicitamente l’intera cronologia della conversazione a ogni richiesta. Così hai controllo completo su cosa 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 system prompt per modellare il comportamento

Un system prompt serve a definire in anticipo il comportamento del modello, ad esempio 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 applicazioni interattive, la reattività è importante quanto la correttezza. Ollama supporta sia lo streaming che l’esecuzione asincrona per migliorare prestazioni ed esperienza utente.

Streaming delle risposte in tempo reale

Lo streaming ti consente di elaborare l’output man mano che viene generato, invece di aspettare l’intera risposta.

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 applicazioni 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 offre anche strumenti per gestire i modelli in modo programmatico, particolarmente utili 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 embedding con la libreria Python di Ollama

Gli embedding rappresentano il testo come vettori numerici che catturano il significato semantico. Questo consente di confrontare testi in base alla somiglianza, invece che alla corrispondenza esatta delle parole.

Creare embedding testuali

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 generati gli embedding, 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 creare 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 permette al modello di invocare funzioni Python predefinite in base all’intento dell’utente.

Creiamo una funzione che usa questi tool:

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 assicurano che le risposte vengano restituite in un formato coerente e leggibile dalle macchine, come il JSON.

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

Avanzato: modelli di visione e Ollama Cloud in Python

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

Inviare immagini ai modelli di visione

I modelli di visione possono elaborare sia testo sia immagini, abilitando compiti 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 ospitata. È necessario effettuare l’accesso a Ollama Cloud.

ollama signin

Dopo aver eseguito l’accesso, puoi chattare con modelli ospitati su cloud in questo modo:

from ollama import Client
import os

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

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

Gestione degli errori: i tranelli più comuni della libreria Python di Ollama

Quando costruisci applicazioni reali, gestire gli errori in modo esplicito evita malfunzionamenti silenziosi e migliora l’affidabilità.

Gestire le eccezioni ResponseError

L’SDK di Ollama solleva eccezioni strutturate per 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 comuni includono 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, includendo:

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

Gestire questo parametro aiuta a evitare che l’LLM tronchi contenuti precedenti (di solito dall’inizio) o perda istruzioni o dati importanti senza segnalarlo.

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 embedding, tool calling e input multimodali. Gli LLM diventano un servizio locale contro cui puoi fare scripting, test e scalare come qualsiasi altro componente del tuo stack.

Per esperienza con Ollama, ho riscontrato che è una buona opzione da avere senza dover usare LLM su cloud. Ad 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 d’accesso a tutto questo.

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