Integrare Ollama in un'applicazione Python tramite l'API REST

#Perché usare l'API REST

La CLI ollama run est pratica per testare, ma non è stata progettata per essere chiamata da un'applicazione. L'API REST, invece, è stata creata proprio per questo: richieste HTTP standard, input e output in JSON, streaming tramite Server-Sent Events. Questo è ciò che tutte le interfacce (Open WebUI, Cline, LangChain) usano all'interno.

Compatibilità con OpenAI

L'endpoint /v1/chat/completions accetta esattamente lo stesso payload di api.openai.com/v1/chat/completions. Basta cambiare l'URL e la chiave, e il tuo codice esistente funziona.

Non serve reinventare

Lo SDK ufficiale openai per Python (o qualsiasi client HTTP) comunica direttamente con Ollama. Non serve imparare a usare un client specifico.

Disaccoppiamento del runtime

La tua app Python viene eseguita nel proprio container, Ollama nel suo. Il giorno in cui passerai a vLLM o LM Studio, cambierai solo base_url.

Più client simultanei

Diversi script Python, un notebook Jupyter e Open WebUI possono inviare richieste alla stessa istanza Ollama. Il daemon gestisce la coda da solo.

#Prerequisiti

Ollama installato e avviato

Il daemon deve ascoltare su http://localhost:11434. Verifica con curl http://localhost:11434 — devi vedere "Ollama is running".

Python 3.10+

Gli SDK recenti (openai 1.x) richiedono almeno Python 3.8, ma 3.10+ per le annotazioni moderne.

Un modello compatibile con la chat

ollama pull qwen3.5:9b ou gemma4:12b. Pour le function calling, choisissez un modèle qui le supporte : Qwen 3.5, Granite 4.2, Mistral Small 24B, Devstral.

VRAM sufficiente

Un modello 9B Q4 (come Qwen 3.5 9B) richiede circa 6-7 GB di VRAM, un 12B (Gemma 4 12B) circa 8 GB. Senza GPU funziona anche se a 5-10 tok/s

#1. Le due API dal lato Ollama

Prima di scrivere codice Python, diamo un'occhiata agli endpoint dal terminale per capire bene cosa succede. Con curl parliamo direttamente al daemon, senza alcuna astrazione.

curl http://localhost:11434/api/chat -d '{
  "model": "qwen3.5:9b",
  "messages": [{"role": "user", "content": "Bonjour"}],
  "stream": false
}'

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.5:9b",
    "messages": [{"role": "user", "content": "Bonjour"}]
  }'

Il secondo restituisce un payload esattamente identico a quello di OpenAI: campi choices[0].message.content, id, model, usage. È questo che rende possibile la sostituzione diretta (drop-in).

#2. Lo SDK OpenAI configurato per usare Ollama

Lo schema di base per integrare l'API di Ollama in Python sta in cinque righe: si installa l'SDK OpenAI, lo si istanzia con la base_url locale e si chiama chat.completions.create come di consueto.

pip install openai

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",  # ignoré, mais requis par le SDK
)

reponse = client.chat.completions.create(
    model="qwen3.5:9b",
    messages=[
        {"role": "system", "content": "Tu réponds en français, de façon concise."},
        {"role": "user", "content": "Explique en une phrase ce qu'est un LLM."},
    ],
    temperature=0.3,
)

print(reponse.choices[0].message.content)

Avvia lo script. Se Ollama funziona e il modello è scaricato, ottieni una frase. Se vedi un ConnectionRefusedError, verifica con ollama ps che il daemon sia attivo.

model

Il nome esatto come elencato da ollama list (qwen3.5:9b, gemma4:12b, mistral-small, ecc.).

messages

L'elenco dei turni della conversazione. Ruoli supportati: system, user, assistant, tool.

temperature

0 per risposte deterministiche, 0.7 per risposte creative. Per l'estrazione di dati, mantieni il valore a 0 o 0.1.

max_tokens

Limite massimo della risposta. Facoltativo — Ollama applica un valore predefinito ragionevole per num_predict.

#3. Streaming token per token con SSE

Per una buona esperienza utente (chatbot, generazione di testi lunghi), è meglio visualizzare i token man mano che vengono generati invece di aspettare la fine. Ollama supporta lo streaming tramite Server-Sent Events e l'SDK OpenAI permette di gestirlo con un semplice ciclo Python.

from openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

flux = client.chat.completions.create(
    model="qwen3.5:9b",
    messages=[{"role": "user", "content": "Raconte une courte histoire de robot."}],
    stream=True,
)

