第一次在 Mac 上把本地大模型跑起来的人十个里有八个会在同一个地方卡住图形界面装了一堆模型文件下了一堆硬盘占了几十 G可到底哪个界面调的是哪个后端、采样参数藏在哪个面板、换了台机器怎么把同一套东西复现出来全成了一笔糊涂账。我把这套东西重做了一遍去掉所有图形外壳只留命令行起名macai——一个跑在 macOS 上的原生 AI 工具集管两件事本地 LLM 推理和本地图像生成。它不是什么新模型也不是什么新框架本质是一层很薄的调度壳子把模型文件、量化格式、推理参数、输出协议收敛成几条能写进脚本、能进版本库的命令。适合三类人想在没有外网的机器上跑推理的、想把 AI 塞进现有自动化流程的、以及受够了点鼠标点半天还不知道改了哪个参数的人。下面我把设计思路、参数账本、踩坑记录一次讲完照着抄能跑改着用也不难。1. 为什么值得把 AI 工具做成命令行形态1.1 图形界面的三个隐性成本先说结论图形界面对尝鲜友好对长期使用很不友好。第一层成本是参数不可见。你在界面上拖一个滑块背后可能同时改了采样温度、重复惩罚和 top-p 三个值出图变好看了你不知道为什么好变丑了也不知道该退哪一步。第二层成本是流程不可复现。同一个提示词、同一张图隔一周再跑一次效果不一样因为你在界面上顺手换了个模型版本而这个信息根本没被记录下来。第三层成本是无法组合。你想批量处理 500 条文本或者按 CSV 里的一列提示词批量出图图形界面只能一条条手点。命令行把这三点全部反过来参数写在配置文件里谁改了什么在 diff 里看得见每次调用的完整参数连同时间戳一起落盘事后能一比一重放命令能被 shell 脚本、任务计划、编辑器插件任意调用。我在实际项目里最常用的场景是——把一篇长文档切段后丢给本地模型做结构化提取几百段的活儿写个循环十分钟搞定这在图形界面里是不可想象的。1.2 macai 的定位调度层而不是推理层这里必须把边界划清楚否则后面的设计全是空中楼阁。macai 自己不做矩阵乘法一行推理代码都没有。它做的事情是四件把模型这个概念抽象成一个带元数据的条目包含文件路径、量化位宽、上下文上限、适用任务类型把调用抽象成一个子命令接收提示词和参数转译成对应后端的命令行参数把输出统一成一套 JSON 协议不管底层是文本模型还是图像模型上层脚本拿到的结构一致把配置分层全局默认值、项目级覆盖、单次调用临时参数三级合并。这种薄壳设计的好处是显而易见的底层后端换代、换实现、甚至换成完全不同的技术路线上层脚本一行不用改。坏处也要认——每一层抽象都会吞掉一部分底层能力遇到后端特有的高级参数你得留一个透传的口子。我的做法是给每个子命令加一个--extra参数原样拼接到后端命令行末尾专治各种抽象覆盖不到的情况。1.3 你需不需要这套东西三个判断标准不是所有人都该上命令行。给你三个判断标准中两条以上再考虑一是你每周用 AI 工具超过五次重复劳动明显二是你有批量任务比如几百份文档摘要、几百张配图三是你对这次结果为什么和上次不一样有强需求需要可追溯。反过来如果你只是偶尔问两句、偶尔出一张图装个现成应用更省事命令行对你来说是负收益。还有一点要说清楚本地推理不等于免费。它省的是调用费用花的是电费、硬盘和时间。一个 7B 级别的模型在笔记本上跑速度大概每秒二三十个词元写一篇千字的稿子要等半分钟以上图像生成一张 512 分辨率的图十几秒到一分钟不等。这笔账要提前算别指望本地跑出云端的速度。2. 整体架构拆解一个薄壳如何托住两类后端2.1 为什么不做成全家桶见过太多工具死在这一步一开始想做一个什么都能干的平台于是自己实现推理、自己实现采样、自己实现图像调度最后维护成本爆炸每个方向都比专业实现慢半拍。macai 从一开始就放弃了这条路只做编排。文本推理交给编译好的原生后端二进制图像生成交给另一套扩散模型管线macai 只负责找到它们、拼参数、收结果、转格式。这个取舍背后的逻辑很朴素——性能敏感的部分让专业的来体验敏感的部分自己做。推理内核的优化量化算法、算子融合、内存布局是深水区投入产出比极低而参数管理、输出协议、批量调度这些胶水工作恰恰是现成工具做不好的地方也是每个人都要重复造一遍的轮子。把力气花在胶水上收益最高。2.2 目录结构与配置分层配置文件分三层优先级从低到高全局~/.macai/config.yaml、项目级./.macai.yaml、命令行参数。合并规则是深合并不是覆盖——项目级只写和全局不同的键没写的继承全局。这样你在不同项目里可以只覆盖模型和上下文长度其余沿用默认。# ~/.macai/config.yaml defaults: text_model: qwen-7b-q4 image_model: sd15-base threads: 6 ctx: 4096 output_format: json models: qwen-7b-q4: path: ~/Models/text/qwen-7b-q4_k_m.gguf ctx_max: 32768 family: chat llama-13b-q5: path: ~/Models/text/llama-13b-q5_k_m.gguf ctx_max: 4096 family: base sd15-base: path: ~/Models/image/sd15-base.safetensors resolution: 512 steps: 24模型用别名引用不写全路径。这个设计的价值在换机器的时候体现得最明显新机器上只要目录结构一致配置文件原样拷过去就能跑路径里的用户名部分用~展开。我见过太多人因为硬编码绝对路径迁移一次环境改半小时配置。2.3 两类任务的接口统一文本和图像在底层完全是两套东西但对外我只暴露两个子命令macai text和macai image。两者共享同一套参数解析、同一套日志、同一套输出封装。差异部分收敛在各自的--help里。统一输出协议是这套设计里我最满意的部分。文本模式返回{ ok: true, model: qwen-7b-q4, text: ……, usage: {prompt_tokens: 312, completion_tokens: 184}, timing: {load_ms: 820, prompt_ms: 410, gen_ms: 6120, tok_per_s: 30.1} }图像模式返回{ ok: true, model: sd15-base, images: [{path: /out/2024-06-11_142233_seed42.png, seed: 42}], timing: {load_ms: 3100, gen_ms: 18400} }关键在于ok字段和timing字段。上层脚本只判断ok不用去猜后端退出码的含义timing让你在一个月后还能回答那天为什么这么慢这种灵魂拷问。失败时返回{ok: false, error: {code: MODEL_NOT_FOUND, detail: ...}}错误码是枚举值脚本可以按码分流处理而不是正则匹配错误文本——后者是维护噩梦。2.4 流式输出的处理取舍文本推理默认流式输出逐词元打到标准输出方便人眼阅读加--json就切换成等全部生成完再吐出完整 JSON方便脚本解析。这两个模式不能同时用因为流式和结构化本质冲突。这里有个坑要提前说流式模式下标准输出被词元占满你没法在同一条命令里再打印其他信息。所有进度、警告、耗时统计必须走标准错误。这个约定看起来是细节实际上是 shell 管道能正常工作的前提——macai text ... --stream | grep 关键词如果警告信息混进了标准输出grep 结果就被污染了。3. 环境准备从芯片代际到模型目录约定3.1 硬件门槛与环境检查先说硬门槛。统一内存架构的机器跑本地推理有天然优势因为模型权重和计算缓冲共享同一块内存不需要来回拷贝。但能跑和跑得舒服是两回事按经验给个参考档位内存文本模型可用上限图像生成可用上限体验评价8G7B Q4上下文 4K512 分辨率基础模型勉强能跑别开多任务16G13B Q4 或 7B Q6上下文 8K512 分辨率流畅768 吃力日常够用32G32B Q4 或 13B Q6上下文 16K1024 分辨率可跑舒服64G 及以上70B Q4长上下文大分辨率批量出图宽裕内存不够时的表现很有意思不是报错而是系统开始疯狂换页风扇狂转速度掉到每秒两三个词元你以为模型坏了其实是内存不够。所以第一条排查铁律速度异常慢先看内存压力别急着怀疑模型。3.2 编译工具链与依赖准备后端二进制要么自己编要么用预编译包。自己编的好处是能针对具体芯片代际开优化选项坏处是首次编译可能二十分钟起步而且工具链版本不对会卡在各种奇怪的链接错误上。我的建议先用预编译包跑通链路确认整条流程没问题再考虑自己编。依赖清单不长但要装全# 编译基础 xcode-select --install # 包管理 command -v brew || /bin/bash -c $(curl -fsSL https://brew.sh/install.sh) # 常用辅助工具 brew install cmake git jq exiftooljq是解析 JSON 输出的必备品后面批量脚本里全靠它取值exiftool用于把生成参数写进图片元数据这个技巧在第 5 节展开。提示不要在系统自带的 shell 里堆几十行环境变量。macai 的所有路径都从配置文件读唯一的例外是模型根目录用MACAI_HOME一个变量控制指向哪里模型就从哪里找。编译后端时最关键的一个选项是是否启用系统图形计算接口加速。不开的话纯 CPU 跑7B Q4 大概每秒五六个词元开了能到二三十。这个开关通常叫-DGGML_METALON之类的名字具体名字随版本变编之前翻一下后端的构建说明。编完跑一次--version输出里应该带加速标识没带就是没编进去。3.3 模型文件的获取与目录约定模型文件从公开的模型仓库下载格式优先选GGUF——它是为本地推理设计的容器格式把权重、词表、元数据打包在一个文件里还带量化版本。目录约定我建议按任务分两级~/Models/ ├── text/ │ ├── qwen-7b-q4_k_m.gguf │ └── llama-13b-q5_k_m.gguf ├── image/ │ ├── sd15-base.safetensors │ └── lora/ │ └── style-a.safetensors └── cache/cache目录放后端产生的临时文件定期清理。这个结构看起来平平无奇价值在于文件名即信息从qwen-7b-q4_k_m.gguf这串字符里你能立刻读出模型家族、参数量、量化方式和具体变体。不要用model-final-v2-new.gguf这种命名三个月后你自己都想不起来它是哪个。3.4 一个容易被忽略的系统设置模型目录建议放在不被系统索引的位置或者手动把它加入索引排除列表。原因很实际一个几十 G 的目录系统后台索引会持续扫描硬盘读写和 CPU 都有开销你跑推理的时候它还在扫速度就受影响。同理备份工具也会盯着大目录反复备份浪费空间和时间。具体做法因系统版本而异通用思路是把模型目录挪到用户主目录之外的独立位置或者在索引设置里显式排除。这一条没有代码可抄但它是很多人跑了一段时间后莫名变慢的真实原因值得单独花五分钟处理。4. 本地 LLM 推理把参数账算在前面4.1 量化位宽怎么选算一遍账量化是本地推理的第一道门槛。简单说就是把模型权重从 16 位浮点压缩成 4 位、5 位、8 位整数模型变小、跑得快代价是精度损失。常见档位的实际差异量化档相对体积7B 模型文件大小质量损失感受Q8_0约 50%~7.2 GB几乎无感Q6_K约 40%~5.6 GB极难察觉Q5_K_M约 35%~4.8 GB轻微长文本略明显Q4_K_M约 28%~4.1 GB可接受推荐起点Q3_K_M约 22%~3.3 GB明显代码和数学先崩Q2_K约 15%~2.7 GB不建议容易胡言乱语选档的实操原则先看内存再看任务。16G 机器跑 7BQ4_K_M 是最稳的平衡点如果任务是代码生成或数学推理宁可降到 13B Q4 也别用 7B Q3因为小模型低位量化的损失是叠加的而大模型高位量化的损失是可控的。这个反直觉的结论我验证过很多次参数量的收益通常大于量化精度的收益前提是量化不低于 Q4。还有一条容易被忽略不同量化算法对注意力层和前馈层的处理不一样K 系列量化Q4_K_M 里的 K对关键层保精度比早期的对称量化好不少。文件名里带_K_M的优先选_K_S是更激进的版本只有在内存实在紧张时才用。4.2 上下文长度与缓存内存的估算上下文长度是第二个吃内存的大户而且很多人完全没算过这笔账。推理时每个已处理的词元都要在缓存里存一份注意力键值对这个缓存随上下文线性增长。估算公式每词元缓存字节数 ≈ 2 × KV头数 × 头维度 × 精度字节数 × 层数拿一个典型 7B 模型举例32 层、隐藏维度 4096、32 个注意力头、8 个 KV 头分组查询注意力、头维度 128、缓存用 16 位浮点。每层每词元2 × 8 × 128 × 2 4096字节即 4 KB乘以 32 层每词元 128 KB。那么4K 上下文4096 × 128KB ≈ 512 MB8K 上下文约 1 GB32K 上下文约 4 GB注意这只是缓存还要加上模型权重本身。所以 16G 机器跑 7B Q44.1G 权重 32K 上下文4G 缓存 运行时开销其实已经接近临界了。开长上下文之前先算这一笔比事后对着风扇声发愁有用得多。再补一个细节上下文长度不等于一次能喂多少字。中文一个汉字大约 1 到 2 个词元标点和英文单词更碎。做长文档处理时我一般按汉字数 × 1.5估词元数留 20% 余量不然容易在接近上限时被截断而截断往往不报错只是回答变得莫名其妙。4.3 线程数与加速卸载的调法线程数不是越大越好。物理性能核数量是最优起点超过物理核数之后多出来的线程在抢同一批执行单元反而变慢。命令行里通常用-t指定# 先测 4、6、8 三档看哪档 tok/s 最高 for t in 4 6 8; do echo threads$t macai text 用一句话解释什么是量化 --threads $t --json \ | jq -r .timing.tok_per_s done这个测法很土但很有效五分钟就能摸清你机器的甜点值。我测过的几台机器甜点值普遍在性能核数到性能核数2 之间超过就掉。另一个关键参数是卸载到加速单元的层数。绝大多数后端支持把部分或全部层交给加速单元计算剩下的留 CPU。全卸载通常写--gpu-layers 99这种夸张数字速度最快但受限于加速单元可用的内存配额配额不够时会静默回退速度断崖式下跌。判断方法很简单跑一次全卸载跑一次零卸载对比tok_per_s如果两者接近说明卸载没生效去查配额或者查二进制有没有编进加速支持。4.4 采样参数三个旋钮的配合心法采样参数决定模型怎么选下一个词是最玄学也最容易调坏的部分。三个核心旋钮temperature温度控制随机性。0 是每次选概率最高的词完全确定0.7 到 0.8 是通用区间1.2 以上开始发散。top-p核采样只在累计概率前 p 的候选里采样。0.9 到 0.95 是常规值调低更保守。repeat penalty重复惩罚压制刚出现过的词防止复读。1.1 左右温和1.3 以上容易导致语句断裂。我的经验配方是分任务定的任务类型temperaturetop-prepeat penalty说明结构化抽取0.10.81.05要稳定不要创意代码生成0.20.91.05略留余量避免死板通用问答0.70.951.1默认档创意写作0.90.951.15放开但要防复读头脑风暴1.10.981.1要发散接受跑题注意这三个参数是联动的。你把温度调高又不加重复惩罚模型容易陷入同一个句式循环把重复惩罚调太狠模型会开始生造词来躲避惩罚。改参数一次只改一个别同时动三个否则你永远不知道是哪个起的作用。还有一个隐藏项系统提示词的位置和格式。不同模型家族对对话模板的要求不一样有的需要特定的开始/结束标记有的要求系统提示放在最前面。模板错了不会报错只是效果变差——这是本地推理里最隐蔽的坑之一后面第 7 节还会提到。5. 图像生成把随机性关进可复现的笼子5.1 在 Mac 上做本地出图的现实预期先把预期摆正统一内存架构跑扩散模型是可行的但速度和独立显卡不是一个量级。512 分辨率、20 到 30 步采样一张图大概十几秒到一分钟1024 分辨率会翻好几倍而且内存压力陡增。这个速度用来做一天出几十张备选完全够用用来做实时预览不够。内存开销主要来自两块模型权重基础模型通常 2 到 4 G加上文本编码器和变分自编码器和注意力计算的中间张量。中间张量随分辨率平方增长所以 512 到 1024 是四倍关系不是两倍。这解释了为什么很多人 512 跑得挺顺一上 1024 就卡死。5.2 分辨率、步数、引导强度三者的关系这三个参数是出图质量的主开关理解它们的关系比记数值更重要。分辨率决定构图容量。512 适合半身像和特写768 到 1024 才撑得起全身和场景。但直接把分辨率拉高不等于变好——训练时的分辨率分布决定了模型在哪个尺寸下最习惯超出太多会出现重复肢体、多头多手这类结构崩坏。稳妥做法是分段放大先在原生分辨率出图再用放大流程二次处理。采样步数决定去噪的细致程度。20 到 30 步是绝大多数采样器的收敛区间超过 40 步的边际收益很小纯属浪费电。低于 15 步会明显发糊。有个经验换采样器比加步数更有效某些采样器 20 步的效果胜过另一些的 40 步。引导强度也叫 CFG scale控制多听提示词的话。太低3 以下画面松散、不听指令太高12 以上颜色过饱和、构图僵硬、出现锐利边缘伪影。日常取 6 到 8。参数常用区间偏低表现偏高表现分辨率512 / 768 / 1024细节不足结构崩坏、重复肢体步数20-30发糊、噪点残留收益递减、耗时翻倍引导强度6-8不听提示、构图散过饱和、僵硬伪影5.3 种子、提示词、参数一起落盘出图最容易犯的错是出了一张满意的想微调一下结果再也复现不出来。原因永远是同一个——随机种子没记。macai 的做法是强制记录每次生成返回的 JSON 里带seed图片文件名里也带。未指定种子时用一个递增或随机的整数指定时原样使用。macai image a quiet reading room, morning light, wide shot \ --model sd15-base \ --size 768x768 \ --steps 28 \ --cfg 7.0 \ --seed 1234567 \ --out ./out \ --json配合exiftool把完整参数写进图片元数据这一步花不了几秒钟但价值巨大exiftool -overwrite_original \ -Commentmodelsd15-base;steps28;cfg7.0;seed1234567;prompta quiet reading room, morning light, wide shot \ ./out/2024-06-11_142233_seed1234567.png以后不管过多久拖进任何支持读元数据的工具参数全在里面。我现在的习惯是宁可多存五十字节元数据也不删任何一张出过的图——因为你永远不知道哪张废图的种子会在三个月后变成爆款。5.4 风格微调与批量出图风格微调用的是低秩适配权重LoRA本质是一个小文件加载后对基础模型的行为做偏移。命令行里通常用--lora 路径 --lora-scale 0.7这样的参数。系数很关键0.5 到 0.8 是常用区间1.0 往往过拟合——画面变成风格的复制粘贴失去了提示词的控制力。批量出图的核心是同一组参数扫一个变量。比如固定种子、固定提示词只扫引导强度看哪档最稳#!/bin/bash set -euo pipefail PROMPTa quiet reading room, morning light, wide shot SEED1234567 for cfg in 5.5 6.5 7.5 8.5; do macai image $PROMPT \ --model sd15-base --size 768x768 --steps 28 \ --cfg $cfg --seed $SEED \ --out ./out/sweep_cfg_${cfg} --json \ | jq -r .images[0].path doneset -euo pipefail这三件套是必须的出错立即停、未定义变量报错、管道中间环节失败也报错。少了它某个参数拼错时脚本会安静地生成一堆无效图你还以为跑成功了。6. 脚本化实战把命令串成流水线6.1 用标准输入做批量文本处理单条命令的价值有限管道里才是它的主场。macai 支持从标准输入读提示词--stdin开关打开后每行输入触发一次推理cat docs/*.txt \ | macai text --stdin \ --system 把输入压缩成一句不超过 40 字的中文摘要不加任何前缀 \ --temperature 0.1 --json \ | jq -r select(.ok) | .text \ summaries.txt这条链里有三个设计点在起作用。第一--system单独传系统提示不混在用户输入里避免模板拼接出错。第二--json让每条结果独立成行jq才能逐行处理。第三select(.ok)过滤掉失败条目防止一行错误信息把后面的解析全带崩。如果文件很多逐行处理会反复加载模型开销巨大。这时候用--batch模式模型只加载一次把整个文件当一批处理。加载 4G 模型大概要一秒处理一千条的话省下来的是十几分钟。6.2 长文本切分与结果合并上下文有上限长文档必须先切。切分策略比想象中重要按固定字数硬切会把句子拦腰斩断导致每段开头都是半句话摘要质量必然下降。我用的策略是按段落聚合到接近上限再切保留自然边界。def chunk(text, max_chars1500): paras [p.strip() for p in text.split(\n) if p.strip()] out, buf [], for p in paras: if len(buf) len(p) 1 max_chars and buf: out.append(buf) buf p else: buf f{buf}\n{p} if buf else p if buf: out.append(buf) return out1500 字这个阈值是按汉字 × 1.5 ≈ 词元数倒推的1500 字约 2250 词元留出系统提示和输出的空间4K 上下文刚好放得下。如果你的模型支持 8K这个值可以放宽到 3500 左右。结果合并环节要注意顺序。并行处理快但输出顺序会乱串行慢但顺序天然正确。我的做法是每个任务带一个序号处理完后按序号排序兼顾速度和正确性ls chunk_*.txt | sort | while read -r f; do idx$(basename $f .txt | sed s/chunk_//) macai text --file $f --system 写一句摘要 --json \ | jq -r --arg i $idx \($i)\t\(.text) done | sort -n | cut -f2 merged.txt6.3 输出命名与元数据规范批量跑完之后最痛的不是生成是找不到东西。我的命名规范固定三段日期_时间_种子前缀可选加任务类型。之所以把时间放前面是因为文件管理器默认按名字排序时间前缀天然按时间线排列找昨天下午那批一眼就能定位。元数据除了写进图片的注释字段还额外落一份 JSONL 索引文件每行一条记录包含输入、参数、输出路径、耗时。这个索引文件的用处是可以直接用jq做统计平均耗时多少、哪个模型用得最多、哪批任务失败率高。跑了一个月之后回头看这些数据比凭感觉优化靠谱得多。7. 常见问题与排查实录7.1 问题速查表把这两年遇到的问题按现象归档先查表再深挖能省大量时间现象最可能原因处理方向速度突然掉到每秒几个词元内存压力、换页关掉其他应用降上下文换低量化加载就报错找不到模型路径含空格或波浪号未展开用引号包裹或写绝对路径输出全是重复句重复惩罚过低或温度过低惩罚提到 1.1温度提到 0.7回答答非所问、格式错乱对话模板不匹配检查该模型家族要求的模板格式出图全黑或全噪点步数过低、引导强度过低步数提到 20CFG 提到 6出图肢体结构崩坏分辨率超出训练分布回到原生分辨率改分段放大中文输出夹英文乱码词表或编码问题确认模型支持中文检查输入编码为 UTF-8脚本跑到一半静默退出管道中间失败未捕获加set -euo pipefail首次调用特别慢后面正常模型冷加载正常现象或用常驻服务模式生成结果每次都不一样固定种子某些算子非确定性属正常追求完全一致需关掉部分优化7.2 性能不达预期的排查顺序速度慢是最常见的抱怨但原因可能在南辕北辙的地方。我固定按这个顺序查能覆盖九成情况。第一步查内存压力。开着内存监控跑一次推理看峰值。如果系统在换页速度必然崩这时候优化参数毫无意义先减负。第二步查加速是否真的生效。跑一次零卸载做对比如果速度只差一点点说明加速根本没进去去查二进制编译选项和配额。第三步查线程数。按 4.3 的方法测一遍很多人默认用了逻辑核数超配了。第四步查上下文长度。开着 32K 上下文跑短对话等于每次都分配了一大块缓存白白占内存按需降下来。第五步才是换模型。前面四步都排除之后才考虑量化档位和模型尺寸。这个顺序的逻辑是从影响最大、成本最低的因素开始排。换模型成本最高放最后。7.3 内存吃紧时的六个手段内存不够是本地推理的常态尤其是笔记本。按见效速度排降上下文从 32K 降到 8K直接省几个 G对多数对话任务毫无影响。降量化Q6 换 Q47B 模型省 1.5G 左右。关掉其他大应用浏览器开五十个标签页的内存占用常常超过模型本身。缩短输出设最大输出词元数上限防止模型滔滔不绝把缓存撑满。分批处理长文档不要一次喂切段跑每段跑完释放。图像降分辨率512 和 1024 的中间张量差四倍先从分辨率下手。注意不要在内存边缘反复试探。系统接近临界时会变得极度卡顿你以为程序死了其实在换页。留 20% 余量是底线。7.4 出图质量异常的定位思路图像出问题比文本更难定位因为失败模式更模糊。我的排查路径是固定的四问种子固定了吗步数够吗引导强度在区间内吗提示词和模型匹配吗前三个都是数值问题查参数就行。第四个最容易被忽略——某些模型对提示词的语言和写法有强偏好用中文提示词配一个主要在英文语料上训练的模型效果会明显打折。这不是模型不能用中文而是它对中文概念的理解粒度更粗。稳妥做法是核心描述用英文关键词风格和氛围词可以中英混用实测下来这样最稳。还有一个反直觉的经验提示词不是越长越好。超过一定长度后模型对每个词的注意力被稀释靠后的词几乎不起作用。我的习惯是控制在 30 个关键词以内把最重要的主体放最前面风格词放最后权重递减。如果确实需要堆细节用权重语法给关键项加权比单纯堆词有效。8. 我踩过之后才明白的几件事跑了这么久有些结论是文档里不会写的纯靠试错换来的。第一配置文件比命令行参数重要得多。我一开始什么都写在命令里结果每次都要翻历史记录找上次那串参数。后来把所有稳定参数沉到配置文件命令行只留变量部分效率翻倍。判断标准很简单一个参数你连着用了三次以上就该进配置。第二模型不是越新越好是越匹配越好。我追过几次新发布的模型结果发现在我的具体任务上一个半年前的中等尺寸模型反而更稳。原因是新模型往往在通用能力上强但在特定格式输出上不如经过针对性微调的旧模型。换模型之前先跑一组固定测试集用同一批输入对比别凭印象。第三日志要写到磁盘不要只看终端。终端滚过去就没了。我把每次调用的完整参数、耗时、输出长度追加到一个日志文件里一个月后做统计发现某类任务的失败率异常高追下去是提示词模板里的一个标点问题。这种问题不靠日志永远发现不了。第四别在中午跑批量任务。听起来像玩笑但真事笔记本满载跑推理风扇狂转机身烫手电池掉得飞快而且系统会主动降频保护速度反而更慢。批量任务放晚上或者插电的时候跑实际总耗时更短。我现在的习惯是插上电源再启动批量脚本。第五留一条最小可复现命令。每个项目的 README 里我都会放一条最短的、能跑通的命令不带任何可选参数。这条命令的价值在于三个月后环境变了、配置乱了跑一遍它就知道是环境问题还是参数问题。这个习惯救过我很多次。最后分享一个小技巧关于测试新模型。不要拿一个复杂任务去试用三个体检问题就够让它做一次简单的算术、一次格式化的 JSON 输出、一次两百字的中文说明。三个都过说明基本可用任何一个拉胯这个模型在你的场景里大概率也不靠谱。这套体检花不到一分钟比下载十个模型挨个跑正式任务省太多时间。这套工具集现在的状态是文本部分日常在用图像部分周末批量出图脚本都放在一个仓库里换机器时 clone 加拷模型就能恢复。后面打算补的方向是把量化转换和模型体检也做成子命令省得每次都翻笔记。不过那属于锦上添花现在这套已经够我用了。 
长河君 · 2026/10/29 6:51:00 · 阅读 1.2k macai：macOS 原生命令行本地 LLM 推理与图像生成工具集
第一次在 Mac 上把本地大模型跑起来的人十个里有八个会在同一个地方卡住图形界面装了一堆模型文件下了一堆硬盘占了几十 G可到底哪个界面调的是哪个后端、采样参数藏在哪个面板、换了台机器怎么把同一套东西复现出来全成了一笔糊涂账。我把这套东西重做了一遍去掉所有图形外壳只留命令行起名macai——一个跑在 macOS 上的原生 AI 工具集管两件事本地 LLM 推理和本地图像生成。它不是什么新模型也不是什么新框架本质是一层很薄的调度壳子把模型文件、量化格式、推理参数、输出协议收敛成几条能写进脚本、能进版本库的命令。适合三类人想在没有外网的机器上跑推理的、想把 AI 塞进现有自动化流程的、以及受够了点鼠标点半天还不知道改了哪个参数的人。下面我把设计思路、参数账本、踩坑记录一次讲完照着抄能跑改着用也不难。1. 为什么值得把 AI 工具做成命令行形态1.1 图形界面的三个隐性成本先说结论图形界面对尝鲜友好对长期使用很不友好。第一层成本是参数不可见。你在界面上拖一个滑块背后可能同时改了采样温度、重复惩罚和 top-p 三个值出图变好看了你不知道为什么好变丑了也不知道该退哪一步。第二层成本是流程不可复现。同一个提示词、同一张图隔一周再跑一次效果不一样因为你在界面上顺手换了个模型版本而这个信息根本没被记录下来。第三层成本是无法组合。你想批量处理 500 条文本或者按 CSV 里的一列提示词批量出图图形界面只能一条条手点。命令行把这三点全部反过来参数写在配置文件里谁改了什么在 diff 里看得见每次调用的完整参数连同时间戳一起落盘事后能一比一重放命令能被 shell 脚本、任务计划、编辑器插件任意调用。我在实际项目里最常用的场景是——把一篇长文档切段后丢给本地模型做结构化提取几百段的活儿写个循环十分钟搞定这在图形界面里是不可想象的。1.2 macai 的定位调度层而不是推理层这里必须把边界划清楚否则后面的设计全是空中楼阁。macai 自己不做矩阵乘法一行推理代码都没有。它做的事情是四件把模型这个概念抽象成一个带元数据的条目包含文件路径、量化位宽、上下文上限、适用任务类型把调用抽象成一个子命令接收提示词和参数转译成对应后端的命令行参数把输出统一成一套 JSON 协议不管底层是文本模型还是图像模型上层脚本拿到的结构一致把配置分层全局默认值、项目级覆盖、单次调用临时参数三级合并。这种薄壳设计的好处是显而易见的底层后端换代、换实现、甚至换成完全不同的技术路线上层脚本一行不用改。坏处也要认——每一层抽象都会吞掉一部分底层能力遇到后端特有的高级参数你得留一个透传的口子。我的做法是给每个子命令加一个--extra参数原样拼接到后端命令行末尾专治各种抽象覆盖不到的情况。1.3 你需不需要这套东西三个判断标准不是所有人都该上命令行。给你三个判断标准中两条以上再考虑一是你每周用 AI 工具超过五次重复劳动明显二是你有批量任务比如几百份文档摘要、几百张配图三是你对这次结果为什么和上次不一样有强需求需要可追溯。反过来如果你只是偶尔问两句、偶尔出一张图装个现成应用更省事命令行对你来说是负收益。还有一点要说清楚本地推理不等于免费。它省的是调用费用花的是电费、硬盘和时间。一个 7B 级别的模型在笔记本上跑速度大概每秒二三十个词元写一篇千字的稿子要等半分钟以上图像生成一张 512 分辨率的图十几秒到一分钟不等。这笔账要提前算别指望本地跑出云端的速度。2. 整体架构拆解一个薄壳如何托住两类后端2.1 为什么不做成全家桶见过太多工具死在这一步一开始想做一个什么都能干的平台于是自己实现推理、自己实现采样、自己实现图像调度最后维护成本爆炸每个方向都比专业实现慢半拍。macai 从一开始就放弃了这条路只做编排。文本推理交给编译好的原生后端二进制图像生成交给另一套扩散模型管线macai 只负责找到它们、拼参数、收结果、转格式。这个取舍背后的逻辑很朴素——性能敏感的部分让专业的来体验敏感的部分自己做。推理内核的优化量化算法、算子融合、内存布局是深水区投入产出比极低而参数管理、输出协议、批量调度这些胶水工作恰恰是现成工具做不好的地方也是每个人都要重复造一遍的轮子。把力气花在胶水上收益最高。2.2 目录结构与配置分层配置文件分三层优先级从低到高全局~/.macai/config.yaml、项目级./.macai.yaml、命令行参数。合并规则是深合并不是覆盖——项目级只写和全局不同的键没写的继承全局。这样你在不同项目里可以只覆盖模型和上下文长度其余沿用默认。# ~/.macai/config.yaml defaults: text_model: qwen-7b-q4 image_model: sd15-base threads: 6 ctx: 4096 output_format: json models: qwen-7b-q4: path: ~/Models/text/qwen-7b-q4_k_m.gguf ctx_max: 32768 family: chat llama-13b-q5: path: ~/Models/text/llama-13b-q5_k_m.gguf ctx_max: 4096 family: base sd15-base: path: ~/Models/image/sd15-base.safetensors resolution: 512 steps: 24模型用别名引用不写全路径。这个设计的价值在换机器的时候体现得最明显新机器上只要目录结构一致配置文件原样拷过去就能跑路径里的用户名部分用~展开。我见过太多人因为硬编码绝对路径迁移一次环境改半小时配置。2.3 两类任务的接口统一文本和图像在底层完全是两套东西但对外我只暴露两个子命令macai text和macai image。两者共享同一套参数解析、同一套日志、同一套输出封装。差异部分收敛在各自的--help里。统一输出协议是这套设计里我最满意的部分。文本模式返回{ ok: true, model: qwen-7b-q4, text: ……, usage: {prompt_tokens: 312, completion_tokens: 184}, timing: {load_ms: 820, prompt_ms: 410, gen_ms: 6120, tok_per_s: 30.1} }图像模式返回{ ok: true, model: sd15-base, images: [{path: /out/2024-06-11_142233_seed42.png, seed: 42}], timing: {load_ms: 3100, gen_ms: 18400} }关键在于ok字段和timing字段。上层脚本只判断ok不用去猜后端退出码的含义timing让你在一个月后还能回答那天为什么这么慢这种灵魂拷问。失败时返回{ok: false, error: {code: MODEL_NOT_FOUND, detail: ...}}错误码是枚举值脚本可以按码分流处理而不是正则匹配错误文本——后者是维护噩梦。2.4 流式输出的处理取舍文本推理默认流式输出逐词元打到标准输出方便人眼阅读加--json就切换成等全部生成完再吐出完整 JSON方便脚本解析。这两个模式不能同时用因为流式和结构化本质冲突。这里有个坑要提前说流式模式下标准输出被词元占满你没法在同一条命令里再打印其他信息。所有进度、警告、耗时统计必须走标准错误。这个约定看起来是细节实际上是 shell 管道能正常工作的前提——macai text ... --stream | grep 关键词如果警告信息混进了标准输出grep 结果就被污染了。3. 环境准备从芯片代际到模型目录约定3.1 硬件门槛与环境检查先说硬门槛。统一内存架构的机器跑本地推理有天然优势因为模型权重和计算缓冲共享同一块内存不需要来回拷贝。但能跑和跑得舒服是两回事按经验给个参考档位内存文本模型可用上限图像生成可用上限体验评价8G7B Q4上下文 4K512 分辨率基础模型勉强能跑别开多任务16G13B Q4 或 7B Q6上下文 8K512 分辨率流畅768 吃力日常够用32G32B Q4 或 13B Q6上下文 16K1024 分辨率可跑舒服64G 及以上70B Q4长上下文大分辨率批量出图宽裕内存不够时的表现很有意思不是报错而是系统开始疯狂换页风扇狂转速度掉到每秒两三个词元你以为模型坏了其实是内存不够。所以第一条排查铁律速度异常慢先看内存压力别急着怀疑模型。3.2 编译工具链与依赖准备后端二进制要么自己编要么用预编译包。自己编的好处是能针对具体芯片代际开优化选项坏处是首次编译可能二十分钟起步而且工具链版本不对会卡在各种奇怪的链接错误上。我的建议先用预编译包跑通链路确认整条流程没问题再考虑自己编。依赖清单不长但要装全# 编译基础 xcode-select --install # 包管理 command -v brew || /bin/bash -c $(curl -fsSL https://brew.sh/install.sh) # 常用辅助工具 brew install cmake git jq exiftooljq是解析 JSON 输出的必备品后面批量脚本里全靠它取值exiftool用于把生成参数写进图片元数据这个技巧在第 5 节展开。提示不要在系统自带的 shell 里堆几十行环境变量。macai 的所有路径都从配置文件读唯一的例外是模型根目录用MACAI_HOME一个变量控制指向哪里模型就从哪里找。编译后端时最关键的一个选项是是否启用系统图形计算接口加速。不开的话纯 CPU 跑7B Q4 大概每秒五六个词元开了能到二三十。这个开关通常叫-DGGML_METALON之类的名字具体名字随版本变编之前翻一下后端的构建说明。编完跑一次--version输出里应该带加速标识没带就是没编进去。3.3 模型文件的获取与目录约定模型文件从公开的模型仓库下载格式优先选GGUF——它是为本地推理设计的容器格式把权重、词表、元数据打包在一个文件里还带量化版本。目录约定我建议按任务分两级~/Models/ ├── text/ │ ├── qwen-7b-q4_k_m.gguf │ └── llama-13b-q5_k_m.gguf ├── image/ │ ├── sd15-base.safetensors │ └── lora/ │ └── style-a.safetensors └── cache/cache目录放后端产生的临时文件定期清理。这个结构看起来平平无奇价值在于文件名即信息从qwen-7b-q4_k_m.gguf这串字符里你能立刻读出模型家族、参数量、量化方式和具体变体。不要用model-final-v2-new.gguf这种命名三个月后你自己都想不起来它是哪个。3.4 一个容易被忽略的系统设置模型目录建议放在不被系统索引的位置或者手动把它加入索引排除列表。原因很实际一个几十 G 的目录系统后台索引会持续扫描硬盘读写和 CPU 都有开销你跑推理的时候它还在扫速度就受影响。同理备份工具也会盯着大目录反复备份浪费空间和时间。具体做法因系统版本而异通用思路是把模型目录挪到用户主目录之外的独立位置或者在索引设置里显式排除。这一条没有代码可抄但它是很多人跑了一段时间后莫名变慢的真实原因值得单独花五分钟处理。4. 本地 LLM 推理把参数账算在前面4.1 量化位宽怎么选算一遍账量化是本地推理的第一道门槛。简单说就是把模型权重从 16 位浮点压缩成 4 位、5 位、8 位整数模型变小、跑得快代价是精度损失。常见档位的实际差异量化档相对体积7B 模型文件大小质量损失感受Q8_0约 50%~7.2 GB几乎无感Q6_K约 40%~5.6 GB极难察觉Q5_K_M约 35%~4.8 GB轻微长文本略明显Q4_K_M约 28%~4.1 GB可接受推荐起点Q3_K_M约 22%~3.3 GB明显代码和数学先崩Q2_K约 15%~2.7 GB不建议容易胡言乱语选档的实操原则先看内存再看任务。16G 机器跑 7BQ4_K_M 是最稳的平衡点如果任务是代码生成或数学推理宁可降到 13B Q4 也别用 7B Q3因为小模型低位量化的损失是叠加的而大模型高位量化的损失是可控的。这个反直觉的结论我验证过很多次参数量的收益通常大于量化精度的收益前提是量化不低于 Q4。还有一条容易被忽略不同量化算法对注意力层和前馈层的处理不一样K 系列量化Q4_K_M 里的 K对关键层保精度比早期的对称量化好不少。文件名里带_K_M的优先选_K_S是更激进的版本只有在内存实在紧张时才用。4.2 上下文长度与缓存内存的估算上下文长度是第二个吃内存的大户而且很多人完全没算过这笔账。推理时每个已处理的词元都要在缓存里存一份注意力键值对这个缓存随上下文线性增长。估算公式每词元缓存字节数 ≈ 2 × KV头数 × 头维度 × 精度字节数 × 层数拿一个典型 7B 模型举例32 层、隐藏维度 4096、32 个注意力头、8 个 KV 头分组查询注意力、头维度 128、缓存用 16 位浮点。每层每词元2 × 8 × 128 × 2 4096字节即 4 KB乘以 32 层每词元 128 KB。那么4K 上下文4096 × 128KB ≈ 512 MB8K 上下文约 1 GB32K 上下文约 4 GB注意这只是缓存还要加上模型权重本身。所以 16G 机器跑 7B Q44.1G 权重 32K 上下文4G 缓存 运行时开销其实已经接近临界了。开长上下文之前先算这一笔比事后对着风扇声发愁有用得多。再补一个细节上下文长度不等于一次能喂多少字。中文一个汉字大约 1 到 2 个词元标点和英文单词更碎。做长文档处理时我一般按汉字数 × 1.5估词元数留 20% 余量不然容易在接近上限时被截断而截断往往不报错只是回答变得莫名其妙。4.3 线程数与加速卸载的调法线程数不是越大越好。物理性能核数量是最优起点超过物理核数之后多出来的线程在抢同一批执行单元反而变慢。命令行里通常用-t指定# 先测 4、6、8 三档看哪档 tok/s 最高 for t in 4 6 8; do echo threads$t macai text 用一句话解释什么是量化 --threads $t --json \ | jq -r .timing.tok_per_s done这个测法很土但很有效五分钟就能摸清你机器的甜点值。我测过的几台机器甜点值普遍在性能核数到性能核数2 之间超过就掉。另一个关键参数是卸载到加速单元的层数。绝大多数后端支持把部分或全部层交给加速单元计算剩下的留 CPU。全卸载通常写--gpu-layers 99这种夸张数字速度最快但受限于加速单元可用的内存配额配额不够时会静默回退速度断崖式下跌。判断方法很简单跑一次全卸载跑一次零卸载对比tok_per_s如果两者接近说明卸载没生效去查配额或者查二进制有没有编进加速支持。4.4 采样参数三个旋钮的配合心法采样参数决定模型怎么选下一个词是最玄学也最容易调坏的部分。三个核心旋钮temperature温度控制随机性。0 是每次选概率最高的词完全确定0.7 到 0.8 是通用区间1.2 以上开始发散。top-p核采样只在累计概率前 p 的候选里采样。0.9 到 0.95 是常规值调低更保守。repeat penalty重复惩罚压制刚出现过的词防止复读。1.1 左右温和1.3 以上容易导致语句断裂。我的经验配方是分任务定的任务类型temperaturetop-prepeat penalty说明结构化抽取0.10.81.05要稳定不要创意代码生成0.20.91.05略留余量避免死板通用问答0.70.951.1默认档创意写作0.90.951.15放开但要防复读头脑风暴1.10.981.1要发散接受跑题注意这三个参数是联动的。你把温度调高又不加重复惩罚模型容易陷入同一个句式循环把重复惩罚调太狠模型会开始生造词来躲避惩罚。改参数一次只改一个别同时动三个否则你永远不知道是哪个起的作用。还有一个隐藏项系统提示词的位置和格式。不同模型家族对对话模板的要求不一样有的需要特定的开始/结束标记有的要求系统提示放在最前面。模板错了不会报错只是效果变差——这是本地推理里最隐蔽的坑之一后面第 7 节还会提到。5. 图像生成把随机性关进可复现的笼子5.1 在 Mac 上做本地出图的现实预期先把预期摆正统一内存架构跑扩散模型是可行的但速度和独立显卡不是一个量级。512 分辨率、20 到 30 步采样一张图大概十几秒到一分钟1024 分辨率会翻好几倍而且内存压力陡增。这个速度用来做一天出几十张备选完全够用用来做实时预览不够。内存开销主要来自两块模型权重基础模型通常 2 到 4 G加上文本编码器和变分自编码器和注意力计算的中间张量。中间张量随分辨率平方增长所以 512 到 1024 是四倍关系不是两倍。这解释了为什么很多人 512 跑得挺顺一上 1024 就卡死。5.2 分辨率、步数、引导强度三者的关系这三个参数是出图质量的主开关理解它们的关系比记数值更重要。分辨率决定构图容量。512 适合半身像和特写768 到 1024 才撑得起全身和场景。但直接把分辨率拉高不等于变好——训练时的分辨率分布决定了模型在哪个尺寸下最习惯超出太多会出现重复肢体、多头多手这类结构崩坏。稳妥做法是分段放大先在原生分辨率出图再用放大流程二次处理。采样步数决定去噪的细致程度。20 到 30 步是绝大多数采样器的收敛区间超过 40 步的边际收益很小纯属浪费电。低于 15 步会明显发糊。有个经验换采样器比加步数更有效某些采样器 20 步的效果胜过另一些的 40 步。引导强度也叫 CFG scale控制多听提示词的话。太低3 以下画面松散、不听指令太高12 以上颜色过饱和、构图僵硬、出现锐利边缘伪影。日常取 6 到 8。参数常用区间偏低表现偏高表现分辨率512 / 768 / 1024细节不足结构崩坏、重复肢体步数20-30发糊、噪点残留收益递减、耗时翻倍引导强度6-8不听提示、构图散过饱和、僵硬伪影5.3 种子、提示词、参数一起落盘出图最容易犯的错是出了一张满意的想微调一下结果再也复现不出来。原因永远是同一个——随机种子没记。macai 的做法是强制记录每次生成返回的 JSON 里带seed图片文件名里也带。未指定种子时用一个递增或随机的整数指定时原样使用。macai image a quiet reading room, morning light, wide shot \ --model sd15-base \ --size 768x768 \ --steps 28 \ --cfg 7.0 \ --seed 1234567 \ --out ./out \ --json配合exiftool把完整参数写进图片元数据这一步花不了几秒钟但价值巨大exiftool -overwrite_original \ -Commentmodelsd15-base;steps28;cfg7.0;seed1234567;prompta quiet reading room, morning light, wide shot \ ./out/2024-06-11_142233_seed1234567.png以后不管过多久拖进任何支持读元数据的工具参数全在里面。我现在的习惯是宁可多存五十字节元数据也不删任何一张出过的图——因为你永远不知道哪张废图的种子会在三个月后变成爆款。5.4 风格微调与批量出图风格微调用的是低秩适配权重LoRA本质是一个小文件加载后对基础模型的行为做偏移。命令行里通常用--lora 路径 --lora-scale 0.7这样的参数。系数很关键0.5 到 0.8 是常用区间1.0 往往过拟合——画面变成风格的复制粘贴失去了提示词的控制力。批量出图的核心是同一组参数扫一个变量。比如固定种子、固定提示词只扫引导强度看哪档最稳#!/bin/bash set -euo pipefail PROMPTa quiet reading room, morning light, wide shot SEED1234567 for cfg in 5.5 6.5 7.5 8.5; do macai image $PROMPT \ --model sd15-base --size 768x768 --steps 28 \ --cfg $cfg --seed $SEED \ --out ./out/sweep_cfg_${cfg} --json \ | jq -r .images[0].path doneset -euo pipefail这三件套是必须的出错立即停、未定义变量报错、管道中间环节失败也报错。少了它某个参数拼错时脚本会安静地生成一堆无效图你还以为跑成功了。6. 脚本化实战把命令串成流水线6.1 用标准输入做批量文本处理单条命令的价值有限管道里才是它的主场。macai 支持从标准输入读提示词--stdin开关打开后每行输入触发一次推理cat docs/*.txt \ | macai text --stdin \ --system 把输入压缩成一句不超过 40 字的中文摘要不加任何前缀 \ --temperature 0.1 --json \ | jq -r select(.ok) | .text \ summaries.txt这条链里有三个设计点在起作用。第一--system单独传系统提示不混在用户输入里避免模板拼接出错。第二--json让每条结果独立成行jq才能逐行处理。第三select(.ok)过滤掉失败条目防止一行错误信息把后面的解析全带崩。如果文件很多逐行处理会反复加载模型开销巨大。这时候用--batch模式模型只加载一次把整个文件当一批处理。加载 4G 模型大概要一秒处理一千条的话省下来的是十几分钟。6.2 长文本切分与结果合并上下文有上限长文档必须先切。切分策略比想象中重要按固定字数硬切会把句子拦腰斩断导致每段开头都是半句话摘要质量必然下降。我用的策略是按段落聚合到接近上限再切保留自然边界。def chunk(text, max_chars1500): paras [p.strip() for p in text.split(\n) if p.strip()] out, buf [], for p in paras: if len(buf) len(p) 1 max_chars and buf: out.append(buf) buf p else: buf f{buf}\n{p} if buf else p if buf: out.append(buf) return out1500 字这个阈值是按汉字 × 1.5 ≈ 词元数倒推的1500 字约 2250 词元留出系统提示和输出的空间4K 上下文刚好放得下。如果你的模型支持 8K这个值可以放宽到 3500 左右。结果合并环节要注意顺序。并行处理快但输出顺序会乱串行慢但顺序天然正确。我的做法是每个任务带一个序号处理完后按序号排序兼顾速度和正确性ls chunk_*.txt | sort | while read -r f; do idx$(basename $f .txt | sed s/chunk_//) macai text --file $f --system 写一句摘要 --json \ | jq -r --arg i $idx \($i)\t\(.text) done | sort -n | cut -f2 merged.txt6.3 输出命名与元数据规范批量跑完之后最痛的不是生成是找不到东西。我的命名规范固定三段日期_时间_种子前缀可选加任务类型。之所以把时间放前面是因为文件管理器默认按名字排序时间前缀天然按时间线排列找昨天下午那批一眼就能定位。元数据除了写进图片的注释字段还额外落一份 JSONL 索引文件每行一条记录包含输入、参数、输出路径、耗时。这个索引文件的用处是可以直接用jq做统计平均耗时多少、哪个模型用得最多、哪批任务失败率高。跑了一个月之后回头看这些数据比凭感觉优化靠谱得多。7. 常见问题与排查实录7.1 问题速查表把这两年遇到的问题按现象归档先查表再深挖能省大量时间现象最可能原因处理方向速度突然掉到每秒几个词元内存压力、换页关掉其他应用降上下文换低量化加载就报错找不到模型路径含空格或波浪号未展开用引号包裹或写绝对路径输出全是重复句重复惩罚过低或温度过低惩罚提到 1.1温度提到 0.7回答答非所问、格式错乱对话模板不匹配检查该模型家族要求的模板格式出图全黑或全噪点步数过低、引导强度过低步数提到 20CFG 提到 6出图肢体结构崩坏分辨率超出训练分布回到原生分辨率改分段放大中文输出夹英文乱码词表或编码问题确认模型支持中文检查输入编码为 UTF-8脚本跑到一半静默退出管道中间失败未捕获加set -euo pipefail首次调用特别慢后面正常模型冷加载正常现象或用常驻服务模式生成结果每次都不一样固定种子某些算子非确定性属正常追求完全一致需关掉部分优化7.2 性能不达预期的排查顺序速度慢是最常见的抱怨但原因可能在南辕北辙的地方。我固定按这个顺序查能覆盖九成情况。第一步查内存压力。开着内存监控跑一次推理看峰值。如果系统在换页速度必然崩这时候优化参数毫无意义先减负。第二步查加速是否真的生效。跑一次零卸载做对比如果速度只差一点点说明加速根本没进去去查二进制编译选项和配额。第三步查线程数。按 4.3 的方法测一遍很多人默认用了逻辑核数超配了。第四步查上下文长度。开着 32K 上下文跑短对话等于每次都分配了一大块缓存白白占内存按需降下来。第五步才是换模型。前面四步都排除之后才考虑量化档位和模型尺寸。这个顺序的逻辑是从影响最大、成本最低的因素开始排。换模型成本最高放最后。7.3 内存吃紧时的六个手段内存不够是本地推理的常态尤其是笔记本。按见效速度排降上下文从 32K 降到 8K直接省几个 G对多数对话任务毫无影响。降量化Q6 换 Q47B 模型省 1.5G 左右。关掉其他大应用浏览器开五十个标签页的内存占用常常超过模型本身。缩短输出设最大输出词元数上限防止模型滔滔不绝把缓存撑满。分批处理长文档不要一次喂切段跑每段跑完释放。图像降分辨率512 和 1024 的中间张量差四倍先从分辨率下手。注意不要在内存边缘反复试探。系统接近临界时会变得极度卡顿你以为程序死了其实在换页。留 20% 余量是底线。7.4 出图质量异常的定位思路图像出问题比文本更难定位因为失败模式更模糊。我的排查路径是固定的四问种子固定了吗步数够吗引导强度在区间内吗提示词和模型匹配吗前三个都是数值问题查参数就行。第四个最容易被忽略——某些模型对提示词的语言和写法有强偏好用中文提示词配一个主要在英文语料上训练的模型效果会明显打折。这不是模型不能用中文而是它对中文概念的理解粒度更粗。稳妥做法是核心描述用英文关键词风格和氛围词可以中英混用实测下来这样最稳。还有一个反直觉的经验提示词不是越长越好。超过一定长度后模型对每个词的注意力被稀释靠后的词几乎不起作用。我的习惯是控制在 30 个关键词以内把最重要的主体放最前面风格词放最后权重递减。如果确实需要堆细节用权重语法给关键项加权比单纯堆词有效。8. 我踩过之后才明白的几件事跑了这么久有些结论是文档里不会写的纯靠试错换来的。第一配置文件比命令行参数重要得多。我一开始什么都写在命令里结果每次都要翻历史记录找上次那串参数。后来把所有稳定参数沉到配置文件命令行只留变量部分效率翻倍。判断标准很简单一个参数你连着用了三次以上就该进配置。第二模型不是越新越好是越匹配越好。我追过几次新发布的模型结果发现在我的具体任务上一个半年前的中等尺寸模型反而更稳。原因是新模型往往在通用能力上强但在特定格式输出上不如经过针对性微调的旧模型。换模型之前先跑一组固定测试集用同一批输入对比别凭印象。第三日志要写到磁盘不要只看终端。终端滚过去就没了。我把每次调用的完整参数、耗时、输出长度追加到一个日志文件里一个月后做统计发现某类任务的失败率异常高追下去是提示词模板里的一个标点问题。这种问题不靠日志永远发现不了。第四别在中午跑批量任务。听起来像玩笑但真事笔记本满载跑推理风扇狂转机身烫手电池掉得飞快而且系统会主动降频保护速度反而更慢。批量任务放晚上或者插电的时候跑实际总耗时更短。我现在的习惯是插上电源再启动批量脚本。第五留一条最小可复现命令。每个项目的 README 里我都会放一条最短的、能跑通的命令不带任何可选参数。这条命令的价值在于三个月后环境变了、配置乱了跑一遍它就知道是环境问题还是参数问题。这个习惯救过我很多次。最后分享一个小技巧关于测试新模型。不要拿一个复杂任务去试用三个体检问题就够让它做一次简单的算术、一次格式化的 JSON 输出、一次两百字的中文说明。三个都过说明基本可用任何一个拉胯这个模型在你的场景里大概率也不靠谱。这套体检花不到一分钟比下载十个模型挨个跑正式任务省太多时间。这套工具集现在的状态是文本部分日常在用图像部分周末批量出图脚本都放在一个仓库里换机器时 clone 加拷模型就能恢复。后面打算补的方向是把量化转换和模型体检也做成子命令省得每次都翻笔记。不过那属于锦上添花现在这套已经够我用了。