1. 端侧 LLM 部署到底在解决什么问题把大模型塞进手机、开发板、车机或者一台没有独立显卡的迷你主机里这件事从 2023 年下半年开始就不再是实验室里的玩具了。我最早接触端侧推理是在一个 RK3588 的板子上跑视觉模型后来发现同一套思路完全可以迁移到大语言模型上——核心矛盾从来没变过算力有限、内存有限、功耗有限但用户期望的响应速度和云端 API 一样快。端侧 LLM 部署说白了就是让模型权重和推理引擎都跑在本地设备上不依赖网络请求。它解决的问题很具体数据不出设备、断网可用、没有按 token 计费的成本、响应延迟可控。适合谁来参考三类人最需要一是做端侧 Agent 的开发者LLM 只是 Agent 的一个组件部署方式直接决定整个 Agent 的架构二是做嵌入式 AI 产品的工程师需要在资源受限环境下做取舍三是想在自己电脑上跑本地模型的爱好者想搞清楚量化、显存、推理框架这些概念到底怎么落地。这一篇是“深入理解端侧 Agent”系列的第二部分聚焦 LLM 部署本身。Agent 的规划、工具调用、记忆管理都建立在 LLM 能稳定推理的基础上所以这一步没搞扎实后面全是空中楼阁。2. 部署方案的整体设计与选型逻辑2.1 先搞清楚你的设备属于哪一档端侧设备差异极大选型第一步不是挑框架而是给自己的硬件定位。我习惯按内存和算力分三档档位典型设备可用内存适合模型规模推理框架倾向入门档手机、树莓派、RK35884-8GB0.5B-3B量化后llama.cpp、MNN、NCNN中档迷你主机、轻薄本、车机8-16GB3B-8B量化后llama.cpp、Ollama、MLC-LLM高档带独显的工作站、Mac Studio16GB8B-32B量化后vLLM、TensorRT-LLM、LM Studio这个分档不是绝对的但能帮你快速排除不合适的方案。比如你拿一块 4GB 内存的板子去跑 7B 模型不管怎么量化都会爆内存这时候要么换更小的模型要么换设备没有第三条路。2.2 量化端侧部署绕不开的第一道坎原始模型权重通常是 FP16一个 7B 模型光权重就要 14GB 左右端侧设备根本放不下。量化就是把权重从高精度浮点压缩成低精度整数常见的有 INT8、INT4甚至更低。量化的本质是用精度换空间和速度。我一般这样估算FP16 每参数 2 字节INT8 是 1 字节INT4 是 0.5 字节。一个 7B 模型FP16约 14GBINT8约 7GBINT4约 3.5GB再加上 KV Cache 和运行时开销实际占用还要往上浮 20%-30%。所以 8GB 内存的设备跑 INT4 的 7B 模型是可行的但余量不多上下文长度不能开太大。注意量化不是越低越好。INT4 相比 INT8 在多数任务上损失可控但再往下比如 INT3、INT2质量下降会非常明显尤其是需要精确推理和代码生成的任务。我实测下来Q4_K_M 这个档位是质量和体积的甜点区。2.3 推理框架怎么选框架选型我踩过不少坑总结下来看三个维度硬件适配、量化支持、易用性。llama.cpp 是我用得最多的纯 C/C 实现CPU 推理效率高支持 GGUF 格式的各种量化跨平台性好从 x86 到 ARM 都能跑。缺点是 GPU 加速配置相对繁琐。Ollama 本质上是 llama.cpp 的封装把模型下载、加载、API 服务都做成了开箱即用适合快速验证和本地开发。但它对底层参数的控制不如直接用 llama.cpp 灵活。MLC-LLM 走的是另一条路基于 TVM 编译能把模型编译成针对特定硬件的优化代码在移动端 GPU 上表现不错但上手门槛高一些。vLLM 和 TensorRT-LLM 更适合有独显的场景吞吐量优化做得好但端侧小设备基本用不上。我的建议是先用 Ollama 快速跑通验证效果确定模型和量化档位后再用 llama.cpp 做精细化部署。这样能省掉大量反复编译的时间。3. 核心细节解析与实操要点3.1 模型格式转换的完整链路从 HuggingFace 上下载的模型通常是 safetensors 格式不能直接被 llama.cpp 使用需要转成 GGUF。这个转换过程有几个关键点。第一步是准备转换脚本。llama.cpp 仓库里自带convert_hf_to_gguf.py用法如下python convert_hf_to_gguf.py ./Qwen2.5-7B-Instruct \ --outfile qwen2.5-7b-f16.gguf \ --outtype f16这里--outtype f16表示先转成 FP16 的 GGUF这是中间格式后面再量化。第二步是量化。llama.cpp 提供了llama-quantize工具./llama-quantize qwen2.5-7b-f16.gguf \ qwen2.5-7b-q4_k_m.gguf \ Q4_K_MQ4_K_M 里的 K 表示使用了 k-quant 方法M 表示 medium 档位。k-quant 的核心思路是对不同层用不同的量化策略重要的层保留更高精度不重要的层压得更狠这样整体质量比均匀量化好。实操心得转换大模型时内存占用会比较高7B 模型转换大概需要 20GB 以上内存。如果机器内存不够可以先用--outtype q8_0直接转成量化格式跳过 FP16 中间步骤但质量会略差一点。3.2 上下文长度与 KV Cache 的内存账很多人部署完发现模型能加载但一对话就崩八成是 KV Cache 爆了。KV Cache 是推理时缓存注意力机制的 key 和 value长度和上下文窗口成正比。估算公式大致是KV Cache 大小 2 × 层数 × 隐藏维度 × 上下文长度 × 精度字节数以 7B 模型为例32 层、隐藏维度 4096、上下文 4096、FP16 精度2 × 32 × 4096 × 4096 × 2 字节 ≈ 2GB如果量化到 INT8能降到 1GB 左右。所以你在 8GB 设备上跑 INT4 的 7B 模型权重占 3.5GBKV Cache 占 1-2GB加上运行时开销基本就满了。这时候要么缩短上下文要么开启 KV Cache 量化。llama.cpp 里可以这样配置./llama-server -m qwen2.5-7b-q4_k_m.gguf \ -c 2048 \ --cache-type-k q8_0 \ --cache-type-v q8_0 \ -ngl 0-c 2048把上下文限制在 2048--cache-type-k/v q8_0把 KV Cache 量化到 8 位-ngl 0表示不用 GPU 层纯 CPU 推理。3.3 线程数与批处理的调优CPU 推理时线程数不是越多越好。我实测下来线程数设置为物理核心数最合适超线程反而会因为调度开销导致性能下降。比如 8 核 16 线程的 CPU设-t 8比-t 16快。批处理大小batch size影响的是 prompt 处理速度。-b参数控制逻辑批大小-ub控制物理批大小。默认值在多数场景下够用但如果你的输入 prompt 很长适当调大-b能提升首 token 延迟。./llama-server -m qwen2.5-7b-q4_k_m.gguf \ -t 8 \ -b 512 \ -ub 512 \ -c 4096注意-ub调太大会增加内存峰值占用在内存紧张的设备上要谨慎。我一般从 256 开始试逐步往上加观察内存和速度的变化。4. 实操过程与核心环节实现4.1 从零搭建一个端侧推理服务我以一台 16GB 内存的迷你主机为例完整走一遍流程。目标是部署 Qwen2.5-7B-Instruct 的 INT4 量化版本提供一个兼容 OpenAI 接口的本地服务。第一步编译 llama.cpp。不要直接下载预编译二进制自己编译能针对当前 CPU 做指令集优化git clone https://github.com/ggerganov/llama.cpp cd llama.cpp cmake -B build -DGGML_NATIVEON -DGGML_OPENMPON cmake --build build --config Release -j$(nproc)GGML_NATIVEON会让编译器针对当前 CPU 的指令集AVX2、AVX512 等生成优化代码性能提升明显。第二步下载并转换模型。如果社区已经有现成的 GGUF 文件直接下载最省事。以 ModelScope 上的 Qwen2.5-7B-Instruct-GGUF 为例下载 Q4_K_M 版本即可。第三步启动服务./build/bin/llama-server \ -m ./models/qwen2.5-7b-instruct-q4_k_m.gguf \ -c 4096 \ -t 8 \ -b 512 \ --host 0.0.0.0 \ --port 8080 \ --cache-type-k q8_0 \ --cache-type-v q8_0启动后访问http://localhost:8080就能看到 Web UI也可以直接调 APIcurl http://localhost:8080/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5-7b, messages: [{role: user, content: 你好}], temperature: 0.7 }4.2 性能实测与参数对照我在同一台机器上跑了不同量化档位的对比测试输入固定为 128 token输出 256 token记录首 token 延迟和生成速度量化档位模型体积首 token 延迟生成速度主观质量Q8_07.2GB0.8s12 tok/s几乎无损Q5_K_M4.8GB0.6s18 tok/s基本无损Q4_K_M4.1GB0.5s22 tok/s轻微损失Q3_K_M3.3GB0.4s26 tok/s可感知损失Q2_K2.6GB0.3s30 tok/s明显损失从数据看Q4_K_M 是性价比最高的档位速度比 Q8_0 快了将近一倍质量损失在日常对话和简单任务上几乎察觉不到。Q3 以下就不太推荐了尤其是需要模型做逻辑推理的时候错误率会明显上升。4.3 接入 Agent 框架的注意事项端侧 LLM 部署好之后通常要接入 Agent 框架。这里有个容易被忽略的点端侧模型的输出稳定性不如云端大模型格式遵循能力偏弱容易在工具调用时产生不合法的 JSON。我的做法是在 Agent 和 LLM 之间加一层输出解析和重试机制。比如用 LangChain 或者自己写一个简单的 wrapper对模型输出做 JSON 校验失败就重新请求最多重试三次。同时把 temperature 调低到 0.1-0.3减少随机性。另外端侧模型的上下文窗口通常比云端小Agent 的记忆管理要更激进地做截断和摘要。我一般把对话历史控制在 2048 token 以内超出部分用规则或小模型做摘要压缩。5. 常见问题与排查技巧实录5.1 模型加载失败或推理崩溃这是最常见的问题原因通常有三类内存不足、格式不兼容、参数配置错误。内存不足的表现是加载到一半进程被 kill或者推理时突然崩溃。排查方法是先用free -h看可用内存再对照模型体积和 KV Cache 估算值。如果确实不够换更小的量化档位或者缩短上下文。格式不兼容通常是 GGUF 版本和 llama.cpp 版本不匹配。llama.cpp 更新很快老版本编译的程序可能读不了新格式的 GGUF。解决办法是重新拉取最新代码编译。参数配置错误里-ngl设得过大是高频问题。在没有独显的机器上-ngl必须设为 0否则会尝试加载 GPU 层然后失败。5.2 生成速度慢得离谱速度慢一般不是模型的问题而是编译选项或线程配置的问题。首先检查编译时有没有开GGML_NATIVEON。如果用的是通用二进制没有针对 CPU 指令集优化速度可能差好几倍。其次检查线程数。用lscpu看物理核心数-t设成物理核心数。我见过有人设成 32 线程结果比 8 线程还慢的就是超线程调度开销导致的。还有一个隐蔽的原因是内存带宽瓶颈。CPU 推理时模型权重需要从内存反复读取如果内存频率低或者通道数少速度上不去。这种情况下换设备比调参数更有效。5.3 输出质量突然变差如果之前用得好好的突然输出变得胡言乱语先检查是不是换了量化档位。不同档位的质量差异在复杂任务上很明显。如果量化档位没变检查 prompt 模板。不同模型的 chat template 不一样用错了会导致模型理解偏差。Qwen 系列用 ChatML 格式Llama 系列用自己的一套混用会出问题。llama.cpp 的llama-server会自动读取 GGUF 里内置的 chat template但如果你用的是自己转换的模型可能没有内置模板需要手动指定--chat-template参数。5.4 常见问题速查表现象可能原因排查方法解决方式加载到一半崩溃内存不足free -h看可用内存换小量化档位或缩短上下文推理时进程被 killOOMdmesg看 OOM 记录降低-c和-b速度异常慢未开指令集优化检查编译参数重新编译加GGML_NATIVEON速度异常慢线程数不合理lscpu看核心数-t设为物理核心数输出乱码chat template 错误检查模型文档指定正确的 template输出质量差量化档位过低对比不同档位换 Q4_K_M 或更高GPU 加载失败-ngl设置不当确认是否有独显无独显设-ngl 0API 无响应端口被占用ss -tlnp看端口换端口或杀占用进程避坑技巧每次调整参数后只改一个变量记录前后差异。我见过太多人一次改五六个参数出问题后根本不知道是哪个导致的。养成单变量调试的习惯能省下大量排查时间。6. 端侧部署的边界与后续扩展端侧 LLM 部署不是万能的。它的边界很清晰模型规模受限于内存推理速度受限于算力上下文长度受限于 KV Cache。在这些约束下端侧模型适合做的是轻量级对话、意图识别、简单工具调用、文本摘要这类任务。复杂的多步推理、长文档分析、高精度代码生成还是得靠云端大模型。但这不意味着端侧部署没有价值。恰恰相反在隐私敏感、网络不稳定、成本敏感的场景下端侧方案是唯一可行的选择。而且随着模型蒸馏和量化技术的进步小模型的能力在快速提升3B 级别的模型已经能处理相当多的实际任务了。后续如果要继续深入有两个方向值得探索。一是投机采样用一个小模型做草稿大模型做验证能在不损失质量的前提下提升推理速度。二是模型分片把大模型的不同层分布到多台设备上突破单设备内存限制。这两个方向在 llama.cpp 和 MLC-LLM 里都有初步支持但配置复杂度较高适合有一定经验的开发者尝试。我个人在实际操作中的体会是端侧部署最耗时间的不是技术本身而是反复的试错和参数调优。把量化档位、上下文长度、线程数这几个关键参数摸清楚后面就是体力活了。建议一开始就用小模型快速跑通全流程建立信心和直觉再逐步换大模型、加功能。