Connecter un LLM local ou une IA personnalisée à votre navigateur avec SurfMind

SurfMind ne vous enferme pas dans un seul ensemble de modèles. Grâce à la Custom Model API (API de modèle personnalisé), vous pouvez le diriger vers un modèle qui tourne sur votre propre machine (Ollama, LM Studio, Jan, llama.cpp, vLLM) ou vers presque n'importe quel fournisseur d'IA externe qui parle l'API de complétion OpenAI — Poe, z.ai, Together, Groq, DeepSeek, AWS Bedrock, et des dizaines d'autres.

Le hic : quand ça ne marche pas du premier coup, c'est peut-être à cause d'une petite erreur de configuration. L'erreur que vous obtenez en retour (« connexion échouée », « 401 », « 404 », « model not found ») peut être déroutante.

Cet article est un guide de vérification et de dépannage rapide. Parcourez la checklist et confirmez votre configuration. Si ça ne fonctionne toujours pas, écrivez-nous à wave@surfmind.ai.

Vous cherchez un fournisseur précis ? Consultez notre liste : modèles locaux (Ollama, LM Studio, Jan…) ou fournisseurs d'IA (Poe, z.ai, Together, Groq, AWS…).

La checklist en 60 secondes

Avant toute chose, passez en revue ces points. La plupart des problèmes de configuration se résument à l'un d'entre eux :

1. Le serveur tourne-t-il vraiment ? Pour les modèles locaux, le moteur (Ollama, LM Studio, etc.) doit être démarré et avoir un modèle chargé.
2. Le port est-il le bon ? Ollama, c'est 11434. LM Studio, c'est 1234. Ils ne sont pas interchangeables, et c'est l'erreur la plus fréquente de toutes.
3. Le chemin est-il le bon ? Le chemin natif d'Ollama est /api/chat. Pour presque tout le reste, c'est /v1/chat/completions. Les confondre génère une erreur.
4. Avez-vous collé l'endpoint complet, et pas seulement la base ? Le champ API URL de SurfMind attend l'URL complète se terminant par /chat/completions (ou /api/chat pour Ollama), et non simplement https://api.provider.com/v1.
5. La clé API (et son en-tête) sont-elles correctes ? Les moteurs locaux n'ont généralement pas besoin de clé. Les fournisseurs externes ont besoin de Authorization comme en-tête et de votre vraie clé comme valeur.
6. Pour les modèles locaux dans le navigateur : le CORS est-il autorisé ? C'est l'étape supplémentaire dont les configurations locales ont besoin (OLLAMA_ORIGINS, ou « Enable CORS » dans LM Studio).

Si vous êtes toujours bloqué après ça, poursuivez votre lecture — chacun de ces points a une variante subtile qui piège bien des utilisateurs.

Ce qu'il faut mettre dans chaque champ

Quand vous ouvrez l'onglet Custom → Add Custom Models, vous obtenez le formulaire « Custom Model API ». Voici exactement ce qu'attend chaque champ :

Les deux champs sur lesquels on se trompe le plus souvent sont API URL (base ou endpoint complet) et API Key Header (quel en-tête). Le reste de ce guide approfondit ces deux points.

Erreur n°1 : le chemin de l'API URL (le piège /api/chat vs /v1/chat/completions)

C'est la grosse erreur, et ça vaut la peine de comprendre pourquoi elle se produit.

Il existe deux « dialectes » d'API différents dans cet univers :

• L'API native d'Ollama, qui utilise http://localhost:11434/api/chat.
• L'API de complétion OpenAI, qui utilise .../v1/chat/completions. C'est ce que parlent LM Studio, vLLM, Jan, Poe, z.ai, Together, Groq — en gros tout le reste.

Donc si vous copiez un guide de configuration écrit pour LM Studio et que vous essayez d'utiliser ce chemin avec Ollama (ou inversement), vous obtiendrez un 404 alors même que le serveur tourne parfaitement. Le serveur est bien là ; vous frappez juste à la mauvaise porte.

Bon à savoir : Ollama parle en fait les deux dialectes. Le Ollama preset dans SurfMind utilise le chemin natif /api/chat, qui est la voie la plus simple et vous offre la découverte automatique des modèles. Vous n'avez besoin du chemin /v1/chat/completions d'Ollama que si un outil exige spécifiquement le format OpenAI. Pour SurfMind, utilisez simplement le preset.

Erreur n°2 : le numéro de port