for chunk in flux:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)
print()

Ogni chunk contiene un delta (la porzione di testo aggiunta). Nell'ultimo chunk, delta.content è impostato a None e finish_reason è valorizzato — è il segnale di arresto.

#4. Modalità JSON per output strutturati

Quando vuoi effettuare il parsing della risposta (estrazione, classificazione, generazione di payload), chiedere "restituisci JSON" nel prompt non basta — il modello inserisce spesso del testo prima o dopo. La modalità JSON obbliga il decoder a produrre solo JSON valido.

from openai import OpenAI
import json

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

reponse = client.chat.completions.create(
    model="qwen3.5:9b",
    messages=[
        {"role": "system", "content": (
            "Tu extrais des informations structurées. "
            "Réponds uniquement avec un objet JSON contenant les clés : "
            "nom (string), age (int), ville (string)."
        )},
        {"role": "user", "content": "Marie a 34 ans, elle habite à Lyon."},
    ],
    response_format={"type": "json_object"},
    temperature=0,
)

donnees = json.loads(reponse.choices[0].message.content)
print(donnees)
# {'nom': 'Marie', 'age': 34, 'ville': 'Lyon'}

response_format={"type": "json_object"} attiva la modalità JSON. In Ollama, questo si traduce in un vincolo a livello del sampler: ogni token che produrrebbe un JSON non valido viene scartato. È più affidabile che scrivere nel prompt "rispondi in JSON" e pregare.

#5. Chiamata di funzione (uso degli strumenti)

Il function calling permette al modello di segnalare che vuole chiamare una funzione Python piuttosto che rispondere direttamente. Non tutti i modelli lo supportano — controlla su ollama.com/library che la dicitura "tools" compaia tra le capacità. Qwen 3.5, Granite 4.2, Mistral Small 24B e Devstral lo supportano nativamente.

from openai import OpenAI
import json

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

# 1. Une fonction Python réelle
def meteo(ville: str) -> dict:
    # En vrai, vous appelleriez Open-Meteo ou autre
    return {"ville": ville, "temperature_c": 18, "conditions": "nuageux"}

# 2. Sa description au format OpenAI
outils = [{
    "type": "function",
    "function": {
        "name": "meteo",
        "description": "Donne la météo actuelle d'une ville française.",
        "parameters": {
            "type": "object",
            "properties": {
                "ville": {"type": "string", "description": "Nom de la ville"},
            },
            "required": ["ville"],
        },
    },
}]

messages = [{"role": "user", "content": "Quel temps fait-il à Bordeaux ?"}]

# 3. Premier appel : le modèle décide d'appeler la fonction
reponse = client.chat.completions.create(
    model="qwen3.5:9b",
    messages=messages,
    tools=outils,
)

appel = reponse.choices[0].message.tool_calls[0]
args = json.loads(appel.function.arguments)
resultat = meteo(**args)

# 4. Second appel : on renvoie le résultat au modèle pour la réponse finale
messages.append(reponse.choices[0].message)
messages.append({
    "role": "tool",
    "tool_call_id": appel.id,
    "content": json.dumps(resultat),
})

finale = client.chat.completions.create(model="qwen3.5:9b", messages=messages)
print(finale.choices[0].message.content)

Il ciclo ha due iterazioni: la prima restituisce un tool_calls (il modello dice "chiama meteo con ville=Bordeaux"), la seconda restituisce la risposta in linguaggio naturale dopo che hai eseguito la funzione e inserito il suo risultato. In produzione, ripeti il ciclo finché tool_calls non è vuoto.

#6. Esporre Ollama tramite FastAPI

Caso tipico: il tuo frontend chiama il tuo backend Python, che chiama Ollama. FastAPI gestisce correttamente le operazioni asincrone e lo streaming arriva fino al browser tramite una StreamingResponse.

pip install fastapi uvicorn openai

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from pydantic import BaseModel
from openai import OpenAI

app = FastAPI()
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

class Question(BaseModel):
    message: str
    model: str = "qwen3.5:9b"

@app.post("/chat")
def chat(q: Question):
    reponse = client.chat.completions.create(
        model=q.model,
        messages=[{"role": "user", "content": q.message}],
    )
    return {"reponse": reponse.choices[0].message.content}

@app.post("/chat/stream")
def chat_stream(q: Question):
    def generateur():
        flux = client.chat.completions.create(
            model=q.model,
            messages=[{"role": "user", "content": q.message}],
            stream=True,
        )
        for chunk in flux:
            delta = chunk.choices[0].delta.content
            if delta:
                yield delta
    return StreamingResponse(generateur(), media_type="text/plain")

