API di Ollama compatibile con OpenAI

Ollama esegue modelli open sul tuo computer e li rende disponibili tramite un’API compatibile con OpenAI all’indirizzo http://localhost:11434/v1. Poiché il formato di comunicazione corrisponde a quello di OpenAI, l’SDK ufficiale OpenAI funziona con Ollama senza modifiche; lo stesso codice consente di accedere ai modelli frontier ospitati modificando solo l’URL di base.

Cos’è l’API di Ollama compatibile con OpenAI

Ollama è un progetto open source indipendente per eseguire localmente modelli come Llama, Qwen e Mistral. Oltre alla sua API nativa, offre un’interfaccia compatibile con OpenAI, così gli strumenti creati per OpenAI funzionano senza riscritture. Implementa gli endpoint usati dalla maggior parte delle app:

Supporta chat, completamenti ed embedding (oltre all’input visivo sui modelli locali multimodali). Non genera immagini, video o audio. Kunavo implementa lo stesso contratto /v1/chat/completions — quel riferimento documenta ogni parametro, la struttura dei delta nello streaming e l’oggetto usage, e include una tabella di corrispondenza riga per riga con l’interfaccia v1 di Ollama.

Chiama Ollama con l’SDK OpenAI

Imposta base_url su http://localhost:11434/v1. L’SDK richiede un api_key, ma Ollama in locale ne ignora il valore: passa una stringa qualsiasi. Imposta model su un modello che hai scaricato (ad es. ollama pull llama3.2).

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",  # Ollama's OpenAI-compatible API
    api_key="ollama",  # required by the SDK, ignored by local Ollama
)

resp = client.chat.completions.create(
    model="llama3.2",
    messages=[{"role": "user", "content": "Explain quicksort in one paragraph."}],
)
print(resp.choices[0].message.content)

Oppure con curl:

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "messages": [{"role": "user", "content": "Hello, Ollama"}]
  }'

Lo stesso codice, con modelli frontier ospitati

Ollama è ideale per lo sviluppo offline e per le attività sensibili alla privacy, ma sui compiti più complessi di ragionamento, programmazione e gestione di contesti lunghi i modelli locali sono inferiori ai modelli frontier. Poiché anche Kunavo è compatibile con OpenAI, spostare una chiamata a un modello ospitato richiede due modifiche: base_url e lo slug del modello:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.kunavo.com/v1",  # only this line changes
    api_key="sk-kn-...",               # a real key now
)

resp = client.chat.completions.create(
    model="claude-sonnet-5",  # a hosted frontier model
    messages=[{"role": "user", "content": "Explain quicksort in one paragraph."}],
)
print(resp.choices[0].message.content)

Scegli in base all’ambiente

Un approccio comune consiste nell’usare Ollama per lo sviluppo locale e modelli ospitati in produzione, selezionandoli tramite una variabile d’ambiente. Il client e il codice della richiesta sono identici: cambiano solo base_url e il modello:

import os
from openai import OpenAI

# One client, switched by environment. Local for dev, hosted for prod.
if os.getenv("APP_ENV") == "production":
    client = OpenAI(base_url="https://api.kunavo.com/v1",
                    api_key=os.environ["KUNAVO_API_KEY"])
    MODEL = "claude-haiku-4-5"
else:
    client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
    MODEL = "llama3.2"

resp = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "ping"}],
)
print(resp.choices[0].message.content)

FAQ

Prossimi passi

• Guida all’API compatibile con OpenAI — dall’endpoint locale di Ollama ai modelli ospitati
• Cos’è un gateway AI? — il modello a endpoint unico
• Documentazione di riferimento per i completamenti di chat
• Guida rapida — la tua prima richiesta in 60 secondi