Windsurf如何配置本地大模型端口,如Ollama?

文章导读
把Windsurf接到本地Ollama模型上,本质上只需要让Windsurf的模型请求指向Ollama对外提供的OpenAI兼容接口。看起来是一行配置,实际要处理的问题散落在服务是否监听、接口路径是否匹配、模型名是否正确几个环节里。按顺序处理,能省去不少来回试探。
📋 目录
  1. 一 先确认Ollama健康状态
  2. 二 在Windsurf配置里填什么
  3. 三 用curl替Windsurf探路
  4. 四 监听边界与远程调用
  5. 五 连接失败时的检查顺序
A A

把Windsurf接到本地Ollama模型上,本质上只需要让Windsurf的模型请求指向Ollama对外提供的OpenAI兼容接口。看起来是一行配置,实际要处理的问题散落在服务是否监听、接口路径是否匹配、模型名是否正确几个环节里。按顺序处理,能省去不少来回试探。

在使用Windsurf接入Ollama前,先确认本地模型服务是否在监听预期端口。以Ollama为例,默认REST API在11434端口提供,可通过访问 http://127.0.0.1:11434/health 判断服务是否健康,如果看到类似‘Ollama is running’的返回内容则说明服务正常。很多配置失败案例源于模型服务未启动、端口被占用或监听地址被改过,因此这一步不能跳过。还要留意的是,Windsurf识别的是OpenAI兼容的接口路径,所以需要确认Ollama的API版本包含 /v1 端点,而不是直接指向根路径。

先确认Ollama健康状态

在使用Windsurf接入Ollama前,先确认本地模型服务是否在监听预期端口。以Ollama为例,默认REST API在11434端口提供,可通过访问 http://127.0.0.1:11434/health 判断服务是否健康,如果看到类似“Ollama is running”的返回内容则说明服务正常。很多配置失败案例源于模型服务未启动、端口被占用或监听地址被改过,因此这一步不能跳过。还要留意的是,Windsurf识别的是OpenAI兼容的接口路径,所以需要确认Ollama的API版本包含 /v1 端点,而不是直接指向根路径。

这一步建议在终端里完成,不要直接拿Windsurf试错。如果 /health 没有响应,先把Ollama服务拉起来,看启动日志里有没有端口占用或监听地址被改动的记录;端口正常了再处理Windsurf侧。

在Windsurf配置里填什么

在Windsurf的模型设置中,选择自定义或OpenAI兼容选项,把Base URL填写为 http://127.0.0.1:11434/v1,API Key填入任意非空字符串,因为本地服务通常不校验密钥。模型名称务必与Ollama中已经下载的模型完全一致,例如 llama3、qwen2.5 等,如果记不准,就先到终端执行 ollama list 查看。这里有个常见坑:地址不要写 localhost,因为某些环境会把 localhost 解析成 IPv6 的 ::1,而 Ollama 默认只监听 IPv4,导致连接被拒绝,改为 127.0.0.1 往往能立即解决问题。

Windsurf如何配置本地大模型端口,如Ollama?

填完之后,记得在聊天窗口的模型选择器里把当前模型切到刚添加的本地模型。新增配置不会自动替换当前会话正在使用的模型,继续沿用之前的远程模型,配置看起来像没生效。

用curl替Windsurf探路

配置完成后,建议先在终端用 curl 模拟一个对话请求,向 /v1/chat/completions 发送最小JSON数据,确认返回结果再做界面测试。如果收到连接拒绝或超时,说明端口未监听或有防火墙拦截;如果返回404,说明当前Ollama版本不支持该路径,需要检查兼容层的正确路径;如果返回模型相关错误,则多半是模型名称拼写有误。在Windsurf里第一次提问时,如果立刻看到“model not found”之类的提示,回去执行 ollama list,用输出里的准确名称重填即可。

curl http://127.0.0.1:11434/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"llama3","messages":[{"role":"user","content":"hello"}]}'

把命令里的模型名换成实际存在的名称。如果返回包含回复内容的JSON,说明Ollama这一侧已通,剩下的问题多半在Windsurf的Base URL或模型选择上。

Windsurf如何配置本地大模型端口,如Ollama?

监听边界与远程调用

Ollama默认只监听127.0.0.1,这个边界建议保留。为方便另一台电脑调用,把OLLAMA_HOST改成0.0.0.0是常见做法,但这会让整段局域网都能直接请求模型接口,没有认证也没有加密,既消耗本机算力,也可能暴露对话内容。远程调用场景下,更稳妥的做法是让Ollama继续监听回环地址,在远程机器上执行 ssh -L 11434:127.0.0.1:11434 user@主机地址,登录后本地Windsurf仍然填127.0.0.1:11434/v1即可。

改过OLLAMA_HOST之后,用 lsof -i:11434 看实际监听地址。如果服务没起来或监听地址不在预期范围,后面Windsurf怎么调都连不上。要回滚也很简单,把环境变量恢复为默认值再重启Ollama。

连接失败时的检查顺序

如果curl返回连接拒绝,先确认Shell环境里是否设置过OLLAMA_HOST,这个变量可能把服务带到非预期端口。再用 lsof -i:11434 看监听进程与地址。如果端口正常但Windsurf仍报错,检查Base URL末尾是否被自动补了斜杠,有些客户端会在后续拼接时产生类似/v1/v1的重复路径。这几步之后问题仍未解决,再看Windsurf实际发出的请求日志,日志里记录了完整的请求地址和HTTP状态码,能直接看出卡在哪一段。

多数连接问题都能落到几个环节上:服务是否监听、路径是否指向/v1、模型名是否一致、监听地址是否和填写地址匹配。按顺序排查,报错信息通常能直接指出问题位置。