Come usare Ollama con un'interfaccia grafica (e un fallback ospitato)

Perché Ollama ha bisogno di un'interfaccia grafica separata

Se vuoi sapere come usare ollama con un'interfaccia grafica, il primo fatto da accettare è che il progetto Ollama è un server e uno strumento a riga di comando. Estrae i modelli e risponde alle richieste su una porta locale. La finestra di chat è compito di altri e ci sono diverse buone opzioni.

Questa separazione è utile. Poiché Ollama espone un'API in stile OpenAI sulla tua macchina (di default sulla porta 11434 sotto /v1), qualsiasi front end che ti permetta di impostare un URL base OpenAI personalizzato può usarlo. La stessa proprietà significa che puoi puntare quel front end altrove in seguito. Questo articolo mostra prima la configurazione locale, poi aggiunge un endpoint in hosting come seconda connessione.

Scegli un front end

Tre famiglie di strumenti coprono la maggior parte degli utenti. Controlla la documentazione di ciascun progetto per i passaggi di installazione attuali, perché cambiano spesso.

• Open WebUI. Un'interfaccia browser self-hosted. Supporta Ollama direttamente e accetta anche qualsiasi connessione compatibile con OpenAI. Solitamente installato con Docker o pip.
• Client per desktop. Le app native come Chatbox o Msty ti permettono di aggiungere un server Ollama o un provider compatibile con OpenAI tramite una schermata di impostazioni. Nessun server da eseguire.
• Interfacce per roleplay e scrittura. SillyTavern ti permette di aggiungere un endpoint compatibile con OpenAI e esistono strumenti simili per narrativa lunga e personaggi companion per adulti.

Se non vuoi un container Docker, un client desktop è la strada più breve. Se vuoi un'interfaccia condivisa per più persone su una rete, Open WebUI è la scelta abituale.

Guida passo passo con Open WebUI

1. Installa e avvia Ollama, poi scarica un modello con il comando ollama pull. Conferma che risponda dal terminale prima di procedere.
2. Avvia Open WebUI. Con Docker il pattern usuale è pubblicare una porta e montare un volume per i suoi dati.
3. Apri la pagina web, crea il primo account locale (diventerà l'amministratore) e cerca l'area delle connessioni nelle impostazioni di amministrazione.
4. Verifica che l'URL di Ollama punti alla macchina dove Ollama gira. Quando sono entrambi sullo stesso host questo è normalmente l'indirizzo locale sulla porta 11434. Quando Open WebUI gira dentro un container, localhost significa il container stesso, che è la ragione più comune per cui l'elenco dei modelli resta vuoto.
5. Ricarica, scegli un modello dal menu a discesa e invia un messaggio.

Questa è un'interfaccia grafica locale completa. Nulla esce dal tuo computer e la velocità dipende dalla tua GPU o CPU.

Aggiungere una connessione OpenAI compatibile in hosting

Ora il fallback. Supponi che il modello che puoi eseguire localmente sia troppo piccolo per una scena lunga, o che la tua GPU sia occupata nel rendering. Puoi aggiungere una seconda connessione alla stessa GUI. Per questo hai bisogno di una chiave API, che puoi richiedere dalla pagina delle chiavi API dopo esserti registrato con Google o con email e password. Un credito di prova una tantum di $0,50 è disponibile con un clic, non richiede pagamento e dura 7 giorni.

In Open WebUI, aggiungi una connessione OpenAI con questi valori:

• URL di base: https://api.ollamansfw.com/v1
• Chiave API: la tua chiave, inviata come Authorization: Bearer
• Modello: uncensored

Se preferisci le variabili d'ambiente quando lanci il container, Open WebUI documenta OPENAI_API_BASE_URL e OPENAI_API_KEY per questo scopo:

Copydocker run -d -p 3000:8080 \
  -e OPENAI_API_BASE_URL=https://api.ollamansfw.com/v1 \
  -e OPENAI_API_KEY=YOUR_KEY \
  -v open-webui:/app/backend/data \
  --name open-webui ghcr.io/open-webui/open-webui:main
# model to pick in the UI: uncensored

Dopo un ricaricamento, uncensored dovrebbe apparire nel menu a discesa dei modelli accanto ai tuoi modelli locali. Il front end lo trova tramite GET /v1/models. Ora puoi passare tra un modello locale e quello in hosting nella stessa lista di conversazioni.

Testare l'endpoint prima dall'esterno dell'interfaccia grafica

Quando un'interfaccia grafica mostra un errore vago, il modo più veloce per capire se il problema è la chiave o l'interfaccia è una chiamata diretta. Ecco una richiesta di streaming con curl:

Copycurl -N https://api.ollamansfw.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "stream": true,
    "messages": [{"role": "user", "content": "Write two sentences about a lighthouse keeper."}]
  }'

