本地大语言模型部署初探:基于 Ollama 与 Qwen3 的实践与分析
本次部署使用 M5 Pro MacBook Pro、Ollama 和 Qwen3-8B 的 Q4_K_M 量化版本。模型启动后,检查加载状态和生成速度,再通过 Ollama 的本地 API 接入 DeepSeek Harness。
下载和启动只需要几条命令。过程中更值得记录的是几个具体问题:5.2GB 的模型为什么加载后显示 10GB,100% GPU 表示什么,以及本地服务不需要密钥,客户端为什么仍然报 API Key 错误。
第一章:背景与部署目标
1.1 为什么考虑本地部署大语言模型?
本地部署可以用于学习模型推理和 API 接入。从下载权重、检查运行状态到配置客户端,可以直接观察模型从文件加载为服务的过程。
本地部署与云端服务的主要区别如下:
| 比较维度 | 本地部署 | 云端服务 / API |
|---|---|---|
| 计算资源 | 使用本机资源,受可用内存和计算能力限制 | 使用服务商的资源,能力与配额取决于所选服务 |
| 模型与环境 | 可以选择支持的模型、量化版本和运行配置 | 服务商管理底层环境,用户通过界面或 API 使用 |
| 网络依赖 | 权重准备好后,纯本地推理可以离线 | 通常需要连接远端服务 |
| 数据处理 | 本地推理路径可以在设备内处理输入 | 输入需发送至服务商,处理方式取决于服务政策 |
| 成本 | 硬件、电力、存储和维护成本 | 订阅或按量计费等成本 |
| 使用体验 | 需要自行处理下载、配置、更新和兼容问题 | 更容易直接开始使用,但存在网络、配额等限制 |
对于已有合适硬件、需要离线处理文本或想学习部署的人,本地模型值得尝试。需要特定模型的能力或较高并发时,使用云端服务通常更方便。成本则取决于调用频率、硬件投入和模型选择,不能只比较 API 费用。
模型可以离线推理,客户端的更新、搜索和插件仍可能联网。涉及数据隐私时,还需要检查这些功能的请求会发往哪里。Ollama 本身也支持云端模型,使用时需要确认选中的是本地模型。Ollama FAQ
1.2 本次实践的目标与环境
这次实践包括三个部分:
- 在 Apple Silicon 上运行一个开放权重的大语言模型。
- 查看加载状态、内存统计和短文本生成速度。
- 通过本地 API,让第三方客户端调用模型。
实验环境如下:
| 项目 | 配置 |
|---|---|
| 设备 | MacBook Pro |
| 芯片 | Apple M5 Pro |
| 统一内存 | 48GB |
| 操作系统 | macOS Golden Gate 27.0.1 |
| 运行与服务工具 | Ollama 0.35.1 |
| 模型名称 | qwen3:8b |
| 权重量化方案 | Q4_K_M |
| 第三方客户端 | DeepSeek Harness Desktop 0.2.0-rc.2 |
| 接入协议 | OpenAI Chat Completions |
文中的性能数据来自这台 Mac,48GB 是设备配置,并非模型的最低内存要求。
第二章:本地大语言模型部署的基础架构
2.1 本地模型系统由哪些部分组成?
从输入到返回结果,大致经过以下环节:
用户输入
↓
客户端:终端 / Ollama 桌面端 / DeepSeek Harness
↓
服务接口:Ollama 原生 API / OpenAI 兼容 API
↓
Ollama 服务:管理模型、接收请求、组织推理
↓
推理后端:加载 Qwen3-8B 权重,在硬件上执行计算
↓
生成结果,经接口返回客户端
模型权重保存训练得到的数值参数。推理时,程序读取这些参数,对输入文本进行计算。
推理后端负责加载权重、处理输入、管理缓存,并逐步生成 token。模型服务在此基础上接收客户端请求、安排推理并返回结果。
客户端负责组织会话和展示回答,也可能调用工具或管理任务。这里使用的客户端是 DeepSeek Harness,语言模型是 Qwen3-8B。
Ollama 已经集成模型管理、推理运行和服务接口,无需按图中的每一层分别安装软件。
2.2 Ollama、LM Studio、llama.cpp 与 MLX 的区别
选型时经常会遇到以下工具。它们有的是应用,有的是推理项目或机器学习框架:
| 工具 | 主要定位 | 功能与使用场景 |
|---|---|---|
| Ollama | 模型管理、运行与服务工具 | 提供命令行、桌面端和 API,本次使用的工具 |
| LM Studio | 本地模型应用 | 通过图形界面下载、聊天和提供模型服务 |
| llama.cpp | 模型推理项目 | 支持 GGUF 格式和多种硬件后端 |
| MLX | Apple 发起的机器学习数组框架 | 面向 Apple Silicon 优化,可用于构建推理程序 |
| MLX-LM | 基于 MLX 的语言模型工具 | 用于文本生成和模型微调 |
| vLLM | 推理服务系统 | 面向高吞吐、批处理等服务场景 |
Ollama 可以使用 MLX 作为推理引擎,官方在 2026 年已经加入了这项支持。Ollama MLX 公告
这次下载的 Q4_K_M 版本更可能走 GGUF 推理路径,具体后端还需要查看运行日志。仅凭 ollama ps 显示的 GPU 状态,无法判断是否使用了 MLX。
2.3 为什么选择 Ollama?
Ollama 提供模型库、下载与运行命令、状态查询和本地 API。初次部署无需单独配置服务框架,就能完成模型运行和客户端接入,因此本次采用 Ollama。
第三章:模型选择与基本概念
3.1 怎样理解开放权重模型?
本地推理需要先获取模型权重。Qwen、DeepSeek 和 Gemma 等模型家族都有公开权重,但不同版本的规模、用途和许可证可能不同,下载前需要查看具体模型的说明。Qwen3-8B、DeepSeek-R1、Gemma 文档
“开放权重”指权重可以获取,训练数据和完整训练流程可能并未公开。修改、分发或商用的条件,需要查看对应许可证。
本次选型主要考虑中文文本能力、Ollama 支持情况和量化后的资源需求。公开评测可以参考,实际任务中的回答质量仍需通过测试判断。
3.2 什么是模型参数量?
模型参数是训练过程中学习到的数值。模型名称中的 B 是 Billion,即十亿:7B 约为 70 亿参数,8B 约为 80 亿参数,14B 约为 140 亿参数。
参数量影响存储和计算需求,但不单独决定回答质量。架构、训练、任务类型、上下文和量化方式都可能改变实际表现;对于混合专家模型,还需要区分总参数量与每次计算激活的参数量。
参数量、磁盘空间和运行内存分别描述不同的量:
| 概念 | 描述的对象 |
|---|---|
| 参数量 | 模型包含多少参数 |
| 模型文件大小 | 权重等内容在磁盘上占用的空间 |
| 运行资源占用 | 加载和推理时需要的内存、缓存及其他资源 |
同样约 80 亿参数,采用不同数值表示,文件大小会不同;同一份权重,在不同上下文和并发设置下,运行资源需求也可能不同。
3.3 什么是模型量化?
量化使用更低位宽的数值近似表示权重等数据,减少存储和运行开销。它会引入数值误差,对回答质量的影响与模型、量化方案和任务有关。
常见的权重表示与量化方案大致有以下区别:
| 权重表示与量化方案 | 基本含义 | 需要注意 |
|---|---|---|
| FP16 / BF16 | 16 位浮点表示 | 常作为较高精度权重的表示方式,二者数值特性不同 |
| Q8 类方案 | 通常以约 8 位的低位宽表示为主 | 具体资源和质量取决于方案 |
| Q5 类方案 | 通常以约 5 位表示为主 | 可作为精度与资源需求之间的折中 |
| Q4 类方案 | 通常以约 4 位表示为主 | 文件更紧凑,不代表所有张量都使用完全相同的表示 |
FP16/BF16 是浮点格式,Q4、Q5、Q8 则是量化方案的简写。具体到 Q4_K_M,部分张量会采用不同表示,文件中还包含量化元数据,因此不能按每个参数恰好 4 bit 计算文件大小。推理速度也受硬件和实现影响,并非位宽越低就一定越快。llama.cpp 量化说明
下载的模型信息如下:
| 属性 | 内容 |
|---|---|
| 模型 | Qwen3-8B |
| 调用名称 / 标签 | qwen3:8b |
| 参数量 | 8.19B,Ollama 页面显示值 |
| 权重量化方案 | Q4_K_M |
| 文件大小 | 约 5.2GB |
ollama list 显示的摘要标识 |
500a1f067a9f |
这些信息与 Ollama 模型库中的条目一致。调用时使用 qwen3:8b,摘要标识 500a1f067a9f 用于核对下载的版本。同一个标签的内容可能更新,因此记录模型时最好同时保留摘要。Ollama 模型页面
3.4 为什么选择 Qwen3-8B?
Qwen3-8B 支持中文文本任务,Q4_K_M 版本约 5.2GB,适合在这台设备上做初步部署。它还支持思考模式和工具调用,后续可以继续测试这些功能。
这里使用的是文本语言模型,图片和音频输入需要选择对应的多模态模型。Qwen3-8B 模型说明
第四章:基于 Ollama 的本地部署实践
4.1 安装并确认服务
安装 Ollama:
curl -fsSL https://ollama.com/install.sh | sh
也可以从官方 macOS 下载页面下载安装应用。Ollama macOS 下载页面
安装后验证:
ollama --version
安装后的版本输出为:
ollama version is 0.35.1
命令行通过 Ollama 服务运行模型。在默认本地配置下,桌面端与命令行共用服务和模型存储,已经下载的模型无需重复下载。
如果提示无法连接服务,先检查 Ollama 应用是否已启动。只使用命令行时,可以在一个终端中运行 ollama serve,再从另一个终端执行后续操作;已有服务运行时无需重复启动。
4.2 检查本地模型
ollama list
初次执行时,列表中没有模型。安装 Ollama 后,还需要另外下载模型权重。
ollama list 用来查看本地保存的模型,后面的 ollama ps 则用来查看当前加载的模型。模型在磁盘上存在,不代表它此刻正在占用推理所需的内存。
4.3 下载 Qwen3-8B
ollama pull qwen3:8b
下载时曾遇到速度下降,进度接近完成后停滞。遇到这种情况,可以中断后重试同一命令,已有的有效下载内容通常可以复用。
下载完成后,ollama list 中出现了以下条目,这里保留名称、摘要和大小三个字段:
NAME ID SIZE
qwen3:8b 500a1f067a9f 5.2 GB
4.4 启动模型并测试对话
ollama run qwen3:8b
进入交互模式后,输入一个简短的中文问题:
用中文简单解释一下什么是本地大语言模型,不超过200字。
模型正常返回了中文回答,内容准确性仍需另行检查。
退出交互模式使用:
/bye
退出会话不一定立即卸载模型。如果需要主动卸载,可使用 ollama stop qwen3:8b;Ollama 也会根据保留时间和运行状态管理已加载模型。模型保留与卸载说明
4.5 查看模型运行状态
在模型加载后执行:
ollama ps
当时显示的主要字段为:
NAME SIZE PROCESSOR CONTEXT
qwen3:8b 10 GB 100% GPU 32768
这里出现了几个容易混淆的数字:磁盘上的模型约 5.2GB,加载后显示 10GB,处理器一栏则是 100% GPU。
第五章:模型资源占用与推理性能分析
5.1 为什么文件约 5.2GB,运行显示约 10GB?
5.2GB 是磁盘上的模型文件大小。加载后,除了权重,还需要 KV Cache、计算缓冲区等空间:
运行资源需求 ≈ 权重 + KV Cache + 计算缓冲区 + 其他运行时资源
各部分占多少空间,与模型结构、上下文、缓存精度、并发和推理实现有关。
Apple Silicon 的 CPU 和 GPU 共享统一内存,系统和其他应用也会使用这部分空间。因此,48GB 统一内存不能全部当作模型可用的专用显存。MLX 同样在共享内存上执行 CPU 和 GPU 计算。MLX 官方说明
ollama ps 的 10GB 是 Ollama 对当前加载模型的统计,不等于系统实际物理内存增加了 10GB。由于没有同时记录活动监视器的数据,各部分开销还无法拆分,也不能把与文件大小的差额全部归到 KV Cache。
5.2 100% GPU 代表什么?
根据 Ollama 官方文档,PROCESSOR 列描述模型的加载分配状态:
| 显示值 | 基本含义 |
|---|---|
100% GPU |
模型完全加载到 GPU 侧 |
100% CPU |
模型完全加载到 CPU 侧的系统内存 |
48%/52% CPU/GPU |
模型部分加载到 CPU 侧、部分加载到 GPU 侧 |
这次显示 100% GPU,说明模型完全加载到 GPU 侧。GPU 利用率是另一项指标,CPU 仍会参与请求处理和调度等工作。在这台 Mac 上,GPU 使用的也是统一内存。Ollama GPU 加载说明
5.3 上下文窗口与 KV Cache
token 是模型处理文本的基本单位,常译作“词元”。它可能对应一个字、一个词的一部分或其他文本片段,所以 token 数不能直接等同于中文字数。
上下文窗口限制模型一次推理能够处理的序列长度,输入、历史对话、系统提示和生成内容都需要考虑在内。聊天界面可以保存更长的历史,但客户端可能通过截断或摘要等方式组织实际发送的上下文。
KV Cache 保存此前 token 在注意力计算中产生的键和值。生成后续 token 时复用这些结果,可以减少重复计算。更长的上下文通常需要更多缓存空间,具体是提前分配还是按需增长,取决于推理实现。
CONTEXT: 32768 是当时加载实例的上下文配置,实际输入远短于这个长度。Qwen3-8B 的原生上下文为 32768 token,使用 YaRN 可以扩展。这次没有测试上下文扩展或长文本效果。Qwen3-8B 上下文说明
5.4 单次短文本生成的数据
下面是当时一次短文本测试的数据。温度、电源模式等设置没有完整记录,这组数据主要用来观察生成速度。
total duration: 8.352425667s
load duration: 3.585417ms
prompt eval count: 27 token(s)
prompt eval cached: 3 token(s)
prompt eval duration: 171.366ms
prompt eval rate: 140.05 tokens/s
eval count: 406 token(s)
eval duration: 8.1601s
eval rate: 49.75 tokens/s
Prompt Eval Rate 是输入处理速度。27 个输入 token 中有 3 个命中缓存,实际计算的部分为 24 个:
(27 − 3) / 0.171366 ≈ 140.05 token/s
输入统计可能包含对话模板等内容,并不只对应问题中的文字。这次输入很短,140.05 token/s 不适合用来估计长文档的处理速度。
Eval Rate 是生成阶段的平均速度。406 个 token 用时 8.1601 秒:
406 / 8.1601 ≈ 49.75 token/s
上述速率计算方式与 Ollama 0.35.1 的指标输出实现一致。Ollama 0.35.1 指标源码
Qwen3-8B 支持思考模式。这 406 个 token 可能包含思考内容;当时没有完整保留模式设置和输出分段,因此不能直接把它看作最终回答的长度。Qwen3-8B 思考模式说明
加载耗时仅约 3.6ms,结合此前已经运行过模型的操作,这次很可能是模型已驻留内存后的测试。冷启动加载时间需要另测,首个 token 的延迟也没有单独记录。
生成速度约为 49.75 token/s。这只是一次短文本结果,长上下文和持续运行的表现还需要重复测试。
运行时添加 --verbose,可以查看这些指标:
ollama run qwen3:8b --verbose "用中文简单解释一下什么是本地大语言模型,不超过200字。"
做性能比较时,需要固定模型版本、上下文和思考模式等条件,分别记录冷启动与模型已加载后的结果,并重复测量。缓存和输出长度的变化都会影响数据。
第六章:通过 API 接入 DeepSeek Harness
6.1 为什么要把模型作为服务使用?
模型运行正常后,可以通过 API 接入图形界面。客户端组织会话并发送请求,Ollama 负责推理和返回结果。
Harness 调用本地模型的路径如下:
DeepSeek Harness
↓ OpenAI Chat Completions 请求
http://127.0.0.1:11434/v1/chat/completions
↓
本机 Ollama 服务
↓
Qwen3-8B 本地推理
↓
结果返回 Harness
6.2 理解本地 API 地址
Harness 中配置的 API 基础地址为:
http://127.0.0.1:11434/v1
| 部分 | 含义 |
|---|---|
127.0.0.1 |
本机回环地址;本次客户端和服务位于同一台 Mac |
11434 |
Ollama 默认服务端口 |
/v1 |
OpenAI 兼容接口的基础路径 |
客户端会根据协议继续拼接具体接口路径。Ollama 也有 /api/chat 等原生接口,两种路径的请求格式不能直接混用。
支持 OpenAI 兼容协议的客户端,可以通过修改地址和模型名称来调用 Ollama。请求仍然发送到本机服务;Ollama 支持的功能与参数范围需要查看其兼容文档。Ollama 兼容接口文档
也可以直接发送一个请求,检查接口是否正常:
curl http://127.0.0.1:11434/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{
"model": "qwen3:8b",
"messages": [{"role": "user", "content": "你好,请用一句话介绍自己。"}],
"stream": false
}'
正常响应中的 choices[0].message.content 包含回答内容。直接请求可以帮助区分问题出在模型服务,还是上层客户端的配置。
6.3 配置自定义模型
在 Harness 的“设置 → 模型 → 自定义模型 API”入口中,配置如下:
| 参数 | 配置值 |
|---|---|
| Provider ID | ollama |
| 显示名称 | Ollama Local |
| API 地址 | http://127.0.0.1:11434/v1 |
| API 协议 | OpenAI Chat Completions |
| API Key | 非空占位字符串,例如 ollama |
| 模型 ID | qwen3:8b |
Provider ID 是客户端中自定义的服务标识,这里取名为 ollama。模型 ID 则需要与 ollama list 中的名称一致,填写完整的 qwen3:8b。
6.4 实际遇到的问题:API Key
初次调用时遇到以下错误:
No API key for provider: ollama
PI_AI_ERROR
在自定义模型配置中补上一个非空占位 Key 后,调用成功。
原因在于客户端或适配层可能在发送请求前检查凭据,即使本地 Ollama 并不验证这个 Key。官方兼容示例也使用占位值,Harness 社区有同样报错的讨论。Ollama 兼容示例、Harness 对应讨论
占位 Key 不提供访问控制。这次服务只通过本机回环地址调用,若以后开放给其他设备,需要另外配置认证等保护措施。
6.5 接入后的观察
保存配置后,在会话中选择 Ollama Local 下的 qwen3:8b,就可以通过 Harness 与本地模型对话了。
在一次会话中,界面显示的速度约为 40 tok/s。它与前面的终端测试使用了不同的上下文,统计方式也未必相同,所以不能用两个数字的差值来衡量客户端带来的性能损失。
普通对话调用成功后,工具调用和文件操作仍需要分别测试。模型生成工具调用请求,由 Harness 或其运行环境执行。
第七章:总结与后续研究方向
7.1 本次实践的结论
Qwen3-8B 的 Q4_K_M 版本在这台 M5 Pro MacBook Pro 上正常运行,Ollama 显示完整 GPU 加载。一次短文本测试的生成速度约为 49.75 token/s,随后也成功接入了 DeepSeek Harness。
这次主要完成了模型下载、运行状态检查和 API 接入。遇到的配置问题是 Harness 要求凭据,而本地 Ollama 忽略该凭据,补上占位 Key 后即可正常调用。
7.2 本次实践的局限
目前只做了一次短文本性能测试,还没有重复测量,也没有完整记录测试参数。内存分析使用的是 Ollama 的报告值,缺少系统内存、内存压力和交换情况的数据;具体推理后端也需要进一步确认。
不同模型、量化方案和运行工具之间的比较,以及长上下文和复杂工具任务的表现,都还没有测试。
7.3 后续可以研究的方向
后续实验可以从模型规模和量化精度入手,比较相同任务下的资源占用、生成速度和回答质量。质量测试需要固定问题和评判标准,速度则需要重复测量。
另一个方向是比较 Ollama 与 MLX-LM。测试前应确认 Ollama 使用的后端,并尽量统一模型、量化、上下文和缓存条件。条件无法统一时,比较的就是两套运行方案,而不是单一框架的性能。
如果要在一个应用中同时使用本地与云端模型,可以先用简单规则分配任务,考虑数据能否离开设备,以及任务所需的能力、延迟和成本:
应用接收任务
↓
路由规则
├─ 适合本地处理 → 本地模型服务
└─ 适合远端处理 → 云端模型 API
↓
返回结果,并记录质量、延迟与成本
模型路由尚未实现。