Executando LLMs Locais com Cursor: Guia Completo de Configuração
Se você trabalha com código proprietário, lida com dados sensíveis ou simplesmente não quer que seus trechos de código saiam da sua máquina, executar um LLM local com Cursor é uma excelente opção. Este guia aborda a configuração prática para Ollama e LM Studio, além dos compromissos que você deve conhecer antes de fazer a mudança.
Por que se Preocupar com Modelos Locais?
Três motivos aparecem repetidamente na comunidade:
- Privacidade: Seu código nunca sai da sua rede local. Sem API de terceiros, sem política de retenção de dados para interpretar.
- Custo: Após os custos de hardware, a inferência é gratuita. Sem cobrança por token, sem picos de uso.
- Acesso offline: Funciona em aviões, em redes corporativas restritas ou em qualquer lugar sem internet.
Modelos locais se destacam na geração de boilerplate, refatorações simples e perguntas rápidas sobre sua própria base de código. Você não precisa do GPT-4 para tudo.
Backends de Modelos Locais Suportados
O Cursor não vem com suporte nativo a modelos locais da mesma forma que suporta as APIs da OpenAI ou Anthropic. Em vez disso, você aponta o Cursor para um servidor local que expõe uma API compatível com OpenAI. As três opções mais comuns:
| Backend | Melhor Para | Complexidade de Configuração |
|---|---|---|
| Ollama | Início rápido, gerenciamento de modelos | Baixa |
| LM Studio | Amantes de GUI, usuários Windows/Mac | Baixa |
| llama.cpp | Controle máximo, overhead mínimo | Média |
Este guia foca em Ollama e LM Studio porque são o que a maioria dos desenvolvedores realmente usa no dia a dia.
Ollama + Cursor: Passo a Passo
1. Instalar o Ollama
Baixe em ollama.com e instale. Ele roda como um serviço em segundo plano no macOS, Linux e Windows.
Verifique se está funcionando:
ollama --version
2. Baixar um Modelo
Comece com um modelo capaz de lidar com código. Os favoritos da comunidade são:
codellama:7b-codeoucodellama:13b-code— rápido, decente para tarefas simplesdeepseek-coder:6.7b— forte em autocompletar códigoqwen2.5-coder:7bou14b— bom equilíbrio entre velocidade e qualidade
ollama pull deepseek-coder:6.7b
3. Iniciar o Servidor Compatível com OpenAI
O Ollama expõe uma API compatível com OpenAI em localhost:11434. Mantenha-o em execução:
ollama serve
Ou deixe o serviço em segundo plano cuidar disso.
4. Configurar o Cursor
Abra as Configurações do Cursor (Ctrl/Cmd + ,) e navegue até:
Settings > Models > OpenAI API Key
Defina a URL base como:
http://localhost:11434/v1
Deixe o campo de chave de API em branco ou insira qualquer string fictícia (algumas versões exigem um valor não vazio).
Selecione o nome do modelo que corresponde ao que você baixou. Por exemplo:
deepseek-coder:6.7b
O Cursor envia solicitações no formato de chat completions da OpenAI. O endpoint /v1 do Ollama traduz isso automaticamente. Você não precisa de um proxy.
5. Testar
Abra um arquivo e pressione Ctrl/Cmd + L para abrir o painel de chat. Faça uma pergunta simples:
Write a Python function that reverses a string without using slicing.
Se você receber uma resposta, está conectado. Se travar, verifique se ollama serve está rodando e se o nome do modelo corresponde exatamente.
LM Studio + Cursor: Passo a Passo
O LM Studio é a melhor escolha se você quer uma interface gráfica para baixar e alternar entre modelos.
1. Instalar o LM Studio
Baixe em lmstudio.ai. Disponível para macOS, Windows e Linux.
2. Baixar um Modelo
Abra o LM Studio, vá para a aba Discover e pesquise por um modelo de código. Boas opções:
TheBloke/CodeLlama-7B-Instruct-GGUFTheBloke/DeepSeek-Coder-6.7B-Instruct-GGUFQwen/Qwen2.5-Coder-7B-Instruct-GGUF
Baixe a quantização Q4_K_M ou Q5_K_M para um equilíbrio entre tamanho e qualidade.
3. Iniciar o Servidor Local
No LM Studio, vá para a aba Local Server à esquerda. Carregue seu modelo e clique em Start Server.
Por padrão, ele roda em:
http://localhost:1234/v1
4. Configurar o Cursor
Mesmo processo do Ollama. Nas Configurações do Cursor > Models > OpenAI API Key, defina:
http://localhost:1234/v1
O campo de nome do modelo pode ser deixado como local-model ou qualquer placeholder que o LM Studio espere. O LM Studio ignora o nome do modelo e usa o que está atualmente carregado.
5. Verificar
Execute o mesmo prompt de teste. Os logs do servidor do LM Studio mostram as solicitações recebidas, o que é útil para depuração.
O que Funciona e o que Não Funciona
Modelos locais não são um substituto direto para o Claude 3.5 Sonnet ou GPT-4o. Aqui está a análise honesta:
| Tarefa | Local 7B-13B | Nuvem (Claude/GPT-4) |
|---|---|---|
| Refatorações simples | Bom | Excelente |
| Geração de boilerplate | Bom | Excelente |
| Decisões de arquitetura complexas | Fraco | Excelente |
| Entendimento de grandes bases de código | Fraco | Excelente |
| Edições multi-arquivo | Fraco | Bom |
| Velocidade (com GPU) | Rápida | Dependente de rede |
| Velocidade (apenas CPU) | Lenta | Dependente de rede |
Executar um modelo de 13B na CPU pode levar de 10 a 30 segundos por resposta. Uma GPU moderna (RTX 3060 ou melhor) reduz isso para 1 a 3 segundos. Gerencie suas expectativas.
Estratégia Híbrida: A Abordagem Prática
A maioria dos desenvolvedores que persistem com modelos locais usa um fluxo de trabalho híbrido em vez de adotar totalmente:
- Modelo local para tarefas rápidas e seguras: correções de lint, renomeação, regex simples, explicar uma função.
- Modelo em nuvem para trabalho pesado: projetar novos recursos, depurar problemas difíceis, refatoração entre arquivos.
- Alternar com base no projeto: código aberto ou não sensível → nuvem; proprietário ou regulado → local.
O Cursor facilita isso porque você pode mudar o modelo nas configurações sem reiniciar o IDE. Alguns usuários mantêm duas janelas do Cursor abertas — uma apontada para local, outra para nuvem — embora isso seja mais uma solução alternativa do que um recurso.
Se você tem um Mac com Apple Silicon, o Ollama aproveita bem o Neural Engine. Um MacBook Pro M3 Pro pode executar um modelo de 13B em velocidades utilizáveis sem drenar a bateria como uma GPU dedicada faria.
Solução de Problemas
Erros "Connection refused"
- Verifique se o servidor está rodando (
ollama serveou aba do servidor do LM Studio). - Verifique a porta: Ollama usa 11434, LM Studio usa 1234.
- Verifique seu firewall ou proxy corporativo.
Respostas lentas
- Use um modelo menor ou uma quantização mais alta (Q4 em vez de Q5).
- Certifique-se de que sua GPU está sendo usada. Os logs do Ollama mostram
GPUouCPUno carregamento. - Feche outros aplicativos intensivos em GPU.
Saídas sem sentido
- O nome do modelo pode não corresponder. O Ollama é exigente com nomes exatos.
- Alguns modelos precisam de um formato de prompt específico. Modelos instruct funcionam melhor que modelos base para chat.
Cursor ignora a configuração local
- Certifique-se de que está substituindo a URL base da OpenAI, não apenas adicionando um modelo personalizado.
- Reinicie o Cursor após alterar a URL base.
Considerações Finais
LLMs locais com Cursor são viáveis hoje para um subconjunto de tarefas. Eles não são tão capazes quanto modelos em nuvem, mas para desenvolvedores conscientes com a privacidade ou aqueles que trabalham em ambientes restritos, geralmente são suficientemente bons. Comece com o Ollama se quiser velocidade de configuração, ou LM Studio se preferir uma GUI. Espere iterar na escolha do modelo e no fluxo de trabalho antes de encontrar o que funciona para seus projetos.