Dovresti vedere una serie di righe data: che terminano con le informazioni di utilizzo. Se questo funziona, la chiave e l'URL sono a posto e il problema risiede nel frontend. La pagina di risoluzione dei problemi copre errori tipici come un /v1 mancante o uno spazio finale nella chiave.

Le stesse impostazioni del client che usi per i modelli locali si applicano per lo più. Temperatura, top_p, sequenze di stop, seed e penalità vengono passati al modello.

Utilizzo dell'endpoint ospitato dal tuo codice

Un'interfaccia grafica è un client. Script e piccole app sono un altro caso, e l'endpoint in hosting funziona con gli SDK OpenAI standard. Sono supportati tool calling e modalità JSON, il che è importante se la tua interfaccia grafica o agente li usa.

Copyfrom openai import OpenAI

client = OpenAI(base_url="https://api.ollamansfw.com/v1", api_key="YOUR_KEY")

resp = client.chat.completions.create(
    model="uncensored",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": "Reply with a JSON object with keys title and summary."},
        {"role": "user", "content": "A short story about a lighthouse keeper."},
    ],
)
print(resp.choices[0].message.content)

In Node il pattern è identico:

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.ollamansfw.com/v1",
  apiKey: process.env.API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  stream: true,
  messages: [{ role: "user", content: "Name three sailing knots." }],
});
for await (const part of stream) {
  process.stdout.write(part.choices[0]?.delta?.content ?? "");
}

La guida rapida ha più esempi, incluse chiamate di funzioni con tool_choice.

Problemi comuni e soluzioni

La maggior parte dei guai in una configurazione dell'interfaccia grafica deriva da un breve elenco di cause.

• Elenco modelli vuoto per la connessione locale. Il front end non riesce a raggiungere Ollama. Controlla l'indirizzo e ricorda che un'interfaccia grafica containerizzata non vede il tuo host come localhost.
• 401 dall'endpoint in hosting. La chiave è mancante o errata. Incollala di nuovo senza spazi e assicurati che l'interfaccia grafica la invii come token bearer.
• 404 su ogni richiesta. L'URL base probabilmente manca di /v1, o lo ha due volte.
• Le risposte si fermano o l'interfaccia si blocca. Alcuni front end bufferizzano l'output in streaming attraverso un proxy. Prova il test curl diretto sopra e, se trasmette, controlla le impostazioni del proxy davanti alla tua interfaccia grafica.
• Risposte locali lente. Il modello è troppo grande per la tua VRAM e sta usando la memoria di sistema. Scegli una quantizzazione più piccola o passa quella chat alla connessione in hosting.

Tieni a mente una regola per le app di narrativa e companion per adulti: il modello in hosting risponde senza rifiuti di contenuto per l'uso adulto legale, ma il contenuto sessuale che coinvolge minorenni non è mai consentito e il servizio lo applica come limite rigido.

Limiti e costi da conoscere in un'interfaccia grafica

I frontend possono inviare più richieste contemporaneamente, ad esempio quando generano un titolo della chat in background mentre la risposta principale viene inviata in streaming. Una chiave completa consente 8 richieste parallele e 300 richieste al minuto. Una chiave di prova consente 2 richieste parallele e 60 al minuto. Una richiesta in streaming occupa la sua posizione fino alla fine dello streaming. Se superi un limite, ricevi un HTTP 429 con il codice rate_limited o concurrency, e in caso di sovraccarico temporaneo un 429 con Retry-After: 5. Disattivare la generazione del titolo in background nell'interfaccia grafica è una soluzione semplice per una chiave di prova.

Il costo è per token: $0,15 per 1M input e $0,50 per 1M output. Un turno di chat con 2.000 token di cronologia e una risposta di 500 token costa $0,0003 più $0,00025, che è $0,00055. Le intestazioni di risposta includono X-Balance-USD, così puoi osservare il tuo credito diminuire. I dettagli sui ricarichi sono nella pagina dei prezzi. Questo sito è solo cripto: USDT su TRC20 o USDC su Base, qualsiasi importo intero da $20 a $500.

La finestra di contesto è di 100.000 token, quindi chat molto lunghe costeranno di più per turno man mano che la cronologia cresce, perché l'intera cronologia viene inviata ogni volta. La maggior parte delle GUI ha un'impostazione per tagliare o riassumere i messaggi vecchi.

Altre guide

• Alternative software Ollama: API Uncensored ospitata
• Prezzi API Ollamansfw: spiegazione dei costi per token
• Guida API LLM Uncensored