Comment utiliser Ollama avec une interface graphique (et une solution de secours hébergée)

Pourquoi Ollama nécessite une interface graphique séparée

Si vous voulez savoir comment utiliser ollama avec une interface graphique, le premier fait à accepter est que le projet Ollama est un serveur et un outil en ligne de commande. Il télécharge des modèles et répond aux requêtes sur un port local. La fenêtre de chat est le travail d'un autre projet, et il en existe plusieurs de très bons.

Cette séparation est utile. Parce qu'Ollama expose une API de style OpenAI sur votre propre machine (par défaut sur le port 11434 sous /v1), n'importe quelle interface qui vous permet de définir une URL de base OpenAI personnalisée peut l'utiliser. La même propriété signifie que vous pouvez pointer cette interface ailleurs plus tard. Cet article explique d'abord la configuration locale, puis ajoute un endpoint hébergé comme deuxième connexion.

Choisissez une interface

Trois familles d'outils couvrent la plupart des utilisateurs. Consultez la documentation propre à chaque projet pour les étapes d'installation actuelles, car elles changent souvent.

• Open WebUI. Une interface navigateur auto-hébergée. Elle prend en charge Ollama directement et accepte également n'importe quelle connexion compatible OpenAI. Généralement installée avec Docker ou pip.
• Clients de bureau. Des applications natives telles que Chatbox ou Msty vous permettent d'ajouter un serveur Ollama ou un fournisseur compatible OpenAI via un écran de paramètres. Aucun serveur à exécuter.
• Interfaces de jeu de rôle et d'écriture. SillyTavern vous permet d'ajouter un endpoint compatible OpenAI, et des outils similaires existent pour la fiction longue et les personnages compagnons pour adultes.

Si vous ne souhaitez pas de conteneur Docker, un client de bureau est le chemin le plus court. Si vous souhaitez une interface partagée pour plusieurs personnes sur un même réseau, Open WebUI est le choix habituel.

Étapes avec Open WebUI

1. Installez et démarrez Ollama, puis téléchargez un modèle avec la commande ollama pull. Confirmez qu'il répond depuis le terminal avant d'aller plus loin.
2. Démarrez Open WebUI. Avec Docker, le schéma habituel consiste à publier un port et à monter un volume pour ses données.
3. Ouvrez la page web, créez le premier compte local (il devient l'administrateur), et recherchez la zone de connexions dans les paramètres d'administration.
4. Vérifiez que l'URL Ollama pointe vers la machine où Ollama s'exécute. Lorsque les deux sont sur le même hôte, il s'agit normalement de l'adresse locale sur le port 11434. Lorsque Open WebUI s'exécute dans un conteneur, localhost signifie le conteneur lui-même, ce qui est la raison la plus courante pour laquelle la liste des modèles reste vide.
5. Actualisez, choisissez un modèle dans la liste déroulante, et envoyez un message.

C'est une interface graphique locale complète. Rien ne quitte votre ordinateur, et la vitesse dépend de votre GPU ou CPU.

Ajout d'une connexion OpenAI compatible hébergée

Voici la solution de secours. Supposons que le modèle que vous pouvez exécuter localement soit trop petit pour une scène longue, ou que votre GPU soit occupé à rendre. Vous pouvez ajouter une deuxième connexion à la même interface graphique. Pour cela, vous avez besoin d'une clé API, que vous pouvez réclamer sur la page Clé API après vous être inscrit avec Google ou avec un e-mail et un mot de passe. Un crédit d'essai unique de $0,50 est disponible en un seul clic, sans besoin de paiement, et dure 7 jours.

Dans Open WebUI, ajoutez une connexion OpenAI avec ces valeurs :

• URL de base : https://api.ollamansfw.com/v1
• Clé API : votre clé, envoyée en tant que Authorization: Bearer
• Modèle : uncensored

Si vous préférez les variables d'environnement lors du lancement du conteneur, Open WebUI documente OPENAI_API_BASE_URL et OPENAI_API_KEY à cette fin :

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

Après un rechargement, uncensored devrait apparaître dans la liste déroulante des modèles à côté de vos modèles locaux. L'interface le trouve via GET /v1/models. Vous pouvez maintenant basculer entre un modèle local et celui hébergé dans la même liste de conversations.

Testez l'endpoint en dehors de l'interface graphique d'abord

Lorsqu'une interface affiche une erreur vague, le moyen le plus rapide de déterminer si le problème vient de la clé ou de l'interface est un appel direct. Voici une requête de streaming avec 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."}]
  }'