Chaque moteur local choisit son propre port par défaut, et ils se ressemblent assez pour qu'on se trompe :

11434 vs 1234, c'est la confusion classique — ils sont faciles à confondre au premier coup d'œil, mais un chiffre de travers et plus rien ne se connecte. Si vous avez vous-même changé le port (par ex. vous avez lancé vLLM avec --port 9000), utilisez votre port, pas celui par défaut.

Petite vérification rapide : ouvrez le port dans votre navigateur. Visiter http://localhost:11434 devrait afficher le message « Ollama is running » d'Ollama. Si la page ne se charge pas du tout, c'est que le serveur n'est pas démarré ou que vous avez le mauvais port.

Erreur n°3 : coller l'URL de base au lieu de l'endpoint

La documentation des fournisseurs vous donne presque toujours une URL de base — quelque chose comme https://api.poe.com/v1. C'est parce que leurs exemples de code utilisent le SDK OpenAI, qui ajoute /chat/completions pour vous en coulisses.

Le champ API URL de SurfMind ne fait pas ça pour vous. Il attend l'endpoint complet. Vous devez donc ajouter le chemin vous-même :

• URL de base dans la doc : https://api.poe.com/v1
• Ce que vous collez dans SurfMind : https://api.poe.com/v1/chat/completions

Même principe pour le champ Models URL (utilisé pour lister automatiquement les modèles disponibles) : prenez la base et ajoutez /models → https://api.poe.com/v1/models.

Deux faux pas associés :

• Double /v1. Si la base se termine déjà par /v1, n'en ajoutez pas un autre. .../v1/v1/chat/completions donne un 404.
• Slashs en fin d'URL. .../chat/completions/ avec un slash final peut échouer sur certains serveurs. Supprimez-le.

Erreur n°4 : le Models URL ne correspond pas à l'API URL

Le Models URL est optionnel. C'est l'endpoint que SurfMind appelle pour récupérer la liste des modèles proposés par un fournisseur, afin de les afficher dans un menu déroulant plutôt que de vous faire saisir les noms. Si vos modèles n'apparaissent pas dans le sélecteur après l'enregistrement, ce champ est généralement le coupable. Il doit suivre le même dialecte que l'endpoint de chat :

Une erreur courante consiste à les mélanger — utiliser /api/tags avec un fournisseur compatible OpenAI, ou /v1/models avec le Ollama preset natif. Si vous avez utilisé le Ollama preset, ce champ est rempli correctement pour vous ; n'y touchez pas.

Quand le laisser vide : certains fournisseurs n'exposent pas d'endpoint public de liste de modèles, ou le bloquent. Pas de souci — laissez Models URL vide et saisissez vous-même l'id exact du modèle dans le champ correspondant (voir Erreur n°7). Le chat fonctionnera quand même ; vous n'aurez simplement pas le menu déroulant rempli automatiquement.

Erreur n°5 : l'API Key Header (Bearer vs x-api-key)

Le menu déroulant API Key Header décide comment votre clé est attachée à la requête. Choisissez le mauvais et vous obtiendrez un 401 Unauthorized même avec une clé parfaitement valide. Il y a trois choix :

Ensuite, le champ API Key ne prend que la clé elle-même :

• Ne saisissez pas le mot Bearer — SurfMind l'ajoute quand vous choisissez Authorization.
• Ne laissez pas d'espace en fin de valeur (une cause étonnamment fréquente de 401).
• Pour les modèles locaux, laissez vide. (LM Studio est l'exception — il veut une valeur non vide ; sa propre doc utilise lm-studio.)

Si vous ne savez pas quel en-tête un fournisseur utilise : 99 % des fournisseurs compatibles OpenAI utilisent Authorization. N'optez pour x-api-key que si la doc du fournisseur montre explicitement un en-tête x-api-key. Toujours un 401 ? Régénérez la clé, revérifiez le choix de l'en-tête, et assurez-vous qu'il n'y a pas d'espace parasite.

Erreur n°6 : le CORS — le piège propre au local

Les navigateurs refusent d'appeler un serveur local à moins que ce serveur n'autorise explicitement les requêtes en provenance de l'extension. Cela piège spécifiquement les configurations locales (les fournisseurs externes l'autorisent déjà).

