想在自己的电脑上运行一个能回答问题、整理笔记、辅助写作的 AI 助手,通常会遇到一串陌生概念:模型权重、量化、推理框架、显存、上下文窗口。还没有真正问出第一个问题,就已经花了不少时间研究环境。
Ollama 把下载、管理和运行模型的常见操作放进了一套工具。你可以先通过桌面应用或几条命令完成对话,再逐步学习如何让自己的程序调用本地模型。
这篇教程从零开始,带你完成安装、选择中文模型、进行多轮对话、调用 HTTP API,并写出一个完整的 Python 聊天程序。读到最后,你还会知道如何判断模型为什么慢、怎样释放内存,以及更换模型存储位置时应该修改哪个进程的配置。
一、Ollama 是什么,适合解决什么问题
可以先把 Ollama 理解为运行大模型的工具。它负责把模型准备好、加载到电脑的计算资源中,并对外提供对话接口;真正决定回答风格、知识范围和能力上限的,是你选择的模型。
这里有三个容易混淆的对象:
| 对象 | 负责什么 | 本文中的例子 |
|---|---|---|
| Ollama | 下载、管理、加载模型并提供服务 | 桌面应用、ollama 命令、本地 HTTP 服务 |
| 模型 | 根据输入生成回答 | qwen3:4b |
| 使用模型的程序 | 组织界面、消息和业务流程 | 命令行聊天、本文的 Python 程序 |
安装了 Ollama,并不等于所有模型都已经装好。就像安装了视频播放器后还需要选择视频文件,你还需要下载合适的模型。
对于初学者,比较容易上手的用途包括:把自己的学习笔记整理成提纲,把一段文字改写得更清楚,解释看不懂的报错,生成待核对的代码草稿,以及从一段已提供的材料中抽取信息。
这些任务都能从短文本开始,效果也容易检查。第一次尝试时,不必马上搭建一个能够读取整个硬盘、访问网站和自动操作电脑的助手。先让模型稳定完成一个明确的小任务,你会更容易分辨问题来自安装、模型能力,还是输入表达。
本地模型与云端模型要分清
当前 Ollama 同时支持本地模型和云端模型。本文的主线是下载模型,在自己的电脑上完成推理。本地公开模型的这条使用路径不需要配置云端 API Key;调用官方云端服务则涉及账号、认证和相应的使用规则。官方快速开始
尤其要注意:请求发给 localhost,不能单独证明推理发生在本机。Ollama 的本地服务也可以转发云端模型请求。判断时要看实际选择的模型和功能,而不能只看地址栏。本地与云端认证说明
如果你希望练习离线使用,先完成程序安装和本地模型下载,再关闭联网搜索、云端模型及其他需要联网的集成功能,断网测试一次。下载完成后,本地文本推理可以离线运行,但程序更新、模型下载和在线工具仍然需要网络。
本地部署有助于控制数据流向,不过使用第三方聊天界面时,还要了解界面自身是否上传消息、调用外部服务或保存聊天记录。涉及工作资料时,应先使用不敏感的演示内容确认整个链路。
二、开始之前,先看电脑资源
运行大模型时,最值得关注的是内存、显存和磁盘空间。CPU 和 GPU 决定计算速度,内存和显存则直接影响模型能否装得下,以及能同时处理多少输入。
磁盘上的模型大小,不等于运行时的全部内存需求。 除了模型权重,推理还需要运行缓冲区,以及保存上下文相关状态的缓存。输入越长、并行请求越多,资源需求通常越高。
本文使用的 qwen3:4b 是一个明确可查的练习模型。写作时,官方模型页标注它约为 2.5 GB,采用 Q4_K_M 量化,参数规模约 40 亿。这里引用的是该标签当前展示的信息,下载时应以页面和命令实际显示的内容为准。Qwen3 4B 模型页
先理解模型名称
以 qwen3:4b 为例,qwen3 是模型系列,冒号后面是标签。4b 表示约 40 亿参数;参数更多通常意味着更高的资源需求,但不同架构、训练方式和任务之间,不能只靠这个数字比较效果。
你还会看到量化标签。量化可以理解为用更紧凑的数值表示模型权重,以减少存储和运行资源需求。它通常涉及体积、速度与效果的取舍。刚开始不必逐个研究所有量化格式,先选官方模型库里明确标注用途、大小和能力的版本。
下面是本文给新手的保守试用顺序,属于实践建议,不能当作硬件兼容性保证:
| 当前条件 | 建议的起步方式 |
|---|---|
| 约 8 GB 系统内存、没有可用独立显卡 | 从 1B 左右或更小的模型开始,先处理短文本 |
| 约 16 GB 系统内存 | 可以尝试本文的 4B 量化模型,关闭占内存较多的程序 |
| 有受支持且空闲显存较充足的显卡 | 先运行小模型,确认实际使用 GPU 后再增加规模 |
| Apple Silicon Mac | 使用原生应用,结合可用统一内存评估模型和上下文 |
系统内存和独立显卡显存不是简单相加就能得到“等效显存”。Apple Silicon 的统一内存也同时供系统和其他应用使用,不能把整机标称容量全部分配给模型。
没有独立显卡仍然可以学习 Ollama,只是 CPU 推理可能明显更慢。GPU 是否能加速,还取决于具体硬件、操作系统、驱动及计算后端;购买设备或安装驱动前,应核对官方支持列表,而不是只看显卡品牌。硬件支持说明
三、安装 Ollama:选择自己的操作系统
下载入口统一使用 Ollama 官方下载页。初学者优先使用稳定版,先完成一条原生安装路径。Docker、WSL 和系统原生安装可以分别使用,但刚开始同时安装多套,会增加端口、模型目录和 GPU 配置方面的排查成本。
下面的平台要求按本文写作时的官方文档整理。后续版本可能调整最低系统要求,实际安装前请再次检查对应页面。
Windows:先安装,再重新打开终端
官方 Windows 文档列出的系统要求是 Windows 10 22H2 或更新版本。下载 Windows 安装程序,按提示安装,再从开始菜单启动 Ollama。原生安装路径不要求先配置 WSL。Windows 官方安装说明
安装完成后,重新打开 PowerShell,输入:
ollama --version
看到版本信息,说明终端已经能够找到命令。如果提示无法识别 ollama,先关闭旧 PowerShell 窗口,再打开一个新窗口。安装程序对 PATH 的修改,通常不会自动进入安装前已经启动的终端进程。
Windows 版本可以在后台运行。接下来直接使用 ollama run 即可,不需要每次都额外启动一个 ollama serve。若出现端口占用,先确认托盘里的 Ollama 是否已经在运行。
macOS:使用原生应用
官方文档当前要求 macOS Sonoma 14 或更新版本,Apple M 系列支持 CPU 和 GPU,Intel x86 Mac 则是 CPU 路径。下载磁盘映像,把 Ollama 拖到 Applications,然后启动应用,按提示完成命令行工具配置。macOS 官方安装说明
打开终端,检查:
ollama --version
如果应用可以打开而终端找不到命令,检查首次启动时的命令行链接安装提示,再重新打开终端。不要一边保留原生应用,一边反复安装其他来源的同名命令来碰运气。
Apple Silicon 用户第一次学习时,建议直接沿着这条原生路径完成后面的实验。这样比较容易确认应用、命令和模型都来自同一套环境。
Linux:使用官方脚本,检查服务状态
官方提供的安装方式如下。这条命令会下载并执行安装脚本,可能请求提权并创建系统服务,应在你准备安装 Ollama 的机器上执行。Linux 官方安装说明
curl -fsSL https://ollama.com/install.sh | sh
在采用 systemd、且安装程序已经创建 Ollama 服务的发行版上,检查并启动服务:
sudo systemctl start ollama
systemctl status ollama --no-pager
ollama --version
如果使用的是没有 systemd 的环境,或者采用了手动安装方式,可以在一个终端中运行:
ollama serve
保持这个终端运行,再打开另一个终端执行模型命令。手动启动和系统服务启动二选一;已有服务监听同一地址时,再启动一份通常会报地址被占用。
检查本地 HTTP 服务
macOS 和 Linux 终端可以执行:
curl http://localhost:11434/api/tags
Windows PowerShell 使用原生命令:
Invoke-RestMethod -Uri 'http://localhost:11434/api/tags'
这个接口列出本地已有模型。刚安装时返回空的模型列表是正常情况,意味着服务可达,但你还没有下载模型。它并不代表模型推理和 GPU 加速已经验证完成。模型列表 API
四、下载第一个中文模型,完成一次对话
下面的 ollama 命令适用于前面三种系统。本文固定使用 qwen3:4b 作为练习对象,是为了让所有步骤使用一致的模型名称;它不是“当前最新模型”或“所有电脑的最佳选择”。
如果你的电脑资源紧张,可以在官方模型库核对 qwen3:1.7b 等较小标签,并在后续命令和代码中统一替换模型名称。不要只修改下载命令,却让 API 继续请求另一个名称。
先下载,再运行
ollama pull qwen3:4b
ollama run qwen3:4b
pull 负责下载模型,run 负责运行并进入交互对话。模型不存在时,run 也可以触发下载;这里分成两步,方便观察下载和运行分别发生在哪个阶段。命令行参考
第一次下载会显示进度,所需时间取决于模型大小和网络。下载完成后,首次加载还需要等待一会儿。以后再次运行同一模型,通常不需要重新下载整份权重。
进入对话后,输入:
请用中文向第一次接触人工智能的读者解释什么是大语言模型。
要求:不超过 200 字,举一个生活中的例子,最后说明一个局限。
回答出现后,再输入:
把刚才的解释改成适合初中生阅读的版本,保留最后的局限说明。
如果第二次回答能够接着修改上一次内容,说明你已经完成了一次基础多轮对话。生成式模型的措辞可能每次不同,教程不要求得到完全相同的句子。
退出对话和停止模型有什么区别
在交互窗口里输入:
/bye
这会退出当前交互。需要释放已加载模型占用的资源时,在普通终端中执行:
ollama stop qwen3:4b
退出聊天、从内存中卸载模型、从磁盘中删除模型,是三件不同的事情。stop 不会删除已经下载的模型文件;下次运行时可以重新加载。
模型显示“思考中”,是不是卡住了
Qwen3 属于支持思考能力的模型系列。有时你会先看到思考相关输出,再看到最终答案,这与纯粹输出答案的体验不同。API 中的思考内容和回答内容也有不同字段,聊天接口对应 message.thinking 与 message.content。思考能力说明
后面的 API 示例会为本文模型显式设置 think: false,让短任务更容易观察。换用其他模型时,思考开关和支持的取值需要按模型文档确认,不能把同一套参数机械套在所有模型上。
五、掌握模型管理的几个常用命令
第一次使用时,记住下面这组操作就足够了:
| 目的 | 命令 |
|---|---|
| 查看命令帮助 | ollama --help |
| 下载或更新指定标签 | ollama pull qwen3:4b |
| 查看磁盘中已有的模型 | ollama ls |
| 查看当前已加载的模型 | ollama ps |
| 查看模型信息 | ollama show qwen3:4b |
| 开始交互对话 | ollama run qwen3:4b |
| 卸载内存中的模型 | ollama stop qwen3:4b |
| 删除本地模型 | ollama rm qwen3:4b |
这些命令可以从 官方 CLI 文档 查询。删除操作会让你在下次使用时需要重新获取相应模型,执行前确认模型名称。
ls 与 ps 的区别尤其有用:前者回答“我下载过什么”,后者回答“现在加载了什么”。一个模型出现在 ls 中,并不代表它持续占用显存;ps 没有列出它,也不代表磁盘里的文件丢失。
你也可以直接执行一次性任务,避免每次进入聊天窗口:
ollama run qwen3:4b "请用中文列出学习 Git 前需要理解的三个概念,每项一句话。"
学习时建议记录 Ollama 版本、模型完整标签、ls 显示的模型 ID,以及自己的提示词。标签让命令更明确,但它仍可能被上游更新;只有一个 4b 标签,不能保证几个月后下载到的内容完全相同。
另外,模型能下载、能运行,不等于它适合任意商业用途。正式分发模型或接入产品前,还需要查看具体模型许可证和使用要求。Ollama 软件的许可与每个模型权重的许可需要分别核对。
六、让模型更好用:从提示词和任务拆分开始
很多“模型不好用”的体验,来自输入过于模糊。例如,只说“帮我总结一下”,模型不知道你希望保留结论、行动项,还是关键数字,也不知道目标读者了解多少背景。
一个实用的提示词可以按四部分组织:要完成的任务、可参考的材料、输出格式、遇到信息不足时怎么办。这些约束越具体,你越容易检查结果。
下面的提示词有多行内容。桌面聊天界面可以直接粘贴;在 CLI 里手动分行输入时,用一行 """ 开始,再输入提示词,最后用另一行 """ 结束并提交。命令行多行输入
练习一:整理自己的学习笔记
把下面的完整提示词复制到聊天窗口:
请只根据下面的笔记整理复习卡片。
输出格式:
1. 核心概念:最多三条。
2. 容易混淆的地方:两条。
3. 自测题:三道简答题,并在末尾给参考答案。
如果笔记没有提供某项信息,请写“笔记未说明”,不要补充成事实。
笔记:
进程是操作系统分配资源的重要单位。
线程是操作系统进行调度的重要单位。
同一进程内的多个线程通常共享进程的地址空间。
线程共享数据时,需要考虑并发访问引起的问题。
生成后,重点检查模型是否把笔记未提及的细节写成了既定结论。这里的约束是帮助模型收敛行为,最终仍需要你核对内容,尤其是数字、代码语义和专业术语。
练习二:修改文字,而不是只要求“润色”
请改写下面的通知,让第一次参加活动的人也能看懂。
保留日期、地点和报名截止时间,不添加新的承诺。
先输出改写后的正文,再列出你修改的三处表达。
原文:
本周六下午两点在社区二楼举办读书分享活动。
有意参加者请在周五下午六点前登记。
参加者可以带一本自己最近读过的书。
这种任务的好处是有明确的核对对象。你可以逐项检查原文里的时间、地点和条件有没有被改错,再决定是否使用生成结果。
练习三:让模型解释报错
提供报错时,尽量同时给出运行环境、完整错误、相关代码和你已经尝试过的步骤。要求模型先解释错误含义,再给最小修改方案,并把推测与已知事实分开。
不要因为建议看起来专业,就直接执行涉及删除文件、修改权限或替换系统配置的命令。先在临时环境中复现,并阅读命令实际操作的路径。模型适合协助分析,代码能否运行仍然要通过实际执行确认。
长文档不要一次全部塞进去
上下文窗口决定模型一次能参考的内容范围。Token 是模型处理文本的单位,与汉字数、英文单词数没有固定的一一对应关系。系统提示、历史消息、当前输入与生成内容都需要在上下文预算内安排。
超出可用范围后,应用可能裁剪历史,模型也可能遗漏前面的信息。对于长文档,先按章节拆分,分别提取结论与证据,再让模型合并摘要;同时保留原文位置,方便回查。
把一整本书交给一个小模型,再要求它精确记住每个细节,通常不是有效的起步方式。先选择一两页材料,建立你能核对的工作流程,效果会更容易评估。上下文长度说明
七、通过 HTTP API 调用本地模型
命令行适合人工体验,API 则可以把模型接入脚本或自己的应用。本文使用 Ollama 原生的 /api/chat 接口,本地基础地址是 http://localhost:11434/api。API 地址与接入说明
先确认 Ollama 已经运行,并且 qwen3:4b 已下载。
macOS 和 Linux 的完整请求
curl --fail-with-body http://localhost:11434/api/chat \
-H 'Content-Type: application/json' \
-d '{
"model": "qwen3:4b",
"messages": [
{"role": "system", "content": "你是一位中文学习助手,回答要简洁。"},
{"role": "user", "content": "请用三个要点解释什么是缓存。"}
],
"stream": false,
"think": false,
"options": {
"temperature": 0.3,
"num_ctx": 4096,
"num_predict": 512
}
}'
这里使用支持 --fail-with-body 的 curl。如果你的旧版 curl 不认识这个选项,可以升级 curl,或者临时移除该选项,并自行检查 HTTP 状态及返回的错误内容。
Windows PowerShell 的完整请求
PowerShell 的引号和换行规则与 Bash 不同。下面使用对象生成 JSON,并显式转成 UTF-8 字节,避免直接复制 Bash 命令产生参数或中文编码问题。
$payload = @{
model = 'qwen3:4b'
messages = @(
@{ role = 'system'; content = '你是一位中文学习助手,回答要简洁。' }
@{ role = 'user'; content = '请用三个要点解释什么是缓存。' }
)
stream = $false
think = $false
options = @{
temperature = 0.3
num_ctx = 4096
num_predict = 512
}
} | ConvertTo-Json -Depth 8
$request = @{
Uri = 'http://localhost:11434/api/chat'
Method = 'Post'
ContentType = 'application/json; charset=utf-8'
Body = [System.Text.Encoding]::UTF8.GetBytes($payload)
}
$result = Invoke-RestMethod @request
$result.message.content
请求参数分别表示什么
| 参数 | 本文中的作用 |
|---|---|
model | 指定模型名称,必须与已经下载的标签一致 |
messages | 按顺序提供本次对话需要的消息 |
role | 区分系统要求、用户输入与助手回复 |
stream: false | 等待生成完成后返回一个 JSON 对象 |
think: false | 为本文的 Qwen3 练习请求关闭思考输出 |
options.temperature | 调整采样随机性,较低值通常让表达更集中 |
options.num_ctx | 为本次运行设置上下文窗口大小 |
options.num_predict | 限制生成 Token 数量,避免回答无限拉长 |
接口定义见 Chat API,运行参数见 Modelfile 参数参考。这些示例值用于短文本练习,不是所有任务的最佳配置。较低温度也不能保证事实正确,num_predict 更不是汉字数量限制。
非流式返回结果通常包含 message 和 done 等字段,回答正文读取 message.content。API 调用方还需要检查 HTTP 状态、错误字段和实际内容,不能把“成功连接服务”当作“业务结果一定正确”。
done: true 只表示这一轮生成已经结束,达到输出上限时也可能结束。若答案明显在半句话中断,应结合 done_reason 和生成上限检查,而不是直接把截断的内容当成完整结果。
为什么有的请求会返回很多行 JSON
聊天接口默认可以流式返回。Ollama 原生流式响应使用 NDJSON:每一行都是一个独立 JSON 对象,程序应逐行解析并拼接回答片段,直到完成。不能直接把整段流当作一个 JSON 文档解析。流式响应格式
本文先显式关闭流式输出,目的是让第一次调用容易理解。以后制作聊天界面时,再考虑流式展示。还要处理生成过程中的错误:流已经开始后,即使中途出错,HTTP 状态也未必改变,错误可能出现在后续的数据对象中。API 错误处理
八、实战:用 Python 写一个多轮聊天程序
下面把 HTTP 请求变成一个完整的小程序。你需要先安装仍受维护的 Python 3,确认终端可以运行 Python,并启动 Ollama、下载本文模型。程序只使用 Python 标准库,不需要额外安装第三方包。
在你自己的练习目录里新建 chat_local.py,把下面的完整代码保存进去。本文的全部实现都在这里,不需要下载额外源码。
import json
import socket
import urllib.error
import urllib.request
API_URL = "http://localhost:11434/api/chat"
MODEL = "qwen3:4b"
TIMEOUT_SECONDS = 180
MAX_HISTORY_ROUNDS = 4
SYSTEM_MESSAGE = {
"role": "system",
"content": "你是中文学习助手。优先回答当前问题;不确定时明确说明。",
}
def request_answer(messages):
payload = {
"model": MODEL,
"messages": messages,
"stream": False,
"think": False,
"options": {
"temperature": 0.3,
"num_ctx": 4096,
"num_predict": 512,
},
}
request = urllib.request.Request(
API_URL,
data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
headers={"Content-Type": "application/json; charset=utf-8"},
method="POST",
)
try:
with urllib.request.urlopen(request, timeout=TIMEOUT_SECONDS) as response:
result = json.loads(response.read().decode("utf-8"))
except urllib.error.HTTPError as exc:
detail = exc.read().decode("utf-8", errors="replace")
raise RuntimeError(f"HTTP {exc.code}: {detail}") from exc
except urllib.error.URLError as exc:
raise RuntimeError(f"无法连接或读取 Ollama 服务:{exc.reason}") from exc
except (TimeoutError, socket.timeout) as exc:
raise RuntimeError("请求超时,请检查模型大小和电脑负载。") from exc
if not isinstance(result, dict):
raise RuntimeError("服务返回了意外的数据结构。")
if result.get("error"):
raise RuntimeError(str(result["error"]))
if result.get("done") is not True:
raise RuntimeError("本次响应尚未完成,请检查接口和流式设置。")
message = result.get("message")
if not isinstance(message, dict):
raise RuntimeError("响应中缺少 message 对象。")
answer = message.get("content")
if not isinstance(answer, str) or not answer.strip():
raise RuntimeError("没有收到回答正文,请检查模型能力与生成参数。")
return answer
def main():
history = []
print(f"本地模型:{MODEL}")
print("输入 /reset 清空当前程序的历史;输入 /exit 退出。")
while True:
try:
question = input("\n你:").strip()
except (EOFError, KeyboardInterrupt):
print("\n已退出。")
break
if question == "/exit":
break
if question == "/reset":
history.clear()
print("已清空历史。")
continue
if not question:
continue
user_message = {"role": "user", "content": question}
messages = [SYSTEM_MESSAGE] + history + [user_message]
try:
answer = request_answer(messages)
except KeyboardInterrupt:
print("\n已退出,服务端可能仍在处理刚才的请求。")
break
except (RuntimeError, ValueError, OSError) as exc:
print(f"调用失败:{exc}")
continue
print(f"\n助手:{answer}")
history.extend([
user_message,
{"role": "assistant", "content": answer},
])
history = history[-2 * MAX_HISTORY_ROUNDS:]
if __name__ == "__main__":
main()
macOS、Linux 的运行命令:
python3 chat_local.py
Windows 如果已经安装 Python Launcher,可以运行:
py -3 chat_local.py
如果没有 py 命令,但已经正确配置 python,也可以使用 python chat_local.py。文件保存为 UTF-8,运行时让终端停留在该文件所在目录。
怎么确认多轮对话真的生效
程序启动后,依次输入:
请记住:我正在学习网络编程,今天的主题是 TCP。
我今天学习的主题是什么?
/reset
我今天学习的主题是什么?如果没有记录,请说明不知道。
/exit
第二问应能参考前面的消息;清空后,程序不会再发送之前的学习主题,模型应根据当前材料回答。模型仍可能猜测,因此判断程序是否传对历史,要检查发送的 messages,而不能仅凭一次回答措辞。
为什么历史记录由程序维护
在这份实现中,每次请求都会发送系统要求、保留的历史和当前问题。/api/chat 不会因为上次来自同一个终端,就自动替你的程序记住所有对话。多轮效果来自调用方正确组织消息。聊天消息定义
MAX_HISTORY_ROUNDS 控制保留最近几轮,TIMEOUT_SECONDS 控制客户端等待时间,MODEL 与 API_URL 分别指定模型和服务地址。失败的请求不会加入成功历史,避免下一次对话混入没有得到回答的半轮消息。
这里按轮数截断历史,是便于理解的简化方案,不是精确的 Token 管理。即使只保留四轮,如果每轮输入都很长,仍然可能超过上下文预算。正式应用需要限制单条输入、计算或估算 Token,并根据任务决定是否压缩历史。
程序退出后,内存中的聊天记录就丢失;这份代码没有把消息写入磁盘。若将来增加保存功能,应明确保存位置、保留期限和删除方式。客户端超时或被中断,也不一定意味着服务端已经停止生成,不要立刻开启许多重复请求。
九、进一步练习:让模型返回结构化数据
聊天回答适合人阅读,程序处理业务时往往更需要字段明确的 JSON。例如,你希望从一句通知里提取活动名称和地点,而不想再从一整段解释中查找答案。
Ollama 的本地接口支持通过 format 提供 JSON Schema,约束输出结构。下面的示例仅针对本地模型;云端能力需要另外核对,不能因为接口地址或字段相似,就假定所有功能一致。结构化输出文档
在 macOS 或 Linux 终端执行:
curl --fail-with-body http://localhost:11434/api/chat \
-H 'Content-Type: application/json' \
-d '{
"model": "qwen3:4b",
"messages": [
{
"role": "user",
"content": "只根据材料提取信息并返回 JSON,字段为 title 和 location,都是字符串。材料:读书分享会将在社区二楼举行。"
}
],
"stream": false,
"think": false,
"format": {
"type": "object",
"properties": {
"title": {"type": "string"},
"location": {"type": "string"}
},
"required": ["title", "location"],
"additionalProperties": false
},
"options": {"temperature": 0, "num_predict": 256}
}'
HTTP 响应本身是一个 JSON 对象,其中 message.content 仍然是字符串。处理时要先解析外层响应,再把 message.content 当 JSON 字符串解析,最后检查字段和业务规则。
Schema 约束的是结构,不能替你证明活动地点提取正确,也不能证明原材料真实。如果材料没有说明报名人数,就不应让模型凭空补一个数字。做数据抽取时,最好预先约定缺失值如何表示,再对照原文检查。
十、用 Modelfile 固定助手的行为
如果你经常重复同一套系统提示,可以创建一个基于现有模型的命名配置。例如,做一个专门帮助你复习计算机基础的中文助手。
在自己的练习目录里创建名为 Modelfile 的文件,不要自动加成 .txt 后缀,内容如下:
FROM qwen3:4b
PARAMETER temperature 0.3
PARAMETER num_ctx 4096
PARAMETER num_predict 512
SYSTEM """
你是一位中文计算机基础学习助手。
回答先给核心结论,再举一个短例子。
遇到资料不足时明确说明,不编造出处。
用户请求练习时,先给题目,等用户作答后再点评。
"""
在这个文件所在目录执行:
ollama create study-helper -f ./Modelfile
ollama run study-helper --think=false
FROM 指定基础模型,PARAMETER 保存运行参数,SYSTEM 保存系统要求。名称 study-helper 是你为这个配置起的名字,创建完成后也可以在 API 的 model 字段中使用它。Modelfile 官方参考
这里通过 --think=false 关闭本次运行的思考,避免短输出预算主要消耗在思考阶段。这个开关属于运行请求,上面的 Modelfile 没有保存它;API 调用仍需显式传入相应的 think 设置。CLI 思考开关
这份配置没有进行权重训练。给助手起一个新名字、改变温度或写入一段角色说明,不会让模型学会新的专业知识,也不会让它自动读取你电脑里的笔记。
理解这一点,可以避免把几种不同工作混在一起:系统提示用于约定行为,检索用于把相关资料送进输入,微调涉及调整模型权重。初学阶段先把提示与输入组织好,通常就能解决一批实际问题。
十一、模型为什么慢,怎样判断内存是否够用
性能排查要从可观察的信息开始。与其马上修改十几个环境变量,不如先用短提示词运行一次,再查看:
ollama ps
重点看 PROCESSOR 和版本支持时显示的 CONTEXT。PROCESSOR 反映模型在 CPU、GPU 之间的加载分配,并不是任务管理器里的实时 GPU 利用率百分比。上下文实际分配可能受版本、硬件、模型和设置影响,不要把某个教程里的默认值当成永久规则。上下文与卸载检查
先区分四种等待
第一次运行时,等待可能发生在下载、模型加载、输入处理或者答案生成阶段。下载慢应检查网络;模型加载慢要看存储和内存;长输入处理慢,要先缩短材料;生成慢才更直接涉及推理吞吐。
如果同一个模型首次请求较慢、紧接着第二次较快,可能是第一次包含了加载开销。不要把下载时间或首次加载时间当成模型持续生成速度。
对于 API,返回的 load_duration、prompt_eval_duration 和 eval_duration 可以帮助区分这些阶段。时间字段以纳秒计;在 eval_duration 大于零时,可以用 eval_count / (eval_duration / 1e9) 粗算生成阶段的 Token 每秒。这不等于用户从发出请求到看到答案的总体验。响应统计字段
优先尝试这些调整
- 把模型换小,确认短问答能够稳定完成,再考虑增加规模。
- 缩短输入,减少不必要的对话历史和重复资料。
- 把上下文显式设为短任务需要的范围,不要第一次就追求超长窗口。
- 通过
ollama ps看是否同时加载了不需要的模型,必要时使用ollama stop。 - 检查其他应用的内存、显存占用,再检查驱动与硬件兼容性。
扩大上下文有成本:它会提高运行资源需求。把 num_ctx 设置得很大,也不会让模型自动拥有更可靠的长文理解能力,更不能超过模型及当前运行方式支持的范围。
如果 API 用完后希望立即卸载模型,可以在请求的顶层设置 keep_alive: 0;它管理的是模型驻留时间,不会删除模型文件。频繁卸载又马上重新加载,会增加下一次请求的等待时间,应按使用频率选择。模型驻留参数
十二、模型存在哪里,配置为什么没有生效
模型下载后会持续占用磁盘。学习初期建议只保留一两个练习模型,明确用途后再下载更多版本。需要清理时,优先使用 ollama rm,避免手动删除内部文件导致管理信息与实际文件不一致。
常见默认模型目录如下;实际位置还取决于安装方式、服务用户及自定义设置:
| 环境 | 常见模型目录 |
|---|---|
| macOS 当前用户应用 | ~/.ollama/models |
| Windows 当前用户应用 | C:\Users\你的用户名\.ollama\models |
| Linux 官方标准服务安装 | /usr/share/ollama/.ollama/models |
可以通过 OLLAMA_MODELS 指定其他目录。环境变量要进入运行 Ollama 服务的进程才有效。只在新终端里设置变量,通常不会改变已经运行的桌面后台程序或 systemd 服务。模型位置与服务配置
不同平台可以按以下方式处理:
- Windows:在用户环境变量中设置
OLLAMA_MODELS,完全退出托盘里的 Ollama,再从开始菜单启动。 - macOS:为桌面应用通过
launchctl setenv设置变量,然后退出并重新启动 Ollama。 - Linux systemd:通过服务覆盖配置设置变量,再重载并重启服务,确认服务用户能够读写目标目录。
例如,Windows 用户可以把变量值设置为 D:\OllamaModels。设置新路径本身不会自动把旧模型全部搬过去;迁移前先停止服务,确认旧目录和备份,再决定移动已有文件还是重新下载。重新启动后,通过 ollama ls 和一次实际对话确认模型可见且可用。
如果只想在本地使用,可以按官方说明给服务设置 OLLAMA_NO_CLOUD=1 并重启。这个配置用于禁用 Ollama 云功能,不是系统级断网开关,也不代表其他应用失去了网络访问能力。仅本地运行配置
十三、常见问题:按现象找到下一步
遇到故障,先记录系统版本、Ollama 版本、模型完整名称、执行命令和完整错误,再按下面的顺序检查。这样比反复重装更容易保留线索。
1. 提示找不到 ollama 命令
先确认应用已安装并启动,再重新打开终端。应用能运行但命令找不到,通常应优先检查 PATH 或命令行链接。Windows 和 macOS 的安装步骤都提供了命令行入口,不要把下载了安装文件当成已经完成安装。
2. 提示无法连接服务
先请求 /api/tags。如果连接被拒绝,检查后台应用是否启动;Linux 使用 systemd 时检查服务状态。手动运行 ollama serve 的用户则确认对应终端仍然保持运行。
如果 Python 程序在容器、远程服务器或另一台电脑上运行,localhost 指的是那个程序所在的环境,不是你桌面上的电脑。先画清楚“调用方在哪里、服务在哪里”,再确定应该使用哪个地址。
3. 提示地址已经被占用
通常是已有一个服务监听了同一端口。先验证现有服务是否正常;如果正常,直接使用它。不要遇到这个错误就随机杀掉进程,也不要一边运行桌面应用,一边启动多个独立服务。
4. 提示模型不存在,或者下载标签找不到
先执行 ollama ls,检查模型名称和标签,再与官方模型页核对。qwen3、qwen3:4b 和其他标签不能凭感觉互换。API 返回 404 也可能涉及请求路径,应该结合响应里的 error 信息判断。错误状态说明
如果提示模型架构或功能不受支持,先查看该模型要求的 Ollama 版本及官方发布说明,再更新程序。重新下载同一份模型,未必能解决运行时版本过旧的问题。
5. 下载速度很慢或反复失败
先检查剩余磁盘空间、网络连接和服务日志。如果你的网络需要代理,要把相应配置交给下载模型的服务进程。修改当前终端变量后仍使用旧后台进程,可能看不到任何变化。
代理、证书和网络错误需要按实际环境排查。不要把未知来源的镜像、脚本或模型文件直接替换进现有目录。模型来源和完整性不清楚时,即使能运行,也会增加后续维护的不确定性。
6. 内存不足、模型加载失败或电脑明显卡顿
先停止不需要的模型和应用,再换更小的模型、缩短上下文。磁盘还有很多空间,并不能解决内存或显存不足。若系统频繁使用交换空间,整个桌面也可能变慢。
观察 ollama ps,结合系统资源监视器和服务日志判断。先让单个短请求成功,再增加历史长度或并发,避免同时改变多个因素。
7. 有显卡,但似乎一直使用 CPU
检查 ollama ps 的加载分配,再对照硬件支持列表、驱动要求和日志。对于 NVIDIA 环境,nvidia-smi 能帮助确认驱动是否识别显卡,但它本身不能证明 Ollama 已把当前模型完整加载到 GPU。
不同计算后端的兼容性会变化。按照你实际安装版本的说明处理,不要为一个无关教程的配置强行覆盖 GPU 型号或计算架构。官方硬件说明
8. 返回一堆 JSON,或者程序说 JSON 解析失败
先检查 stream。原生流式响应是一行一个 JSON;非流式才适合一次解析为一个外层对象。再检查接口:/api/chat 的正文位于 message.content,不能照搬另一个接口的字段路径。
如果使用结构化输出,还要记得解析 message.content 里的 JSON 字符串。接口响应正常、JSON 结构有效和业务字段正确,分别需要验证。
9. 回答容易编造,或者总是答非所问
先换成短而明确的问题,提供必要材料,并要求标出不确定部分。模型没有接入检索时,不能保证知道刚发生的事情;你把一个网址发给它,也不代表它已经读取了网页。
同样,发出“请阅读我的电脑文件”不会让模型自动获得文件内容。读取文件、联网、调用工具需要应用层提供相应能力。处理重要结论时,返回原始资料核对,比单纯降低温度更可靠。
10. 去哪里看日志
手动运行 ollama serve 时,先看那个终端的输出。其他常见位置如下:故障排查文档
| 平台 | 查看方式 |
|---|---|
| macOS | 查看 ~/.ollama/logs/server.log |
| Windows | 打开 %LOCALAPPDATA%\Ollama,查看 server.log |
| Linux systemd | 执行 journalctl -u ollama -n 100 --no-pager |
反馈故障时提供必要上下文即可;粘贴日志前检查其中是否包含自己的路径、提示内容或其他不希望公开的信息。
十四、局域网访问之前,先理解服务边界
默认的本地监听地址适合个人电脑实验。修改 OLLAMA_HOST 可以改变监听范围,但 Ollama 本地 API 本身不要求认证。把端口对外开放,并不会自动出现用户登录和权限管理。监听配置 · 认证边界
因此,第一次练习建议保持本机访问。如果以后要让局域网设备调用,应先确定允许哪些设备、通过什么网络访问,并在需要时通过有认证的网关或反向代理提供访问控制。公网部署还需要考虑加密、请求限制和资源配额。
浏览器报跨域错误时,也要区分来源规则与访问认证。允许一个网页来源发起请求,并不等于这个网页里的用户已经通过身份验证。不能用放开跨域规则代替服务的权限设计。
第三方聊天界面同样要配置正确的服务地址。浏览器、界面的后端和 Ollama 可能在不同环境里,界面设置里的 localhost 究竟指向谁,应按请求实际从哪个进程发出判断。
十五、接下来怎样继续学习
完成本文后,可以按下面的顺序继续,每一步都保留一个能够人工核对的小样本。
先稳定使用一个模型。 选取五到十条常用任务,例如整理笔记、解释术语、修改通知,把提示词和期待的输出结构保存下来。以后更新模型时,重新运行同一批任务,比仅凭一次聊天更容易判断变化。
再把模型接入一段实际流程。 可以把今天的 Python 程序改成“读取你明确指定的一段文本并生成摘要”,随后加入输入长度限制、错误提示和输出保存。先把一个小流程做好,再扩展到复杂界面。
需要资料问答时,再学习检索增强。 它通常包括解析资料、切分文本、建立检索索引、找出相关片段,再把片段交给模型回答。Embedding 模型用于把内容转成便于检索的向量,与直接聊天的模型承担不同任务。
需要自动执行动作时,再学习工具调用。 模型提出调用请求后,仍需要应用验证参数、执行函数并把结果返回。让模型能提出一个操作,和允许它不受限制地操作电脑,是不同层面的系统设计。
你也可以先使用 Ollama 自带的桌面界面熟悉模型,再考虑第三方界面、知识库或开发工具集成。界面只是入口,模型能力、上下文预算、数据流向和调用程序的错误处理,仍然是理解整个系统的基础。
十六、入门完成检查
做到下面这些,就已经具备继续实践的基础:
- 能运行
ollama --version,并确认本地 HTTP 服务可达。 - 能下载一个明确标签的本地模型,完成两轮相关对话。
- 能区分
ollama ls、ollama ps、ollama stop和ollama rm。 - 能通过
/api/chat发送请求,知道回答正文在哪个字段里。 - 能运行 Python 程序,理解历史为什么需要由调用方传入。
- 知道长上下文会增加资源需求,遇到慢或报错时会检查日志。
- 能判断当前使用的是本地还是云端能力,并理解本地 API 的访问边界。
下一次打开 Ollama 时,可以从一份真实但不敏感的学习笔记开始:先提出明确要求,检查输出,再把重复操作写进脚本。这样,每一个新参数和每一次集成,都能对应到你已经理解的具体需求。
官方资料与版本说明
本文于 2026 年 11 月 22 日依据官方资料整理。模型标签、平台要求和功能支持会更新,文中 qwen3:4b 是教学基线,不代表最新版本或通用性能结论。
安装与推理需要在读者自己的系统上验证;不同硬件上的速度、内存和显卡兼容性不能由教程统一保证。完整示例保留在正文中,遇到版本差异时优先核对下列官方入口: