Collega un LLM locale o un'AI personalizzata al tuo browser con SurfMind

SurfMind non ti vincola a un unico insieme di modelli. Puoi collegarlo a un modello in esecuzione sulla tua macchina (Ollama, LM Studio, Jan, llama.cpp, vLLM) oppure a quasi qualsiasi provider AI esterno che supporti la completion API di OpenAI — Poe, z.ai, Together, Groq, DeepSeek, AWS Bedrock e decine di altri.

La maggior parte dei provider più diffusi e dei runner locali è già configurata nelle impostazioni di SurfMind: clicchi su Connect e incolli la tua chiave API. Per tutto il resto, il modulo Custom Providers / API ti permette di aggiungere l'endpoint da solo.

Se qualcosa non va: quando non funziona al primo tentativo, spesso è colpa di un piccolo errore di configurazione. E l'errore che ricevi ("connection failed", "401", "404", "model not found") non sempre aiuta a capire cosa sia andato storto.

Questo articolo è una guida rapida di verifica e diagnosi. Scorri la checklist e controlla la tua configurazione. Se ancora non funziona, scrivici a wave@surfmind.ai.

Cerchi un provider specifico? Dai un'occhiata al nostro elenco: modelli locali (Ollama, LM Studio, OpenWebUI, Jan…) o provider AI (Poe, z.ai, Together, Groq, AWS…).

La checklist di 60 secondi

Prima di ogni altra cosa, scorri questi punti. La maggior parte dei problemi di configurazione si riduce a uno di essi:

1. Il server è effettivamente in esecuzione? Per i modelli locali, il runner (Ollama, LM Studio, ecc.) deve essere avviato e avere un modello caricato.
2. La porta è giusta? Ollama è 11434. LM Studio è 1234. Non sono intercambiabili, ed è l'errore più comune in assoluto.
3. Il percorso è giusto? Il percorso nativo di Ollama è /api/chat. Quasi tutto il resto usa /v1/chat/completions. Confonderli genera un errore.
4. Il protocollo è giusto — http o https? I modelli locali su localhost usano http:// (senza s). I provider cloud usano https://. Se li confondi, sembrerà che la connessione non funzioni.
5. Hai incollato l'endpoint completo, non solo la base? Il campo API URL di SurfMind vuole l'URL completo che termina con /chat/completions (o /api/chat per Ollama), non solo https://api.provider.com/v1.
6. La chiave API (e il suo formato) è corretta? I runner locali di solito non richiedono alcuna chiave. I provider esterni vogliono Authentication impostato su API Key, il formato Authorization: Bearer e la tua chiave vera.
7. Per i modelli locali nel browser: il CORS è consentito? È l'unico passaggio aggiuntivo richiesto dalle configurazioni locali (OLLAMA_ORIGINS oppure "Enable CORS" in LM Studio).

Se dopo tutto questo sei ancora bloccato, continua a leggere — ognuno di questi punti ha un risvolto meno ovvio su cui in molti inciampano.

Come collegare un provider

Bastano pochi clic dal selettore dei modelli:

Passaggio 1. Clicca sul nome del modello in fondo al pannello di SurfMind per aprire i tuoi Preferiti, poi clicca su Show all.

Passaggio 2. In cima all'elenco dei modelli, clicca su Add model provider. Si apre la pagina Models nelle impostazioni di SurfMind.

Passaggio 3. Trova il tuo provider. I runner locali (Ollama, LM Studio, vLLM, llama.cpp, Open WebUI) si trovano sotto Self-hosted. I provider cloud (OpenAI, Anthropic, Google, OpenRouter, Groq, DeepSeek, Mistral, Poe, z.ai, Together, AWS Bedrock e altri) si trovano sotto Providers. Se l'elenco è lungo usa la casella di ricerca, poi clicca su Connect.

Passaggio 4. Per un provider cloud, incolla la tua chiave API e clicca su Connect. La finestra di dialogo contiene un link alla pagina dove puoi ottenere una chiave. Per un runner self-hosted, il modulo si apre con gli URL locali già compilati, quindi devi solo salvarlo (Open WebUI richiede anche la tua chiave).