• Ollama : démarrez-le avec l'accès navigateur activé :

  # Mac/Linux
  OLLAMA_ORIGINS="*" ollama serve
  
  # Windows (PowerShell)
  $env:OLLAMA_ORIGINS="*"; ollama serve

  « port 11434 already in use » ? L'application Ollama en arrière-plan tourne déjà. Quittez-la d'abord (barre de menus sur Mac, zone de notification sur Windows), puis lancez la commande ci-dessus.

• LM Studio : dans l'onglet Developer / serveur local, activez Enable CORS avant de démarrer le serveur.

Une subtilité de plus : si localhost ne se connecte pas, essayez 127.0.0.1 à la place (ou l'inverse). Sur certains systèmes, ils ne se résolvent pas de la même manière.

Erreur n°7 : le nom du modèle doit correspondre exactement

Une fois connecté, le nom du modèle que vous sélectionnez doit correspondre à ce qu'attend le fournisseur — exactement, casse comprise. Cela piège les utilisateurs sur les fournisseurs qui ne listent pas automatiquement les modèles, ou qui utilisent un nommage inhabituel :

• Poe utilise des noms de bots tels qu'affichés, comme Claude-Sonnet-4.6 et GPT-5.4 — copiez-les exactement tels qu'ils apparaissent sur Poe.
• z.ai utilise des ids comme glm-4.6 et glm-5.
• Together AI utilise des ids avec espace de noms : meta-llama/Llama-3.3-70B-Instruct-Turbo, deepseek-ai/DeepSeek-V3.
• Fireworks utilise un id en chemin complet : accounts/fireworks/models/llama-v3p3-70b-instruct.

Si la connexion fonctionne mais que vous obtenez « model not found », c'est presque toujours une faute de frappe dans le nom ou une mauvaise casse. Quand SurfMind peut lister automatiquement les modèles via le Models URL, choisissez dans la liste plutôt que de saisir.

Référence rapide : modèles locaux

Tous ceux-ci tournent sur votre propre machine. Ouvrez l'onglet Custom de SurfMind → Add Custom Models, choisissez le preset correspondant (Ollama a le sien ; le reste utilise le preset générique OpenAI-compatible), et réglez API Key Header sur None. Les noms de fournisseurs renvoient vers la doc de configuration de chaque outil.

Ollama

• API URL : http://localhost:11434/api/chat
• Models URL : http://localhost:11434/api/tags
• Clé API : aucune

LM Studio

• API URL : http://localhost:1234/v1/chat/completions
• Models URL : http://localhost:1234/v1/models
• Clé API : n'importe quelle valeur non vide (par ex. lm-studio)

Jan

• API URL : http://localhost:1337/v1/chat/completions
• Models URL : http://localhost:1337/v1/models
• Clé API : aucune (ou votre clé Jan)

llama.cpp

• API URL : http://localhost:8080/v1/chat/completions
• Models URL : http://localhost:8080/v1/models
• Clé API : aucune (sauf si vous l'avez démarré avec --api-key)

vLLM

• API URL : http://localhost:8000/v1/chat/completions
• Models URL : http://localhost:8000/v1/models
• Clé API : votre --api-key si vous en avez défini une

LocalAI

• API URL : http://localhost:8080/v1/chat/completions
• Models URL : http://localhost:8080/v1/models
• Clé API : aucune

N'oubliez pas l'étape CORS (Erreur n°6) pour n'importe lequel d'entre eux. Pour Ollama en particulier, le tutoriel complet avec captures d'écran se trouve dans notre guide Ollama, et si vous hésitez entre les deux premiers, voyez Ollama vs LM Studio.

Référence rapide : fournisseurs d'IA populaires

Ces fournisseurs cloud parlent tous l'API compatible OpenAI. Utilisez le preset générique OpenAI-compatible, réglez l'API Key Header sur Authorization (ils utilisent tous des tokens Bearer), et collez votre clé. Les noms de fournisseurs renvoient vers la doc API de chaque fournisseur.

Poe — une seule clé pour des centaines de modèles (Claude, GPT, Gemini, Llama…), facturés sur les points de votre abonnement Poe. Les noms de modèles sont des noms de bots tels qu'affichés — copiez-les exactement tels qu'ils apparaissent sur Poe (par ex. Claude-Sonnet-4.6, GPT-5.4). Clé depuis poe.com → Settings → API key.

• API URL : https://api.poe.com/v1/chat/completions
• Models URL : https://api.poe.com/v1/models

CanopyWave — fournisseur de cloud GPU servant des modèles ouverts (Kimi, DeepSeek, Llama, Qwen). Clé depuis le tableau de bord CanopyWave.

• API URL : https://inference.canopywave.io/v1/chat/completions
• Models URL : https://inference.canopywave.io/v1/models

z.ai (GLM) — les modèles GLM de Zhipu (glm-4.6, glm-5). Attention : z.ai publie aussi un endpoint Coding Plan distinct (https://api.z.ai/api/coding/paas/v4) et un endpoint PaaS (https://api.z.ai/api/paas/v4) — utilisez celui compatible OpenAI ci-dessous et n'ajoutez pas un /v1 supplémentaire.

• API URL : https://api.z.ai/api/openai/v1/chat/completions
• Models URL : https://api.z.ai/api/openai/v1/models

Together AI — vaste catalogue de modèles ouverts. Les ids de modèles sont longs (meta-llama/Llama-3.3-70B-Instruct-Turbo) — copiez-les exactement depuis la page modèles de Together.

• API URL : https://api.together.xyz/v1/chat/completions
• Models URL : https://api.together.xyz/v1/models

Groq — inférence extrêmement rapide. Piège : le chemin est /openai/v1, pas seulement /v1.

• API URL : https://api.groq.com/openai/v1/chat/completions
• Models URL : https://api.groq.com/openai/v1/models

DeepSeek — les modèles actuels sont deepseek-v4-flash et deepseek-v4-pro (les anciens alias deepseek-chat / deepseek-reasoner sont en cours de retrait — consultez la doc de DeepSeek pour les dernières infos). Le /v1 est optionnel ; DeepSeek accepte l'URL avec ou sans.

• API URL : https://api.deepseek.com/v1/chat/completions
• Models URL : https://api.deepseek.com/v1/models

Mistral — mistral-large-latest, mistral-small-latest, etc. Standard compatible OpenAI.

• API URL : https://api.mistral.ai/v1/chat/completions
• Models URL : https://api.mistral.ai/v1/models

Fireworks AI — piège : le chemin est /inference/v1, pas /v1. Les ids de modèles ressemblent à accounts/fireworks/models/llama-v3p3-70b-instruct.

• API URL : https://api.fireworks.ai/inference/v1/chat/completions
• Models URL : https://api.fireworks.ai/inference/v1/models

xAI (Grok) — les modèles Grok (grok-4, etc.). Standard compatible OpenAI.

• API URL : https://api.x.ai/v1/chat/completions
• Models URL : https://api.x.ai/v1/models

AWS Bedrock — Bedrock dispose désormais d'un endpoint compatible OpenAI, mais avec deux pièges : l'hôte est spécifique à la région (par ex. us-west-2) et le chemin est /openai/v1. Vous devez utiliser une Bedrock API key (un token bearer que vous générez dans la console) — pas vos clés d'accès AWS habituelles / SigV4. Les ids de modèles ressemblent à openai.gpt-oss-120b-1:0.

• API URL : https://bedrock-runtime.<region>.amazonaws.com/openai/v1/chat/completions
• Models URL : laissez vide — saisissez l'id du modèle plus tard

Toujours pas de connexion ? Triage final

Parcourez cette liste de haut en bas :

1. Ouvrez l'hôte de l'API URL dans votre navigateur. Le serveur local ne se charge pas → il ne tourne pas, ou mauvais port.
2. Relisez le chemin. Ollama → /api/chat. Tous les autres → /v1/chat/completions (ou le chemin spécial du fournisseur indiqué dans le tableau).
3. Vérifiez que vous avez collé l'endpoint complet, pas la base, et qu'il n'y a pas de double /v1 ni de slash final.
4. 401 ? C'est la clé ou l'en-tête. En-tête = Authorization, clé sans espaces, sans préfixe Bearer.
5. 404 « model not found » ? La connexion est bonne — corrigez le nom du modèle (casse exacte).
6. Modèle local, navigateur bloqué ? Activez le CORS (OLLAMA_ORIGINS="*" ou le bouton de LM Studio), et essayez 127.0.0.1 vs localhost.

Cette séquence résout l'écrasante majorité des configurations.

Besoin d'aide supplémentaire ?

Si vous avez parcouru la checklist et que votre fournisseur refuse toujours de se connecter, écrivez-nous à wave@surfmind.ai en indiquant le fournisseur que vous essayez et l'erreur que vous voyez. Nous vous aiderons à établir la connexion.

---

Connexion établie ? Ouvrez SurfMind sur la prochaine page que vous alliez lire et mettez votre modèle au travail.

Obtenir SurfMind →