Vous devriez voir une série de lignes data: se terminant par des informations d'utilisation. Si cela fonctionne, la clé et l'URL sont correctes et le problème se situe dans l'interface. La page de dépannage couvre les erreurs typiques comme un /v1 manquant ou un espace à la fin de la clé.

Les mêmes paramètres client que vous utilisez pour les modèles locaux sont principalement compatibles. La température, top_p, les séquences d'arrêt, la graine et les pénalités sont transmises au modèle.

Utiliser l'endpoint hébergé depuis votre propre code

Une interface graphique est un client. Les scripts et les petites applications en sont un autre, et l'endpoint hébergé fonctionne avec les SDK OpenAI standard. L'appel de fonctions et le mode JSON sont pris en charge, ce qui est important si votre interface graphique ou agent les utilise.

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)

En Node, le motif est identique :

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

Le guide de démarrage rapide contient plus d'exemples, y compris les appels de fonctions avec tool_choice.

Problèmes courants et solutions

La plupart des échecs dans une configuration d'interface graphique proviennent d'une courte liste de causes.

• Liste de modèles vide pour la connexion locale. L'interface ne peut pas atteindre Ollama. Vérifiez l'adresse, et souvenez-vous qu'une interface graphique conteneurisée ne voit pas votre hôte comme localhost.
• 401 de l'endpoint hébergé. La clé est manquante ou incorrecte. Collez-la à nouveau sans espaces, et assurez-vous que l'interface l'envoie en tant que jeton porteur.
• 404 sur toutes les requêtes. L'URL de base manque probablement de /v1, ou l'a deux fois.
• Les réponses s'arrêtent ou l'interface se bloque. Certaines interfaces mettent en mémoire tampon la sortie diffusée via un proxy. Essayez le test curl direct ci-dessus, et s'il diffuse, vérifiez les paramètres du proxy devant votre interface.
• Réponses locales lentes. Le modèle est trop volumineux pour votre VRAM et déborde vers la mémoire système. Choisissez une quantification plus petite, ou basculez cette conversation vers la connexion hébergée.

Gardez à l'esprit une règle pour les applications de fiction et de compagnons pour adultes : le modèle hébergé répond sans refus de contenu pour une utilisation adulte légale, mais le contenu sexuel impliquant des mineurs n'est jamais autorisé, et le service l'applique comme une limite stricte.

Limites et coûts à connaître dans une interface graphique

Les interfaces peuvent déclencher plusieurs requêtes à la fois, par exemple lorsqu'elles génèrent un titre de chat en arrière-plan pendant que la réponse principale diffuse. Une clé complète permet 8 requêtes concurrentes et 300 requêtes par minute. Une clé d'essai permet 2 requêtes concurrentes et 60 par minute. Une requête diffusée conserve son emplacement jusqu'à la fin du flux. Si vous dépassez une limite, vous obtenez HTTP 429 avec le code rate_limited ou concurrency, et en cas de surcharge temporaire un 429 avec Retry-After: 5. Désactiver la génération de titres en arrière-plan dans l'interface est une solution simple pour une clé d'essai.

Le coût est par token : $0,15 par 1M en entrée et $0,50 par 1M en sortie. Un tour de chat avec 2 000 tokens d'historique et une réponse de 500 tokens coûte $0,0003 plus $0,00025, soit $0,00055. Les en-têtes de réponse incluent X-Balance-USD, afin que vous puissiez suivre la diminution de votre crédit. Les détails sur les recharges se trouvent sur la page des tarifs. Ce site est crypto uniquement : USDT sur TRC20 ou USDC sur Base, tout montant entier de $20 à $500.

La fenêtre de contexte est de 100 000 tokens, donc les conversations très longues coûteront plus cher par tour à mesure que l'historique grandit, car tout l'historique est envoyé à chaque fois. La plupart des interfaces ont un paramètre pour réduire ou résumer les anciens messages.

Plus de guides

• Alternatives logicielles Ollama : API hébergée Uncensored
• Tarification de l'API Ollamansfw : explication des coûts par token
• Guide de l'API LLM sans censure