Una volta collegato, i modelli del provider compaiono nel selettore dei modelli. Espandi la riga del provider per scegliere quali mostrare.

Non trovi il tuo provider? Aggiungilo come provider personalizzato

Se il tuo provider o runner non è nell'elenco (Jan, LocalAI, il gateway della tua azienda o un provider che non abbiamo ancora aggiunto), clicca su Custom Providers / API in cima alla pagina Models.

Si apre il modulo "Custom Model API", in cui inserisci tu stesso l'endpoint.

Il resto di questa guida riguarda soprattutto questo modulo, perché è lì che si commettono gli errori di configurazione.

Cosa va inserito in ogni campo

Quando clicchi su Custom Providers / API, ottieni il modulo "Custom Model API". Ecco esattamente cosa vuole ogni campo:

Le due cose che si sbagliano più spesso sono API URL (base vs. endpoint completo) e API Key Format (quale header). Il resto della guida approfondisce proprio questi.

Errore #1: il percorso dell'API URL (la trappola /api/chat vs /v1/chat/completions)

Questo è il problema principale, e vale la pena capire perché accade.

Qui si usano due formati API diversi:

• L'API nativa di Ollama, che usa http://localhost:11434/api/chat.
• La completion API di OpenAI, che usa .../v1/chat/completions. È quella usata da LM Studio, vLLM, Jan, Poe, z.ai, Together, Groq — praticamente tutti gli altri.

Quindi se copi una guida di configurazione scritta per LM Studio e provi a usare quel percorso con Ollama (o viceversa), otterrai un 404 anche se il server funziona perfettamente. Il server è attivo; stai solo bussando alla porta sbagliata.

Buono a sapersi: Ollama supporta entrambi i formati API. La voce Ollama sotto Self-hosted in SurfMind usa il percorso nativo /api/chat, che è la via più semplice e ti offre il rilevamento automatico dei modelli. Il percorso /v1/chat/completions di Ollama ti serve solo se uno strumento richiede espressamente il formato OpenAI. Con SurfMind, clicca semplicemente su Connect nella riga di Ollama.

Errore #2: il numero di porta

Ogni runner locale usa la propria porta predefinita, e i numeri si somigliano, quindi è facile sbagliare a digitarli:

11434 vs 1234 è la classica confusione — sono facili da scambiare a colpo d'occhio, ma con una cifra sbagliata non si connette nulla. Se hai cambiato tu stesso la porta (ad es. hai avviato vLLM con --port 9000), usa la tua porta, non quella predefinita.

Una verifica veloce: apri nel browser l'indirizzo del server, includendo la porta. Visitando http://localhost:11434 dovresti vedere il messaggio "Ollama is running" di Ollama. Se la pagina non si carica affatto, il server non è attivo oppure hai sbagliato porta.

Errore #3: incollare l'URL di base invece dell'endpoint

La documentazione dei provider ti fornisce quasi sempre un URL di base — qualcosa come https://api.poe.com/v1. Questo perché i loro esempi di codice usano l'SDK di OpenAI, che aggiunge /chat/completions al posto tuo dietro le quinte.

Il campo API URL di SurfMind non lo fa al posto tuo. Si aspetta l'endpoint completo. Quindi il percorso devi aggiungerlo tu:

• URL di base dalla documentazione: https://api.poe.com/v1
• Cosa incolli in SurfMind: https://api.poe.com/v1/chat/completions

Stesso ragionamento per il campo Models URL (usato per elencare automaticamente i modelli disponibili): prendi la base e aggiungi /models → https://api.poe.com/v1/models.

Due sviste correlate:

• Doppio /v1. Se la base termina già con /v1, non aggiungerne un altro. .../v1/v1/chat/completions è un 404.
• Slash finali. .../chat/completions/ con uno slash finale può fallire su alcuni server. Rimuovilo.

Errore #4: discordanza tra http e https

Lo schema all'inizio dell'URL conta, e confonderlo produce un "connection failed" che sembra un server spento quando invece non lo è.