uvicorn main:app --reload --port 8000

curl -N -X POST http://localhost:8000/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"message": "Écris un haïku sur Paris."}'

L'opzione -N (--no-buffer) di curl disattiva il buffering lato client per visualizzare lo streaming in tempo reale. Nel frontend JS, leggi il ReadableStream della risposta fetch, come per l'API OpenAI.

#7. Chatbot Flask con storico

Per un chatbot completo, bisogna conservare la cronologia dei messaggi tra un turno e l'altro. Ecco una versione minimalista basata su Flask che conserva la conversazione in memoria (da sostituire con una vera sessione o un database in produzione).

pip install flask openai

from flask import Flask, request, jsonify, Response
from openai import OpenAI
from collections import defaultdict

app = Flask(__name__)
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

# Historiques par session — en prod : Redis, Postgres, etc.
historiques: dict[str, list] = defaultdict(lambda: [
    {"role": "system", "content": "Tu es un assistant en français, concis et utile."},
])

@app.post("/chat/<session_id>")
def chat(session_id: str):
    message = request.json["message"]
    historique = historiques[session_id]
    historique.append({"role": "user", "content": message})

    reponse = client.chat.completions.create(
        model="qwen3.5:9b",
        messages=historique,
    )
    contenu = reponse.choices[0].message.content
    historique.append({"role": "assistant", "content": contenu})
    return jsonify({"reponse": contenu})

@app.post("/chat/<session_id>/stream")
def chat_stream(session_id: str):
    message = request.json["message"]
    historique = historiques[session_id]
    historique.append({"role": "user", "content": message})

    def generateur():
        morceaux = []
        flux = client.chat.completions.create(
            model="qwen3.5:9b",
            messages=historique,
            stream=True,
        )
        for chunk in flux:
            delta = chunk.choices[0].delta.content
            if delta:
                morceaux.append(delta)
                yield delta
        historique.append({"role": "assistant", "content": "".join(morceaux)})

    return Response(generateur(), mimetype="text/plain")

@app.delete("/chat/<session_id>")
def reset(session_id: str):
    historiques.pop(session_id, None)
    return "", 204

if __name__ == "__main__":
    app.run(port=5000, debug=True)

#Per la produzione

Esporre Ollama sulla rete

Per impostazione predefinita, il daemon ascolta solo su 127.0.0.1. Per consentire l'accesso ad altre macchine, avvialo con OLLAMA_HOST=0.0.0.0 e proteggilo con un reverse proxy con autenticazione, altrimenti chiunque sulla rete può usare i tuoi modelli.

Concorrenza e coda

Ollama serializza le richieste per modello. Per servire più utenti in parallelo, avvia più istanze o passa a vLLM che gestisce il batching dinamico nativamente.

Timeouts dal lato client

Una richiesta a un modello non caricato può richiedere 10-30 s (caricamento in VRAM). Imposta il timeout del client OpenAI: OpenAI(..., timeout=120) anziché lasciare il valore predefinito di 10 minuti della libreria; sul reverse proxy, invece, il timeout è spesso breve.

Mantenere il modello caricato

Per impostazione predefinita, Ollama scarica un modello dalla memoria dopo 5 minuti di inattività. Quando usi l'API, passa keep_alive="30m" tramite l'API nativa /api/chat, oppure mantieni un ping periodico per evitare un avvio a freddo alla prima richiesta dell'utente.

Osservabilità

Registra sistematicamente model, prompt_tokens, completion_tokens (presenti in reponse.usage). Sono le tue metriche di inferenza — utili per individuare un modello che rallenta o un prompt che cresce a dismisura.

#Per approfondire

Hai le basi. Tre percorsi per andare oltre in base al tuo caso d'uso:

Costruire un agente che decida da solo

La guida sugli agenti IA locali in Python con LangChain porta il function calling fino a un ciclo completo dell'agente, con gestione di più strumenti e ragionamento in più passaggi.

Aggiungere il RAG basato sui tuoi documenti

Per far sì che la tua app risponda a partire da un corpus interno (PDF, note, codice), collega un database vettoriale. La guida introduttiva al RAG locale fornisce le basi.

Personalizzare il comportamento del modello

Piuttosto che ripetere il system prompt a ogni chiamata, crea una variante tramite Modelfile. La guida alla personalizzazione con Ollama Modelfile mostra come definire stabilmente un assistente in francese o una modalità di programmazione associandoli a un nome di modello riutilizzabile.