如果你最近开始接触大模型应用开发大概率会被同一个问题卡住想跑个开源模型练手又要 Python 环境、又要显卡驱动、又要配置模型依赖还没开始写代码就先被环境磨掉一半耐心。另一条路是直接调云端 API注册、实名、充值思路总是被打断还担心调试时把不该传的数据传出去。这里有一个非常值得优先了解的答案Ollama。它把“下载模型、启动服务、调用接口”压缩成了几条命令是目前本地部署大语言模型最接近“开箱即用”的工具。这篇文章就是一份面向零基础读者的保姆级教程从下载安装、模型管理到用本地模型做应用开发再把它接入 OpenCode 这类编程 Agent 并理解 Skill 的含义一次性跑通完整链路。先说判断Ollama 不是又一款“AI 玩具”而是本地大模型时代的基础设施层。它解决的问题非常具体——你不需要理解模型权重如何加载、KV Cache 如何分配也能在本地拥有一台可调用的模型服务。读完后你不仅能独立装好 Ollama还会知道如何用 OpenAI 兼容接口写自己的第一行本地大模型应用代码以及为什么 OpenCode Ollama 会成为越来越多开发者的日常组合。1. 为什么大家都在说 Ollama、本地部署和大模型应用开发把时间拨回到两年前想在自己电脑上运行一个有对话能力的模型难度比现在高一个数量级。你需要手动下载权重文件自己写加载逻辑甚至要懂显存管理。而现在开源社区把这条路几乎铺平了。Ollama 在这一轮“本地部署大模型”热潮中扮演的角色可以类比 Docker 之于容器它不一定是最底层的技术但它把复杂操作封装成了统一入口。你不需要关心模型文件放在哪里、推理服务怎么启动只需要两条命令ollama pull下载模型ollama run启动对话。很多人在搜索“Ollama 下载太慢怎么解决”“Ollama 国内镜像源”时真正想要的并不是某个镜像地址而是一条顺畅的本地大模型学习路径。这也是为什么标题里常常同时出现“Ollama 本地部署 大模型应用开发”它们是同一条链路的前后环节。当然不是所有场景都适合本地部署。这张表可以帮你快速判断场景是否适合 Ollama 本地部署原因学习大模型开发、跑通示例非常适合环境统一命令简单调试成本低代码片段需要严格保密非常适合数据不出本机不经过外部 API需要持续离线运行适合模型下载完成后可以完全离线推理需要超大模型70B 以上效果不太适合本地硬件通常无法流畅运行需要非常强的多语言、长文本能力看情况可以用 7B~32B 模型验证再切云端团队需要统一模型服务适合可以在一台 GPU 服务器上提供服务从搜索结果里能看到“OpenCode”“Codex 本地部署”“本地部署 DeepSeek”这类词热度很高。这说明很多人已经不只是想聊天而是想跑通“写作代码、被 Agent 调用、完成任务”的完整工作流。Ollama 恰好是这个链条里最容易上手的一环。2. Ollama 核心概念与工作原理2.1 Ollama 到底是什么严格来说Ollama 是一个本地推理服务管理工具。它并不训练模型也不自带模型能力而是负责三件事模型分发从模型库拉取开源模型管理本地已下载的模型文件。推理服务启动一个本地 HTTP 服务默认监听11434端口接收请求并返回模型结果。客户端入口通过ollama run这类命令直接与模型对话。换句话说你在终端里和模型对话时实际流程是你的输入 - Ollama 客户端 - Ollama 服务 - 本地模型 - 返回文本。这个设计非常重要因为“本地运行”意味着即使断网只要模型已经下载到本地你依然可以正常使用。2.2 基础概念模型、Tag、Modelfile模型ModelOllama 中的模型以名字标识例如deepseek-r1、qwen2.5。这些名字对应的是经过量化和打包后的开源模型权重。Tag标签同一个模型可以有多个版本例如deepseek-r1:7b、deepseek-r1:14b。标签用来区分参数量、量化方式。Modelfile类似 Dockerfile 的描述文件。它不包含模型权重而是描述“如何组装一个自定义模型”例如指定基础模型、设定 system prompt、调整温度参数等。不要一上来就啃 Modelfile 的完整语法。先把“拉取模型、运行模型、调用接口”跑通再回来看自定义组装会容易得多。2.3 Ollama 在应用开发中的位置大模型应用开发通常分为两层模型层和应用层。模型层负责推理应用层负责业务逻辑。Ollama 属于模型层但它最聪明的地方是提供了一个 OpenAI 兼容的接口。这意味着你之前用openaiPython SDK 写的代码只要把base_url从云端地址改成http://localhost:11434/v1就能把请求转发给本地模型。这种兼容策略极大降低了迁移成本也让 Dify、OpenCode、Cline、Continue 这类工具不需要为 Ollama 单独定制接口就能直接使用本地模型。3. 环境准备与前置条件在开始安装之前先强调一个结论安装 Ollama 本身门槛极低真正影响体验的是硬件尤其是内存和显卡。官方支持的操作系统包括Windows 10 及以上macOS 11 及以上Apple Silicon 芯片体验更好主流 Linux 发行版Ubuntu、Debuan、CentOS 等硬件建议按用途区分用途最低配置建议配置跑通命令、简单对话8GB 内存无独显16GB 内存运行 7B~8B 模型并流畅对话16GB 内存20GB 以上内存或 8GB 显存显卡运行 13B~14B 模型16GB 内存24GB 以上内存或 12GB 以上显存显卡运行 32B 模型32GB 内存独立显卡 24GB 显存如果机器只有一个 CPU没有 NVIDIA/AMD 显卡也不是不能用。Ollama 会退回到 CPU 模式速度慢一些但对于体验流程和编写示例代码完全足够。本文不会写死某个具体版本号因为 Ollama 迭代很快建议以官网或 GitHub Releases 当前发布版本为准。4. Ollama 下载安装Windows、macOS、Linux 保姆级步骤4.1 Windows 安装Windows 用户最稳妥的方式是打开 ollama.com/download 下载 Windows 安装包文件通常命名为OllamaSetup.exe。下载完成后双击运行安装程序会默认把 Ollama 安装到当前用户目录不需要勾选复杂选项。安装完成后打开一个新的 PowerShell 或 CMD 窗口输入ollama --version如果能输出版本号说明安装成功。如果你的 D 盘空间充足想避免模型占满 C 盘可以参考下文“把模型目录改到其他盘”一节。很多人在搜索“Ollama 怎么安装到 D 盘”时遇到的就是这个问题本质上不是安装路径而是模型存储路径。4.2 macOS 安装macOS 用户同样从官网下载.zip压缩包解压后把Ollama.app拖入“应用程序”文件夹即可。首次启动时macOS 可能会提示“无法打开因为无法验证开发者”此时可以进入“系统设置 - 隐私与安全性”点击“仍要打开”。如果使用的是 Apple Silicon 芯片Ollama 会默认使用 Metal 加速效果通常不错。打开终端验证ollama --version如果提示command not found先确认是否已经在“应用程序”中运行过 Ollama。图形界面启动后命令行工具会被自动加入 PATH。4.3 Linux 安装Linux 用户通常使用官方安装脚本curl -fsSL https://ollama.com/install.sh | sh这个命令会下载脚本并自动安装。如果机器没有外网访问条件可以换一种方式从 GitHub Releases 页面手动下载对应架构的二进制包解压后把ollama可执行文件放到/usr/local/bin/目录。安装后启动服务ollama serve服务默认监听127.0.0.1:11434。如果终端显示类似listening on 127.0.0.1:11434的日志说明服务已正常启动。4.4 国内网络下载慢的思路与误区“Ollama 下载太慢了”是高频搜索词。这里要分清楚下载慢可能发生在两个阶段一个是安装包下载慢另一个是模型文件下载慢。对于安装包下载慢如果官网访问不稳定可以从 GitHub Releases 下载也可以等网络空闲时段重试。对于模型下载慢需要先明确一个事实Ollama 并没有官方国内镜像源。网上流传的所谓“Ollama 国内镜像”大多数是第三方加速项目稳定性无法保证不建议在重要环境依赖。更稳妥的替代方案是“手动导入模型”。你可以在国内模型社区下载 GGUF 格式的模型文件比如从 ModelScope 下载qwen2.5-7b-instruct-gguf或deepseek-r1-7b-gguf然后在本地编写一个极简 Modelfile把模型导入 Ollama。这部分操作放在第 5 章后面详细说明。4.5 把模型存储目录改到其他盘Windows 下 Ollama 默认将模型存放在C:\Users\你的用户名\.ollama\models很容易让 C 盘空间告急。正确做法是设置环境变量OLLAMA_MODELS。右键“此电脑” - “属性” - “高级系统设置”。点击“环境变量”。在“用户变量”中新建变量变量名OLLAMA_MODELS变量值D:\ollama\models保存后关闭所有命令行窗口重新打开。之后执行ollama pull时模型会下载到新的目录。如果在设置前已经下载过模型可以把旧目录里的文件移动到新目录避免重复下载。5. 下载模型、启动对话与手动导入5.1 下载模型Ollama 安装成功后先拉取一个适合零基础入门的模型。从网络热度看DeepSeek 系列是很好的选择ollama pull deepseek-r1:7b如果更看重中文理解和通用对话也可以选择ollama pull qwen2.5:7b可以同时下载多个模型Ollama 会按名称区分。查看本地已有哪些模型ollama list结果类似NAME ID SIZE MODIFIED deepseek-r1:7b xxxxxxxx 4.7 GB ... qwen2.5:7b yyyyyyyy 4.8 GB ...5.2 对话体验下载完成后直接运行ollama run qwen2.5:7b进入交互式终端后输入问题即可看到回复。输入/bye退出。常见的内置指令包括/bye退出当前对话/clear清空上下文/show info查看当前模型信息/set temperature 0.7调整随机性这里要解释一个新手容易误解的地方ollama run的交互式对话会保留上下文。也就是说当你追问“刚才那句话是什么意思”时模型是能结合前文回答的除非显式执行/clear。5.3 手动导入 GGUF 模型如果你已经通过模型社区下载了 GGUF 文件例如qwen2.5-7b-instruct-q4_k_m.gguf则可以这样导入。先编写一个 Modelfile假设文件放在模型同目录FROM ./qwen2.5-7b-instruct-q4_k_m.gguf # 设定一个温和的系统提示词 SYSTEM 你是一个乐于助人的 AI 助手。请简洁、准确地回答问题。然后执行导入ollama create my-qwen -f Modelfile创建成功后用ollama list就能看到名为my-qwen的模型可以像其他模型一样运行ollama run my-qwen这种方式的优势是绕开 Ollama 官方仓库下载瓶颈特别适合内网环境或模型发布源不在官方仓库的场景。6. 大模型应用开发第一步调用本地模型接口很多初学者容易卡在“模型跑起来了但怎么在代码里用它”。这一步我们把 Ollama 的 OpenAI 兼容接口用起来这实际上就是大模型应用开发的第一行代码。6.1 确认服务状态先确认 Ollama 服务正在运行。如果是通过桌面应用启动或者已经执行过ollama run服务一般已经在后台运行。可以用 curl 检查curl http://localhost:11434/v1/models如果服务正常会返回一个包含模型列表的 JSON。如果提示拒绝连接先手动执行ollama serve保持该终端窗口不要关闭另开一个终端继续操作。6.2 使用 Python 编写请求代码日常开发中更推荐用 Python 的requests库直接调用逻辑清晰且不引入额外依赖。新建文件test_ollama.pyimport requests import json url http://localhost:11434/v1/chat/completions payload { model: qwen2.5:7b, messages: [ {role: system, content: 你是一个简洁的助手只用一句话回答。}, {role: user, content: 用一句话解释什么是大模型微调。} ], stream: False } resp requests.post(url, jsonpayload, timeout120) data resp.json() print(data[choices][0][message][content])运行python test_ollama.py这段代码主要有三个关键点url指向/v1/chat/completions这是 OpenAI 协议的对话补全端点。model必须是ollama list里存在的模型名。stream设置为False方便第一次调试时直接打印完整结果。如果你想在真实项目中统一用openaiSDK只需设置base_urlfrom openai import OpenAI client OpenAI( base_urlhttp://localhost:11434/v1, api_keyollama # 本地服务不校验但格式上需要填一个值 ) response client.chat.completions.create( modelqwen2.5:7b, messages[{role: user, content: 你好请介绍你自己。}] ) print(response.choices[0].message.content)这种方式的好处是以后想从本地模型切换到云端 API只需要改base_url、api_key和model业务代码几乎不用动。6.3 流式输出示例对话聊天类应用通常需要边生成边输出。把stream改成True逐行读取返回内容import requests url http://localhost:11434/v1/chat/completions payload { model: qwen2.5:7b, messages: [{role: user, content: 写一段 200 字的春天描写。}], stream: True } resp requests.post(url, jsonpayload, streamTrue, timeout120) for line in resp.iter_lines(): if not line: continue # 流式返回的每一行以 data: 开头 text line.decode(utf-8) if text.startswith(data: ): content text[6:] if content [DONE]: break try: import json obj json.loads(content) delta obj[choices][0][delta].get(content, ) print(delta, end, flushTrue) except json.JSONDecodeError: continue这里的核心逻辑是解析data:前缀的行并在遇到[DONE]时结束。如果第一次运行报错优先检查模型名是否写错以及 Ollama 服务是否在后台运行。7. 实战把 Ollama 接入 OpenCode理解 Skill 的用途当本地模型可以被 Python 调用后你已经完成了大模型应用开发中最基础的闭环。但最近热度更高的玩法是把本地模型接入编程 Agent例如 OpenCode。这也是标题里“AI大模型 / OpenCode / Skill”这几个关键词所在的层面。7.1 OpenCode 是什么为什么需要它OpenCode 是终端里运行的 AI 编程代理工具。它的定位和 Claude Code、Codex 类似你告诉它一个任务比如“修复这个项目的测试失败”它会自己读取代码、定位原因、修改文件再告诉你改动结果。很多开发者关心“OpenCode 免费模型”“OpenCode 怎么接入 Ollama”背后的原因是编程 Agent 如果一直调用云端大模型成本高且代码可能被发送到外部服务。接入 Ollama 后模型在本地运行代码不出本机这对隐私敏感的项目很有吸引力。7.2 安装 OpenCode安装方式以官方文档为准常见做法是通过 npm 全局安装npm install -g opencode-ai安装后检查版本opencode --version如果你更习惯在 VS Code 里使用也可以安装对应的 OpenCode 扩展。从社区讨论来看OpenCode 和 VS Code 的集成度不错可以直接在编辑器里查看 Agent 的改动。7.3 配置 OpenCode 使用 Ollama 本地模型OpenCode 的配置文件一般位于~/.config/opencode/opencode.json。下面是一个把 Ollama 作为 Provider 的最简配置{ $schema: https://opencode.ai/config.json, provider: { ollama: { models: { qwen2.5-coder:7b: {} } } }, model: qwen2.5-coder:7b }如果你希望模型支持更长的代码理解上下文可以在模型配置中增加options{ provider: { ollama: { models: { qwen2.5-coder:7b: { options: { num_ctx: 8192 } } } } }, model: qwen2.5-coder:7b }num_ctx对应模型上下文窗口长度。调大后能理解更长的项目上下文但内存和显存占用也会增加。这里稳妥的建议是先用默认值跑通再根据机器配置微调。配置完成后在项目目录启动opencodeOpenCode 会进入交互式终端。你可以输入类似这样的任务请阅读当前项目结构解释 main.py 的入口逻辑并指出可能存在的问题。如果一切正常Agent 会调用 Ollama 中的本地模型一步一步分析代码。这里一定要降低预期7B 级别的本地模型在复杂代码任务上的能力与云端顶级模型有明显差距。它能帮你做格式化、补测试、解释代码但不要指望它像 GPT-5 级别模型一样重构整个系统。7.4 Skill 的含义与简单示例既然标题提到了 Skill这里需要用一个容易理解的类比来解释。可以把 Skill 理解成“给 Agent 的一份岗位说明书”。模型本身知道很多通用知识但不知道你项目的特殊约定。Skill 就是一组预先写好的规则和示例放在约定的目录下当 Agent 执行相关任务时会自动参考这些内容从而遵循团队规范。比如团队要求所有 Python 代码必须包含类型注解且对外接口必须写 docstring。你可以把这条规则写成一个 Skill让 Agent 在每次写代码时自动遵守而不是每次重复用自然语言强调。在不少 Agent 工具中Skill 的目录结构大致如下skills/ python-standard/ SKILL.md examples/ sample.py其中SKILL.md是核心说明文件# Python Standard When writing Python code, follow these rules: 1. All public functions must have type annotations. 2. Every public function must include a docstring. 3. Use ruff for linting.需要特意提醒的是不同工具的 Skill 机制细节并不完全相同。OpenCode 的 Skill 能力仍处于快速迭代中建议以你安装版本的官方文档为准。理解 Skill 的本质比死记硬背目录结构更重要它把人的经验沉淀成 Agent 能阅读的规则文件是团队级 AI 协作的关键抽象。7.5 本地模型接入 OpenCode 的验证方法要判断接入是否成功可以执行opencode models如果配置正确列表中会出现ollama/qwen2.5-coder:7b之类的模型。然后随便让它完成一个明确的小任务例如请创建一个 hello.py 文件里面定义一个 greet(name) 函数并输出打招呼信息。观察 OpenCode 是否读取了模型回复并创建文件。失败时优先检查三点Ollama 服务是否在运行。opencode.json 中模型名是否与ollama list完全一致。num_ctx是否设置得过大导致内存不足。8. 常见问题与排查思路问题现象可能原因排查方式解决方案Windows 安装后提示ollama不是内部或外部命令安装后没有重开终端或 PATH 未生效关闭所有命令行窗口后重新打开手动检查环境变量或直接运行 Ollama 桌面应用ollama pull长时间卡住网络连通性不佳模型文件较大观察进度条是否变化更换网络环境后重试或使用 GGUF 手动导入模型下载到一半失败无法续传网络中断或磁盘空间不足查看磁盘剩余空间删除残留文件后重新pull或设置OLLAMA_MODELS到新目录调用接口时提示model not found模型名不存在或未真正下载成功执行ollama list核对名称用完整名称再次ollama pullCPU 跑模型特别慢没有显卡加速执行ollama ps查看运行状态接受 CPU 速度或使用更小的量化模型回答被截断或者“记不住”前文上下文长度不足使用/show info查看参数调大num_ctx或精简 PromptLinux 下端口 11434 被占用其他服务占用了端口执行 netstat -anpgrep 11434修改OLLAMA_MODELS后不生效环境变量设置后未重启服务重启终端和 Ollama 服务在服务启动前确认环境变量已生效补充一个高频问题Windows 用户设置好OLLAMA_MODELS后如果 Ollama 桌面应用仍在运行需要彻底退出托盘图标后再重启否则新路径不会生效。9. 最佳实践与工程建议9.1 用 Modelfile 固化配置如果你发现自己每次都要在 Prompt 中重复“你是我的编程助手”不如把它写入 ModelfileFROM qwen2.5:7b SYSTEM 你是我的编程助手擅长 Python 和 Java。 回答时尽量给出可运行代码并解释关键思路。 然后创建模型ollama create coding-assistant -f Modelfile日常开发直接使用ollama run coding-assistant这样能减少重复输入也能在团队内共享统一配置。9.2 本地服务不要直接暴露到公网Ollama 默认没有复杂的鉴权机制它面向的通常是本机或内网环境。生产环境如果需要提供服务建议只监听内网地址例如OLLAMA_HOST0.0.0.0时务必配合防火墙策略。不要将11434端口映射到公网。在应用层自行增加 API Key 或认证转发层例如通过后端服务转发请求。安全的原则是最小暴露面最大可控性。本地开发的便利性不应该以安全风险为代价。9.3 小模型也有适用边界在资源有限的环境里7B 模型足够处理文本分类、意图识别、摘要提取等任务。嵌入类任务甚至可以选用更小的nomic-embed-text或bge-m3系列模型。先判断任务复杂度再决定模型大小这才是务实的工程思路。9.4 多模型并存时注意命名规范本地模型多了以后建议使用统一命名规则例如项目名-用途-参数量例如blog-rewrite-7b用这种格式能避免过一段时间后忘记模型用途。9.5 关注模型效果评测不要只凭一两句话对话判断模型好坏。实际开发中建议准备一份固定的测试集覆盖你的真实场景例如“总结这段客户反馈”“从日志中提取错误码”。在换模型或换量化版本后用同样的问题对比输出能帮助你做出更理性的选择。10. 总结与下一步实践建议这篇文章从零开始讲清楚了 Ollama 的安装位置和安装方法也带你把本地模型跑起来并用 OpenAI 兼容接口写了自己的第一段调用代码。更进一步你也看到了 Ollama 怎样作为模型后端接入 OpenCode理解了 Skill 的本质不是神秘技术而是把人类经验转成 Agent 可读规则的一组文件。下一步的实践路线可以这样规划安装 Ollama下载一个qwen2.5:7b或deepseek-r1:7b先跑通对话。用 Python 写一个调用接口的脚本体验请求与响应的完整过程。把项目中的一个小任务交给 OpenCode配合 Ollama 本地模型跑一遍。尝试编写一个自己的 Skill让它自动遵守你项目的代码规范。等你对本地模型的能力边界有感觉后再学习 Dify、LangChain 这类上层框架最后回到应用开发本身。本地部署大模型不是终点而是让你理解 AI 应用开发底层逻辑的捷径。希望这份教程能帮你少走弯路把环境搭建的时间压缩到最短把精力留到真正值得研究的问题上。