Ollama gebruiken met een GUI (en een gehoste fallback)

Waarom Ollama een aparte GUI nodig heeft

Als je wilt weten hoe je ollama met een gui gebruikt, is het eerste feit dat je moet accepteren dat het Ollama-project een server en een commandoregeltool is. Het haalt modellen op en beantwoordt verzoeken op een lokale poort. Het chatvenster is de taak van iemand anders, en er zijn verschillende goede.

Die splitsing is nuttig. Omdat Ollama een OpenAI-achtige API blootlegt op je eigen machine (standaard op poort 11434 onder /v1), kan elke frontend die je een aangepaste OpenAI-basis-URL laat instellen, deze gebruiken. Dezelfde eigenschap betekent dat je die frontend later ergens anders op kunt wijzen. Dit artikel behandelt eerst de lokale setup en voegt vervolgens een gehost endpoint toe als een tweede verbinding.

Kies een front-end

Drie categorieën tools dekken de meeste gebruikers. Controleer de eigen documentatie van elk project voor actuele installatiestappen, omdat deze vaak veranderen.

• Open WebUI. Een zelfgehoste browserinterface. Het ondersteunt Ollama direct en accepteert ook elke OpenAI-compatible verbinding. Meestal geïnstalleerd met Docker of pip.
• Desktopclients. Native apps zoals Chatbox of Msty laten je een Ollama-server of een OpenAI-compatibele provider toevoegen via een instellingenscherm. Geen server om te draaien.
• Roleplay- en schrijffrontends. SillyTavern stelt je in staat een OpenAI-compatible endpoint toe te voegen, en er zijn vergelijkbare tools voor langverhalende fictie en metgezelkarakters voor volwassenen.

Als je geen Docker-container wilt, is een desktopclient de kortste weg. Als je een gedeelde interface wilt voor meerdere mensen op één netwerk, is Open WebUI de gebruikelijke keuze.

Stap voor stap met Open WebUI

1. Installeer en start Ollama, en haal vervolgens een model op met het ollama pull commando. Bevestig dat het reageert vanuit de terminal voordat je verder gaat.
2. Start Open WebUI. Met Docker is het gebruikelijke patroon om een poort te publiceren en een volume te koppelen voor de gegevens.
3. Open de webpagina, maak het eerste lokale account aan (het wordt de admin), en zoek het verbindingengebied in de admin-instellingen.
4. Controleer of de Ollama URL wijst naar de machine waar Ollama draait. Wanneer beide op dezelfde host zijn, is dit normaal gesproken het lokale adres op poort 11434. Wanneer Open WebUI in een container draait, betekent localhost de container zelf, wat de meest voorkomende reden is dat de modellijst leeg blijft.
5. Herlaad, kies een model uit de dropdown, en stuur een bericht.

Dat is een complete lokale GUI. Niets verlaat je computer, en de snelheid hangt af van je GPU of CPU.

Een gehoste OpenAI-compatibele verbinding toevoegen

Nu de uitvaloptie. Stel dat het model dat je lokaal kunt draaien te klein is voor een lange scène, of je GPU is bezig met renderen. Je kunt een tweede verbinding aan dezelfde GUI toevoegen. Hiervoor heb je een API-sleutel nodig, die je kunt claimen op de API-sleutelpagina na het aanmelden met Google of met e-mail en wachtwoord. Een eenmalig proeftegoed van $0,50 is met één klik beschikbaar, vereist geen betaling en duurt 7 dagen.

In Open WebUI, voeg een OpenAI-verbinding toe met deze waarden:

• Basis-URL: https://api.ollamansfw.com/v1
• API-sleutel: je sleutel, verzonden als Authorization: Bearer
• Model: uncensored

Als je de voorkeur geeft aan omgevingsvariabelen bij het starten van de container, documenteert Open WebUI OPENAI_API_BASE_URL en OPENAI_API_KEY voor dit doel:

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

Na een herladen zou uncensored in de modelkeuzelijst moeten verschijnen naast je lokale modellen. De frontend vindt het via GET /v1/models. Je kunt nu schakelen tussen een lokaal model en het gehoste model binnen dezelfde gesprekslijst.

Test het endpoint eerst buiten de GUI