• I modelli locali sono http. Ollama, LM Studio, Jan, llama.cpp — qualsiasi cosa su localhost — serve semplice http://. Digitare https://localhost:11434 fallisce, perché su un server locale non c'è alcun certificato TLS. Se hai copiato uno snippet con https davanti a localhost, togli la s.
• I provider cloud sono https. Poe, z.ai, Together, Groq e tutti gli altri accettano solo https://. Inviare loro http:// viene rifiutato o reindirizzato silenziosamente.

C'è anche un aspetto legato alla sicurezza del browser: le pagine servite via https bloccano le richieste verso endpoint in semplice http ("mixed content"). SurfMind gestisce http://localhost come un'eccezione fidata, quindi i modelli locali funzionano — ma un semplice IP della LAN come http://192.168.1.50:11434 potrebbe comunque essere bloccato. Se stai puntando a un'altra macchina della tua rete, preferisci https, oppure servi il modello dietro un proxy https locale.

Regola pratica: http per localhost, https per tutto ciò che è su internet pubblico.

Errore #5: il Models URL non corrisponde all'API URL

Il Models URL è opzionale. È l'endpoint che SurfMind chiama per recuperare l'elenco dei modelli offerti da un provider, così da poterli mostrare in un menu a discesa invece di farti digitare i nomi. Se i tuoi modelli non compaiono nel selettore dopo aver salvato, di solito il colpevole è questo campo. Deve usare lo stesso formato API dell'endpoint di chat:

Un errore comune è mescolarli — usare /api/tags con un provider compatibile con OpenAI, oppure /v1/models con il percorso nativo /api/chat di Ollama. Se ti sei collegato tramite la riga Ollama sotto Self-hosted, questo viene compilato correttamente al posto tuo; non toccarlo.

Quando lasciarlo vuoto: alcuni provider non espongono un endpoint pubblico di elenco modelli, oppure lo bloccano. Va bene — lascia il Models URL vuoto e digita semplicemente l'id esatto del modello nel campo del modello tu stesso (vedi Errore #8). La chat funzionerà comunque; semplicemente non avrai il menu a discesa popolato automaticamente.

Errore #6: il formato della chiave API (Bearer vs x-api-key)

Nel modulo personalizzato, Authentication e API Key Format decidono come la tua chiave viene allegata alla richiesta. Se scegli quello sbagliato otterrai un 401 Unauthorized anche con una chiave perfettamente valida. Le opzioni:

Poi il campo API Key accetta solo la chiave stessa:

