作者主页编程的一拳超人⛺️ 欢迎关注点赞 留言 收藏 于高山之巅方见大河奔涌于群峰之上更觉长风浩荡。专栏系列AI开发实战 / 大模型应用开发 / 多系统安装/全场景问题排查⭐如果本文对你有帮助欢迎点赞、收藏、关注三连支持问题交流评论区留言或私信看到必回Ollama在Windows /macOS/ Linux系统本地大模型完整部署教程一、概述与前置准备1.1 什么是 Ollama1.2 硬件配置要求与模型选型热门中文模型推荐二、全系统详细安装教程2.1 Windows 系统安装方式一图形化安装包新手推荐方式二PowerShell 一键安装安装验证国内镜像加速配置必做2.2 macOS 系统安装方式一终端一键安装推荐方式二DMG 图形化安装方式三Homebrew 安装安装验证国内镜像加速配置2.3 Linux 系统安装一键脚本安装服务管理命令系统级镜像加速配置重要权限说明三、基础使用全指南3.1 核心命令速查表3.2 运行第一个模型3.3 交互式对话内置指令3.4 非交互式单次调用3.5 模型管理操作四、进阶配置与性能优化4.1 修改模型存储路径Windows 系统macOS / Linux 系统Linux 服务级配置推荐4.2 常用环境变量大全4.3 GPU 加速配置与优化NVIDIA 显卡AMD 显卡Apple Silicon多显卡负载均衡4.4 局域网访问配置五、API 接口调用详解5.1 原生 API 接口对话接口Chat Completion生成接口Completion5.2 OpenAI 兼容接口六、图形化 Web 界面部署6.1 Open WebUI最推荐6.2 其他优质客户端七、自定义模型Modelfile7.1 常用指令说明7.2 实战案例创建翻译助手7.3 导入本地 GGUF 模型八、常见问题排查与解决方案8.1 安装与启动类问题问题1提示 ollama 不是内部或外部命令问题2Ollama 服务启动失败问题3Linux 下自定义路径报 Permission denied8.2 模型下载类问题问题1模型下载速度极慢/超时失败问题2下载中途断网需要重新下载吗问题3手动下载的 GGUF 模型如何导入8.3 运行性能类问题问题1模型运行卡顿生成速度很慢问题2GPU 没生效只用 CPU 运行问题3提示显存不足 / Out of Memory8.4 接口与连接类问题问题1局域网其他设备无法访问 API问题2WebUI 连接不上 Ollama8.5 其他常见问题问题1中文回答出现乱码问题2如何更新 Ollama问题3如何完全卸载 Ollama九、总结Ollama在Windows /macOS/ Linux系统本地大模型完整部署教程一、概述与前置准备1.1 什么是 OllamaOllama 是一款开源的本地大语言模型运行与管理框架它封装了模型量化、显存调度、推理引擎等底层技术细节用户只需几条命令即可在个人电脑上运行 Llama、Qwen、DeepSeek 等上百种开源大模型全程数据本地处理完全离线可用。核心特性跨平台原生支持 Windows、macOS、Linux自动硬件加速NVIDIA/AMD/Apple Silicon内置模型仓库一键下载运行原生兼容 OpenAI API 格式便于二次开发支持自定义模型、参数调优、多模型并行1.2 硬件配置要求与模型选型大模型运行核心取决于显存/内存大小显存优先用显卡显存不足时自动占用系统内存。可用显存/内存推荐模型参数典型速度适用场景4GB ~ 6GB1.5B ~ 3B20~40 token/s轻量对话、入门测试8GB7B ~ 8B15~30 token/s日常聊天、代码辅助16GB14B ~ 22B10~20 token/s专业写作、复杂推理32GB32B ~ 34B5~12 token/s高质量生成、深度分析64GB 以上70B3~8 token/s接近云端级效果实际内存占用 ≈ 模型文件大小 × 1.2建议预留 20% 以上余量热门中文模型推荐模型名称参数文件大小核心特点运行命令qwen2.57B4.7GB中文能力天花板综合均衡ollama run qwen2.5:7bdeepseek-r17B4.7GB推理能力强带思考过程ollama run deepseek-r1:7bqwen2.5-coder7B4.7GB代码专用补全与解释能力强ollama run qwen2.5-coder:7bllama3.23B2.0GB轻量高速英文能力优秀ollama run llama3.2:3bgemma29B5.5GBGoogle 出品质量稳定ollama run gemma2:9bphi33.8B2.3GB微软小模型同参数性能顶尖ollama run phi3:mini完整官方模型库ollama.com/library二、全系统详细安装教程2.1 Windows 系统安装支持 Windows 10 1809 / Windows 11推荐 64 位系统。方式一图形化安装包新手推荐打开官方下载页ollama.com/download点击 Windows 图标下载OllamaSetup.exe安装包双击运行安装包点击Install开始安装默认安装路径C:\Users\用户名\AppData\Local\Programs\Ollama安装程序会自动配置系统环境变量并注册后台服务安装完成后点击Finish系统托盘会出现小羊头图标方式二PowerShell 一键安装按下Win X选择「终端(管理员)」或「PowerShell(管理员)」执行以下命令irmhttps://ollama.com/install.ps1|iex等待脚本自动下载安装完成后自动启动服务安装验证按下Win R输入cmd打开命令提示符输入命令查看版本ollama--version输出版本号如ollama version 0.32.3即表示安装成功。国内镜像加速配置必做国内网络直接下载模型极易超时建议提前配置魔搭镜像按下Win S搜索「编辑系统环境变量」并打开点击右下角「环境变量」按钮在下方「系统变量」区域点击「新建」填写变量信息变量名OLLAMA_HF_MIRROR变量值https://modelscope.cn连续点击「确定」保存所有窗口右键点击系统托盘 Ollama 图标 → 选择「Quit」退出重新从开始菜单打开 Ollama配置即可生效2.2 macOS 系统安装支持 Intel 芯片与 Apple SiliconM1/M2/M3 系列全系列 Mac。方式一终端一键安装推荐打开「终端」应用Launchpad → 其他 → 终端执行一键安装命令curl-fsSLhttps://ollama.com/install.sh|sh输入开机密码授权等待脚本自动完成安装与服务启动方式二DMG 图形化安装官网下载对应芯片的.dmg安装包双击打开安装包将 Ollama 图标拖拽到「应用程序」文件夹首次运行从启动台打开 Ollama点击「打开」确认运行顶部菜单栏会出现小羊图标表示后台服务已启动方式三Homebrew 安装brewinstallollama安装验证ollama--version国内镜像加速配置# 永久生效zsh 终端Mac 默认echoexport OLLAMA_HF_MIRRORhttps://modelscope.cn~/.zshrcsource~/.zshrc# bash 终端echoexport OLLAMA_HF_MIRRORhttps://modelscope.cn~/.bash_profilesource~/.bash_profile2.3 Linux 系统安装支持 Ubuntu、Debian、CentOS、Fedora 等主流发行版。一键脚本安装打开终端执行官方安装脚本curl-fsSLhttps://ollama.com/install.sh|sh脚本会自动检测系统架构、安装二进制文件、注册 systemd 服务安装完成后服务自动后台运行服务管理命令# 查看服务状态sudosystemctl status ollama# 启动/停止/重启服务sudosystemctl start ollamasudosystemctl stop ollamasudosystemctl restart ollama# 设置开机自启/关闭自启sudosystemctlenableollamasudosystemctl disable ollama# 查看运行日志sudojournalctl-uollama-f系统级镜像加速配置Linux 下 Ollama 服务以ollama用户运行需配置全局环境变量# 写入系统全局配置sudoechoOLLAMA_HF_MIRRORhttps://modelscope.cn/etc/environment# 重启服务生效sudosystemctl restart ollama重要权限说明Ollama 服务默认运行在ollama用户下若自定义模型存储路径在个人目录或外接硬盘需授权访问权限# 给 ollama 用户授予目录读写权限sudosetfacl-R-mu:ollama:rwx /你的/模型/存储路径# 若没有 setfacl 命令先安装sudoaptinstallacl# Debian/Ubuntusudoyuminstallacl# CentOS三、基础使用全指南3.1 核心命令速查表命令功能说明ollama run 模型名运行模型不存在则自动下载ollama pull 模型名仅下载模型不启动运行ollama list列出本地所有已下载模型ollama rm 模型名删除指定本地模型ollama ps查看当前正在运行的模型ollama show 模型名查看模型详细参数与配置ollama create 名称 -f 文件从 Modelfile 创建自定义模型ollama serve手动启动 Ollama 后台服务ollama help查看所有命令帮助3.2 运行第一个模型以中文表现最优的qwen2.5:7b为例打开终端 / CMD / PowerShell执行运行命令ollama run qwen2.5:7b首次运行会自动下载模型文件下载进度实时显示下载完成后自动进入对话界面出现提示符即可提问输入问题按回车即可获得回答退出对话输入/bye或按下Ctrl D3.3 交互式对话内置指令在对话界面中可使用以下斜杠命令/set system 提示词设置系统角色设定/set parameter 参数名 值临时调整模型参数/show info显示当前模型与会话信息/show model查看模型完整 Modelfile 内容/clear清空当前对话历史上下文/help查看所有内置指令/bye退出对话3.4 非交互式单次调用无需进入对话界面直接传入问题获得答案ollama run qwen2.5:7b用通俗语言解释什么是大语言模型3.5 模型管理操作# 查看所有本地模型ollama list# 删除不需要的模型释放空间ollamarmqwen2.5:3b# 更新模型到最新版本ollama pull qwen2.5:7b四、进阶配置与性能优化4.1 修改模型存储路径大模型文件体积较大默认存储在系统盘强烈建议迁移到空间充足的分区。Windows 系统方法一系统环境变量配置推荐打开「系统环境变量」设置在「系统变量」中点击「新建」变量名OLLAMA_MODELS变量值D:\Ollama\Models替换为你的目标路径确定保存后重启 Ollama 服务net stop ollama net start ollama方法二托盘设置新版支持右键点击系统托盘 Ollama 图标 → Settings → Model location → Browse 选择新路径 → 重启生效。macOS / Linux 系统# 临时生效仅当前终端exportOLLAMA_MODELS/path/to/your/models# 永久生效写入配置文件echoexport OLLAMA_MODELS/path/to/your/models~/.zshrcsource~/.zshrcLinux 服务级配置推荐若使用 systemd 服务需修改服务配置文件编辑服务文件sudosystemctl edit ollama.service添加以下内容[Service] EnvironmentOLLAMA_MODELS/你的/模型/存储路径保存退出重载并重启服务sudosystemctl daemon-reloadsudosystemctl restart ollama4.2 常用环境变量大全环境变量作用说明默认值OLLAMA_HOSTAPI 监听地址与端口127.0.0.1:11434OLLAMA_MODELS模型文件存储目录系统默认路径OLLAMA_NUM_PARALLEL最大并行请求数自动计算OLLAMA_CONTEXT_LENGTH上下文窗口大小模型默认值OLLAMA_GPU_LAYERSGPU 加速层数自动全量OLLAMA_TEMPERATURE全局默认温度值模型默认OLLAMA_HF_MIRRORHuggingFace 镜像地址无OLLAMA_SCHED_SPREAD多卡负载均衡开关04.3 GPU 加速配置与优化NVIDIA 显卡正常情况下 Ollama 会自动检测 CUDA 并启用加速无需手动配置前提安装最新 NVIDIA 显卡驱动CUDA 版本 ≥ 11.8验证方式运行模型后执行ollama ps查看 processor 列是否显示 GPU老显卡兼容问题GTX 10 系列等若出现 GPU 不识别升级 Ollama 到 v0.13.2 及以上版本即可原生支持计算能力 6.1 以上显卡。AMD 显卡Linux安装 ROCm 驱动后自动识别Windows支持有限建议使用 CPU 或升级最新版 OllamaApple SiliconM 系列芯片自动启用 Metal 加速性能极佳统一内存架构内存即显存无需额外配置多显卡负载均衡多卡环境下默认单卡运行显存不足时才溢出到其他卡。开启均匀分布# Linux 系统添加到服务环境变量EnvironmentOLLAMA_SCHED_SPREAD1EnvironmentCUDA_VISIBLE_DEVICES0,1# 指定使用的显卡编号4.4 局域网访问配置默认仅本机可访问如需局域网其他设备调用设置环境变量OLLAMA_HOST0.0.0.0:11434重启 Ollama 服务防火墙放行 11434 端口局域网内通过http://你的IP:11434即可访问五、API 接口调用详解Ollama 启动后默认在http://localhost:11434提供 REST API同时完全兼容 OpenAI 接口格式。5.1 原生 API 接口对话接口Chat Completioncurlhttp://localhost:11434/api/chat-d{ model: qwen2.5:7b, messages: [ {role: system, content: 你是一个专业的编程助手}, {role: user, content: 写一个 Python 快速排序} ], stream: false }生成接口Completioncurlhttp://localhost:11434/api/generate-d{ model: qwen2.5:7b, prompt: 介绍一下 Ollama, stream: false, temperature: 0.7 }stream: true开启流式输出逐字返回支持参数temperature、top_p、num_ctx、num_predict 等5.2 OpenAI 兼容接口可直接使用 OpenAI 官方 SDK 无缝切换到本地模型只需修改 base_url。Python 示例fromopenaiimportOpenAI# 初始化客户端clientOpenAI(base_urlhttp://localhost:11434/v1/,api_keyollama# 任意非空字符串即可不做校验)# 调用对话接口responseclient.chat.completions.create(modelqwen2.5:7b,messages[{role:user,content:写一段 Java 冒泡排序代码}],temperature0.3)print(response.choices[0].message.content)JavaScript 示例importOpenAIfromopenai;constopenainewOpenAI({apiKey:ollama,baseURL:http://localhost:11434/v1/,});asyncfunctionchat(){constcompletionawaitopenai.chat.completions.create({model:qwen2.5:7b,messages:[{role:user,content:你好}],});console.log(completion.choices[0].message.content);}六、图形化 Web 界面部署命令行交互不够直观推荐搭配 Web 客户端使用功能接近云端 ChatGPT。6.1 Open WebUI最推荐功能最全面的开源 Web 客户端支持多模型切换、对话管理、知识库 RAG、插件系统、多用户等。Docker 一键部署确保已安装 Docker 环境执行部署命令dockerrun-d\-p3000:3000\-eOLLAMA_BASE_URLhttp://host.docker.internal:11434\-vopen-webui:/app/backend/data\--nameopen-webui\--restartalways\ghcr.io/open-webui/open-webui:main浏览器访问http://localhost:3000首次打开注册管理员账号即可开始使用6.2 其他优质客户端Lobe Chat界面美观支持插件与知识库Chatbox跨平台桌面客户端轻量简洁OllaMan专注 Ollama 的桌面管理工具Dify低代码 AI 应用开发平台支持接入 Ollama七、自定义模型Modelfile通过 Modelfile 可以定制模型行为、设定角色、调整参数、导入本地模型。7.1 常用指令说明指令作用FROM 基础模型指定基于哪个模型创建SYSTEM 提示词设置系统提示词定义模型角色PARAMETER 参数 值设置模型运行参数TEMPLATE 模板自定义提示词模板LICENSE 许可证指定模型许可证7.2 实战案例创建翻译助手新建一个名为Modelfile的文件FROM qwen2.5:7b SYSTEM 你是专业的中英互译专家严格遵循以下规则 1. 用户输入中文则翻译成英文输入英文则翻译成中文 2. 只输出翻译结果不要添加任何解释、说明或问候语 3. 保持原文语气与格式专业术语准确 PARAMETER temperature 0.3 PARAMETER top_p 0.9执行构建命令ollama create translator-fModelfile运行自定义模型ollama run translator7.3 导入本地 GGUF 模型如果有手动下载的 GGUF 格式模型文件可通过 Modelfile 导入FROM ./你的模型文件.gguf然后执行ollama create 模型名 -f Modelfile即可导入。八、常见问题排查与解决方案8.1 安装与启动类问题问题1提示 ‘ollama’ 不是内部或外部命令原因环境变量未配置或未生效。解决步骤重启终端 / CMD / PowerShell重新尝试检查安装路径是否存在Windows 默认路径C:\Users\用户名\AppData\Local\Programs\Ollama手动添加环境变量将安装目录添加到系统 Path 变量中完全卸载后重新运行安装包问题2Ollama 服务启动失败原因端口被占用、权限不足、文件损坏。解决步骤检查 11434 端口是否被占用Windowsnetstat -ano | findstr 11434Linux/macOSlsof -i :11434若被占用结束占用进程或修改OLLAMA_HOST换端口Windows右键托盘图标退出重新从开始菜单启动Linux查看错误日志sudo journalctl -u ollama -n 50尝试重新安装 Ollama 最新版问题3Linux 下自定义路径报 Permission denied原因ollama 用户没有目录访问权限。解决步骤给 ollama 用户授予 ACL 权限sudosetfacl-R-mu:ollama:rwx /你的/模型路径若使用外接硬盘检查挂载选项是否允许普通用户访问备选方案将模型放在/var/lib/ollama/models默认目录8.2 模型下载类问题问题1模型下载速度极慢/超时失败原因国内网络访问境外源不稳定。解决步骤配置OLLAMA_HF_MIRRORhttps://modelscope.cn镜像详见各系统安装章节配置后必须重启 Ollama 服务才会生效若仍慢使用代理工具加速或手动下载模型导入问题2下载中途断网需要重新下载吗Ollama 支持断点续传重新执行ollama pull命令会从断点继续下载无需从头开始。问题3手动下载的 GGUF 模型如何导入解决步骤从 HuggingFace / ModelScope 下载 GGUF 格式模型文件新建 Modelfile内容为FROM ./模型文件名.gguf执行ollama create 自定义模型名 -f Modelfile完成后即可通过ollama run 自定义模型名运行8.3 运行性能类问题问题1模型运行卡顿生成速度很慢原因使用 CPU 运行、模型参数过大、显存不足。解决步骤确认 GPU 加速是否生效执行ollama ps查看更换更小参数的模型如从 14B 换到 7B关闭其他占用显存的程序浏览器、游戏等降低上下文窗口大小/set parameter num_ctx 2048笔记本电脑接通电源开启高性能模式问题2GPU 没生效只用 CPU 运行原因驱动问题、版本不兼容、环境变量错误。排查步骤NVIDIA 显卡先执行nvidia-smi确认驱动正常升级 Ollama 到最新版本老版本对新显卡支持差检查是否设置了OLLAMA_GPU_LAYERS00 表示禁用 GPUGTX 10 系列老显卡升级到 v0.13.2 以上版本尝试设置环境变量强制启用OLLAMA_GPU_LAYERS999问题3提示显存不足 / Out of Memory原因模型大小超过可用显存。解决步骤更换更小参数的模型或更高量化等级如 q4_k_m关闭其他占用显存的应用手动减少 GPU 层数让部分层放到内存运行设置OLLAMA_GPU_LAYERS20数值根据显存调整增加系统虚拟内存 / swap 空间牺牲速度8.4 接口与连接类问题问题1局域网其他设备无法访问 API原因监听地址未放开、防火墙拦截。解决步骤设置OLLAMA_HOST0.0.0.0:11434并重启服务系统防火墙放行 11434 端口确认两台设备在同一局域网IP 地址正确本机测试http://127.0.0.1:11434是否正常问题2WebUI 连接不上 Ollama原因地址配置错误、服务未启动、跨域问题。解决步骤确认 Ollama 服务正常运行本机 API 可调用Docker 部署的 Open WebUI检查OLLAMA_BASE_URL是否正确Windows Docker 环境使用host.docker.internal代替localhost非 Docker 部署填写http://127.0.0.1:114348.5 其他常见问题问题1中文回答出现乱码原因终端编码不兼容。解决步骤Windows CMD 执行chcp 65001切换到 UTF-8 编码推荐使用 Windows Terminal 或 PowerShell 7更换模型部分英文原生模型中文支持较差问题2如何更新 OllamaWindows / macOS下载最新安装包直接覆盖安装Linux重新执行一键安装脚本即可升级升级不会删除已下载的模型文件问题3如何完全卸载 OllamaWindows设置 → 应用 → 找到 Ollama 卸载macOS将应用程序中的 Ollama 拖到废纸篓删除~/.ollama目录Linux执行sudo systemctl stop ollama sudo systemctl disable ollama sudo rm /usr/local/bin/ollama删除/var/lib/ollama目录九、总结Ollama 极大降低了本地大模型的使用门槛从安装到运行仅需几分钟。建议新手从 7B 级模型开始尝试根据硬件条件逐步升级配合 Open WebUI 等图形界面可获得接近云端产品的使用体验同时保障数据完全隐私。对于开发者基于 Ollama 的 OpenAI 兼容 API可以快速迁移原有云端应用到本地搭建私有化智能客服、代码助手、企业知识库等各类 AI 应用。