在 MacBook 上运行大模型,最吸引我的地方,是可以把一部分开发和业务分析工作放到自己电脑上完成。比如解释一段库存预占 SQL、整理采购异常邮件、阅读仓库单据截图,或者给 Java 项目提供一个可调用的本地模型接口。
Gemma 4 提供了适合这些场景的模型尺寸。真正用起来之后,需要解决的问题也很具体:电脑能装下哪个版本?下载完成为什么还会内存不足?终端聊天如何升级成程序调用?怎样让模型返回业务系统能够校验的 JSON?
这篇笔记以 Apple Silicon MacBook 和 Ollama 为主线,从安装、模型选型、接口调用,一直讲到 MLX、结构化输出、Java 接入、供应链示例、性能评估和维护。文中的供应链数据是演示数据,可以用同一组输入比较不同模型。
一 先理解Gemma 4和本地运行环境
Gemma 是 Google DeepMind 的开放模型系列。Gemma 4 提供开放权重,包含预训练版和指令微调版,覆盖 E2B、E4B、12B、26B A4B、31B 等尺寸。日常对话和应用接入,应选择指令微调版,常见仓库名称中的 it 就是 instruction-tuned。Google模型卡
有几个名字需要先对齐:
| 名称 | 在本地部署中的作用 |
|---|---|
| Gemma 4 | 模型,决定理解和生成能力 |
| Ollama | 下载、加载、管理模型,并提供聊天与HTTP接口 |
| Metal | macOS上的GPU计算接口 |
| MLX | 适配Apple Silicon的机器学习框架,可作为推理运行时 |
| GGUF和MLX权重 | 不同运行时使用的模型文件形式,需要匹配支持的架构 |
| Java应用 | 组织业务上下文,调用模型,校验结果并执行后续流程 |
Gemma 4 的小尺寸模型具有 128K 上下文,12B、26B A4B 和 31B 具有最高 256K 的模型上下文能力。26B A4B 是混合专家模型,推理时只激活其中一部分参数;这会影响计算量,但不能据此把全部权重的内存需求按 4B 估算。模型结构说明
模型能力与客户端能力也要分开看。部分 Gemma 4 变体原生支持音频,但 Google 的 Ollama 部署说明将对应发行包列为文本和图像路线。本文用这些已说明的输入类型,不把录音文件直接发给文本聊天端点。Google的Ollama部署指南
二 判断自己的MacBook适合哪个版本
确认芯片 内存和系统
在 macOS 终端执行:
1 | uname -m |
arm64 通常表示当前终端运行在 Apple Silicon 原生环境。Apple Silicon 机器如果显示 x86_64,先检查终端是否通过 Rosetta 启动;Intel Mac 显示这个值则是正常情况。
Ollama 的 macOS 文档要求 macOS Sonoma 14 或更新版本,Apple M 系列支持 CPU 和 GPU,Intel x86 路线是 CPU 推理。本文后续性能调优主要面向 M 系列 MacBook;Intel 机型可以尝试小模型,但不要预期相同体验。macOS安装要求
按可用内存选择起点
下面是便于日常使用的保守起点,假设同时保留浏览器和必要开发工具,并从 4K 上下文、单请求开始;它不是官方最低配置或速度保证。
| 统一内存 | 建议从哪里开始 |
|---|---|
| 8GB | 优先评估E2B及较低位量化;内存压力较高时停止,不把它作为长期开发配置 |
| 16GB | 先试E2B或E4B;12B是否合适取决于量化、上下文和剩余内存 |
| 24GB | 可以从12B的较低位量化开始,逐步增加上下文 |
| 32GB至36GB | 12B通常更从容;26B需要额外评估运行时开销 |
| 48GB至64GB及以上 | 可评估26B或31B,再按真实任务调节上下文和并发 |
不要只看“下载文件是几 GB”。运行时的内存账本大致是:
1 | 模型权重 + KV Cache + 运行时缓冲 + 图像处理开销 |
Apple Silicon 的统一内存由 CPU、GPU 和系统共享。打开 IDE、Docker、数据库容器、浏览器之后,还能分配给模型的资源会明显减少。判断能否稳定使用时,观察活动监视器里的内存压力和交换空间,比只看总内存更有意义。
上下文也不是越长越好。先让一个 4K 请求稳定完成,再尝试 8K、16K;需要多文档检索或编程Agent时,再测更长的上下文。模型规格中的 128K、256K 上限,不等于当前笔记本可以舒适地使用这个长度。上下文配置
三 选择部署路线
| 路线 | 适合的情况 | 本文安排 |
|---|---|---|
| Ollama本地应用和CLI | 希望快速跑通,再给Java程序调用 | 完整主线 |
| Ollama的MLX标签 | Apple Silicon上比较不同推理后端 | 进阶对照 |
| Google AI Edge Gallery或LM Studio | 更偏好图形界面体验 | 可选入口 |
| 直接使用MLX LM等开发库 | 需要控制Python推理、转换或训练过程 | 后续研究方向 |
Google 已发布 Gemma 4 12B 的本地开发资料,并列出 Ollama、LM Studio 和 macOS AI Edge Gallery 等体验方式。初次部署只选一个入口即可,减少同时运行多个模型服务造成的资源竞争。Google开发指南
四 安装Ollama并验证服务
安装macOS应用
从 Ollama官方下载页 下载 macOS 安装包,将应用拖入 Applications,然后打开 Ollama。首次启动如果提示安装命令行链接,按提示完成。
重新打开终端后执行:
1 | ollama --version |
第一条应显示版本,第二条应返回本地模型列表。刚安装时列表为空很正常。
如果 ollama 命令找不到,先检查应用是否安装在标准位置,也可以临时使用应用内的CLI确认:
1 | /Applications/Ollama.app/Contents/Resources/ollama --version |
应用已经启动时,通常不需要再运行 ollama serve。只有选择纯终端方式、并且没有其他实例占用端口时,才在独立终端执行:
1 | ollama serve |
这个命令持续占用当前终端用于运行服务。另开终端执行后续请求;结束手工启动的服务可以按 Ctrl+C。CLI参考
为纯本地使用设置运行环境
Ollama 默认监听本机 127.0.0.1:11434。需要明确关闭其云端能力时,可在 macOS 终端设置应用环境:
1 | launchctl setenv OLLAMA_NO_CLOUD "1" |
完成后从菜单栏彻底退出 Ollama,再重新打开。launchctl setenv 影响之后启动的进程,需要在目标进程的启动环境中配置;它不是修改当前已运行服务的开关,也不保证跨登录永久保留。本地运行配置
首次安装和下载权重需要网络。文件下载完整后,使用本地标签可以断网验证聊天和API。浏览器前端、外部插件、联网搜索属于各自的网络路径,要分别判断。
五 下载Gemma 4并完成第一次聊天
16GB 机器可以先尝试 E4B,内存更紧张时换 E2B:
1 | ollama pull gemma4:e4b |
进入交互后输入:
1 | 请用Java后端工程师能理解的方式解释乐观锁。 |
也可以直接完成单次调用:
1 | ollama run gemma4:e4b "用中文解释数据库事务中的原子性" |
其他尺寸的标签如下,按硬件选择一个下载即可:
1 | ollama pull gemma4:e2b |
具体量化、文件大小和可用标签以 Ollama模型库 为准。模型标签可能更新,latest 也不是固定版本,所以演示和项目配置都写明确标签。
常用管理命令
1 | ollama ls |
ls 查看已下载模型,ps 查看当前加载模型及处理器分配,stop 卸载运行中的模型来释放资源,不会删除权重。确实需要删除某个已下载模型时,再使用 ollama rm 模型名。命令说明
六 先用HTTP把模型变成可调用服务
原生聊天端点是 POST /api/chat:
1 | curl --fail-with-body --max-time 120 \ |
先明确四个配置:stream:false 返回一次完整JSON,方便普通HTTP客户端解析;think:false 先关闭思考输出以建立短请求基线;num_ctx 控制本次上下文;num_predict 限制输出长度。思考模式是否可用以及支持哪些值,应以模型和当前服务返回的信息为准。聊天API
文字答案在 message.content。把 stream 改为 true 后,原生接口返回逐行JSON事件,客户端需要增量解析,不能把整段数据一次交给普通JSON反序列化。
每次 API 请求需要自己传入相关的历史 messages。上一轮聊天不会因为模型还在内存里,就自动成为下一轮请求的对话上下文。服务常驻、权重驻留和聊天历史是三个不同概念。
已有兼容客户端怎样接入
已有工具支持 Chat Completions 兼容接口时,可以使用:
1 | curl --fail-with-body --max-time 120 \ |
这条接口的答案位置是 choices[0].message.content。Ollama只兼容相关API的一个子集,不能因为基础聊天成功,就推断任意工具调用、状态会话或扩展参数都兼容。本文供应链程序直接使用原生接口,便于控制输出Schema和运行参数。兼容接口文档
七 固定系统提示和参数
在项目目录新建 Modelfile:
1 | FROM gemma4:e4b |
然后执行:
1 | ollama create supply-chain-gemma4 -f Modelfile |
这种方式是保存模型配置和提示模板,基础模型权重没有因此接受训练。需要改变模型知识或行为时,先确认问题来自提示、业务上下文还是能力本身,再决定是否微调。Modelfile说明
八 进阶比较Apple Silicon上的MLX路线
已经跑通普通标签后,再比较 MLX 版本:
1 | ollama pull gemma4:12b-mlx |
这里的 12b-mlx 是独立标签,不是给普通权重加一个命令参数。Google部署指南明确列出了 Apple Silicon 上通过 -mlx 标签使用 MLX 的方式。先确认自己安装的 Ollama 版本能够识别该标签,再评估是否保留普通版本作为对照。MLX标签说明
建议固定同一组需求、同样的输入输出长度,分别测量普通12B与MLX12B。比较时记录量化方式;不同量化和不同后端同时变化,测出来的是整个方案的差异,不能把全部收益都归因于 MLX。
若提示架构不支持,先升级到支持对应模型的 Ollama 正式版,然后检查模型库标签。不要把 GGUF 文件改后缀当作 MLX 权重,也不要假设所有旧版运行时都能加载新模型。
直接使用 Python 推理库时,可以从 MLX LM官方仓库 继续研究。它适合需要编程控制的场景;具体模型架构、量化方式和多模态能力仍要逐项确认。
九 用结构化输出处理供应链消息
假设采购系统拿到下面的材料:
1 | { |
这里有两类工作。库存计算应由代码完成:可用量为 180 - 80 = 100,缺口为 max(0, 400 - 100) = 300。模型负责理解供应商消息,提取异常类型、明确承诺日期、原文证据和摘要。
“争取10月8日发货”不能自动升级为承诺,promised_date 应保留为 null。这个区别直接影响采购是否需要继续追问,是本例最值得测试的业务语义。
Ollama 的本地结构化输出支持把 JSON Schema 放进 format。应用依然要校验返回值,因为格式正确不等于业务理解正确。结构化输出
1 | { |
下载并运行完整Python示例
示例只使用 Python 标准库,无需安装模型SDK。将下面三个文件放在同一目录:
1 | mkdir -p ~/gemma4-supply-chain |
运行需要 Python 3.10 或更新版本,以及已经启动的本地 Ollama。前面的单元测试不调用模型,验证计算、结果校验和HTTP协议处理;最后一条命令才会请求实际模型。
内存足够时,可用同一份输入切换模型:
1 | python3 supply_chain_demo.py sample-event.json --model gemma4:12b |
程序包含三段关键处理:
1 | # 数量口径来自程序计算。 |
这里的低温度是抽取任务的实验配置,不能作为所有 Gemma 4 任务的统一最佳参数。应在自己的验证集上比较字段准确率、漏报和延迟后再固定。
程序还会检查日期是否合法、分类是否在枚举内、输出是否被截断、是否出现额外字段。任何一项失败都会返回非零退出码,不把错误结果继续送进业务流程。
对于这组输入,人工验收时应检查以下结果:
1 | { |
这是一组验收要点,完整程序输出会把模型抽取放在 extraction 下,并附带耗时指标。模型可能理解错误,因此还要人工确认“意向不等于承诺”是否真的成立;校验日期格式不能替代这项语义验收。
十 在Java和Spring项目中接入
模型部署在 MacBook 上之后,Java 通过本地HTTP调用即可。第一步先用 JDK 17 自带的 HttpClient,把问题缩小到网络、JSON和超时,避免同时引入框架版本问题。
下载 GemmaLocalDemo.java 和 request.json:
1 | curl -fLO https://guxingxianyue.github.io/downloads/code/gemma4-mac/GemmaLocalDemo.java |
程序的请求核心如下,完整代码已经包含UTF-8读取、5秒连接超时、120秒请求超时和非2xx错误处理:
1 | HttpRequest request = HttpRequest.newBuilder( |
示例直接打印原生响应,业务代码应该使用项目已经采用的JSON库,读取 message.content 后再反序列化目标DTO。JSON由序列化库生成,不要把供应商原文手工拼接进字符串模板。
Spring项目建议的调用结构
1 | SupplierMessageController |
将模型地址、模型标签、连接超时和请求超时放进配置,并把HTTP客户端作为可复用组件。模型调用安排在数据库长事务之外;先读取带版本的快照,分析结束后如果要写单据,再重新检查版本和业务状态。
接口失败时,可以先保存“待人工处理”的异常记录,让采购正常流程继续工作。对于耗时任务,返回任务ID再异步处理,会比让一个同步业务请求长时间等待更合适。
Java应用也运行在当前Mac上时,127.0.0.1 指向同一台电脑。如果Java运行在Docker容器中,应使用Docker提供的宿主机访问方式;如果Java运行在服务器上,这个地址指向服务器自己,不能直接访问MacBook。
十一 使用图片理解仓库单据
将一张清晰的送货单放在本机,例如 ~/Documents/delivery-note.png:
1 | ollama run gemma4:e4b \ |
CLI可以识别图片路径;直接使用REST接口时,images 中应提供图片的Base64数据,不能把本地路径字符串当作已经上传的图片。图片输入说明
完整供应链程序也提供图片参数:
1 | python3 supply_chain_demo.py sample-event.json \ |
这个参数给同一条消息补充视觉上下文,输出Schema仍是前面的异常抽取Schema。如果要提取单据行项目,应重新设计 items 数组,校验SKU存在性、数量单位和合计,而不是直接沿用邮件分类对象。
为了提高小字识别质量,可以先裁剪到单据区域,避免整屏截图;长表格按区域拆开读取,再由代码做行数、金额和数量核对。视觉模型返回的文字仍可能把相近字符识别错,关键单号要和业务主数据比对。
十二 用RAG补充知识而不是反复塞整本手册
模型不会自动知道公司的采购规范,也不会因为文件放在本地目录就自动读取。需要回答“延迟交货应该由谁处理”时,可以引入检索增强生成,也就是RAG。
一个适合先落地的流程是:
- 把采购制度、仓库操作手册按自然段或业务章节切分,保存文档ID、版本和生效时间。
- 先用关键词或数据库全文检索找到少量相关片段,验证召回是否可靠。
- 将片段连同来源编号、用户问题一起提交给Gemma 4,要求回答引用来源编号。
- 没找到依据时返回“现有资料不足”,而不是要求模型补齐公司规则。
- 文档规模增长后再比较向量检索、混合检索和重排,并更新评估集。
例如,给采购异常问题提供两段经过筛选的材料:
1 | [DOC-PUR-07 v3] |
权重、嵌入模型和向量库是不同组件。不要假设生成模型的聊天接口可以直接用来生成高质量检索向量。原文证据、检索来源和库存事实都有各自的校验方式,接入时分别记录。
十三 让模型调用业务工具
当任务需要查实时库存、采购单或在途量时,工具调用比把所有数据预先塞进提示更灵活。应用向模型提供工具的名字和参数结构,模型提出调用,应用执行后把结果作为 tool 消息送回,模型再组织答案。Ollama工具调用
供应链系统可以从这两个只读工具开始:
1 | query_inventory_snapshot(skuCode, warehouseId) |
应用端需要处理所有返回的工具调用,并限制每个任务的轮数和总耗时。工具不存在、参数错误或查询失败时,返回明确的结果;不能因为模型提出了调用,就认为业务操作已经成功。
工具调用和 MCP 也有不同职责:Gemma 4 决定需要什么能力,Agent程序负责调度,MCP客户端负责连接相应服务器。把 Gemma 4 跑在本地,不会自动得到一个能使用所有MCP服务的Agent。可以先复用已有Java查询Service,再逐步接入MCP适配层。
十四 怎样测性能和定位瓶颈
先区分冷启动和热请求
第一次请求可能需要读取权重并初始化运行时,之后在模型仍驻留时请求会更快。比较不同方案时,分别记录冷启动和热请求,不能只选最快的一次。
原生API返回 total_duration、load_duration、prompt_eval_count、eval_count、eval_duration 等字段,时间单位是纳秒。解码速度可用下面的方式计算:返回字段说明
1 | 输出tokens每秒 = eval_count / (eval_duration / 1_000_000_000) |
这个指标只表示输出阶段的吞吐,不代表端到端延迟,也不是首字延迟。需要测首字延迟时,使用流式请求,从客户端发出请求开始计时,到收到第一段实际可见输出为止。
示例Python程序已经输出总耗时、加载耗时和解码速度。每组测试固定模型标签、量化、上下文、输入、输出上限和并发,再记录多次结果的中位数与较慢分位数。
按瓶颈调整配置
| 现象 | 可采取的动作 |
|---|---|
| 加载后内存压力持续升高 | 换小模型或较低位量化,缩短上下文,关闭其他大内存应用 |
| 第一次很慢,后续正常 | 分开统计加载耗时;为频繁调用设置合适的驻留时间 |
| 输入很长时首字很慢 | 压缩历史消息,检索少量相关片段,减少不必要图片 |
| 输出非常长 | 设定合理的输出上限,让任务聚焦于必要字段 |
| 单请求正常,多请求明显变慢 | 应用侧先用单并发或有界队列,再测扩容收益 |
| 生成变快但错误增多 | 回查量化、提示和模型差异,用固定业务集比较 |
MacBook Air 的持续负载还要考虑温度;短请求体验好,不代表连续半小时的吞吐相同。MacBook休眠、合盖和网络切换也会中断服务,它更适合本机开发与小规模验证。需要稳定团队服务时,把同样的客户端契约部署到常驻环境。
留下可以复查的版本记录
1 | ollama --version |
/api/tags 可返回模型名、digest、大小和量化等信息。把这些信息和评估结果保存到项目的实验记录中,升级后重新回放同一组案例,而不是只记录“用了Gemma 4”。模型列表API
十五 从能回答到能够可靠使用
准备一个小而明确的业务评估集,比不断改提示词更有帮助。供应链异常场景可以先收集50至100条经过确认的样本,覆盖:
- 明确延期、尚未承诺日期和已经承诺日期。
- 质量问题、付款问题和普通询问。
- 同一消息包含多个问题,以及信息相互矛盾的情况。
- 缺少关键字段、无效库存快照和模糊单据图片。
- 夹带“忽略规则”等指令式文本的业务材料。
分别统计字段准确率、日期误判率、原文证据覆盖、人工修订比例、延迟和内存压力。对“把争取日期错当承诺”这类影响业务的错误单独统计,不让整体平均分掩盖问题。
如果表现不理想,我会依次检查任务定义、样本标注、上下文、模型尺寸和量化。RAG适合补充可更新知识;LoRA等微调适合在合法可用的数据集上适配稳定任务,但还需要匹配训练框架、预留更多内存并保留独立测试集。它不是给运行中的模型记住几次聊天的同义词。
十六 常见问题排查
| 问题 | 检查方法 |
|---|---|
command not found: ollama |
重新打开终端,检查应用和命令行链接,尝试应用内CLI路径 |
connection refused |
确认Ollama已启动,使用curl /api/tags检查本机端口 |
| 11434端口已被占用 | 用lsof -nP -iTCP:11434 -sTCP:LISTEN确认进程,避免重复启动服务 |
model not found |
对照ollama ls和模型库标签,先执行对应ollama pull |
| 下载中断或报证书错误 | 检查网络、代理和磁盘空间,再重试下载;不靠关闭证书验证解决 |
| GPU没有参与 | 对照芯片类型、运行时和ollama ps的处理器分配 |
| 机器交换空间持续增加 | 先降低模型尺寸、上下文和并发,再看内存压力是否恢复 |
| JSON解析失败 | 确认原生API关闭流式输出,再检查Schema、输出上限和message.content |
| 图像不能读取 | 检查视觉能力和文件是否清晰,REST请求须提供Base64图片数据 |
| MLX标签无法加载 | 核对Ollama版本、Apple Silicon环境和该标签支持情况 |
| Java请求在容器里连接失败 | 容器的localhost不是Mac宿主机,改用正确的宿主机地址 |
macOS上的服务日志可以从 ~/.ollama/logs/server.log 查看。日志位置
1 | tail -n 100 ~/.ollama/logs/server.log |
大模型文件会持续占用SSD空间。需要调整存储位置时,按Ollama文档配置模型目录,并在迁移后检查标签、访问权限和首次加载情况;先确认新目录可用,再清理旧文件。模型存储配置
十七 日常使用的推进顺序
第一次使用,先完成小模型聊天和一次HTTP调用,确认机器没有明显内存压力。第二步用固定输入跑供应链抽取,检查证据和未承诺日期。第三步接入Java,并把错误、超时和人工复核纳入原来的业务流程。
稳定之后,再比较MLX、增加上下文、接入检索和工具调用。每次只改变少量变量,保留同一组测试任务。这样的推进方式能让每一次优化都有可以解释的结果,也更容易知道哪一层出了问题。
对Java开发者来说,本地Gemma 4最有价值的起点,是成为一个职责清楚的组件:读懂给定材料、返回可以验证的结果,再由现有业务代码决定如何使用。把这一条链路做好,MacBook上的本地部署就已经从聊天体验走进了实际开发。