在本地跑大模型这几年已经不是“极客专属”了。Ollama 刚好把“下载模型、运行模型、暴露 API、接入应用”这条链路串成了几条命令就能完成的事。无论你是想把 DeepSeek 这类开源模型部署到自己的电脑上还是准备做本地大模型应用开发都可以从 Ollama 入手。这篇教程会按照安装 → 找模型 → 本地部署 → 接口接入 → 工具联动 → 排错的顺序走一遍。标题里提到零基础那我就默认你暂时不理解“GGUF”“ShaardingPlan”这些概念也没关系——先能跑起来再慢慢消化原理。文章里所有命令都给出可复制的模板直接替换成你自己的路径和模型名即可。先看一眼这个工具到底能干什么Ollama 是一个开源的大语言模型本地运行工具提供命令行和后台服务。它主要负责两件事一是把模型文件统一管理起来二是提供一个本地 HTTP 服务让代码和第三方工具能通过标准接口调用模型。对普通用户来说装好之后只需要ollama run 模型名就能进入问答界面对开发者来说Ollama 的/api/chat和 OpenAI 兼容接口可以直接接入自己的应用。下面进入正题。1. Ollama 核心能力速览在安装之前先把 Ollama 的关键信息做一个整体梳理。这张表里的项目类型、启动方式、接口能力都是从项目本身和日常使用中归纳出来的硬件参数部分我尽量给区间而不是拍脑袋的数字。能力项说明项目类型开源大模型本地运行与管理工具主要功能模型下载、模型运行、交互问答、API 服务、模型导入导出支持平台Windows、macOS、Linux也可通过 Docker 部署是否支持 CPU支持小尺寸模型用 CPU 可运行速度明显慢于 GPU显卡支持NVIDIA GPU 支持较成熟AMD / Intel 与 Apple Silicon 需按版本适配情况测试显存需求由模型尺寸决定1.5B 到 7B 模型可在 6G 到 12G 显存范围内尝试显存不足时可回退 CPU 推理实际占用需按本机测试为准启动方式命令启动 本地后台服务安装后默认常驻服务管理模型默认服务端口11434可在环境变量中修改是否支持 API支持原生/api/generate、/api/chat接口并提供 OpenAI 兼容接口/v1是否支持批量任务本身不提供图形化任务队列但支持命令行和 HTTP 接口循环调用可自行编写批量脚本适合场景本地体验开源模型、离线环境部署、大模型应用开发、AI 编码工具本地底座、数据不出内网从能力速览可以看到Ollama 更像一个“模型运行底座”而不是一个大而全的网页应用。你要用的模型管理、服务启动、接口暴露它都管了具体的聊天界面、知识库、工作流都是接在它外层的东西。2. Ollama 适用场景与使用边界很多文章把 Ollama 吹得什么都能干实际上它更适合下面这些场景。适合你把 Ollama 当成“本地模型服务”来用的场景个人本机体验开源大模型比如跑 DeepSeek、Qwen、Llama 的量化版本。局域网内做模型服务不让数据离开公司内网。开发阶段调试提示词把 Ollama 当作后端接口服务前端写好界面就能换模型。作为 AI 编程工具的推理后端让本地模型承担代码补全或 Agent 对话任务。存放私有模型文件团队内部统一分发模型版本。不太适合的场景超大参数模型的在线高并发服务。60B 以上模型部署到单机后响应速度和并发能力都有限。对输出质量要求非常高的生产任务。本地量化模型的生成质量与云端旗舰 API 仍有差距。需要复杂知识库和流程编排的业务。Ollama 不提供知识库、工作流、多 Agent 管理这些需要搭配 Dify、FastGPT 或自己写编排代码。零显卡、低内存的老机器跑大模型。运行体验会很差不如直接使用云 API。使用边界和安全提醒不管你是用 Ollama 做个人工具、公司应用还是接入编码 Agent都必须注意几个底线问题第一下载模型时确认模型的许可证是否允许商用或二次分发尤其是从第三方渠道拿到的 GGUF 文件第二如果模型要处理用户上传的图片、文档、语音必须提前判断这些内容是否涉及他人隐私或保密信息不能把敏感数据随意外发到非可信环境第三用 Ollama 做自动化 Agent、内容生成或代码审查时生成结果需要人工复核避免大模型幻觉造成实际损失第四涉及人脸、声音、版权素材的生成必须确认授权不来源不明的数据绝不用于训练或生成。3. Ollama 环境准备与前置条件这个环节看起来很简单但很多新手卡在安装后跑不起来往往是环境前置没做好。下面按 Windows、macOS、Linux 三条线路分别给出检查清单。3.1 操作系统与版本Windows建议使用 Windows 10 及以上版本安装时最好以管理员身份运行安装包。macOS建议 macOS 12 以上Apple Silicon 芯片运行体验更顺滑Intel 芯片也能装速度要慢不少。Linux建议 Ubuntu 20.04 或 Debian 10 以上的发行版安装脚本会识别主流 Linux 环境。3.2 GPU 与驱动这是最容易出问题的一环。Ollama 使用 GPU 推理之前会先检测系统驱动。如果你用的是 NVIDIA 显卡建议先更新到当前可用的最新驱动。不需要手动装完整 CUDA ToolkitOllama 自带相关的运行依赖集成你只要保证驱动版本足够新。如果你没有独立显卡或者显存只有 4G 以下不用直接放弃。选择 1B、1.5B、3B 这类小模型使用 CPU 推理是完全可以跑的。Intel 核显和 AMD 核显的适配情况会随着版本更新变化稳妥的做法是先去官网或模型页确认当前版本的官方支持矩阵。3.3 磁盘空间大模型文件通常以 GB 为单位。一个 7B 模型量化后约为 4G 到 5G一个 14B 模型约为 8G 到 10G一个 70B 模型可能超过 40G。所以安装前先执行磁盘空间检查# Windows 可在资源管理器中查看或用 PowerShell Get-PSDrive -Name C # Linux / macOS df -h装多个模型之前预留 20G 以上的磁盘空间是比较舒服的。如果 C 盘空间吃紧后续可以通过设置OLLAMA_MODELS环境变量把模型存储位置挪到其他盘。3.4 端口规划Ollama 默认监听11434。如果你本机已经装了其他服务占用这个端口或者 Docker 容器端口冲突轻则连接失败重则服务起不来。启动前可以先确认端口状态# Windows netstat -ano | findstr 11434 # Linux / macOS lsof -i :11434有输出就说明端口被占用。后面会说明如何通过OLLAMA_HOST换一个端口。4. Ollama 下载安装Windows、macOS、LinuxOllama 的安装本质上是把ollama主程序和后台服务装到系统里。安装完成之后模型文件并不包含在内你仍然需要单独拉取或导入模型。4.1 Windows 安装Windows 用户的安装路径最直接从 Ollama 官网点击 Download 按钮下载 Windows 安装包文件然后双击安装即可。安装完成之后系统通常会自动启动 Ollama 后台服务。验证安装是否成功打开 PowerShell 或 CMD输入下面命令ollama --version如果能显示类似下面的内容就说明安装成功ollama version is 0.x.x如果提示ollama 不是内部或外部命令大概率是安装时没有把路径写入系统的 PATH 环境变量。解决办法是找到 Ollama 安装目录一般是C:\Users\你的用户名\AppData\Local\Programs\Ollama手动把它加到 PATH 中然后重新打开终端。4.2 macOS 安装macOS 同样有两种方式官网下载.zip或者使用 Homebrew。brew install ollama安装完成后在终端先启动一次服务ollama serve另一个终端窗口中执行ollama --version验证。Apple Silicon 芯片的设备在安装 Ollama 后通常会自动调用 GPU 单元加速不需要额外配置。4.3 Linux 安装Linux 官方安装脚本通常是一行命令完成curl -fsSL https://ollama.com/install.sh | sh安装脚本会检测系统包管理器写入 systemd 服务并启动后台进程。如果你不希望直接执行远程脚本也可以选择 Docker 方式docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollamaDocker 方案的好处是环境隔离清晰重装系统后模型数据还在ollama卷里。注意宿主机上的11434端口要与容器映射一致。4.4 验证服务是否正常运行无论哪个平台安装完成后在浏览器打开http://127.0.0.1:11434如果能看到一个简单的返回文本表示 Ollama 服务本身是可访问的。不过此时还没有拉取模型直接交链会提示找不到模型这里只需要确认端口能通即可。5. 模型下载太慢怎么办换存储目录与本地导入Ollama 安装完成之后接下来会面对两个很现实的问题模型下载太慢、C 盘空间不够。这里给出两个不依赖网络加速工具的优化思路。5.1 设置 OLLAMA_MODELS把模型挪到其他盘Windows 上安装 Ollama 后模型默认存储在用户目录下的.ollama/models。如果 C 盘空间紧张可以先新建目标目录比如D:\ollama\models然后通过系统环境变量把模型存放位置指过去。操作步骤打开系统设置 → 系统 → 关于 → 高级系统设置。点击“环境变量”在用户变量或系统变量中新建变量OLLAMA_MODELS。变量值填写D:\ollama\models。保存后重启终端和 Ollama 后台服务。Linux 和 macOS 也可以用同样方式指定路径export OLLAMA_MODELS/data/ollama/models需要特别提醒的是环境变量设置完成后一定要重启 Ollama 进程。Windows 后台服务可以在任务管理器里找到 Ollama 后结束再重新启动即可。5.2 使用本地 GGUF 文件导入模型如果官方模型仓库的下载速度不理想有一点带宽不够稳定的情况下更为可控的做法是先从你能正常访问的模型托管平台下载好 GGUF 文件再用 Ollama 导入。这种方法适合国内网络环境、离线内网部署和需要固定版本模型的团队。先准备一个 Modelfile内容只需要一行指向 GGUF 文件的路径FROM /data/models/qwen2.5-7b-instruct-q4_k_m.gguf然后执行创建命令ollama create my-qwen -f ./Modelfile创建完成后再运行ollama run my-qwen这个流程等于把 Ollama 从一个“模型下载器”变成“模型加载器”。你不一定非要依赖ollama pull这一个途径。需要注意的是GGUF 文件必须与你想要的模型架构匹配且 Modelfile 中FROM的路径要写对。6. 本地部署实操拉取并运行一个 DeepSeek 模型前面说了不少准备知识现在到了最关键的一步——真正把一个大模型本地跑起来。为了降低门槛我会用 DeepSeek 系列的一个小参数模型做演示然后用同样的命令切换更大模型。6.1 拉取模型在终端输入ollama run deepseek-r1:1.5b第一次执行时Ollama 发现本地没有这个模型会自动开始拉取。拉取结束后直接进入交互界面。如果你的机器配置比较低可以先从deepseek-r1:1.5b开始等流程熟悉后再切换deepseek-r1:7b或更大参数版本。具体模型标签以 Ollama 模型库为准可以随时用ollama list查看已经拉取到本地的模型。6.2 进入对话模型下载完成后命令行会提示进入对话模式你直接输入中文或英文提问即可。比如输入用 Python 写一个读取 CSV 文件的函数输出文件行数。模型回复结束后如果要退出对话输入/bye6.3 常用模型管理命令# 查看本地已有模型 ollama list # 查看当前正在运行的模型及资源占用 ollama ps # 删除某个模型释放磁盘空间 ollama rm deepseek-r1:1.5b # 查看模型详细信息 ollama show deepseek-r1:1.5b6.4 连续对话切换模型把模型 A 换成模型 B不需要重启服务。先/bye退出当前对话再执行ollama run deepseek-r1:7b如果你在本地部署过多个模型这一步会明显体会到 Ollama 的便利不同模型之间切换很快不用手动管理进程。7. Ollama API 接口与大模型应用开发实战命令行聊天只是开始。真正让 Ollama 具备工程价值的是它能作为本地 API 服务被其他程序调用。从此开始你就可以把“大模型应用开发”变成“写代码调用本地接口”的过程。7.1 原生接口调用Ollama 默认服务地址是http://localhost:11434。先测试/api/generate接口curl http://localhost:11434/api/generate -d { model: deepseek-r1:1.5b, prompt: 用一句话介绍 Ollama, stream: false }stream设置为false后接口会等模型生成完整回答后一次性返回。Ollama原生接口还有很多参数可以调整比如temperature、top_p、max_tokens等。首次集成时建议把stream设为false方便调试确认功能跑通后再改成true实现流式输出。对话类任务更推荐使用/api/chat接口它可以携带多轮消息历史curl http://localhost:11434/api/chat -d { model: deepseek-r1:1.5b, messages: [ {role: user, content: 你好你是什么模型} ], stream: false }7.2 OpenAI 兼容接口现在很多大模型应用开发框架都默认使用 OpenAI 接口格式。Ollama 提供了一套兼容 OpenAI 风格的本地端点地址是http://localhost:11434/v1。curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d { model: deepseek-r1:1.5b, messages: [ {role: user, content: 写一个快速排序的 Python 实现} ] }注意这里不需要真实的 OpenAI Key因为只请求本地地址所以 Key 可以随便填一个非空字符串。7.3 Python 实现一个本地问答小应用下面这个例子是一个最简单的 Python 调用。它能证明“Ollama 开发框架”是可以跑通的后面你可以据此扩展成 web 后端、命令行工具或自动化脚本。import requests def ask_ollama(prompt: str, model: str deepseek-r1:1.5b) - str: url http://localhost:11434/api/chat payload { model: model, messages: [ {role: user, content: prompt} ], stream: False } resp requests.post(url, jsonpayload, timeout120) resp.raise_for_status() data resp.json() return data[message][content] if __name__ __main__: question 给我解释一下什么是本地部署大模型为什么这样做的数据更安全。 answer ask_ollama(question) print(answer)代码里最关键的是timeout120模型推理耗时会远高于普通 HTTP 请求不给超时时间很容易在批量任务中把请求中断。7.4 从接口到大模型应用开发的路线有了接口之后应用开发的想象空间就打开了写一个命令行工具读取文件内容后交给本地模型做摘要。写一个 Web 后端用同一个接口处理多个用户请求。在业务流程中调用模型做文本分类、实体抽取、翻译等任务模型跑在局域网内数据不会离开本机。接上 Dify、FastGPT 或自建知识库让 Ollama 变成内部知识问答的推理后端。这里先记住一个原则本地大模型应用开发并不等于“使用一个大模型”而是把模型服务和业务逻辑分开。Ollama 管模型生命周期你的代码管业务编排。8. Ollama 作为 AI 编程工具底座Opencode 与 Skill 联动最近 AI 编程工具非常火热像 Opencode、Codex、Claude Code 这类命令行编码 Agent 开始成为开发者的日常助手。这类工具大多支持接入自定义模型端点。把 Ollama 部署在本地后你可以让编码 Agent 请求本地模型而不需要把代码片段发送到外部 API。先解释一条链路Ollama 启动后就是一个本地模型服务端。Opencode 或类似工具相当于客户端它会读取一些模型提供方的配置然后把系统提示词、工具调用、上下文消息发送到模型服务。只要工具软件支持“OpenAI 兼容接口”或自定义 Base URL就能把请求指到http://localhost:11434/v1。8.1 通用接入思路在对接任意编码 Agent 工具之前建议先用 curl 验证 Ollama 的 OpenAI 兼容端点curl http://localhost:11434/v1/models如果返回 JSON 格式的模型列表说明本地模型的 OpenAI 兼容接口是正常的。接下来就根据你的编码工具文档设置 Base URL。常见环境变量方式是export OPENAI_BASE_URLhttp://localhost:11434/v1 export OPENAI_API_KEYollama具体字段名需要以实际工具文档为准这里只给通用示意。如果你使用的工具不识别这些环境变量就去找它的配置文件在模型提供方里新建一个自定义 Provider填入同样的 Base URL 和模型名。8.2 Skill 的本质是什么Skill 在编码 Agent 中被反复提及它的本质是把特定任务的操作步骤、提示词、工具调用规范整理成文本或脚本让模型遇到同类任务时按固定流程执行。比如“修改项目依赖版本后自动运行构建命令”“生成 API 文档模板”都可以做成 Skill。在本地 Ollama 环境中Skill 仍然存在只是它的存在和使用通常由 Opencode 这类外部工具管理跟 Ollama 之间通过消息和工具调用连接。Ollama 负责“听懂”用户意图Skill 负责把意图转换成可执行的步骤。8.3 最容易踩到的问题本地小模型虽然可以驱动 AI 编程工具但其指令遵循能力和代码生成质量无法与闭源大模型完全对标。如果你发现 Agent 频繁误解指令、改错代码文件不要急着怪工具很可能是当前模型参数太小。更实用的做法是让 Ollama 跑的模型承担“简单重复型”任务例如补全单测、翻译注释、生成基础代码结构代码审查、架构设计、跨文件重构等复杂任务仍然使用较强的云端模型。等到本机部署的中大型模型表现稳定后再把复杂任务切过来。9. 资源占用与性能观察本地部署模型时大家最关心的通常不是模型跑得准不准而是“我这台配置能跑吗”。这里不给出固定数值因为 OLLama 的显存占用高度依赖模型量化位宽、上下文长度和并发请求数。下面只讲观察方法和控制策略你可以按这套流程自己测量。9.1 观察显存占用当 Ollama 正在运行某个模型时在另一个终端执行ollama ps这个命令会列出当前加载到内存或显存中的模型列表也会显示处理器类型是 GPU、CPU 还是两者混合。除此之外NVIDIA 用户可以执行nvidia-smi关注Memory-Usage一栏能清楚看到 Ollama 进程占用的显存。注意一个问题Ollama 默认会把模型缓存在显存或内存中即使你已经结束了对话模型也可能继续占着资源直到超时。临时想释放显存可以执行ollama stop deepseek-r1:1.5b9.2 不同硬件规模下的部署策略纯 CPU 机器建议选择 1B 到 3B 范围内的量化模型响应速度还在可接受范围长文本任务会比较煎熬。8G 显存级别的独立显卡7B 模型量化版是常见选择同时尽量限制上下文长度避免显存飙升。16G 显存或更高可以尝试 13B 到 32B 模型的量化版本同时保持较长的上下文。Apple Silicon 统一内存设备内存越大跑大模型越轻松但仍取决于模型加载版本是否经过适配优化。9.3 降低资源占用的手段如果显存不足应用启动时报错优先检查下面几个方向换更小的模型或更低的量化版本。减小上下文长度比如把num_ctx从默认调低。关闭多余的模型进程。降低并发请求数不要同时让多个脚本猛烈请求同一个服务。如果确实需要更大参数模型考虑 CPU GPU 混合推理或纯 CPU 推理只是速度会更慢。9.4 服务进程管理如果你把 Ollama 当作本地服务长期运行可以使用ollama serve这个命令在前台启动服务。在 Windows 上安装后默认已经有一个后台进程在运行在 Linux 上systemd 会管理它。如果需要修改监听的地址和端口可以设置环境变量。修改后需要重启服务进程。export OLLAMA_HOST127.0.0.1:1143510. Ollama 常见问题与排查方法本地部署工具很多时候不是工具不行而是环境细节不对。下面把最常见的问题整理成表方便你出问题时直接对照。问题现象可能原因排查方式解决方案安装后ollama命令不存在PATH 未包含 Ollama 目录输入where ollama或检查安装目录手动把 Ollama 目录加入 PATH然后重启终端模型拉取失败或速度很慢网络波动、模型文件较大或源不稳定观察下载进度与网络状态检查磁盘空间使用能正常访问的镜像/托管平台下载 GGUF 文件后导入或设置OLLAMA_MODELS后重试ollama run提示找不到模型本地不存在该模型或模型名写错执行ollama list检查先拉取模型或修改模型标签为本地已有版本运行大模型时提示显存不足模型体积超过显存容量执行ollama ps和nvidia-smi查看占用换小模型、降低量化级别、降低上下文长度或关闭占用显存的其他进程浏览器打开 11434 端口无反应服务未启动或端口被占用检查进程列表、查看后台服务启动ollama serve或通过OLLAMA_HOST更换端口API 请求报 404 或超时接口路径写错或请求未设置超时用 curl 验证接口检查路径/api/generate、/api/chat为请求设置合理超时windows 环境变量修改后无效果环境变量在服务启动后生效确认变量名拼写、重启服务重启 Ollama 服务与终端代码调用 API 返回乱码或非 JSON请求头或 stream 参数配置不对查看返回原始文本加上Content-Type: application/json设置stream: false或改为 README 要求的请求格式推理速度很慢CPU 推理、模型过大或上下文过长查看ollama ps处理器类型调小模型、增加 GPU 驱动支持、减少上下文长度Agent 工具接本地模型后总是答非所问模型参数过小或工具调用格式不支持换一个模型测试切换参数更大的模型或在配置中开启工具调用相关的参数如果遇到表格里没覆盖的问题建议先查看 Ollama 的日志。前台启动时日志会直接打印在终端Windows 后台服务可以通过事件查看器或日志目录查看。日志里通常会给出更明确的报错原因。11. Ollama 部署最佳实践最后这部分是工程化建议。不管你是个人体验还是团队使用都会少踩很多坑。第一次使用某个新模型不要直接跑大参数版本。先拉一个最小可运行的模型例如 1.5B确认通信链路通畅、接口正常后再切换到目标模型。本地部署过程中最有价值的资产不是模型本身而是一套稳定的“最小可运行配置”包括 Python 版本、依赖清单、环境变量和可复现的命令。建议把目录按功能分开。设定一个根目录里面分别存放输入数据、输出结果、模型文件、脚本和日志。这样可以避免“跑起来不知道结果写哪”的混乱。批量任务场景下不要只写一个for循环就结束。建议在循环中增加日志、重试和失败隔离机制例如某一段文本请求失败后不要把整个任务中断。一个简单的带重试的 Python 模板如下import time import requests def infer_with_retry(prompt, modeldeepseek-r1:1.5b, max_retries3): url http://localhost:11434/api/generate payload {model: model, prompt: prompt, stream: False} for attempt in range(max_retries): try: resp requests.post(url, jsonpayload, timeout300) resp.raise_for_status() return resp.json()[response] except Exception as e: print(fattempt {attempt 1} failed: {e}) time.sleep(2 ** attempt) raise RuntimeError(failed after retries)对接端口时不要只监听0.0.0.0而忽略安全问题。如果 Ollama 服务只在本机使用把OLLAMA_HOST限制为127.0.0.1已经足够如果是局域网内共享建议不要直接暴露到公网。所有请求记录都要有日志方便追溯谁调用了模型、传入了什么内容。在合规方面本地部署模型不代表万事大吉。模型训练数据是否有授权、模型自身的许可证是否允许商用、生成结果是否包含敏感内容这些都需要在项目启动前确认。涉及真实用户隐私、商业机密和受版权保护素材时做好脱敏和访问控制绝不能让未经审查的内容和外部系统自由交互。发布任何基于大模型生成的内容之前建议先做一轮人工复核。本地小模型特别容易出现“看起来合理实则编造”的情况代码、文书、数据结果都不可直接信。12. 总结与下一步Ollama 的价值在于把“本地部署大模型”从一项需要折腾 CUDA、模型格式、API 服务的复杂工程精简成了一套可重复执行的命令工具链。你不需要从零理解模型加载细节只需要先把模型跑起来把接口调通再逐步接入自己的应用或编码工具。看完这篇教程第一步建议从ollama run deepseek-r1:1.5b开始。先完成本地问答再用 curl 请求一次/api/chat接着把文章里的 Python 脚本保存运行——当你在终端里看到程序返回了本地模型的答案整条链路就算跑通了。最容易踩的坑有三个一是模型下载速度不理想就放弃其实可以用 GGUF 文件导入二是显存不足时死磕大模型换小模型或降低上下文长度更稳妥三是把 Ollama 当成生产级调度平台结果遇到并发和批量问题其实它更适合做底座复杂的任务编排要交给上层代码或工具去完成。打完这一轮基础后续可以把模型扩展成 Qwen、Llama、Gemma 系列来对比效果也可以继续学习 Dify 接入 Ollama 做知识库问答或让 Opencode 这类 Agent 工具调用本地模型来完成代码任务。如果这篇文章对你有用建议收藏备用等实际部署时再回来按步骤操作。
Ollama零基础本地部署大模型教程：从安装到API接入与工具联动
在本地跑大模型这几年已经不是“极客专属”了。Ollama 刚好把“下载模型、运行模型、暴露 API、接入应用”这条链路串成了几条命令就能完成的事。无论你是想把 DeepSeek 这类开源模型部署到自己的电脑上还是准备做本地大模型应用开发都可以从 Ollama 入手。这篇教程会按照安装 → 找模型 → 本地部署 → 接口接入 → 工具联动 → 排错的顺序走一遍。标题里提到零基础那我就默认你暂时不理解“GGUF”“ShaardingPlan”这些概念也没关系——先能跑起来再慢慢消化原理。文章里所有命令都给出可复制的模板直接替换成你自己的路径和模型名即可。先看一眼这个工具到底能干什么Ollama 是一个开源的大语言模型本地运行工具提供命令行和后台服务。它主要负责两件事一是把模型文件统一管理起来二是提供一个本地 HTTP 服务让代码和第三方工具能通过标准接口调用模型。对普通用户来说装好之后只需要ollama run 模型名就能进入问答界面对开发者来说Ollama 的/api/chat和 OpenAI 兼容接口可以直接接入自己的应用。下面进入正题。1. Ollama 核心能力速览在安装之前先把 Ollama 的关键信息做一个整体梳理。这张表里的项目类型、启动方式、接口能力都是从项目本身和日常使用中归纳出来的硬件参数部分我尽量给区间而不是拍脑袋的数字。能力项说明项目类型开源大模型本地运行与管理工具主要功能模型下载、模型运行、交互问答、API 服务、模型导入导出支持平台Windows、macOS、Linux也可通过 Docker 部署是否支持 CPU支持小尺寸模型用 CPU 可运行速度明显慢于 GPU显卡支持NVIDIA GPU 支持较成熟AMD / Intel 与 Apple Silicon 需按版本适配情况测试显存需求由模型尺寸决定1.5B 到 7B 模型可在 6G 到 12G 显存范围内尝试显存不足时可回退 CPU 推理实际占用需按本机测试为准启动方式命令启动 本地后台服务安装后默认常驻服务管理模型默认服务端口11434可在环境变量中修改是否支持 API支持原生/api/generate、/api/chat接口并提供 OpenAI 兼容接口/v1是否支持批量任务本身不提供图形化任务队列但支持命令行和 HTTP 接口循环调用可自行编写批量脚本适合场景本地体验开源模型、离线环境部署、大模型应用开发、AI 编码工具本地底座、数据不出内网从能力速览可以看到Ollama 更像一个“模型运行底座”而不是一个大而全的网页应用。你要用的模型管理、服务启动、接口暴露它都管了具体的聊天界面、知识库、工作流都是接在它外层的东西。2. Ollama 适用场景与使用边界很多文章把 Ollama 吹得什么都能干实际上它更适合下面这些场景。适合你把 Ollama 当成“本地模型服务”来用的场景个人本机体验开源大模型比如跑 DeepSeek、Qwen、Llama 的量化版本。局域网内做模型服务不让数据离开公司内网。开发阶段调试提示词把 Ollama 当作后端接口服务前端写好界面就能换模型。作为 AI 编程工具的推理后端让本地模型承担代码补全或 Agent 对话任务。存放私有模型文件团队内部统一分发模型版本。不太适合的场景超大参数模型的在线高并发服务。60B 以上模型部署到单机后响应速度和并发能力都有限。对输出质量要求非常高的生产任务。本地量化模型的生成质量与云端旗舰 API 仍有差距。需要复杂知识库和流程编排的业务。Ollama 不提供知识库、工作流、多 Agent 管理这些需要搭配 Dify、FastGPT 或自己写编排代码。零显卡、低内存的老机器跑大模型。运行体验会很差不如直接使用云 API。使用边界和安全提醒不管你是用 Ollama 做个人工具、公司应用还是接入编码 Agent都必须注意几个底线问题第一下载模型时确认模型的许可证是否允许商用或二次分发尤其是从第三方渠道拿到的 GGUF 文件第二如果模型要处理用户上传的图片、文档、语音必须提前判断这些内容是否涉及他人隐私或保密信息不能把敏感数据随意外发到非可信环境第三用 Ollama 做自动化 Agent、内容生成或代码审查时生成结果需要人工复核避免大模型幻觉造成实际损失第四涉及人脸、声音、版权素材的生成必须确认授权不来源不明的数据绝不用于训练或生成。3. Ollama 环境准备与前置条件这个环节看起来很简单但很多新手卡在安装后跑不起来往往是环境前置没做好。下面按 Windows、macOS、Linux 三条线路分别给出检查清单。3.1 操作系统与版本Windows建议使用 Windows 10 及以上版本安装时最好以管理员身份运行安装包。macOS建议 macOS 12 以上Apple Silicon 芯片运行体验更顺滑Intel 芯片也能装速度要慢不少。Linux建议 Ubuntu 20.04 或 Debian 10 以上的发行版安装脚本会识别主流 Linux 环境。3.2 GPU 与驱动这是最容易出问题的一环。Ollama 使用 GPU 推理之前会先检测系统驱动。如果你用的是 NVIDIA 显卡建议先更新到当前可用的最新驱动。不需要手动装完整 CUDA ToolkitOllama 自带相关的运行依赖集成你只要保证驱动版本足够新。如果你没有独立显卡或者显存只有 4G 以下不用直接放弃。选择 1B、1.5B、3B 这类小模型使用 CPU 推理是完全可以跑的。Intel 核显和 AMD 核显的适配情况会随着版本更新变化稳妥的做法是先去官网或模型页确认当前版本的官方支持矩阵。3.3 磁盘空间大模型文件通常以 GB 为单位。一个 7B 模型量化后约为 4G 到 5G一个 14B 模型约为 8G 到 10G一个 70B 模型可能超过 40G。所以安装前先执行磁盘空间检查# Windows 可在资源管理器中查看或用 PowerShell Get-PSDrive -Name C # Linux / macOS df -h装多个模型之前预留 20G 以上的磁盘空间是比较舒服的。如果 C 盘空间吃紧后续可以通过设置OLLAMA_MODELS环境变量把模型存储位置挪到其他盘。3.4 端口规划Ollama 默认监听11434。如果你本机已经装了其他服务占用这个端口或者 Docker 容器端口冲突轻则连接失败重则服务起不来。启动前可以先确认端口状态# Windows netstat -ano | findstr 11434 # Linux / macOS lsof -i :11434有输出就说明端口被占用。后面会说明如何通过OLLAMA_HOST换一个端口。4. Ollama 下载安装Windows、macOS、LinuxOllama 的安装本质上是把ollama主程序和后台服务装到系统里。安装完成之后模型文件并不包含在内你仍然需要单独拉取或导入模型。4.1 Windows 安装Windows 用户的安装路径最直接从 Ollama 官网点击 Download 按钮下载 Windows 安装包文件然后双击安装即可。安装完成之后系统通常会自动启动 Ollama 后台服务。验证安装是否成功打开 PowerShell 或 CMD输入下面命令ollama --version如果能显示类似下面的内容就说明安装成功ollama version is 0.x.x如果提示ollama 不是内部或外部命令大概率是安装时没有把路径写入系统的 PATH 环境变量。解决办法是找到 Ollama 安装目录一般是C:\Users\你的用户名\AppData\Local\Programs\Ollama手动把它加到 PATH 中然后重新打开终端。4.2 macOS 安装macOS 同样有两种方式官网下载.zip或者使用 Homebrew。brew install ollama安装完成后在终端先启动一次服务ollama serve另一个终端窗口中执行ollama --version验证。Apple Silicon 芯片的设备在安装 Ollama 后通常会自动调用 GPU 单元加速不需要额外配置。4.3 Linux 安装Linux 官方安装脚本通常是一行命令完成curl -fsSL https://ollama.com/install.sh | sh安装脚本会检测系统包管理器写入 systemd 服务并启动后台进程。如果你不希望直接执行远程脚本也可以选择 Docker 方式docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollamaDocker 方案的好处是环境隔离清晰重装系统后模型数据还在ollama卷里。注意宿主机上的11434端口要与容器映射一致。4.4 验证服务是否正常运行无论哪个平台安装完成后在浏览器打开http://127.0.0.1:11434如果能看到一个简单的返回文本表示 Ollama 服务本身是可访问的。不过此时还没有拉取模型直接交链会提示找不到模型这里只需要确认端口能通即可。5. 模型下载太慢怎么办换存储目录与本地导入Ollama 安装完成之后接下来会面对两个很现实的问题模型下载太慢、C 盘空间不够。这里给出两个不依赖网络加速工具的优化思路。5.1 设置 OLLAMA_MODELS把模型挪到其他盘Windows 上安装 Ollama 后模型默认存储在用户目录下的.ollama/models。如果 C 盘空间紧张可以先新建目标目录比如D:\ollama\models然后通过系统环境变量把模型存放位置指过去。操作步骤打开系统设置 → 系统 → 关于 → 高级系统设置。点击“环境变量”在用户变量或系统变量中新建变量OLLAMA_MODELS。变量值填写D:\ollama\models。保存后重启终端和 Ollama 后台服务。Linux 和 macOS 也可以用同样方式指定路径export OLLAMA_MODELS/data/ollama/models需要特别提醒的是环境变量设置完成后一定要重启 Ollama 进程。Windows 后台服务可以在任务管理器里找到 Ollama 后结束再重新启动即可。5.2 使用本地 GGUF 文件导入模型如果官方模型仓库的下载速度不理想有一点带宽不够稳定的情况下更为可控的做法是先从你能正常访问的模型托管平台下载好 GGUF 文件再用 Ollama 导入。这种方法适合国内网络环境、离线内网部署和需要固定版本模型的团队。先准备一个 Modelfile内容只需要一行指向 GGUF 文件的路径FROM /data/models/qwen2.5-7b-instruct-q4_k_m.gguf然后执行创建命令ollama create my-qwen -f ./Modelfile创建完成后再运行ollama run my-qwen这个流程等于把 Ollama 从一个“模型下载器”变成“模型加载器”。你不一定非要依赖ollama pull这一个途径。需要注意的是GGUF 文件必须与你想要的模型架构匹配且 Modelfile 中FROM的路径要写对。6. 本地部署实操拉取并运行一个 DeepSeek 模型前面说了不少准备知识现在到了最关键的一步——真正把一个大模型本地跑起来。为了降低门槛我会用 DeepSeek 系列的一个小参数模型做演示然后用同样的命令切换更大模型。6.1 拉取模型在终端输入ollama run deepseek-r1:1.5b第一次执行时Ollama 发现本地没有这个模型会自动开始拉取。拉取结束后直接进入交互界面。如果你的机器配置比较低可以先从deepseek-r1:1.5b开始等流程熟悉后再切换deepseek-r1:7b或更大参数版本。具体模型标签以 Ollama 模型库为准可以随时用ollama list查看已经拉取到本地的模型。6.2 进入对话模型下载完成后命令行会提示进入对话模式你直接输入中文或英文提问即可。比如输入用 Python 写一个读取 CSV 文件的函数输出文件行数。模型回复结束后如果要退出对话输入/bye6.3 常用模型管理命令# 查看本地已有模型 ollama list # 查看当前正在运行的模型及资源占用 ollama ps # 删除某个模型释放磁盘空间 ollama rm deepseek-r1:1.5b # 查看模型详细信息 ollama show deepseek-r1:1.5b6.4 连续对话切换模型把模型 A 换成模型 B不需要重启服务。先/bye退出当前对话再执行ollama run deepseek-r1:7b如果你在本地部署过多个模型这一步会明显体会到 Ollama 的便利不同模型之间切换很快不用手动管理进程。7. Ollama API 接口与大模型应用开发实战命令行聊天只是开始。真正让 Ollama 具备工程价值的是它能作为本地 API 服务被其他程序调用。从此开始你就可以把“大模型应用开发”变成“写代码调用本地接口”的过程。7.1 原生接口调用Ollama 默认服务地址是http://localhost:11434。先测试/api/generate接口curl http://localhost:11434/api/generate -d { model: deepseek-r1:1.5b, prompt: 用一句话介绍 Ollama, stream: false }stream设置为false后接口会等模型生成完整回答后一次性返回。Ollama原生接口还有很多参数可以调整比如temperature、top_p、max_tokens等。首次集成时建议把stream设为false方便调试确认功能跑通后再改成true实现流式输出。对话类任务更推荐使用/api/chat接口它可以携带多轮消息历史curl http://localhost:11434/api/chat -d { model: deepseek-r1:1.5b, messages: [ {role: user, content: 你好你是什么模型} ], stream: false }7.2 OpenAI 兼容接口现在很多大模型应用开发框架都默认使用 OpenAI 接口格式。Ollama 提供了一套兼容 OpenAI 风格的本地端点地址是http://localhost:11434/v1。curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d { model: deepseek-r1:1.5b, messages: [ {role: user, content: 写一个快速排序的 Python 实现} ] }注意这里不需要真实的 OpenAI Key因为只请求本地地址所以 Key 可以随便填一个非空字符串。7.3 Python 实现一个本地问答小应用下面这个例子是一个最简单的 Python 调用。它能证明“Ollama 开发框架”是可以跑通的后面你可以据此扩展成 web 后端、命令行工具或自动化脚本。import requests def ask_ollama(prompt: str, model: str deepseek-r1:1.5b) - str: url http://localhost:11434/api/chat payload { model: model, messages: [ {role: user, content: prompt} ], stream: False } resp requests.post(url, jsonpayload, timeout120) resp.raise_for_status() data resp.json() return data[message][content] if __name__ __main__: question 给我解释一下什么是本地部署大模型为什么这样做的数据更安全。 answer ask_ollama(question) print(answer)代码里最关键的是timeout120模型推理耗时会远高于普通 HTTP 请求不给超时时间很容易在批量任务中把请求中断。7.4 从接口到大模型应用开发的路线有了接口之后应用开发的想象空间就打开了写一个命令行工具读取文件内容后交给本地模型做摘要。写一个 Web 后端用同一个接口处理多个用户请求。在业务流程中调用模型做文本分类、实体抽取、翻译等任务模型跑在局域网内数据不会离开本机。接上 Dify、FastGPT 或自建知识库让 Ollama 变成内部知识问答的推理后端。这里先记住一个原则本地大模型应用开发并不等于“使用一个大模型”而是把模型服务和业务逻辑分开。Ollama 管模型生命周期你的代码管业务编排。8. Ollama 作为 AI 编程工具底座Opencode 与 Skill 联动最近 AI 编程工具非常火热像 Opencode、Codex、Claude Code 这类命令行编码 Agent 开始成为开发者的日常助手。这类工具大多支持接入自定义模型端点。把 Ollama 部署在本地后你可以让编码 Agent 请求本地模型而不需要把代码片段发送到外部 API。先解释一条链路Ollama 启动后就是一个本地模型服务端。Opencode 或类似工具相当于客户端它会读取一些模型提供方的配置然后把系统提示词、工具调用、上下文消息发送到模型服务。只要工具软件支持“OpenAI 兼容接口”或自定义 Base URL就能把请求指到http://localhost:11434/v1。8.1 通用接入思路在对接任意编码 Agent 工具之前建议先用 curl 验证 Ollama 的 OpenAI 兼容端点curl http://localhost:11434/v1/models如果返回 JSON 格式的模型列表说明本地模型的 OpenAI 兼容接口是正常的。接下来就根据你的编码工具文档设置 Base URL。常见环境变量方式是export OPENAI_BASE_URLhttp://localhost:11434/v1 export OPENAI_API_KEYollama具体字段名需要以实际工具文档为准这里只给通用示意。如果你使用的工具不识别这些环境变量就去找它的配置文件在模型提供方里新建一个自定义 Provider填入同样的 Base URL 和模型名。8.2 Skill 的本质是什么Skill 在编码 Agent 中被反复提及它的本质是把特定任务的操作步骤、提示词、工具调用规范整理成文本或脚本让模型遇到同类任务时按固定流程执行。比如“修改项目依赖版本后自动运行构建命令”“生成 API 文档模板”都可以做成 Skill。在本地 Ollama 环境中Skill 仍然存在只是它的存在和使用通常由 Opencode 这类外部工具管理跟 Ollama 之间通过消息和工具调用连接。Ollama 负责“听懂”用户意图Skill 负责把意图转换成可执行的步骤。8.3 最容易踩到的问题本地小模型虽然可以驱动 AI 编程工具但其指令遵循能力和代码生成质量无法与闭源大模型完全对标。如果你发现 Agent 频繁误解指令、改错代码文件不要急着怪工具很可能是当前模型参数太小。更实用的做法是让 Ollama 跑的模型承担“简单重复型”任务例如补全单测、翻译注释、生成基础代码结构代码审查、架构设计、跨文件重构等复杂任务仍然使用较强的云端模型。等到本机部署的中大型模型表现稳定后再把复杂任务切过来。9. 资源占用与性能观察本地部署模型时大家最关心的通常不是模型跑得准不准而是“我这台配置能跑吗”。这里不给出固定数值因为 OLLama 的显存占用高度依赖模型量化位宽、上下文长度和并发请求数。下面只讲观察方法和控制策略你可以按这套流程自己测量。9.1 观察显存占用当 Ollama 正在运行某个模型时在另一个终端执行ollama ps这个命令会列出当前加载到内存或显存中的模型列表也会显示处理器类型是 GPU、CPU 还是两者混合。除此之外NVIDIA 用户可以执行nvidia-smi关注Memory-Usage一栏能清楚看到 Ollama 进程占用的显存。注意一个问题Ollama 默认会把模型缓存在显存或内存中即使你已经结束了对话模型也可能继续占着资源直到超时。临时想释放显存可以执行ollama stop deepseek-r1:1.5b9.2 不同硬件规模下的部署策略纯 CPU 机器建议选择 1B 到 3B 范围内的量化模型响应速度还在可接受范围长文本任务会比较煎熬。8G 显存级别的独立显卡7B 模型量化版是常见选择同时尽量限制上下文长度避免显存飙升。16G 显存或更高可以尝试 13B 到 32B 模型的量化版本同时保持较长的上下文。Apple Silicon 统一内存设备内存越大跑大模型越轻松但仍取决于模型加载版本是否经过适配优化。9.3 降低资源占用的手段如果显存不足应用启动时报错优先检查下面几个方向换更小的模型或更低的量化版本。减小上下文长度比如把num_ctx从默认调低。关闭多余的模型进程。降低并发请求数不要同时让多个脚本猛烈请求同一个服务。如果确实需要更大参数模型考虑 CPU GPU 混合推理或纯 CPU 推理只是速度会更慢。9.4 服务进程管理如果你把 Ollama 当作本地服务长期运行可以使用ollama serve这个命令在前台启动服务。在 Windows 上安装后默认已经有一个后台进程在运行在 Linux 上systemd 会管理它。如果需要修改监听的地址和端口可以设置环境变量。修改后需要重启服务进程。export OLLAMA_HOST127.0.0.1:1143510. Ollama 常见问题与排查方法本地部署工具很多时候不是工具不行而是环境细节不对。下面把最常见的问题整理成表方便你出问题时直接对照。问题现象可能原因排查方式解决方案安装后ollama命令不存在PATH 未包含 Ollama 目录输入where ollama或检查安装目录手动把 Ollama 目录加入 PATH然后重启终端模型拉取失败或速度很慢网络波动、模型文件较大或源不稳定观察下载进度与网络状态检查磁盘空间使用能正常访问的镜像/托管平台下载 GGUF 文件后导入或设置OLLAMA_MODELS后重试ollama run提示找不到模型本地不存在该模型或模型名写错执行ollama list检查先拉取模型或修改模型标签为本地已有版本运行大模型时提示显存不足模型体积超过显存容量执行ollama ps和nvidia-smi查看占用换小模型、降低量化级别、降低上下文长度或关闭占用显存的其他进程浏览器打开 11434 端口无反应服务未启动或端口被占用检查进程列表、查看后台服务启动ollama serve或通过OLLAMA_HOST更换端口API 请求报 404 或超时接口路径写错或请求未设置超时用 curl 验证接口检查路径/api/generate、/api/chat为请求设置合理超时windows 环境变量修改后无效果环境变量在服务启动后生效确认变量名拼写、重启服务重启 Ollama 服务与终端代码调用 API 返回乱码或非 JSON请求头或 stream 参数配置不对查看返回原始文本加上Content-Type: application/json设置stream: false或改为 README 要求的请求格式推理速度很慢CPU 推理、模型过大或上下文过长查看ollama ps处理器类型调小模型、增加 GPU 驱动支持、减少上下文长度Agent 工具接本地模型后总是答非所问模型参数过小或工具调用格式不支持换一个模型测试切换参数更大的模型或在配置中开启工具调用相关的参数如果遇到表格里没覆盖的问题建议先查看 Ollama 的日志。前台启动时日志会直接打印在终端Windows 后台服务可以通过事件查看器或日志目录查看。日志里通常会给出更明确的报错原因。11. Ollama 部署最佳实践最后这部分是工程化建议。不管你是个人体验还是团队使用都会少踩很多坑。第一次使用某个新模型不要直接跑大参数版本。先拉一个最小可运行的模型例如 1.5B确认通信链路通畅、接口正常后再切换到目标模型。本地部署过程中最有价值的资产不是模型本身而是一套稳定的“最小可运行配置”包括 Python 版本、依赖清单、环境变量和可复现的命令。建议把目录按功能分开。设定一个根目录里面分别存放输入数据、输出结果、模型文件、脚本和日志。这样可以避免“跑起来不知道结果写哪”的混乱。批量任务场景下不要只写一个for循环就结束。建议在循环中增加日志、重试和失败隔离机制例如某一段文本请求失败后不要把整个任务中断。一个简单的带重试的 Python 模板如下import time import requests def infer_with_retry(prompt, modeldeepseek-r1:1.5b, max_retries3): url http://localhost:11434/api/generate payload {model: model, prompt: prompt, stream: False} for attempt in range(max_retries): try: resp requests.post(url, jsonpayload, timeout300) resp.raise_for_status() return resp.json()[response] except Exception as e: print(fattempt {attempt 1} failed: {e}) time.sleep(2 ** attempt) raise RuntimeError(failed after retries)对接端口时不要只监听0.0.0.0而忽略安全问题。如果 Ollama 服务只在本机使用把OLLAMA_HOST限制为127.0.0.1已经足够如果是局域网内共享建议不要直接暴露到公网。所有请求记录都要有日志方便追溯谁调用了模型、传入了什么内容。在合规方面本地部署模型不代表万事大吉。模型训练数据是否有授权、模型自身的许可证是否允许商用、生成结果是否包含敏感内容这些都需要在项目启动前确认。涉及真实用户隐私、商业机密和受版权保护素材时做好脱敏和访问控制绝不能让未经审查的内容和外部系统自由交互。发布任何基于大模型生成的内容之前建议先做一轮人工复核。本地小模型特别容易出现“看起来合理实则编造”的情况代码、文书、数据结果都不可直接信。12. 总结与下一步Ollama 的价值在于把“本地部署大模型”从一项需要折腾 CUDA、模型格式、API 服务的复杂工程精简成了一套可重复执行的命令工具链。你不需要从零理解模型加载细节只需要先把模型跑起来把接口调通再逐步接入自己的应用或编码工具。看完这篇教程第一步建议从ollama run deepseek-r1:1.5b开始。先完成本地问答再用 curl 请求一次/api/chat接着把文章里的 Python 脚本保存运行——当你在终端里看到程序返回了本地模型的答案整条链路就算跑通了。最容易踩的坑有三个一是模型下载速度不理想就放弃其实可以用 GGUF 文件导入二是显存不足时死磕大模型换小模型或降低上下文长度更稳妥三是把 Ollama 当成生产级调度平台结果遇到并发和批量问题其实它更适合做底座复杂的任务编排要交给上层代码或工具去完成。打完这一轮基础后续可以把模型扩展成 Qwen、Llama、Gemma 系列来对比效果也可以继续学习 Dify 接入 Ollama 做知识库问答或让 Opencode 这类 Agent 工具调用本地模型来完成代码任务。如果这篇文章对你有用建议收藏备用等实际部署时再回来按步骤操作。
