Ollama 本地大模型部署实战从下载到接入 IDE、Web 和 API——这句话看起来像教程标题其实更像是一段我反复走了几遍的路。最早我本地部署大模型停留在能在终端里唠嗑的水平然后用起来非常挣扎模型在终端里能回答编辑器里却调用不到想在浏览器里对着一堆文档提问不知道怎么搭想让脚本/服务通过 API 去访问本地模型又搞不明白接口区别。这篇我把整条链路整理成一份能直接落地的实操记录目标是让你拿到模型之后紧接着就能把编辑器、网页、API 三个入口都打通。1. 先理解整条链路从模型文件到你打开的那个聊天框很多人在本地部署这一步就劝退了不是因为命令难而是不知道自己在做什么。先花几分钟把链路拆清楚后面所有配置都是在处理这条链路上的连接问题。1.1 一个典型场景模型有了但用不起来假设你刚把qwen2.5:7b拉回本地在终端里跑了一下发现回答质量不错。然后你打开 VS Code装了一个 AI 插件想让它帮忙改代码却发现插件无论如何都连不上。或者你写了一个小网页想让用户通过浏览器和模型对话结果网页还是空的因为你根本不知道模型对外暴露了什么端口。我一开始也是这样。模型在终端里活蹦乱跳但一到真实应用场景就彻底不动了。问题不在模型本身而在于本地只有模型运行时还缺一个能被外部访问的服务层。终端里的ollama run只是它附带的一个对话界面真正的核心是后台那个常驻服务。理解这一点你就知道后面装 Open WebUI、配 IDE、调 API都是在跟后台服务说话而不是直接跟模型文件说话。1.2 Ollama 在这条链路里扮演的角色Ollama 不是一个模型它是一层模型运行时服务管理。它负责把模型文件加载进内存/显存它负责管理请求队列、上下文窗口、并发数量它默认监听127.0.0.1:11434对外提供 HTTP 接口它提供 OpenAI 兼容端点/v1/chat/completions方便你使用现成的 OpenAI SDK。所以你可以把它理解成本地的模型服务器。终端里的交互模式只是它的一个客户端而已。你要接入 IDE、Web、API本质上就是让 IDE、WebApp、业务代码都变成这个服务器的客户端。理解了这层关系后面再看到http://localhost:11434就不会觉得陌生。它是 Ollama 服务的默认地址所有客户端都要连到这里。2. 安装期最常踩的三个坑下载慢、装错盘、服务没起安装 Ollama 本身不难但国内环境下很多人卡在下载阶段。我见过不少同事折腾一天最后发现连安装包都没下完。这里把安装期的常见问题一次说清。2.1 官方下载慢的处理思路先说结论Ollama 的安装包和模型文件是两回事。安装包只有几百 MB能不能顺利下载取决于网络情况模型文件动辄几个 GB这个才是大户。如果你下载安装包很慢不要反复点同一个链接干等。更稳妥的做法是利用好现有的下载工具和镜像站资源。下载安装包时用带断点续传的下载工具不要用浏览器直接下载以免中断后从头再来模型文件的大头可以从国内可正常访问的开源模型社区拉取 GGUF 格式文件再通过 Ollama 的导入功能转成本地模型绕开官方仓库的慢速下载不要在安装包里纠结版本号稳定版即可安装完成后再用ollama update或重新安装新版都不是大问题。我自己比较常用的场景是这样的如果ollama pull的速度实在无法接受我会直接去模型社区的 GGUF 仓库下载量化文件然后写一个简单的 Modelfile 用ollama create导入。导入完成后ollama list里能看到和官方拉取几乎一样的模型条目使用上没有任何区别。2.2 让模型文件避开系统盘OLLAMA_MODELS 环境变量很多人装完 Ollama 后没注意模型存放路径。默认情况下模型文件会放在系统盘的用户目录下比如 Windows 的C:\Users\你的用户名\.ollama\modelsmacOS 的~/.ollama/models。如果你的 C 盘空间本来就不宽裕拉一两个 7B 模型就要吃掉 5GB 左右拉 32B 模型直接 20GB 起步系统盘很快告急。正确操作方法是在安装之前或安装之后立刻设置OLLAMA_MODELS环境变量把它指向 D 盘或数据盘。以 Windows 为例按Win键搜索编辑系统环境变量并打开点击环境变量在用户变量或系统变量中新建变量名填OLLAMA_MODELS变量值填你要放置模型文件的目录比如D:\ollama\models保存后关闭当前已打开的终端重新打开终端再执行ollama pull。注意如果你是在安装完成、已经拉过模型之后才改路径那么之前下载的模型不会自动搬过去。你需要手动把旧目录下的文件复制到新目录或者干脆重新拉取一次。我吃过这个亏第一次改路径后ollama list变成空的还以为模型丢了其实就是路径变了。Linux 和 macOS 同理。在~/.bashrc或~/.zshrc中写入export OLLAMA_MODELS/data/ollama/models然后source ~/.bashrc生效。另外还有一个容易被忽略的变量OLLAMA_HOST。如果你只是在本地自己用保持默认127.0.0.1就好更安全如果你想在局域网内让其他设备访问才需要把它改成0.0.0.0。这个改动会暴露服务后面我会专门讲安全边界。2.3 装完以后如何确认服务真的在跑很多教程跳过了验证步骤导致后续排查浪费时间。安装完成后先别急着拉模型先确认后台服务正常。执行ollama serve如果服务没有在后台启动它会以前台模式跑起来你能看到日志输出。如果服务已经在运行命令会提示服务已存在不同版本表述不同。更直接的验证方法是请求一下版本接口curl http://127.0.0.1:11434/api/version如果返回类似{version:0.x.x}的 JSON说明服务完全正常。这时候再ollama pull拉模型就会顺畅很多。在 Windows 上如果curl这个命令无法识别你可以直接在浏览器地址栏输入http://127.0.0.1:11434/api/version能返回 JSON 内容就说明服务正常。macOS 上 Ollama 通常会以菜单栏应用的形式常驻Linux 上我一般把它注册成 systemd 服务这样开机自启、崩溃自动拉起都会省心很多。安装包里一般自带服务注册逻辑不需要额外处理。3. 模型拉取与选型不是参数越大越好看显存和场景模型选择是本地部署中最影响体验的一环。选小了觉得笨选大了直接跑不动甚至把电脑搞到卡死。这里给出我的选择和估算方法不一定适合所有人但能帮你少走弯路。3.1 中文场景比较顺手的两档组合我现在的主力模型按使用场景分成两类日常问答和写代码。日常问答我会优先选中文能力强的通用模型写代码则优先选专门的代码模型。入门级8GB 左右显存或 16GB 内存qwen2.5:7b或更新版本的中文通用模型日常问答、文档总结基本够用qwen2.5-coder:7b代码补全和解释代码较好如果你需要推理过程考虑带思维链的模型比如deepseek-r1:7b这类带有推理能力的蒸馏模型。进阶级24GB 左右显存或 32GB 内存14B/32B 级别的模型能明显提升理解力尤其是复杂代码库或多轮对话32B 量级在单卡 3090/4090 上跑 4bit 量化是可以接受的内存条最好 32GB 以上。不要盲目追求最新版本。我建议的原则是先在你当前的硬件范围内挑一个口碑稳定的版本跑通全链路模型以后再换。换模型只需要改配置里的模型名链路本身不会变。3.2 参数量、量化精度和显存的换算思路为什么同样是 7B 模型有的只要 4GB有的要 14GB差距在精度。模型文件一般以 FP16 或 BF16 格式发布每个参数占 2 字节。7B 模型满精度大约 14GB。为了在消费级显卡上跑社区会做量化比如用 Q4_K_M 把每个参数压到半字节左右文件体积立刻降到 4~5GB。代价是质量略有损失但对绝大多数使用场景感知不明显。我做了一个估算表格按 Q4_K_M 量化文件大小近似计算模型规模量化文件大小约最低显存建议可流畅运行配置7B4.7GB8GB12GB 显存或 16GB 内存8B5.2GB8~10GB12GB 显存或 16GB 内存14B9GB16GB16GB 显存或 32GB 内存32B20GB24GB32GB 显存或 32GB 内存以上70B42GB48GB主要依赖多卡或纯 CPU大内存注意这里的最低显存只是能加载模型如果你想设置较大的上下文窗口比如 32K还需要额外预留内存/显存。上下文窗口不是免费的你给模型更多的对话历史它就需要更多的 KV Cache。一般我会额外预留 2~4GB 来应对 32K 上下文的开销。如果是纯 CPU 运行内存需求大约要在上面基础上再加一倍因为要同时承担模型权重和运行时开销。用 CPU 跑 7B 模型倒也不是不行回答速度会慢一些大概每秒几个 token但胜在不需要显卡适合办公电脑临时体验。3.3 拉取命令与中断恢复的细节拉取模型模型用ollama pull qwen2.5:7bOllama 支持断点续传。如果中途因为断网或休眠中断了重新执行一次ollama pull它会从断点继续而不是从头再来。所以遇到拉取中断第一反应不是抱怨而是重新跑一遍命令。查看已经下载的模型ollama list想删除某个不再用的模型释放空间ollama rm qwen2.5:7b另外一个小技巧有些模型会带不同标签比如qwen2.5:7b-instruct-q4_K_M这是某个量化格式的具体标签。只写qwen2.5:7b时Ollama 会拉取该系列默认推荐的格式通常就是官方的默认量化。绝大多数情况下直接用默认标签就够了不建议在没有十足把握时手动选各种奇怪标签。4. IDE 接入VS Code Continue 直连本地模型命令行工具走代理思路模型跑起来之后第一个真正提升效率的场景是集成到 IDE 里写代码。这里先解释我的方案选择过程再给配置细节。4.1 为什么把 Continue 作为 IDE 接入的首选VS Code 里能接本地模型的插件很多。Continue、Cline、Cody 都支持自定义模型服务地址。我优先推荐 Continue原因有几个它对 Ollama 的支持是开箱即用的不需要额外中转它是开源项目配置写在本地 JSON/YAML 文件里方便迁移和版本管理它默认支持 Tab 补全、对话、代码编辑多种能力和本地模型的交互逻辑做得比较规整。如果你之前用过 Cline它会要求你选API Provider并填 Base URL其实也很直观。我这里以 Continue 为例因为它的配置文件更适合手动深调。4.2 Continue 配置文件直改从模型映射到上下文窗口On first launch, Continue 会在用户目录下生成配置目录一般路径是Windows:C:\Users\你的用户名\.continuemacOS / Linux:~/.continue里面有一个config.json或config.yaml文件。我用的是 JSON 版本。核心配置如下{ models: [ { title: Qwen2.5 Coder 7B, provider: ollama, model: qwen2.5-coder:7b, baseUrl: http://127.0.0.1:11434, contextLength: 8192 } ], tabAutocompleteModel: { title: Qwen2.5 Coder 7B, provider: ollama, model: qwen2.5-coder:7b, baseUrl: http://127.0.0.1:11434 } }保存后重启 VS Code打开 Continue 面板应该能直接看到这个模型并开始对话。注意几个字段的含义provider必须是ollama表示走 Ollama 兼容协议model必须和ollama list里的名字完全一致不能随手写qwen2.5-coder要先确认标签baseUrl就是 Ollama 服务地址如果是远程机器可以填http://192.168.x.x:11434contextLength用来告诉前端插件模型最多支持多少上下文需要和实际模型能力匹配。如果你设置过大比如填 1048576但插件实际请求发送时可能因为超出模型限制报 400。我踩过一次很典型的坑把一个上下文上限很高的模型的标签复制过来用在了另一个只支持 8K 上下文的旧模型上。结果每次对话问长一点就报错。后来把contextLength调小问题就消失了。记住contextLength是给客户端做上下文管理用的不是用来提升模型能力的阈值。4.3 Claude Code / Cline 这类命令行工具接本地模型的思路很多人问Claude Code 能不能直接连 Ollama严格来说Claude Code 这类官方 CLI 工具默认是面向 Anthropic 商业 API 设计的它不会直接识别 Ollama 的 11434 端口。绕行方案其实是一种通用的代理思路在 Ollama 之上套一层OpenAI 兼容代理把 CLI 工具的请求格式转换成 Ollama 能理解的格式再指过去。我见过的具体做法有几种利用支持多供应商切换的工具比如社区常见的 CC Switch把自己常用的本地模型端点统一管理让 Claude Code 类工具切换供应商时能指向本地代理在本地跑一个通用的模型代理网关它对外提供 OpenAI 兼容接口对内转发到 Ollama然后通过环境变量强制 CLI 工具走这个代理地址比如设置ANTHROPIC_BASE_URLhttp://127.0.0.1:8080之类的变量。这个方案有一个好处你不需要改 CLI 工具的代码。工具本来就支持环境变量覆盖 API 地址只要代理层能用 OpenAI 兼容协议接收请求并在内部转给 Ollama你就能用商用工具的操作习惯去驱动本地模型。缺点是链路多了一层出问题时排查会稍微复杂。如果你只是想快速在 VS Code 里体验本地模型不折腾 CLI那么 Continue 直连已经足够了。CLI 方案更适合那些已经重度依赖命令行 AI 工具、又希望在敏感代码场景下把数据留在本机的人。5. Web 接入把本地模型变成局域网都可访问的对话服务打通 IDE 之后下一个需求自然会出现我想让模型在浏览器里使用甚至让团队的其他人也访问。这时候最省力的方案是 Open WebUI。5.1 Open WebUI 的两种部署方式Open WebUI 是一个开源项目提供类似 ChatGPT 的界面天然支持 Ollama还能管理多模型、多用户、历史会话和文件上传。部署方式有两种第一种Docker 运行。这也是官方主要推荐的方式。如果你已经装了 Docker很简单docker run -d \ -p 3000:8080 \ --add-hosthost.docker.internal:host-gateway \ -v open-webui:/app/backend/data \ --name open-webui \ --restart always \ ghcr.io/open-webui/open-webui:main第二种Python 直接运行。如果你不想引入 Docker且本机已经有 Python 3.11 或更高版本可以pip install open-webui open-webui serve然后浏览器访问http://127.0.0.1:3000。我个人的经验是如果只是自己玩两种都行如果想长期运行、多人访问优先 Docker。因为 Docker 版本的数据目录、日志、升级都更干净直接 pip 安装的版本升级时要留意依赖冲突我遇到过升级完起不来的情况。5.2 容器与宿主机连通的端口细节这是最容易出问题的环节。Open WebUI 跑在容器里而 Ollama 跑在宿主机上容器默认是无法直接访问宿主机的localhost的。上面的 Docker 命令里加了一行参数--add-hosthost.docker.internal:host-gateway这一行的作用是把host.docker.internal这个域名在容器内解析到宿主机这样 Open WebUI 就可以通过http://host.docker.internal:11434去连接宿主机上的 Ollama。进入 Open WebUI 首次启动设置时管理员账号里会有一步连接 Ollama 地址设置。如果默认没填对你可以在容器环境变量里加OLLAMA_BASE_URLhttp://host.docker.internal:11434如果你把 Ollama 也跑在 Docker 里那就更简单了让两个容器在同一个自定义网桥网络里然后填 Ollama 容器的名字作为地址即可。这里要注意如果你的 Ollama 监听的是宿主机127.0.0.1:11434容器内是永远访问不到这个地址的。你一定要确认 Ollama 的OLLAMA_HOST设置。仅从宿主机访问的话默认配置没问题但容器访问宿主机服务时需要 Ollama 监听在可以被访问的接口上。关于对外开放监听的安全提醒下一节我会细说。5.3 日常使用多模型、历史记录与上传文件Open WebUI 跑起来之后有几个功能值得提前了解。多模型切换Open WebUI 会自动读取 Ollama 里已经安装的模型列表下拉框中可以直接换模型多用户管理管理员可以创建只读用户或普通用户适合小团队共用一个本地模型服务历史会话所有对话默认保存在后端数据库里刷新页面不会丢文件上传部分模型配合文件处理能力可以读文档内容做问答。不过要注意上传文档能否被理解取决于模型本身是否具备文档解析能力。如果模型是纯文本模型上传 PDF 的效果可能有限。我自己在本地跑 Open WebUI 的一个常用场景是把团队内部技术方案文档扔进去让模型基于文档内容帮我整理摘要和风险点。整个过程数据不会离开内网这点对研发团队来说是很大的吸引力。6. API 接入OpenAI 兼容端点怎么调、报错怎么排查当你要把本地模型嵌入到自己的程序里做自动化处理时就需要 API。Ollama 对外暴露了一个 OpenAI 风格的兼容端点这让很多现成的 SDK 可以直接指向本地。6.1 先用 curl 把接口打穿无论后面用什么语言写代码我都建议先用 curl 确认接口和模型名是正确的。模型启动后执行curl http://127.0.0.1:11434/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5:7b, messages: [ {role: user, content: 用一句话解释什么是递归} ] }如果返回 JSON 中包含choices数组就说明 API 链路完全可用。这时候最值得强调的一点model字段一定要和ollama list里显示的模型名完全一致。否则你会收到类似报错提到可用模型名列表。这是很多人第一次调 API 最容易犯的错别问我怎么知道的。你在网页界面里选模型时Open WebUI 已经帮你做了映射但裸调 API 时没人帮你纠正。6.2 用 OpenAI SDK 调用本地模型及连接参数细节因为 Ollama 提供了/v1路径所以 Python 里可以直接用官方 OpenAI SDK只要把base_url和api_key改一下。from openai import OpenAI client OpenAI( base_urlhttp://127.0.0.1:11434/v1, api_keyollama, # 本地服务不校验但字段不能缺 ) resp client.chat.completions.create( modelqwen2.5:7b, messages[{role: user, content: 写一个 Python 快速排序}], temperature0.7, max_tokens2048, ) print(resp.choices[0].message.content)注意几个容易踩的点api_key可以随便填一个字符串但不要留空部分 SDK 版本会在 header 校验中报错base_url必须以/v1结尾不带/chat/completions。OpenAI SDK 自己会拼接路径。如果你填成http://127.0.0.1:11434也不是完全不行但更规范的是填http://127.0.0.1:11434/v1如果你之前用的是 DeepSeek、智谱或其他兼容 API代码里只需要把base_url和model换掉其他逻辑基本不动。这种换底座不换代码的能力是 Ollama 提供 OpenAI 兼容层最大的价值。如果程序是放在远程服务器上访问本地 Ollama记得把 URL 里的127.0.0.1换成 Ollama 所在机器的局域网 IP。6.3 常见报错对照模型名、上下文长度、并发这里整理一份我在实际使用中遇到过的问题对照表比对着排查可以省不少时间。报错/现象可能原因处理办法model ... not found模型名写错或未拉取执行ollama list查看准确名称HTTP 400提示 context length上下文窗口超过模型限制调低请求中的上下文或num_ctxHTTP 429 或请求排队时间很长并发设置过低调大OLLAMA_NUM_PARALLEL响应首字很慢模型冷启动需要先加载进显存用OLLAMA_KEEP_ALIVE保持模型驻留返回内容明显截断max_tokens设置太小增大max_tokens或减少上下文有一个经常让人摸不着头脑的现象明明模型宣称支持几万甚至上百万的上下文长度但一请求就报 400。原因可能是 Ollama 运行时的默认上下文窗口小于模型宣称上限。你需要通过/set parameter num_ctx在交互、或参数中显式指定更大的上下文窗口。很多模型在 Ollama 上的默认num_ctx并不等于宣传值所以不要拿最大能力当默认能力用。关于/api/generate与/v1/chat/completions的区别前者是 Ollama 原生接口传的是prompt而不是messages后者是 OpenAI 兼容格式。我一般只在测试原生功能时才用/api/generate对外统一用/v1/chat/completions。好处是将来换云厂商模型时代码只需要改地址和模型名不需要重新写请求结构。7. 跑起来只是开始并发排队、上下文超限、内存爆掉一次说清最后进入运维和稳定性的部分。部署本地模型最难的往往不是第一次跑通而是跑通之后能不能稳定用下去。如果你只是个人体验可以跳过大部分内容但要跑服务给团队用这几项必须看。7.1 合理设置并发和模型驻留减少排队和重复加载Ollama 默认的并发策略偏保守。如果很多人同时访问你会看到大量请求在排队。这时候需要调整这些环境变量OLLAMA_NUM_PARALLEL同一个模型最多并行处理几个请求。默认值因模型和硬件而异。我把 7B 模型设成 432B 模型设成 1 或 2。太高会导致显存不足反而把整体吞吐拖垮。OLLAMA_MAX_LOADED_MODELS最多同时加载几个模型到内存/显存。如果设置为 1意味着切换模型时需要先卸载旧模型再加载新模型换模型会明显变慢。OLLAMA_KEEP_ALIVE模型在空闲后驻留多长时间。默认是 5 分钟如果频繁有人调用可以设置更长比如30m甚至-1永久驻留。代价是显存一直占用。对硬件配置紧张的小团队我建议把OLLAMA_MAX_LOADED_MODELS设为 1避免同时加载两个大模型把机器打爆。哪怕用户想用不同模型也要接受切换模型时的加载延迟。7.2 排障看日志一条请求到底经历了什么当你的服务报错或响应异常时第一反应不是看模型而是看 Ollama 服务日志。日志位置根据系统不同有差异Linuxsystemd 安装journalctl -u ollama -fmacOS~/.ollama/logs/server.logWindows%LOCALAPPDATA%\Ollama\server.log。如果你想看更细的日志可以临时设置OLLAMA_DEBUG1再重启服务。日志里能看到每个请求的加载耗时、token 生成速度、显存分配情况。排查为什么这么慢时这些数据最直接。举个例子有次我远程调模型发现响应越来越慢日志里全是显存不足、反复卸载模型的消息。调完OLLAMA_NUM_PARALLEL和OLLAMA_KEEP_ALIVE后服务立刻稳定下来。如果你不懂看日志很可能在换模型和重启电脑之间反复横跳问题始终存在。7.3 内网暴露边界、安全与多用户隔离最后讲一个容易被忽视的问题当你把 Ollama 的OLLAMA_HOST改成0.0.0.0时意味着局域网内任何设备都能访问你的模型接口。如果没有鉴权机制别人可以直接通过 API 消耗你的显卡资源。我在本地部署时通常有以下原则本机自己用保持默认127.0.0.1不要开局域网访问如果需要让同事访问只在可信任的内网开放并且最好放在独立开发机上不放个人工作电脑如果需要对外开放必须在前面加一层带用户鉴权的网关比如用 Open WebUI 管理用户或者用 API 网关统一入口不要直接把公网 IP 映射到 11434 端口。Ollama 本身没带复杂的用户认证体系所以谁是客户端这个事需要外层来解决。Open WebUI 的多用户模式是相对友好的方案它在前端做了登录验证再通过后端去访问 Ollama这样可以避免把裸接口暴露在不可信网络上。我在实际使用中的体会是本地大模型的部署链路并不复杂真正麻烦的是每个环节的一些小细节模型名是否一致、上下文窗口配得对不对、并发参数是否和自己的硬件匹配、日志里到底报了什么错。把这篇里的链路走通一遍你得到的不仅是一个能在终端里聊天的模型而是一套真正可以嵌进编辑器、网页和业务代码里的本地模型服务。以后模型更新了只需要换一行模型名其他逻辑都在。 Ollama本地大模型部署实战：从下载到接入IDE、Web和API
Ollama 本地大模型部署实战从下载到接入 IDE、Web 和 API——这句话看起来像教程标题其实更像是一段我反复走了几遍的路。最早我本地部署大模型停留在能在终端里唠嗑的水平然后用起来非常挣扎模型在终端里能回答编辑器里却调用不到想在浏览器里对着一堆文档提问不知道怎么搭想让脚本/服务通过 API 去访问本地模型又搞不明白接口区别。这篇我把整条链路整理成一份能直接落地的实操记录目标是让你拿到模型之后紧接着就能把编辑器、网页、API 三个入口都打通。1. 先理解整条链路从模型文件到你打开的那个聊天框很多人在本地部署这一步就劝退了不是因为命令难而是不知道自己在做什么。先花几分钟把链路拆清楚后面所有配置都是在处理这条链路上的连接问题。1.1 一个典型场景模型有了但用不起来假设你刚把qwen2.5:7b拉回本地在终端里跑了一下发现回答质量不错。然后你打开 VS Code装了一个 AI 插件想让它帮忙改代码却发现插件无论如何都连不上。或者你写了一个小网页想让用户通过浏览器和模型对话结果网页还是空的因为你根本不知道模型对外暴露了什么端口。我一开始也是这样。模型在终端里活蹦乱跳但一到真实应用场景就彻底不动了。问题不在模型本身而在于本地只有模型运行时还缺一个能被外部访问的服务层。终端里的ollama run只是它附带的一个对话界面真正的核心是后台那个常驻服务。理解这一点你就知道后面装 Open WebUI、配 IDE、调 API都是在跟后台服务说话而不是直接跟模型文件说话。1.2 Ollama 在这条链路里扮演的角色Ollama 不是一个模型它是一层模型运行时服务管理。它负责把模型文件加载进内存/显存它负责管理请求队列、上下文窗口、并发数量它默认监听127.0.0.1:11434对外提供 HTTP 接口它提供 OpenAI 兼容端点/v1/chat/completions方便你使用现成的 OpenAI SDK。所以你可以把它理解成本地的模型服务器。终端里的交互模式只是它的一个客户端而已。你要接入 IDE、Web、API本质上就是让 IDE、WebApp、业务代码都变成这个服务器的客户端。理解了这层关系后面再看到http://localhost:11434就不会觉得陌生。它是 Ollama 服务的默认地址所有客户端都要连到这里。2. 安装期最常踩的三个坑下载慢、装错盘、服务没起安装 Ollama 本身不难但国内环境下很多人卡在下载阶段。我见过不少同事折腾一天最后发现连安装包都没下完。这里把安装期的常见问题一次说清。2.1 官方下载慢的处理思路先说结论Ollama 的安装包和模型文件是两回事。安装包只有几百 MB能不能顺利下载取决于网络情况模型文件动辄几个 GB这个才是大户。如果你下载安装包很慢不要反复点同一个链接干等。更稳妥的做法是利用好现有的下载工具和镜像站资源。下载安装包时用带断点续传的下载工具不要用浏览器直接下载以免中断后从头再来模型文件的大头可以从国内可正常访问的开源模型社区拉取 GGUF 格式文件再通过 Ollama 的导入功能转成本地模型绕开官方仓库的慢速下载不要在安装包里纠结版本号稳定版即可安装完成后再用ollama update或重新安装新版都不是大问题。我自己比较常用的场景是这样的如果ollama pull的速度实在无法接受我会直接去模型社区的 GGUF 仓库下载量化文件然后写一个简单的 Modelfile 用ollama create导入。导入完成后ollama list里能看到和官方拉取几乎一样的模型条目使用上没有任何区别。2.2 让模型文件避开系统盘OLLAMA_MODELS 环境变量很多人装完 Ollama 后没注意模型存放路径。默认情况下模型文件会放在系统盘的用户目录下比如 Windows 的C:\Users\你的用户名\.ollama\modelsmacOS 的~/.ollama/models。如果你的 C 盘空间本来就不宽裕拉一两个 7B 模型就要吃掉 5GB 左右拉 32B 模型直接 20GB 起步系统盘很快告急。正确操作方法是在安装之前或安装之后立刻设置OLLAMA_MODELS环境变量把它指向 D 盘或数据盘。以 Windows 为例按Win键搜索编辑系统环境变量并打开点击环境变量在用户变量或系统变量中新建变量名填OLLAMA_MODELS变量值填你要放置模型文件的目录比如D:\ollama\models保存后关闭当前已打开的终端重新打开终端再执行ollama pull。注意如果你是在安装完成、已经拉过模型之后才改路径那么之前下载的模型不会自动搬过去。你需要手动把旧目录下的文件复制到新目录或者干脆重新拉取一次。我吃过这个亏第一次改路径后ollama list变成空的还以为模型丢了其实就是路径变了。Linux 和 macOS 同理。在~/.bashrc或~/.zshrc中写入export OLLAMA_MODELS/data/ollama/models然后source ~/.bashrc生效。另外还有一个容易被忽略的变量OLLAMA_HOST。如果你只是在本地自己用保持默认127.0.0.1就好更安全如果你想在局域网内让其他设备访问才需要把它改成0.0.0.0。这个改动会暴露服务后面我会专门讲安全边界。2.3 装完以后如何确认服务真的在跑很多教程跳过了验证步骤导致后续排查浪费时间。安装完成后先别急着拉模型先确认后台服务正常。执行ollama serve如果服务没有在后台启动它会以前台模式跑起来你能看到日志输出。如果服务已经在运行命令会提示服务已存在不同版本表述不同。更直接的验证方法是请求一下版本接口curl http://127.0.0.1:11434/api/version如果返回类似{version:0.x.x}的 JSON说明服务完全正常。这时候再ollama pull拉模型就会顺畅很多。在 Windows 上如果curl这个命令无法识别你可以直接在浏览器地址栏输入http://127.0.0.1:11434/api/version能返回 JSON 内容就说明服务正常。macOS 上 Ollama 通常会以菜单栏应用的形式常驻Linux 上我一般把它注册成 systemd 服务这样开机自启、崩溃自动拉起都会省心很多。安装包里一般自带服务注册逻辑不需要额外处理。3. 模型拉取与选型不是参数越大越好看显存和场景模型选择是本地部署中最影响体验的一环。选小了觉得笨选大了直接跑不动甚至把电脑搞到卡死。这里给出我的选择和估算方法不一定适合所有人但能帮你少走弯路。3.1 中文场景比较顺手的两档组合我现在的主力模型按使用场景分成两类日常问答和写代码。日常问答我会优先选中文能力强的通用模型写代码则优先选专门的代码模型。入门级8GB 左右显存或 16GB 内存qwen2.5:7b或更新版本的中文通用模型日常问答、文档总结基本够用qwen2.5-coder:7b代码补全和解释代码较好如果你需要推理过程考虑带思维链的模型比如deepseek-r1:7b这类带有推理能力的蒸馏模型。进阶级24GB 左右显存或 32GB 内存14B/32B 级别的模型能明显提升理解力尤其是复杂代码库或多轮对话32B 量级在单卡 3090/4090 上跑 4bit 量化是可以接受的内存条最好 32GB 以上。不要盲目追求最新版本。我建议的原则是先在你当前的硬件范围内挑一个口碑稳定的版本跑通全链路模型以后再换。换模型只需要改配置里的模型名链路本身不会变。3.2 参数量、量化精度和显存的换算思路为什么同样是 7B 模型有的只要 4GB有的要 14GB差距在精度。模型文件一般以 FP16 或 BF16 格式发布每个参数占 2 字节。7B 模型满精度大约 14GB。为了在消费级显卡上跑社区会做量化比如用 Q4_K_M 把每个参数压到半字节左右文件体积立刻降到 4~5GB。代价是质量略有损失但对绝大多数使用场景感知不明显。我做了一个估算表格按 Q4_K_M 量化文件大小近似计算模型规模量化文件大小约最低显存建议可流畅运行配置7B4.7GB8GB12GB 显存或 16GB 内存8B5.2GB8~10GB12GB 显存或 16GB 内存14B9GB16GB16GB 显存或 32GB 内存32B20GB24GB32GB 显存或 32GB 内存以上70B42GB48GB主要依赖多卡或纯 CPU大内存注意这里的最低显存只是能加载模型如果你想设置较大的上下文窗口比如 32K还需要额外预留内存/显存。上下文窗口不是免费的你给模型更多的对话历史它就需要更多的 KV Cache。一般我会额外预留 2~4GB 来应对 32K 上下文的开销。如果是纯 CPU 运行内存需求大约要在上面基础上再加一倍因为要同时承担模型权重和运行时开销。用 CPU 跑 7B 模型倒也不是不行回答速度会慢一些大概每秒几个 token但胜在不需要显卡适合办公电脑临时体验。3.3 拉取命令与中断恢复的细节拉取模型模型用ollama pull qwen2.5:7bOllama 支持断点续传。如果中途因为断网或休眠中断了重新执行一次ollama pull它会从断点继续而不是从头再来。所以遇到拉取中断第一反应不是抱怨而是重新跑一遍命令。查看已经下载的模型ollama list想删除某个不再用的模型释放空间ollama rm qwen2.5:7b另外一个小技巧有些模型会带不同标签比如qwen2.5:7b-instruct-q4_K_M这是某个量化格式的具体标签。只写qwen2.5:7b时Ollama 会拉取该系列默认推荐的格式通常就是官方的默认量化。绝大多数情况下直接用默认标签就够了不建议在没有十足把握时手动选各种奇怪标签。4. IDE 接入VS Code Continue 直连本地模型命令行工具走代理思路模型跑起来之后第一个真正提升效率的场景是集成到 IDE 里写代码。这里先解释我的方案选择过程再给配置细节。4.1 为什么把 Continue 作为 IDE 接入的首选VS Code 里能接本地模型的插件很多。Continue、Cline、Cody 都支持自定义模型服务地址。我优先推荐 Continue原因有几个它对 Ollama 的支持是开箱即用的不需要额外中转它是开源项目配置写在本地 JSON/YAML 文件里方便迁移和版本管理它默认支持 Tab 补全、对话、代码编辑多种能力和本地模型的交互逻辑做得比较规整。如果你之前用过 Cline它会要求你选API Provider并填 Base URL其实也很直观。我这里以 Continue 为例因为它的配置文件更适合手动深调。4.2 Continue 配置文件直改从模型映射到上下文窗口On first launch, Continue 会在用户目录下生成配置目录一般路径是Windows:C:\Users\你的用户名\.continuemacOS / Linux:~/.continue里面有一个config.json或config.yaml文件。我用的是 JSON 版本。核心配置如下{ models: [ { title: Qwen2.5 Coder 7B, provider: ollama, model: qwen2.5-coder:7b, baseUrl: http://127.0.0.1:11434, contextLength: 8192 } ], tabAutocompleteModel: { title: Qwen2.5 Coder 7B, provider: ollama, model: qwen2.5-coder:7b, baseUrl: http://127.0.0.1:11434 } }保存后重启 VS Code打开 Continue 面板应该能直接看到这个模型并开始对话。注意几个字段的含义provider必须是ollama表示走 Ollama 兼容协议model必须和ollama list里的名字完全一致不能随手写qwen2.5-coder要先确认标签baseUrl就是 Ollama 服务地址如果是远程机器可以填http://192.168.x.x:11434contextLength用来告诉前端插件模型最多支持多少上下文需要和实际模型能力匹配。如果你设置过大比如填 1048576但插件实际请求发送时可能因为超出模型限制报 400。我踩过一次很典型的坑把一个上下文上限很高的模型的标签复制过来用在了另一个只支持 8K 上下文的旧模型上。结果每次对话问长一点就报错。后来把contextLength调小问题就消失了。记住contextLength是给客户端做上下文管理用的不是用来提升模型能力的阈值。4.3 Claude Code / Cline 这类命令行工具接本地模型的思路很多人问Claude Code 能不能直接连 Ollama严格来说Claude Code 这类官方 CLI 工具默认是面向 Anthropic 商业 API 设计的它不会直接识别 Ollama 的 11434 端口。绕行方案其实是一种通用的代理思路在 Ollama 之上套一层OpenAI 兼容代理把 CLI 工具的请求格式转换成 Ollama 能理解的格式再指过去。我见过的具体做法有几种利用支持多供应商切换的工具比如社区常见的 CC Switch把自己常用的本地模型端点统一管理让 Claude Code 类工具切换供应商时能指向本地代理在本地跑一个通用的模型代理网关它对外提供 OpenAI 兼容接口对内转发到 Ollama然后通过环境变量强制 CLI 工具走这个代理地址比如设置ANTHROPIC_BASE_URLhttp://127.0.0.1:8080之类的变量。这个方案有一个好处你不需要改 CLI 工具的代码。工具本来就支持环境变量覆盖 API 地址只要代理层能用 OpenAI 兼容协议接收请求并在内部转给 Ollama你就能用商用工具的操作习惯去驱动本地模型。缺点是链路多了一层出问题时排查会稍微复杂。如果你只是想快速在 VS Code 里体验本地模型不折腾 CLI那么 Continue 直连已经足够了。CLI 方案更适合那些已经重度依赖命令行 AI 工具、又希望在敏感代码场景下把数据留在本机的人。5. Web 接入把本地模型变成局域网都可访问的对话服务打通 IDE 之后下一个需求自然会出现我想让模型在浏览器里使用甚至让团队的其他人也访问。这时候最省力的方案是 Open WebUI。5.1 Open WebUI 的两种部署方式Open WebUI 是一个开源项目提供类似 ChatGPT 的界面天然支持 Ollama还能管理多模型、多用户、历史会话和文件上传。部署方式有两种第一种Docker 运行。这也是官方主要推荐的方式。如果你已经装了 Docker很简单docker run -d \ -p 3000:8080 \ --add-hosthost.docker.internal:host-gateway \ -v open-webui:/app/backend/data \ --name open-webui \ --restart always \ ghcr.io/open-webui/open-webui:main第二种Python 直接运行。如果你不想引入 Docker且本机已经有 Python 3.11 或更高版本可以pip install open-webui open-webui serve然后浏览器访问http://127.0.0.1:3000。我个人的经验是如果只是自己玩两种都行如果想长期运行、多人访问优先 Docker。因为 Docker 版本的数据目录、日志、升级都更干净直接 pip 安装的版本升级时要留意依赖冲突我遇到过升级完起不来的情况。5.2 容器与宿主机连通的端口细节这是最容易出问题的环节。Open WebUI 跑在容器里而 Ollama 跑在宿主机上容器默认是无法直接访问宿主机的localhost的。上面的 Docker 命令里加了一行参数--add-hosthost.docker.internal:host-gateway这一行的作用是把host.docker.internal这个域名在容器内解析到宿主机这样 Open WebUI 就可以通过http://host.docker.internal:11434去连接宿主机上的 Ollama。进入 Open WebUI 首次启动设置时管理员账号里会有一步连接 Ollama 地址设置。如果默认没填对你可以在容器环境变量里加OLLAMA_BASE_URLhttp://host.docker.internal:11434如果你把 Ollama 也跑在 Docker 里那就更简单了让两个容器在同一个自定义网桥网络里然后填 Ollama 容器的名字作为地址即可。这里要注意如果你的 Ollama 监听的是宿主机127.0.0.1:11434容器内是永远访问不到这个地址的。你一定要确认 Ollama 的OLLAMA_HOST设置。仅从宿主机访问的话默认配置没问题但容器访问宿主机服务时需要 Ollama 监听在可以被访问的接口上。关于对外开放监听的安全提醒下一节我会细说。5.3 日常使用多模型、历史记录与上传文件Open WebUI 跑起来之后有几个功能值得提前了解。多模型切换Open WebUI 会自动读取 Ollama 里已经安装的模型列表下拉框中可以直接换模型多用户管理管理员可以创建只读用户或普通用户适合小团队共用一个本地模型服务历史会话所有对话默认保存在后端数据库里刷新页面不会丢文件上传部分模型配合文件处理能力可以读文档内容做问答。不过要注意上传文档能否被理解取决于模型本身是否具备文档解析能力。如果模型是纯文本模型上传 PDF 的效果可能有限。我自己在本地跑 Open WebUI 的一个常用场景是把团队内部技术方案文档扔进去让模型基于文档内容帮我整理摘要和风险点。整个过程数据不会离开内网这点对研发团队来说是很大的吸引力。6. API 接入OpenAI 兼容端点怎么调、报错怎么排查当你要把本地模型嵌入到自己的程序里做自动化处理时就需要 API。Ollama 对外暴露了一个 OpenAI 风格的兼容端点这让很多现成的 SDK 可以直接指向本地。6.1 先用 curl 把接口打穿无论后面用什么语言写代码我都建议先用 curl 确认接口和模型名是正确的。模型启动后执行curl http://127.0.0.1:11434/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5:7b, messages: [ {role: user, content: 用一句话解释什么是递归} ] }如果返回 JSON 中包含choices数组就说明 API 链路完全可用。这时候最值得强调的一点model字段一定要和ollama list里显示的模型名完全一致。否则你会收到类似报错提到可用模型名列表。这是很多人第一次调 API 最容易犯的错别问我怎么知道的。你在网页界面里选模型时Open WebUI 已经帮你做了映射但裸调 API 时没人帮你纠正。6.2 用 OpenAI SDK 调用本地模型及连接参数细节因为 Ollama 提供了/v1路径所以 Python 里可以直接用官方 OpenAI SDK只要把base_url和api_key改一下。from openai import OpenAI client OpenAI( base_urlhttp://127.0.0.1:11434/v1, api_keyollama, # 本地服务不校验但字段不能缺 ) resp client.chat.completions.create( modelqwen2.5:7b, messages[{role: user, content: 写一个 Python 快速排序}], temperature0.7, max_tokens2048, ) print(resp.choices[0].message.content)注意几个容易踩的点api_key可以随便填一个字符串但不要留空部分 SDK 版本会在 header 校验中报错base_url必须以/v1结尾不带/chat/completions。OpenAI SDK 自己会拼接路径。如果你填成http://127.0.0.1:11434也不是完全不行但更规范的是填http://127.0.0.1:11434/v1如果你之前用的是 DeepSeek、智谱或其他兼容 API代码里只需要把base_url和model换掉其他逻辑基本不动。这种换底座不换代码的能力是 Ollama 提供 OpenAI 兼容层最大的价值。如果程序是放在远程服务器上访问本地 Ollama记得把 URL 里的127.0.0.1换成 Ollama 所在机器的局域网 IP。6.3 常见报错对照模型名、上下文长度、并发这里整理一份我在实际使用中遇到过的问题对照表比对着排查可以省不少时间。报错/现象可能原因处理办法model ... not found模型名写错或未拉取执行ollama list查看准确名称HTTP 400提示 context length上下文窗口超过模型限制调低请求中的上下文或num_ctxHTTP 429 或请求排队时间很长并发设置过低调大OLLAMA_NUM_PARALLEL响应首字很慢模型冷启动需要先加载进显存用OLLAMA_KEEP_ALIVE保持模型驻留返回内容明显截断max_tokens设置太小增大max_tokens或减少上下文有一个经常让人摸不着头脑的现象明明模型宣称支持几万甚至上百万的上下文长度但一请求就报 400。原因可能是 Ollama 运行时的默认上下文窗口小于模型宣称上限。你需要通过/set parameter num_ctx在交互、或参数中显式指定更大的上下文窗口。很多模型在 Ollama 上的默认num_ctx并不等于宣传值所以不要拿最大能力当默认能力用。关于/api/generate与/v1/chat/completions的区别前者是 Ollama 原生接口传的是prompt而不是messages后者是 OpenAI 兼容格式。我一般只在测试原生功能时才用/api/generate对外统一用/v1/chat/completions。好处是将来换云厂商模型时代码只需要改地址和模型名不需要重新写请求结构。7. 跑起来只是开始并发排队、上下文超限、内存爆掉一次说清最后进入运维和稳定性的部分。部署本地模型最难的往往不是第一次跑通而是跑通之后能不能稳定用下去。如果你只是个人体验可以跳过大部分内容但要跑服务给团队用这几项必须看。7.1 合理设置并发和模型驻留减少排队和重复加载Ollama 默认的并发策略偏保守。如果很多人同时访问你会看到大量请求在排队。这时候需要调整这些环境变量OLLAMA_NUM_PARALLEL同一个模型最多并行处理几个请求。默认值因模型和硬件而异。我把 7B 模型设成 432B 模型设成 1 或 2。太高会导致显存不足反而把整体吞吐拖垮。OLLAMA_MAX_LOADED_MODELS最多同时加载几个模型到内存/显存。如果设置为 1意味着切换模型时需要先卸载旧模型再加载新模型换模型会明显变慢。OLLAMA_KEEP_ALIVE模型在空闲后驻留多长时间。默认是 5 分钟如果频繁有人调用可以设置更长比如30m甚至-1永久驻留。代价是显存一直占用。对硬件配置紧张的小团队我建议把OLLAMA_MAX_LOADED_MODELS设为 1避免同时加载两个大模型把机器打爆。哪怕用户想用不同模型也要接受切换模型时的加载延迟。7.2 排障看日志一条请求到底经历了什么当你的服务报错或响应异常时第一反应不是看模型而是看 Ollama 服务日志。日志位置根据系统不同有差异Linuxsystemd 安装journalctl -u ollama -fmacOS~/.ollama/logs/server.logWindows%LOCALAPPDATA%\Ollama\server.log。如果你想看更细的日志可以临时设置OLLAMA_DEBUG1再重启服务。日志里能看到每个请求的加载耗时、token 生成速度、显存分配情况。排查为什么这么慢时这些数据最直接。举个例子有次我远程调模型发现响应越来越慢日志里全是显存不足、反复卸载模型的消息。调完OLLAMA_NUM_PARALLEL和OLLAMA_KEEP_ALIVE后服务立刻稳定下来。如果你不懂看日志很可能在换模型和重启电脑之间反复横跳问题始终存在。7.3 内网暴露边界、安全与多用户隔离最后讲一个容易被忽视的问题当你把 Ollama 的OLLAMA_HOST改成0.0.0.0时意味着局域网内任何设备都能访问你的模型接口。如果没有鉴权机制别人可以直接通过 API 消耗你的显卡资源。我在本地部署时通常有以下原则本机自己用保持默认127.0.0.1不要开局域网访问如果需要让同事访问只在可信任的内网开放并且最好放在独立开发机上不放个人工作电脑如果需要对外开放必须在前面加一层带用户鉴权的网关比如用 Open WebUI 管理用户或者用 API 网关统一入口不要直接把公网 IP 映射到 11434 端口。Ollama 本身没带复杂的用户认证体系所以谁是客户端这个事需要外层来解决。Open WebUI 的多用户模式是相对友好的方案它在前端做了登录验证再通过后端去访问 Ollama这样可以避免把裸接口暴露在不可信网络上。我在实际使用中的体会是本地大模型的部署链路并不复杂真正麻烦的是每个环节的一些小细节模型名是否一致、上下文窗口配得对不对、并发参数是否和自己的硬件匹配、日志里到底报了什么错。把这篇里的链路走通一遍你得到的不仅是一个能在终端里聊天的模型而是一套真正可以嵌进编辑器、网页和业务代码里的本地模型服务。以后模型更新了只需要换一行模型名其他逻辑都在。