Conecte um LLM Local ou IA Personalizada ao Seu Navegador com o SurfMind

O SurfMind não prende você a um único conjunto de modelos. Por meio da Custom Model API (API de Modelo Personalizado), você pode apontá-lo para um modelo rodando na sua própria máquina (Ollama, LM Studio, Jan, llama.cpp, vLLM) ou para quase qualquer provedor de IA externo que fale a API de completion da OpenAI — Poe, z.ai, Together, Groq, DeepSeek, AWS Bedrock e dezenas de outros.

O problema: quando não funciona na primeira tentativa, pode ser por causa de um pequeno erro de configuração. A mensagem de erro que aparece ("connection failed", "401", "404", "model not found") nem sempre é fácil de interpretar.

Este post é um guia rápido de verificação e autoajuda. Passe os olhos pelo checklist e confirme sua configuração. Se ainda assim não funcionar, mande um e-mail para wave@surfmind.ai.

Procurando um provedor específico? Confira nossa lista: modelos locais (Ollama, LM Studio, Jan…) ou provedores de IA (Poe, z.ai, Together, Groq, AWS…).

O checklist de 60 segundos

Antes de mais nada, passe por estes pontos. A maioria dos problemas de configuração se resume a um deles:

1. O servidor está realmente rodando? Para modelos locais, o runner (Ollama, LM Studio, etc.) precisa estar iniciado e ter um modelo carregado.
2. A porta está certa? A do Ollama é 11434. A do LM Studio é 1234. Elas não são intercambiáveis, e este é o erro mais comum de todos.
3. O caminho (path) está certo? O caminho nativo do Ollama é /api/chat. Quase todo o resto é /v1/chat/completions. Trocar um pelo outro gera um erro.
4. Você colou o endpoint completo, não só a base? O campo API URL do SurfMind quer a URL completa terminando em /chat/completions (ou /api/chat para o Ollama), e não apenas https://api.provider.com/v1.
5. A API key (e o cabeçalho dela) está correta? Runners locais geralmente não precisam de key. Provedores externos precisam de Authorization como cabeçalho e da sua key real como valor.
6. Para modelos locais no navegador: o CORS está liberado? Esta é a etapa extra que só as configurações locais precisam (OLLAMA_ORIGINS, ou "Enable CORS" no LM Studio).

Se mesmo assim você continuar travado, continue lendo — cada um destes pontos tem uma versão mais sutil que pega as pessoas de surpresa.

O que vai em cada campo

Quando você abre a aba Custom → Add Custom Models, surge o formulário "Custom Model API". Veja exatamente o que cada campo espera:

Os dois campos que as pessoas mais erram são o API URL (base vs. endpoint completo) e o API Key Header (qual cabeçalho). O restante deste guia se aprofunda nesses dois.

Erro #1: o caminho do API URL (a armadilha /api/chat vs /v1/chat/completions)

Este é o grande erro, e vale a pena entender por que ele acontece.

Existem dois "dialetos" de API diferentes neste mundo:

• A API nativa do Ollama, que usa http://localhost:11434/api/chat.
• A API de completion da OpenAI, que usa .../v1/chat/completions. É o que LM Studio, vLLM, Jan, Poe, z.ai, Together, Groq — basicamente todos os outros — falam.

Então, se você copia um guia de configuração escrito para o LM Studio e tenta usar aquele caminho com o Ollama (ou vice-versa), vai receber um 404 mesmo com o servidor rodando perfeitamente. O servidor está no ar; você só está batendo na porta errada.

Bom saber: o Ollama na verdade fala os dois dialetos. O Ollama preset no SurfMind usa o caminho nativo /api/chat, que é a rota mais simples e oferece descoberta automática de modelos. Você só precisa do caminho /v1/chat/completions do Ollama se alguma ferramenta exigir especificamente o formato OpenAI. Para o SurfMind, basta usar o preset.

Erro #2: o número da porta

Cada runner local escolhe sua própria porta padrão, e elas são parecidas o suficiente para você errar a digitação:

11434 vs 1234 é a confusão clássica — são fáceis de confundir num relance, mas um dígito errado e nada conecta. Se você mesmo alterou a porta (ex.: rodou o vLLM com --port 9000), use a sua porta, não a padrão.

Um teste rápido: abra a porta no seu navegador. Visitar http://localhost:11434 deve mostrar a mensagem "Ollama is running" do Ollama. Se a página não carregar nada, o servidor não está no ar ou você está com a porta errada.

Erro #3: colar a URL base em vez do endpoint

A documentação dos provedores quase sempre te dá uma URL base — algo como https://api.poe.com/v1. Isso acontece porque os exemplos de código deles usam o SDK da OpenAI, que adiciona o /chat/completions por baixo dos panos.

O campo API URL do SurfMind não faz isso por você. Ele espera o endpoint completo. Então você precisa adicionar o caminho você mesmo:

• URL base da documentação: https://api.poe.com/v1
• O que você cola no SurfMind: https://api.poe.com/v1/chat/completions

A mesma ideia vale para o campo Models URL (usado para listar automaticamente os modelos disponíveis): pegue a base e adicione /models → https://api.poe.com/v1/models.

Dois deslizes relacionados:

• /v1 duplicado. Se a base já termina em /v1, não adicione outro. .../v1/v1/chat/completions dá 404.
• Barras no final. .../chat/completions/ com barra no final pode falhar em alguns servidores. Remova-a.

Erro #4: o Models URL não combina com o API URL

O Models URL é opcional. É o endpoint que o SurfMind chama para buscar a lista de modelos que um provedor oferece, para poder exibi-los em um dropdown em vez de fazer você digitar nomes. Se seus modelos não aparecerem no seletor depois de salvar, este campo costuma ser o culpado. Ele precisa seguir o mesmo dialeto do endpoint de chat:

Um erro comum é misturá-los — usar /api/tags com um provedor compatível com OpenAI, ou /v1/models com o preset nativo do Ollama. Se você usou o Ollama preset, isto é preenchido corretamente para você; deixe como está.

Quando deixar em branco: alguns provedores não expõem um endpoint público de listagem de modelos, ou o bloqueiam. Tudo bem — deixe o Models URL vazio e simplesmente digite o model id exato no campo de modelo você mesmo (veja o Erro #7). O chat ainda vai funcionar; você só não terá o dropdown preenchido automaticamente.

Erro #5: o API Key Header (Bearer vs x-api-key)

O dropdown API Key Header decide como sua key é anexada à requisição. Escolha o errado e você receberá um 401 Unauthorized mesmo com uma key perfeitamente válida. Há três opções:

Então o campo API Key recebe apenas a key em si:

• Não digite a palavra Bearer — o SurfMind a adiciona quando você escolhe Authorization.
• Não deixe um espaço no final (uma causa surpreendentemente comum de 401s).
• Para modelos locais, deixe vazio. (O LM Studio é a exceção — ele quer algum valor não vazio; a própria documentação dele usa lm-studio.)

Em dúvida sobre qual cabeçalho um provedor usa: 99% dos provedores compatíveis com OpenAI usam Authorization. Só recorra a x-api-key se a documentação do provedor mostrar explicitamente um cabeçalho x-api-key. Ainda recebendo um 401? Gere a key novamente, confira a escolha do cabeçalho e confirme que não há espaço perdido.

Erro #6: CORS — a pegadinha exclusiva dos locais

Os navegadores se recusam a chamar um servidor local a menos que esse servidor permita explicitamente requisições da extensão. Isso atrapalha especificamente as configurações locais (provedores externos já permitem).

• Ollama: inicie-o com o acesso pelo navegador habilitado:

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

  "port 11434 already in use"? O app em segundo plano do Ollama já está rodando. Encerre-o primeiro (barra de menus no Mac, bandeja do sistema no Windows) e então execute o comando acima.

• LM Studio: na aba Developer / servidor local, ative o Enable CORS antes de iniciar o servidor.

Mais uma sutileza: se localhost não conectar, tente 127.0.0.1 (ou o contrário). Em alguns sistemas eles não são resolvidos da mesma forma.

Erro #7: o nome do modelo precisa bater exatamente

Uma vez conectado, o nome do modelo que você seleciona precisa bater com o que o provedor espera — exatamente, incluindo maiúsculas e minúsculas. Isso pega as pessoas em provedores que não listam modelos automaticamente, ou que usam nomenclaturas incomuns:

• Poe usa nomes de bots no estilo de exibição, como Claude-Sonnet-4.6 e GPT-5.4 — copie-os exatamente como aparecem no Poe.
• z.ai usa ids como glm-4.6 e glm-5.
• Together AI usa ids com namespace: meta-llama/Llama-3.3-70B-Instruct-Turbo, deepseek-ai/DeepSeek-V3.
• Fireworks usa um id de caminho completo: accounts/fireworks/models/llama-v3p3-70b-instruct.

Se a conexão funciona mas você recebe "model not found", quase sempre é um erro de digitação no nome ou maiúsculas/minúsculas erradas. Quando o SurfMind consegue listar modelos automaticamente via Models URL, escolha da lista em vez de digitar.

Referência rápida: modelos locais

Todos estes rodam na sua própria máquina. Abra a aba Custom do SurfMind → Add Custom Models, escolha o preset correspondente (o Ollama tem o seu próprio; o resto usa o preset genérico OpenAI-compatible) e defina o API Key Header como None. Os nomes dos provedores levam à documentação de configuração de cada ferramenta.

Ollama

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

LM Studio

• API URL: http://localhost:1234/v1/chat/completions
• Models URL: http://localhost:1234/v1/models
• API key: qualquer valor não vazio (ex.: lm-studio)

Jan

• API URL: http://localhost:1337/v1/chat/completions
• Models URL: http://localhost:1337/v1/models
• API key: nenhuma (ou sua key do Jan)

llama.cpp

• API URL: http://localhost:8080/v1/chat/completions
• Models URL: http://localhost:8080/v1/models
• API key: nenhuma (a menos que você o tenha iniciado com --api-key)

vLLM

• API URL: http://localhost:8000/v1/chat/completions
• Models URL: http://localhost:8000/v1/models
• API key: sua --api-key se você definiu uma

LocalAI

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

Não esqueça da etapa de CORS (Erro #6) para qualquer um destes. Para o Ollama especificamente, o passo a passo completo com capturas de tela está no nosso guia do Ollama, e se você estiver decidindo entre os dois primeiros, veja Ollama vs LM Studio.

Referência rápida: provedores de IA populares

Todos estes provedores de nuvem falam a API compatível com OpenAI. Use o preset genérico OpenAI-compatible, defina o API Key Header como Authorization (todos eles usam tokens Bearer) e cole sua key. Os nomes dos provedores levam à documentação da API de cada provedor.

Poe — uma única key para centenas de modelos (Claude, GPT, Gemini, Llama…), cobrados contra os pontos da sua assinatura do Poe. Os nomes dos modelos são nomes de bots no estilo de exibição — copie-os exatamente como mostrados no Poe (ex.: Claude-Sonnet-4.6, GPT-5.4). Key em poe.com → Settings → API key.

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

CanopyWave — provedor de nuvem com GPU que serve modelos abertos (Kimi, DeepSeek, Llama, Qwen). Key no dashboard da CanopyWave.

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

z.ai (GLM) — os modelos GLM da Zhipu (glm-4.6, glm-5). Atenção: a z.ai também publica um endpoint separado de Coding Plan (https://api.z.ai/api/coding/paas/v4) e um endpoint de PaaS (https://api.z.ai/api/paas/v4) — use o compatível com OpenAI abaixo e não adicione um /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 — grande catálogo de modelos abertos. Os model ids são longos (meta-llama/Llama-3.3-70B-Instruct-Turbo) — copie-os exatamente da página de modelos da Together.

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

Groq — inferência extremamente rápida. Pegadinha: o caminho é /openai/v1, não apenas /v1.

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

DeepSeek — os modelos atuais são deepseek-v4-flash e deepseek-v4-pro (os aliases mais antigos deepseek-chat / deepseek-reasoner estão sendo descontinuados — confira a documentação da DeepSeek para os mais recentes). O /v1 é opcional; a DeepSeek aceita a URL com ou sem ele.

• 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. Compatível com OpenAI padrão.

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

Fireworks AI — pegadinha: o caminho é /inference/v1, não /v1. Os model ids têm a forma 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) — modelos Grok (grok-4, etc.). Compatível com OpenAI padrão.

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

AWS Bedrock — o Bedrock agora tem um endpoint compatível com OpenAI, mas com duas pegadinhas: o host é específico de região (ex.: us-west-2) e o caminho é /openai/v1. Você precisa usar uma Bedrock API key (um bearer token que você gera no console) — não suas chaves de acesso normais da AWS/SigV4. Os model ids têm a forma openai.gpt-oss-120b-1:0.

• API URL: https://bedrock-runtime.<region>.amazonaws.com/openai/v1/chat/completions
• Models URL: deixe em branco — informe o model id depois

Ainda não conecta? Triagem final

Percorra esta lista:

1. Abra o host do API URL no seu navegador. Servidor local não carregando → ele não está rodando, ou a porta está errada.
2. Releia o caminho. Ollama → /api/chat. Todos os outros → /v1/chat/completions (ou o caminho especial do provedor, da tabela).
3. Confirme que você colou o endpoint completo, não a base, e que não há /v1 duplicado ou barra no final.
4. 401? É a key ou o cabeçalho. Cabeçalho = Authorization, key sem espaços, sem prefixo Bearer.
5. 404 "model not found"? A conexão está ok — corrija o nome do modelo (maiúsculas/minúsculas exatas).
6. Modelo local, navegador bloqueado? Habilite o CORS (OLLAMA_ORIGINS="*" ou o toggle do LM Studio) e tente 127.0.0.1 vs localhost.

Essa sequência resolve a esmagadora maioria das configurações.

Ainda precisa de ajuda?

Se você já passou pelo checklist e seu provedor ainda não conecta, mande um e-mail para wave@surfmind.ai com o provedor que você está tentando e o erro que aparece. Vamos ajudar você a conectar.

---

Conseguiu conectar? Abra o SurfMind na próxima página que você ia ler e coloque seu modelo para trabalhar.

Obter o SurfMind →