最近一个月我基本把日常的代码补全、文档总结、SQL 改写都迁到了本地。起因不算复杂手上有一批项目代码没法传到云端 API又不想放弃 AI 辅助带来的效率于是开始折腾 Ollama 本地大模型部署。整个链条从下载安装、拉取模型到接入 IDE 补全、搭 Web 界面再用 API 把模型暴露给业务系统我完整跑了一遍。坦白说链路比想象中短坑却比想象中多。这篇东西不是官方文档的复述是我实际踩出来的操作路径和排查思路适合准备入坑本地模型、或者已经在用但被各种细节卡住的朋友。1. 为什么我最终选了 Ollama本地模型该解决什么问题1.1 它把“跑大模型”变成了三行命令其实跑本地大模型的底层方案一直存在llama.cpp、transformers 都能做。但问题在于要把一个模型真正跑起来你得先搞定量化格式、显存规划、推理后端、tokenizer还要自己写 HTTP 服务去调用。Ollama 做的就是把这些全部封装起来一条命令装服务一条命令拉模型一条命令跑对话然后用一个 11434 端口的 REST API 统一暴露给外部。对绝大多数开发者来说这个封装的价值非常大。它把“用大模型”的门槛从“编译推理引擎”降到了“会用命令行”而且对硬件的要求也没那么苛刻。我手头一台 32G 内存、没有独显的笔记本照样能跑 7B 和 8B 量级的量化模型速度虽然不能跟 GPU 比但写写摘要、改改文案完全够用。1.2 和本地部署、云 API 两条路的对比先说结论选择 Ollama本质上是在“完全自己造轮子”和“完全依赖云端”之间取了一个中间点。与云 API 比数据不出本机、离线可用、调用量不按 token 计费。代价是硬件成本你自己出而且模型能力通常不如云端最新旗舰。云端 DeepSeek API、通义 API 这类服务适合算力敏感、需要超大模型的生产链路调用方式都是 HTTP JSON从云端迁移到本地 Ollama 的成本其实很低改个 base_url 的事。与 llama.cpp 直接部署比Ollama 牺牲了一些底层可定制性。你想魔改采样器、深度优化某个量化算子、做细粒度的显存分配那还是直接上 llama.cpp 更顺手。但如果只是想把模型“用起来”没必要自己跟 CMake 和 GGUF 家族较劲。与 LM Studio 比LM Studio 的图形界面更友好适合纯探索、想点点鼠标就能聊上的人Ollama 的命令行和 API 设计对开发者更友好更容易工程化集成。与 AnythingLLM、Dify 这类应用层比Ollama 定位更底层它自己不做复杂前端而是把 Web、IDE、业务系统的接入方式全部交给生态去解决。所以你会看到 Open WebUI、Continue 这些工具都天然支持 Ollama组合起来非常顺。1.3 什么情况下别选 Ollama如果对权限隔离、多用户计费、模型版本灰度有严格需求Ollama 会比较吃力。它默认是一个单机服务没有内置用户体系和审计。团队级应用一般得在 Ollama 前面再套一层网关做鉴权和限流这个后面讲 API 接入时我会提。另外如果你的工作流重度依赖 GPU 算子定制或者要用 LoRA 做多模型热切换也要先评估清楚再动手。Ollama 对 LoRA 的支持有但远没有专用推理框架成熟。2. 安装与模型下载最容易被“下载慢”卡住的环节2.1 安装包获取官方渠道和提速方式Ollama 的安装本身不复杂Windows 下直接下载 OllamaSetup.exe 双击macOS 下载 Ollama-darwin.zipLinux 用官方安装脚本curl -fsSL https://ollama.com/install.sh | sh装完先验证版本ollama --version版本号出来说明服务本体装好了。这里要注意Windows 版安装完会自动在后台启动服务托盘区能看到 ollama 的图标Linux 版安装脚本会注册一个 systemd 服务开机自动启动。下载慢是大部分人遇到的第一个坎。官方安装包托管在 GitHub Releases 上某些网络环境下确实很慢。我的实际建议是安装包下载慢可以找国内维护的镜像加速地址原理上就是把 GitHub Release 的下载链路换成 CDN 中转文件名和校验值不变。如果命令行安装脚本执行失败多半是脚本下载超时换成手动下载安装包解压后配置 PATH一样能用。安装完成后模型是单独从 registry 拉取的和安装包是两条通道不要混在一起排查。2.2 拉取模型的命令与推荐模型安装完成后的第一件事是拉模型。命令就一行ollama pull qwen2.5:7bpull 后面跟的是“模型名:标签”标签一般代表参数规模或量化方式不写默认拉 latest。第一次用建议直接抄作业我整理了一张常用表模型大概体积适用场景硬件建议qwen2.5:1.5b约 1.1G低配机尝鲜、简单分类纯 CPU 可跑qwen2.5:7b约 4.7G通用对话、知识问答、文本改写8G 显存或 16G 内存qwen2.5-coder:7b约 4.7G代码补全、代码解释8G 显存qwen2.5-coder:14b约 9GIDE 代码补全、生成质量要求更高12G 以上显存deepseek-r1:7b约 4.7G推理、逻辑分析、带思考过程8G 显存llama3.1:8b约 4.9G英文能力较强通用助手8G 显存我个人最常用的是 qwen2.5:7b 和 qwen2.5-coder:14b前者管日常问答后者管代码场景。先别贪大先把小尺寸跑通再根据自己的硬件逐步升级。2.3 下载中断、超时的处理思路模型拉取到一半断掉是常事不用慌。重新执行一次同样的 pull 命令已经下载完成的层会被跳过没有断点续传的进度条那么顺滑但比从头再来好很多。如果反复卡在同一个地方我试过最有效的办法是从模型文件入手绕开官方 registry 下载链路。具体做法是找到对应的 GGUF 格式模型文件放到本地后通过 Modelfile 导入vi ModelfileModelfile 内容FROM ./qwen2.5-7b-instruct-q4_k_m.gguf然后创建本地模型ollama create my-qwen -f Modelfile这样模型文件完全由你掌控不再依赖网络拉取。缺点是需要自己找靠谱的 GGUF 来源并且要搞清楚量化格式和参数量比直接 pull 多一步功课。还有个常见的误解网上有些教程让你设置 OLLAMA_BASE_URL 来给 Ollama “换镜像源”但 OLLAMA_BASE_URL 这个环境变量主要用于 Open WebUI 这类前端作用是告诉前端“Ollama 服务在哪里”并不能改变 Ollama 本体拉取模型时访问的 registry。想真正提速要么改善网络环境要么就走 Modelfile 本地导入这条路。3. 摸清 Ollama 的服务机制端口、模型存储与常用管理命令3.1 本地服务长什么样Ollama 安装完以后后台其实跑了一个本地 HTTP 服务默认监听 127.0.0.1:11434。你可以直接拿 curl 验证curl http://localhost:11434/api/tags返回一长串 JSON里面有当前已经安装的模型列表说明服务正常。手动启动服务的命令是ollama serve这个命令在 Linux 上没有 systemd 的情况下或者你手动改了配置后重启服务时会用到。Windows 上一般不用管托盘进程会拉起服务。3.2 必会的模型管理命令我平时用到的命令就这几个记熟基本够用ollama list列出本地已有模型含大小和修改时间ollama ps查看当前加载在内存里的模型以及它占用的显存/内存ollama show 模型名查看模型详情包括参数规模、上下文长度、嵌入能力ollama run 模型名进入交互式对话ollama cp 模型名 新名字复制模型改配置时会用ollama rm 模型名删除模型省磁盘空间ollama stop 模型名把模型从内存里卸载ollama ps容易被忽略但它非常有用。比如你感觉电脑变卡了先看一眼是不是有模型一直驻留内存再用ollama stop把它踢出去立刻清爽。3.3 几个关键环境变量真正接入 IDE、Web 和 API 之前得懂几个环境变量否则后面配置会一头雾水。环境变量作用我常用的值OLLAMA_HOST服务监听地址默认 127.0.0.1局域网访问要改成 0.0.0.00.0.0.0OLLAMA_MODELS模型文件存放目录默认~/.ollama/models默认OLLAMA_KEEP_ALIVE模型加载后在内存驻留的时间默认 5m10mOLLAMA_NUM_PARALLEL允许并发处理的请求数4OLLAMA_MAX_LOADED_MODELS最多同时加载几个模型默认 1默认Windows 上设置环境变量后需要重启 Ollama 进程才能生效。Linux 上改 systemd 配置的话一般是编辑/etc/systemd/system/ollama.service里的 Environment 行然后systemctl daemon-reload systemctl restart ollama。理解这几个变量的意义在于决定你后续接 IDE、Web、API 时是只能本机访问还是可以给局域网里的其他机器用以及并发上来之后会不会被内存打爆。4. 接入 IDE从 Continue 到 Antigravity、Claude Code4.1 ContinueVS Code 与 JetBrains 通用插件我最早接入的是 VS Code 里的 Continue 插件。它是目前对 Ollama 支持最顺滑的 IDE AI 插件之一不需要写一行代码界面里直接选 Provider 就行。具体路径是安装 Continue 扩展打开左侧的 Continue 面板在模型配置里选择 Chat Model 的 Provider 为 OllamaModel 填你已经 pull 下来的模型名比如qwen2.5-coder:14b。它底层会请求http://localhost:11434如果 Ollama 跑在别的机器上也可以在配置里改成对应地址。Continue 里有两个配置要分开看Chat 模型负责对话、代码解释、Refactor对延迟要求相对低质量优先可以选大一点的模型。Autocomplete 模型负责你打字时的代码补全对延迟极度敏感建议选 7B 左右的专用代码模型qwen2.5-coder:7b这类。我把两个模型分开用补全走小模型对话走大模型体验平衡得最好。配置文件的详细项比较多但折腾过一次就有感觉了官方文档的 Sample 配置可以直接抄。4.2 Antigravity IDE 的本地模型配置思路Antigravity IDE 最近讨论度很高很多人卡在登录上。我的理解是这类云端 AI IDE 把账号体系和 AI 能力绑得很紧对部分用户来说反而成了门槛。如果你只是想用它当编辑器同时把 AI 请求走本地模型思路和上面的 OpenAI 兼容端点一样在设置里找到自定义 OpenAI 兼容服务的入口把 Base URL 改成http://localhost:11434/v1模型名填你本地已有的模型API Key 随便填一个占位符Ollama 不校验 Key这样 AI 对话请求会打到本地模型绕开它对云端能力的依赖。当然不保证每个版本都保留了这个自定义入口但“找 OpenAI 兼容配置”这个方向是对的。4.3 cc-switch 把 Claude Code 指向 OllamaClaude Code 官方默认只接 Anthropic 的 API但开发者社区做了 cc-switch 这个小工具专门用来切换 Claude Code 的 API 供应商。它本质上是个配置管理工具你可以在里面新增一个供应商把 API 地址指向 OllamaAPI 地址http://localhost:11434/v1模型名qwen2.5-coder:14b这里我得泼一盆冷水Claude Code 的核心能力是自主调用工具它依赖模型很好的指令遵循能力。用 7B 量级的本地模型跑 Claude Code做简单问答没问题但工具调用经常不按格式输出多轮下来就乱了。我试下来至少得 14B 起步体验才算能用。想清楚你的场景是“体验本地模型写代码”还是“真正替代云端代码助手”期望值完全不同。4.4 上下文窗口不够时的调整IDE 接入最常见的报错是上下文长度超限比如把一大段项目代码丢进去模型直接报 context length 超了。默认情况下Ollama 加载模型的上下文窗口可能远小于模型本身的上限。调整思路有三种请求时动态指定num_ctx在 Continue 这类客户端里通常有 context 大小配置项。用 Modelfile 固化参数创建一个长期使用的变体FROM qwen2.5-coder:14b PARAMETER num_ctx 16384ollama create coder-16k -f Modelfile之后直接用coder-16k这个模型上下文窗口就有 16k。注意 context 开得越大KV Cache 占的内存越多显存不够就会吃紧甚至崩溃量力而行。5. 接入 Web把本地模型做成团队可用的服务5.1 Open WebUI最省事的网页界面本地模型跑起来后直接在终端里聊天远不够用。Open WebUI 是目前最成熟的 Web 前端界面长得像 ChatGPT支持多用户、历史记录、附件上传、模型切换一个容器就搞定。如果你装了 Docker最省事的启动命令是docker run -d \ -p 3000:8080 \ -v open-webui:/app/backend/data \ --name open-webui \ --restart always \ ghcr.io/open-webui/open-webui:main启动后打开http://localhost:3000第一次访问会要求注册一个管理员账号这个账号只存在 Open WebUI 自己的用户系统里和 Ollama 无关。5.2 免 Docker 的部署方式没装 Docker 的机器可以直接用 Python 装pip install open-webui open-webui serve同样默认 8080 端口。它在启动时会自动去连接本地的http://localhost:11434如果你的 Ollama 跑在别的机器上需要设置环境变量export OLLAMA_BASE_URLhttp://你的Ollama地址:11434这里 OLLAMA_BASE_URL 才真正派上用场它是 Open WebUI 访问 Ollama 服务的地址跟 Ollama 本体拉模型的下载地址完全是两码事。5.3 局域网访问与多人使用想让局域网里的同事也能用先确保 Ollama 监听在非回环地址设置OLLAMA_HOST0.0.0.0再让 Open WebUI 能被局域网访问。Docker 方式下需要把端口映射出来同时注意防火墙放行对应端口。多人使用时的体验主要受硬件限制。一台 32G 内存的机器跑 7B 模型同时应付三四个人没问题再往上就开始排队了。我这里强烈建议一旦服务暴露到局域网前面一定要加访问控制。Open WebUI 自带用户登录体系不要图省事把它裸奔到公网。模型服务一旦开放任何人都能调用这个问题比模型本身的内容合规更实际。6. 接入 API用代码调用本地模型6.1 原生 APIgenerate、chat、embedOllama 原生提供几个核心端点我先把最常用的列出来POST /api/generate单轮文本生成传 prompt 直接返回回答POST /api/chat多轮对话传 messages 数组POST /api/embed生成向量表示给 RAG 场景用GET /api/tags列出已安装模型命令行测试 chat 接口curl http://localhost:11434/api/chat \ -H Content-Type: application/json \ -d { model: qwen2.5:7b, messages: [ {role: user, content: 用一句话解释什么是反向代理} ], stream: false }注意stream字段。不写或者写 true返回的是流式 JSON可以做成打字机效果写 false 则一次性返回完整结果调试时建议先关流。6.2 OpenAI 兼容端点更通用的接入方式Ollama 提供了 OpenAI 兼容端点地址是http://localhost:11434/v1这意味着所有为 OpenAI API 写的 SDK 和工具只要把 base_url 改一下就能直接连本地模型。模型名不再是 gpt-4o而是你本地拉取的模型名。用 curl 测一下curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5:7b, messages: [ {role: user, content: 写一段Python读取CSV的代码} ] }这个端点是生态接力的关键。Continue、Open WebUI、Claude Code 的各种替代方案几乎都是靠这个兼容端点把 Ollama 接进去的。6.3 Python 与 Node.js 示例Python 用 openai 库直接连本地模型代码和调云端 API 几乎一样from openai import OpenAI client OpenAI( api_keyollama, # 本地不校验随便填 base_urlhttp://localhost:11434/v1 ) resp client.chat.completions.create( modelqwen2.5:7b, messages[ {role: user, content: 用三句话总结这篇文章的要点} ] ) print(resp.choices[0].message.content)Node.js 同样用 openai 官方 SDKimport OpenAI from openai; const client new OpenAI({ apiKey: ollama, baseURL: http://localhost:11434/v1, }); const result await client.chat.completions.create({ model: qwen2.5:7b, messages: [{ role: user, content: 解释一下什么是JWT }], }); console.log(result.choices[0].message.content);这套代码接云端 DeepSeek API 时只需要把 base_url 换成https://api.deepseek.com把模型名换成deepseek-chat迁移成本几乎为零。这也是我推荐大家在工程里优先走 OpenAI 兼容端点而不是原生 API 的原因。6.4 常见 400 错误模型名与 context length 排查接入 API 最常见的报错有两种。第一种是模型名对不上返回model xxx not found。这个最简单先ollama list看本地到底叫什么名字URL 和请求体里的 model 字段要和列表完全一致标签也不能省。第二种是上下文超长类似400 this models maximum context length is ...。报错信息会告诉你模型最大上下文长度但实际使用中Ollama 加载时的默认 context 可能小于这个值。除了在请求里带参数调整外需要注意每次修改后重新请求别在旧连接里反复重试。服务没启动时连接会被拒先curl http://localhost:11434/api/tags看通不通。如果 Ollama 被改过监听地址记得代码里也要同步改。最后忠告一句生产环境里别把本地模型服务直接暴露给公网前面加一层网关做 token 鉴权和限流才是个稳妥的做法。7. 真实跑起来之后的几个坑与心得7.1 WSL2 与 Windows 网络问题很多人把 Ollama 装进 WSL2 的 Linux 环境里然后在 Windows 侧访问遇到连不上的问题。新版 WSL2 对 localhost 有自动转发大多数情况下能从 Windows 直接访问 WSL 里的 11434。但如果不行检查两件事WSL 里的 Ollama 是否监听在0.0.0.0以及 Windows 防火墙是否放行了端口。还有一点WSL2 的 IP 会随重启变化别把固定 IP 写死在配置里。7.2 显存不足、加载慢、并发低显存不够时模型会退到 CPU 推理速度可能慢到没法用甚至直接加载失败。我的经验是一步一步降级先试 7B 的 q4 量化版本再不行换 1.5B显存有富余时再考虑 14B。模型体积和质量的平衡点永远是根据你的硬件实测出来的不是看网上的评测。另外不要同时加载多个大模型默认情况下 Ollama 只会加载一个模型切换模型时会有明显的加载等待这个属于正常现象不是故障。7.3 本地部署不等于没人管安全边界顺带回答一个被问过很多次的问题大模型本地部署之后就完全自由了吗不是。模型在训练阶段就已经做了安全对齐本地运行不会自动解除这些限制你在代码里看到的回复边界和云端版本基本一致。作为使用者更要管好自己的服务不要把 Ollama 随意暴露到公网也不要拿本地部署这个理由去做任何越界的事情。从工程角度说开放网络端口前先问自己一句这服务真的需要所有网段都能访问吗7.4 一个值得养成的排查习惯跑这套东西遇到问题不要瞎猜按顺序排查三件事先curl http://localhost:11434/api/tags确认服务活没活再看ollama ps确认模型到底加载没有最后才去翻日志和配置。绝大多数问题都出在这三层之间服务没起、模型没拉、配置地址不对占掉了我遇到的八成故障。我自己的一个习惯是所有接 Ollama 的客户端都优先走http://localhost:11434/v1这个 OpenAI 兼容端点这样切换云端和本地时只改一行 base_url。等哪天本地模型能力不够用了平滑切回云端 API不需要改任何业务代码这个便宜占得最值。