Wanneer een GUI een vaag foutbericht toont, is de snelste manier om te zien of het probleem de sleutel of de interface is, een directe aanroep. Hier is een streaming verzoek met 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."}]
  }'

Je zou een reeks data:-regels moeten zien die eindigen met gebruiksinformatie. Als dat werkt, zijn de sleutel en de URL in orde en ligt het probleem bij de frontend. De probleemoplossingspagina behandelt veelvoorkomende fouten zoals een ontbrekende /v1 of een spatie aan het einde van de sleutel.

Dezelfde clientinstellingen die je voor lokale modellen gebruikt, worden meestal doorgegeven. Temperatuur, top_p, stop-sequenties, seed en de straffactoren worden doorgegeven aan het model.

Het gehoste endpoint gebruiken vanuit je eigen code

Een GUI is één client. Scripts en kleine apps zijn een andere, en het gehoste endpoint werkt met de standaard OpenAI SDKs. Function calling en JSON mode worden ondersteund, wat belangrijk is als je GUI of agent ze gebruikt.

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 is het patroon identiek:

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 ?? "");
}

De quickstart heeft meer voorbeelden, inclusief toolaanroepen met tool_choice.

Veelvoorkomende problemen en oplossingen

De meeste fouten in een GUI-setup komen door een korte lijst van oorzaken.

• Lege modellijst voor de lokale verbinding. De front-end kan Ollama niet bereiken. Controleer het adres, en onthoud dat een gecontaineriseerde GUI je host niet ziet als localhost.
• 401 van het gehost endpoint. De sleutel ontbreekt of is verkeerd. Plak hem opnieuw zonder spaties en zorg ervoor dat de GUI hem als een bearer-token verstuurt.
• 404 op elk verzoek. De basis-URL mist waarschijnlijk /v1, of heeft het twee keer.
• Antwoorden stoppen of de UI blijft hangen. Sommige frontends bufferen gestreamde uitvoer via een proxy. Probeer de directe curl-test hierboven en, als het streamt, controleer dan de proxy-instellingen voor je GUI.
• Trage lokale antwoorden. Het model is te groot voor je VRAM en wordt naar het systeengeheugen verplaatst. Kies een kleinere kwantisatie, of schakel dat gesprek over naar de gehost verbinding.

Houd één regel in gedachten voor fictie en companion apps voor volwassenen: het gehoste model antwoordt zonder inhoudelijke weigeringen voor wettelijk volwassen gebruik, maar seksuele inhoud met minderjarigen is nooit toegestaan, en de service handhaaft dat als een harde limiet.

Limieten en kosten om te weten in een GUI

Frontends kunnen meerdere verzoeken tegelijk afvuren, bijvoorbeeld wanneer ze een gesprekstitel genereren op de achtergrond terwijl het hoofdantwoord streamt. Een volledige sleutel staat 8 gelijktijdige verzoeken en 300 verzoeken per minuut toe. Een proefsleutel staat 2 gelijktijdige en 60 per minuut toe. Een gestreamd verzoek houdt zijn plek vast tot de stream eindigt. Als je een limiet overschrijdt, krijg je HTTP 429 met de code rate_limited of concurrency, en bij tijdelijke overbelasting een 429 met Retry-After: 5. Het uitschakelen van titelgeneratie op de achtergrond in de GUI is een eenvoudige oplossing voor een proefsleutel.

Kosten zijn per token: $0,15 per 1M input en $0,50 per 1M output. Een chatbeurt met 2.000 tokens aan geschiedenis en een antwoord van 500 tokens kost $0,0003 plus $0,00025, wat $0,00055 is. De responsheaders bevatten X-Balance-USD, zodat je kunt zien hoe je tegoed krimpt. Details over opwaarderen staan op de prijzenpagina. Deze site is alleen crypto: USDT op TRC20 of USDC op Base, elk geheel bedrag van $20 tot $500.

Het contextvenster is 100.000 tokens, dus zeer lange chats kosten meer per beurt naarmate de geschiedenis groeit, omdat de hele geschiedenis elke keer wordt verstuurd. De meeste GUIs hebben een instelling om oude berichten bij te snijden of samen te vatten.

Meer handleidingen

• Ollama Software Alternatieven: Gehoste Ongecensureerde API
• Ollamansfw API-prijzen: tokenkosten uitgelegd
• Uncensored LLM API-gids