• Non digitare la parola Bearer — la aggiunge SurfMind quando scegli Authorization: Bearer.
• Non lasciare uno spazio finale (una causa sorprendentemente comune di 401).
• Per i modelli locali, scegli No authentication. (LM Studio è l'eccezione — vuole un qualche valore non vuoto; la sua documentazione usa lm-studio.)

Se non sei sicuro di quale formato usi un provider: il 99% dei provider compatibili con OpenAI usa Authorization: Bearer. Ricorri a x-api-key solo se la documentazione del provider mostra esplicitamente un header x-api-key. Continui a ricevere un 401? Rigenera la chiave, ricontrolla il formato e verifica che non ci sia uno spazio di troppo.

Errore #7: CORS — l'inghippo solo locale

I browser rifiutano di chiamare un server locale a meno che quel server non consenta esplicitamente le richieste dall'estensione. Questo mette in difficoltà specificamente le configurazioni locali (i provider esterni lo consentono già).

• Ollama: avvialo con l'accesso da browser abilitato:

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

  "port 11434 already in use"? L'app Ollama in background è già in esecuzione. Chiudila prima (barra dei menu su Mac, area di notifica su Windows), poi esegui il comando qui sopra.

• LM Studio: nella scheda Developer / server locale, attiva Enable CORS prima di avviare il server.

Un'ultima sottigliezza: se localhost non si connette, prova 127.0.0.1 (o viceversa). Su alcuni sistemi non si risolvono allo stesso modo.

Errore #8: il nome del modello deve corrispondere esattamente

Una volta connesso, il nome del modello che selezioni deve corrispondere a ciò che il provider si aspetta — esattamente, maiuscole comprese. È un problema che si presenta con i provider che non elencano automaticamente i modelli, o che usano una nomenclatura insolita:

• Poe usa nomi dei bot così come vengono visualizzati, tipo Claude-Sonnet-4.6 e GPT-5.4 — copiali esattamente come appaiono su Poe.
• z.ai usa id come glm-4.6 e glm-5.
• Together AI usa id con namespace: meta-llama/Llama-3.3-70B-Instruct-Turbo, deepseek-ai/DeepSeek-V3.
• Fireworks usa un id a percorso completo: accounts/fireworks/models/llama-v3p3-70b-instruct.

Se la connessione funziona ma ottieni "model not found", quasi sempre è un errore di battitura nel nome o un uso sbagliato delle maiuscole. Quando SurfMind può elencare i modelli automaticamente tramite il Models URL, scegli dall'elenco invece di digitare a mano.

Riferimento rapido: modelli locali

Tutti questi girano sulla tua macchina. Ollama, LM Studio, vLLM, llama.cpp e Open WebUI sono già elencati sotto Self-hosted nella pagina Models: clicca su Connect e gli URL qui sotto vengono compilati al posto tuo. Per Jan e LocalAI, clicca su Custom Providers / API, incolla gli URL e imposta Authentication su No authentication. Se hai cambiato la porta di un runner, modifica l'URL di conseguenza. I nomi dei provider rimandano alla documentazione di configurazione di ciascuno strumento.

Ollama

• API URL: http://localhost:11434/api/chat
• Models URL: http://localhost:11434/api/tags
• API key: nessuna

LM Studio

• API URL: http://localhost:1234/v1/chat/completions
• Models URL: http://localhost:1234/v1/models
• API key: qualsiasi valore non vuoto (ad es. lm-studio)

Jan

• API URL: http://localhost:1337/v1/chat/completions
• Models URL: http://localhost:1337/v1/models
• API key: nessuna (oppure la tua chiave Jan)

llama.cpp

• API URL: http://localhost:8080/v1/chat/completions
• Models URL: http://localhost:8080/v1/models
• API key: nessuna (a meno che tu non l'abbia avviato con --api-key)

vLLM

• API URL: http://localhost:8000/v1/chat/completions
• Models URL: http://localhost:8000/v1/models
• API key: la tua --api-key se ne hai impostata una

LocalAI

• API URL: http://localhost:8080/v1/chat/completions
• Models URL: http://localhost:8080/v1/models
• API key: nessuna

OpenWebUI: l'eccezione alla regola "nessuna chiave". OpenWebUI richiede una chiave API, e i suoi percorsi sono /api/..., non /v1/.... Collegalo dall'elenco Self-hosted e incolla la tua chiave sk-… presa da Settings → Account → API keys. Usa http://localhost:3000 per una tipica installazione con Docker, oppure l'indirizzo del tuo server se gira altrove.

• API URL: http://localhost:3000/api/chat/completions
• Models URL: http://localhost:3000/api/models
• API key: la tua chiave OpenWebUI (sk-…)

Configurazione completa e risoluzione dei problemi sono nella nostra guida all'OpenWebUI API.

Non dimenticare il passaggio CORS (Errore #7) per ognuno di questi. Per Ollama in particolare, la guida completa con screenshot si trova nella nostra guida a Ollama, e se stai decidendo tra i primi due, vedi Ollama vs LM Studio.

Riferimento rapido: provider AI popolari

Tutti i provider qui sotto sono già elencati sotto Providers nella pagina Models: clicca su Connect e incolla la tua chiave — gli URL vengono compilati al posto tuo. Li riportiamo qui come riferimento, o nel caso preferissi aggiungerne uno a mano con Custom Providers / API (imposta Authentication su API Key con il formato Authorization: Bearer). I nomi dei provider rimandano alla documentazione API di ciascun provider.

Poe — una sola chiave per centinaia di modelli (Claude, GPT, Gemini, Llama…), addebitati sui punti del tuo abbonamento Poe. I nomi dei modelli sono i nomi dei bot così come vengono visualizzati — copiali esattamente come appaiono su Poe (ad es. Claude-Sonnet-4.6, GPT-5.4). Chiave da poe.com → Settings → API key.

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

CanopyWave — provider GPU-cloud che serve modelli aperti (Kimi, DeepSeek, Llama, Qwen). Chiave dalla dashboard di CanopyWave.

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

z.ai (GLM) — i modelli GLM di Zhipu (glm-4.6, glm-5). Attenzione: z.ai pubblica anche un endpoint Coding Plan separato (https://api.z.ai/api/coding/paas/v4) e un endpoint PaaS (https://api.z.ai/api/paas/v4) — usa quello compatibile con OpenAI qui sotto e non aggiungere un /v1 extra.

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

Together AI — ampio catalogo di modelli aperti. Gli id dei modelli sono lunghi (meta-llama/Llama-3.3-70B-Instruct-Turbo) — copiali esattamente dalla pagina dei modelli di Together.

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

Groq — inferenza estremamente veloce. Inghippo: il percorso è /openai/v1, non solo /v1.

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

DeepSeek — i modelli attuali sono deepseek-v4-flash e deepseek-v4-pro (i vecchi alias deepseek-chat / deepseek-reasoner stanno per essere ritirati — controlla la documentazione di DeepSeek per gli ultimi aggiornamenti). Il /v1 è opzionale; DeepSeek accetta l'URL con o senza.

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

Mistral — mistral-large-latest, mistral-small-latest, ecc. Standard compatibile con OpenAI.

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

Fireworks AI — inghippo: il percorso è /inference/v1, non /v1. Gli id dei modelli hanno l'aspetto 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) — modelli Grok (grok-4, ecc.). Standard compatibile con OpenAI.

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

AWS Bedrock — Bedrock ora ha un endpoint compatibile con OpenAI, ma con due inghippi: l'host è specifico per regione (ad es. us-west-2) e il percorso è /openai/v1. Devi usare una Bedrock API key (un token bearer che generi nella console) — non le tue normali chiavi di accesso AWS/SigV4. Gli id dei modelli hanno l'aspetto openai.gpt-oss-120b-1:0. Quando colleghi Bedrock dall'elenco Providers, scegli la tua regione dal menu a discesa e SurfMind costruisce l'URL al posto tuo.

• API URL: https://bedrock-runtime.<region>.amazonaws.com/openai/v1/chat/completions
• Models URL: lascia vuoto — inserisci l'id del modello in seguito

Ancora non si connette? Ultimi controlli

Segui questi passaggi in ordine:

1. Controlla prima la pagina Models. Se il tuo provider è elencato, collegalo da lì invece di creare una voce personalizzata.
2. Apri l'host dell'API URL nel tuo browser. Server locale che non si carica → non è in esecuzione, oppure la porta è sbagliata.
3. Rileggi il percorso. Ollama → /api/chat. Tutti gli altri → /v1/chat/completions (o il percorso speciale del provider dalla tabella).
4. Verifica di aver incollato l'endpoint completo, non la base, e che non ci sia un doppio /v1 o uno slash finale.
5. 401? È la chiave o il suo formato. Formato = Authorization: Bearer, chiave senza spazi, senza prefisso Bearer.
6. 404 "model not found"? La connessione va bene — correggi il nome del modello (maiuscole esatte).
7. Modello locale, browser bloccato? Abilita il CORS (OLLAMA_ORIGINS="*" o l'interruttore di LM Studio) e prova 127.0.0.1 vs localhost.

Questi passaggi risolvono la grande maggioranza dei problemi di configurazione.

Hai ancora bisogno di aiuto?

Se hai seguito tutta la checklist e il tuo provider continua a non connettersi, scrivici una email all'indirizzo wave@surfmind.ai indicando il provider che stai provando e l'errore che vedi. Ti aiuteremo a connetterlo.

---

Connesso? Apri SurfMind sulla prossima pagina che stavi per leggere e metti al lavoro il tuo modello.

Ottieni SurfMind →