上个月我把 Qwen2.5-1.5B-Instruct 从 HuggingFace 拉下来用 MTK GAI Toolkit 做了转换和量化最终跑在了一块 MTK 平台的端侧开发板上。整个流程折腾了将近两周中途一度搞不清到底是模型的问题、工具链的问题还是我自己对“端侧部署”这件事的理解有问题。现在回头看踩的坑其实都集中在几个固定的环节模型选型时的内存预估、HuggingFace 下载阶段的网络与文件校验、转换量化时的精度把控以及上板后的首包调试。这篇文章就把我验证过的完整路径写下来从“为什么选 1.5B 这个规格”开始到工具链安装、模型下载、转换量化、端侧推理再到性能调优和后续扩展方向。内容偏实战适合手里刚好有 MTK 平台设备、想把小参数大模型部署到边缘侧的工程师也适合对端侧 AI 感兴趣、想了解一条完整链路是怎么串起来的朋友。1. 内存、体验和生态为什么端侧选型的答案偏偏是 Qwen2.5-1.5B很多朋友拿到板子后的第一个问题不是怎么部署而是“到底该选哪个模型”。我的建议是在动手之前先把三笔账算清楚——内存账、体验账、生态账。Qwen2.5-1.5B 之所以在端侧很常被提起不是因为它的参数数字多么特殊而是因为它刚好同时满足了三笔账的条件。1.1 内存账FP16、INT8、INT4 分别要占多少空间模型能不能跑第一道门槛是内存。Qwen2.5-1.5B 的参数量约为 1.54B也就是 15 亿出头。我们先把权重体积算一下FP16半精度每个参数 2 字节1.54B × 2B ≈ 3.08GB约 3GB。INT8每个参数 1 字节约 1.54GB约 1.6GB。INT4每个参数 0.5 字节约 0.77GB约 0.9GB。但注意这只是模型权重本身的体积。实际推理时还有两部分隐性开销一是 KV Cache它跟序列长度和 batch 大小直接相关多轮对话或者长上下文场景下几百 MB 到 1GB 都是正常的二是运行时中间激活值这部分在 prefill 阶段尤其占用内存虽然框架会做内存池复用但峰值仍然不能忽视。所以我的经验是选型时按“权重体积 × 2”来估整机内存需求。这样算下来FP16 直接跑基本需要 6GB 以上可用内存这已经超出大多数端侧设备的承受范围INT8 需要约 3GB勉强可以INT4 是最稳妥的约 2GB 即可落地。这也是为什么端侧部署几乎绕不开量化的根本原因。1.2 体验账0.5B、1.5B、3B 之间的真实差距内存账算完接下来是体验账。0.5B 模型在端侧跑很轻快中文问答速度能到非常流畅的程度但效果说实话只能算“能听懂话”稍微复杂一点的指令跟随、多轮推理、结构化输出翻车概率明显上升。3B 模型在指令跟随和生成质量上确实好但内存压力陡增而且在很多中低端 MTK 平台上推理速度会被内存带宽卡死用户等第一个 token 的耐心是有限的。1.5B 恰好是这个区间里比较折中的选择中文质量明显强于 0.5B较真起来也能做不少实用场景相比 3B 又轻不少普及性更强。我实际测试下来1.5B 的 INT4 部署包在端侧设备上的表现属于“能用且值得调”的范畴。1.3 生态账为什么在 MTK 平台上 Qwen 会特别顺手最后一个影响因素是生态。Qwen 系列在 HuggingFace 和国内主流模型社区上都有官方仓库safetensors 分片、tokenizer 配置、模型 card 都做得比较规范。MTK 的 GAI Toolkit 这类端侧工具链对 transformer 结构的支持会优先对齐社区里最流行的开源模型Qwen 正好在这个清单里这就意味着转换时遇到未知算子的概率低很多。顺带说一句MTK 平台和高通平台在端侧 AI 上的思维方式不太一样高通更侧重手机和高性能场景MTK 的设备覆盖面更广IoT、车载、智能家居、工控都经常见到所以 GAI Toolkit 要同时照顾 Linux 和 Android 生态。这个差异后面会直接影响你对“目标设备”的配置选择。2. 先花十分钟把 MTK GAI Toolkit 的边界摸清后面才不返工很多人拿到工具链就急着装环境、跑转换结果到后面发现方向错了白白浪费一两天。我建议先搞清楚 GAI Toolkit 到底管哪一段、不管哪一段再动手。2.1 GAI Toolkit 在整套 SDK 里的位置MTK 的 AI 软件栈大致分三层。最底下一层是芯片驱动和硬件抽象层负责跟 NPU、GPU、CPU 打交道中间一层是运行时负责算子调度、内存管理、性能优化这一层是承上启下的关键最上面一层才是给应用开发者用的工具链和 SDKGAI Toolkit 就是这一层的核心组件之一。它的定位是“把训练好的模型导出成端侧可高效运行的格式”并提供运行时 API 去加载和执行。换句话说HuggingFace 上拿到的原始模型不能直接丢进端侧设备跑必须经过 GAI Toolkit 的转换和量化才能变成端侧运行时认识的东西。2.2 一条链路上的四个环节缺一不可我习惯把整条链路分成四段模型获取从 HuggingFace 或社区镜像下载原始模型权重、tokenizer 配置等文件。格式转换把 PyTorch/safetensors 格式转换成工具链要求的中间表示这一步本质是把模型结构“翻译”给端侧运行时听。量化压缩根据目标设备的内存和算力约束把 FP16 权重压成 INT8 或 INT4同时尽量保住精度。端侧部署把部署包推送到设备通过运行时 API 加载、推理、输出。这四个环节里导出环节最容易被忽视。很多转换失败问题并不出在 GAI Toolkit 本身而是原始模型目录里的配置文件缺失或者 tokenizer 版本不符合要求。所以后面我会单独说模型下载后要做哪些检查。2.3 我的验证环境与工具链清单为了让你有数我列一下我当时的环境不代表你必须完全一致但可以作为参考项目内容PC 操作系统Ubuntu 22.04建议 20.04 以上Python 版本3.10原始模型Qwen2.5-1.5B-InstructHuggingFace 官方仓库工具链MTK GAI Toolkit版本以你们拿到的 SDK release 为准目标平台MTK 端侧评估板运行定制 Linux 系统连接方式ADB另有串口用于看内核日志GAI Toolkit 具体版本的命令参数会有差异但我下面的思路和流程是通用的。你拿到工具链后先跑一遍它自带的 demo通常有 sample model确认环境本身没有问题再去动 Qwen否则出了问题你根本没法定位是环境坏了还是自己的模型路径弄错了。2.4 环境准备阶段最容易忽略的两个检查第一是 Python 依赖的版本冲突。工具链通常依赖特定版本的 torch、numpy、onnx 等库如果你 PC 上本来就有深度学习的训练环境很可能会撞版本。我当时就是被 torch 版本卡了半天后来用虚拟环境单独隔离一个 Python 环境才解决。第二是目标板上的运行时版本。GAI Toolkit 转出来的部署包对目标设备上的 runtime 版本有要求转换工具本身不会提示你板子的版本够不够这个只能靠你自己查。我的建议是上板之前先执行一次 runtime 自检或跑官方 demo。3. 从 HuggingFace 拿模型网络、目录、完整性三个容易被卡的环节模型下载看起来是最简单的一步实际却是很多人卡住的第一站。这一节内容比较多因为这种“拉模型”的操作人人都要做但很多人做到一半就发现有问题。3.1 不要用浏览器逐个下载直接上 huggingface-cli我见过很多新手在 HuggingFace 网页上把文件一个个点下载再手动传到服务器这样效率低不说还特别容易漏文件。正确做法是用官方命令行工具拉取整个仓库。方式一pip install -U huggingface_hub huggingface-cli download Qwen/Qwen2.5-1.5B-Instruct --local-dir ./Qwen2.5-1.5B-Instruct新版huggingface_hub也支持hf子命令hf download Qwen/Qwen2.5-1.5B-Instruct --local-dir ./Qwen2.5-1.5B-Instruct这个命令会把仓库里的所有文件模型权重、config.json、tokenizer 相关文件、甚至 README都拉下来。--local-dir指定本地目录推荐直接用因为后续转换工具依赖的是一个完整目录而不是散落的几个文件。3.2 网络环境不好时两个可落地的替代思路我知道国内直连 HuggingFace 经常速度很慢甚至中途连接中断。这里有两种比较稳妥的路线都不涉及任何特殊网络手段。第一使用公开镜像源。HuggingFace 社区有公开的端点和镜像服务你可以通过环境变量切换下载源export HF_ENDPOINThttps://hf-mirror.com设置完之后再执行上面的huggingface-cli download命令下载速度通常会明显改善。这是社区里很常见的做法属于公开可用的服务。第二改用国内模型社区。Qwen 系列在国内的 ModelScope 魔搭社区上有官方仓库下载体验更稳定。你只需要用 ModelScope 的 SDKfrom modelscope import snapshot_download model_dir snapshot_download(Qwen/Qwen2.5-1.5B-Instruct) print(model_dir)下载完成后目录结构和 HuggingFace 上的基本一致可以直接给 GAI Toolkit 使用。对我个人来说如果只考虑下载稳定性ModelScope 的体验往往更好。3.3 下载后必做的完整性检查别信“文件都在就是对的”下载完成后先别急着进下一步花五分钟检查一下目录。Qwen2.5-1.5B-Instruct 这类模型仓库正常应该包含这些文件config.json模型配置包括层数、隐藏维度、词汇表大小等。model.safetensors.index.json分片索引文件说明权重被切成哪几个分片。多个model-00001-of-00002.safetensors之类的分片文件。tokenizer.json/tokenizer_config.json/vocab.jsontokenizer 三件套缺一不可。generation_config.json生成参数配置有些工具链会读它。检查分片是否齐全最简单的方式是解析索引文件看它引用的所有分片是否都存在。如果你是用huggingface-cli拉的一般不会漏但如果你手动合并或拷贝过就要小心。还有一个验证方法直接加载 safetensors 看能不能打开from safetensors import safe_open fp ./Qwen2.5-1.5B-Instruct/model-00001-of-00002.safetensors with safe_open(fp, frameworkpt) as f: print(f.keys()[:5])能正常打出 tensor 名字说明文件本身没坏。我遇到过文件大小都对但中间多了几个字节的情况这种问题只有实际加载时才暴露越早发现越省事。4. 转换和量化FP16 到 INT4 之间每一步都是权衡模型下载完毕接下来进入核心环节转换和量化。这也是整条链路里最容易出问题、最考验经验的一步。4.1 为什么不能拿 HuggingFace 原格式直接上板HuggingFace 上的 safetensors 格式是为了训练和推理框架准备的它本身是一种通用的权重存储格式没有针对端侧 NPU 的算子布局做优化。端侧运行时执行计算时需要的是内存布局紧凑、算子版本匹配、能直接映射到硬件加速单元的执行格式。GAI Toolkit 的转换器做的事就是把这个“翻译”过程自动化。它不改变模型的数学表达但会改变权重在内存里的组织方式和计算图的调度方式。4.2 一次典型的转换命令长什么样以我当时的路子为例使用的 GAI Toolkit 转换命令大概长这样不同版本参数名会有差异以你手里的 SDK 文档为准gai_toolkit convert \ --model_type qwen2 \ --input ./Qwen2.5-1.5B-Instruct \ --precision int4 \ --target_device mtk_edge \ --output ./qwen_deploy_pkg这里几个参数值得说一下。--model_type告诉转换器这是什么结构的模型Qwen2 是当前 Qwen2.5 系列的基座结构选错会让算子映射完全错乱。--precision指定量化精度。--target_device指定目标平台配置如果你用的是特定芯片平台某些版本会让你进一步指定芯片型号这个参数决定了它能调度哪些硬件单元。转换结束后会在--output目录下生成一个部署包里面通常包含量化后的模型文件、tokenizer 配置和一份部署说明。提示在跑真机转换前建议先用小模型或官方 sample 跑通一遍转换流程确认命令参数和输出目录结构都正常再换 Qwen。这样可以排除工具链本身配置问题。4.3 INT8 和 INT4 到底怎么选我的判断方法很多人一上来就问“用 INT4 还是 INT8”我觉得这问题不应该问别人应该问自己的设备。先看一组大致对比精度权重体积推理速度趋势精度损失FP16约 3GB参考基准无INT8约 1.6GB比 FP16 略快很小多数场景感知不到INT4约 0.9GB比 INT8 更快但受带宽约束有一定下降复杂任务可见我的经验是先用 INT8 转换跑通推理、验证功能正确后再看设备内存是否吃紧。如果内存充足INT8 其实是最好的选择精度损失小、调试成本低。只有当你发现 INT8 部署包加载后剩余内存已经无法满足 KV Cache 或应用其他模块需求时再降级到 INT4。注意 INT4 的精度损失不是均匀分布的数学推理、代码生成、结构性文本这类任务感受最明显闲聊类任务还好。所以“能不能接受”取决于你的应用场景没有绝对答案。4.4 转换完模型开始“说胡话”问题通常出在这三处我在转换过程中遇到过一个非常典型的现象模型能加载也能生成但生成的文字完全是乱的或者同一个词无限重复。排查到后面发现三个主要原因你以后遇到可以按顺序查第一tokenizer 文件没同步过去。部署包里如果缺少tokenizer.json运行时可能用了错误的词汇表生成的文字当然牛头不对马嘴。第二量化校准环节不合适。虽然多数工具链用“每层特殊量化”的方式但有些方案还是需要一小批校准数据校准集如果跟模型实际使用场景偏差太大模型在量化后容易“崩”。你可以用一小段与真实场景接近的中文文本作为校准输入重新量化。第三输入侧处理错误。有些端侧运行时要求你传入的输入必须经过与训练一致的 chat template 处理少了这步模型虽然会生成但回答可能完全偏离指令。5. 第一个端侧推理程序跑通、测速、盯住三个指标转换终于搞定接下来就到最有成就感的环节把部署包推到设备上跑出第一段文字。这一节我不只讲代码还会讲怎么看指标。5.1 先完成部署包上板的准备工作把生成的部署包目录通过 ADB 推送到目标板比如放到/data/local/qwen下adb push ./qwen_deploy_pkg /data/local/qwen推完后建议先确认目录里的文件权限特别是模型文件如果权限不对运行时可能会拒绝加载。接着确认目标板上的 runtime 是否已安装、版本是否匹配执行 runtime 自检或者跑官方的 helloworld demo。到这一步为止我前面反复强调的“先跑通官方 sample”就发挥作用了。5.2 一个最简单的加载与推理程序骨架GAI Toolkit 的运行时通常提供 C 和 Python 两套 API。我一般先在 PC 端用 Python 验证逻辑再在板子上用 C 集成到实际应用。一个最基本的 Python 推理流程如下from gai_runtime import Runtime runtime Runtime() model runtime.load_model(/data/local/qwen/qwen_deploy_pkg) session model.create_session() prompt 你好请用一句话介绍你自己 output session.generate( prompt, max_new_tokens128, temperature0.7 ) print(output.text)C 的骨架也类似核心步骤是创建 Runtime 实例、加载模型、创建 Session、填入 prompt、调用生成接口。生成接口通常会暴露max_new_tokens、temperature、top_p这些参数跟你在 PC 上使用 transformers 的习惯一致。注意端侧设备的系统 Python 环境可能不包含运行时绑定库如果你打算在板子上直接用 Python记得确认绑定的安装路径或者把推理逻辑封装成独立进程通过 IPC 对外提供接口。5.3 第一个 token 出来之前先盯住三个指标程序能跑通后不要急着做产品先把三个指标测明白加载耗时从调用 runtime 加载模型到模型 ready 的时间这个指标决定了你是否可以做“常驻内存”的守护进程。如果加载耗时超过几十秒那应用启动时就不能临时加载必须用服务常驻。首 token 时延Time to First TokenTTFT从用户输入 prompt 到模型输出第一个 token 的时间。这个数字直接影响用户的第一感受一般端侧设备 INT8 量化后Qwen2.5-1.5B 的首 token 时间在几百毫秒到 1 秒左右都是常见范围取决于平台算力和 prompt 长度。生成速度单位时间生成的 token 数通常用 token/s 表示。对这个量级的模型10 token/s 往上是比较舒服的体验20 token/s 以上就相当流畅了。如果低于 5 token/s用户会明显觉得“卡”。拿到这三个数字后你才能真正判断“这个模型在这块板子上能不能用”而不是靠感觉。5.4 一个很隐蔽的坑日志里没报错但输出为空我在第一次上板时就遇到过这个情况session 正常创建prompt 也传进去了最后返回结果却是空字符串。排查了很久最后发现是模型内部的max_new_tokens设置与输入 prompt 长度加起来超过了模型支持的序列长度上限模型内部触发了截断但运行时没有把这个信息抛成异常。解决办法很简单把max_new_tokens调小或者确认转换时配置的序列长度是否足够。这类问题提醒我端侧推理程序里很多状态是靠输出结果的合理性来判断的日志不报错不等于没问题。6. 往下走的方向内存优化、速度调优与应用整合第一个 demo 跑通只代表链路通了距离真正能用在产品里还有一段路。这一节聊几个我觉得比较重要的优化方向和扩展思路。6.1 最容易碰到的 OOM排查位置要按顺序来内存溢出是端侧场景的常客。我的排查顺序很固定先看模型权重本身把精度从 INT8 降到 INT4再看 KV Cache 的分配策略看运行时是否支持按需分配、是否能限制最大序列长度最后看应用层的 buffer比如视频流、传感器数据是否跟模型抢内存。大部分 OOM 都出在这三个位置里。6.2 速度调优最快的捷径往往不在量化很多人觉得模型跑得慢就降到 INT4其实在端侧LLM 的速度瓶颈往往是内存带宽而不是计算单元。模型每生成一个 token都要把所有权重从内存搬到计算单元这个过程受内存带宽限制。所以你会发现同样的模型在算力更强但带宽不变的情况下速度提升有限反而是减小权重体积比如从 INT8 降到 INT4带来的带宽收益更直接。另外两个实用的优化方向是多轮对话场景下启用 KV Cache 复用避免每次会话重新计算历史部分以及利用工具链对 prefill 和 decode 两个阶段分别调度优化的能力通常工具链会把 prefill 阶段尽量压到 NPU把 decode 阶段也根据你的目标设备动态分配到 CPU/GPU/NPU 以换取更好功耗表现。6.3 从“能跑模型”到“能做产品”的三个扩展方向跑通推理后通常下一步是把它变成真正的功能封装成本地服务在板子上跑一个轻量 HTTP 服务把推理接口暴露出来App 或前端通过 RESTful API 调用避免业务代码跟模型运行时耦合在一起。Python 的 FastAPI 或者 C 的 httplib 都行看你的团队技术栈。结合语音链路如果做语音助手类产品可以用 ASR 模块把用户语音转成文本送进 Qwen再把模型输出接 TTS。1.5B 模型做意图理解、简单对话、内容总结已经够用。大小模型协同用一个小模型做意图分类判断该走知识库检索还是该走大模型生成可以让功耗下降一个层级在嵌入式场景很有价值。关于模型微调如果产品场景非常垂直可以在端侧部署之前先用 LoRA 在 PC 上做低成本微调让模型更贴合你的业务数据再走 GAI Toolkit 转换流程。这不会改变部署链路但会让最终效果明显提升。最后说一个我在整个过程里最大的感受端侧部署 LLM真正难的不是跑通一个 demo而是理解每一步约束的来源。模型下载时的文件完整性、转换时的精度权衡、运行时的内存分配、甚至 target_device 的选择这些细节看似琐碎但每一个都决定了最终能不能稳定上线。如果你也在做类似的事情建议按我上面说的顺序先把每一步都验证扎实再往后走。别急着追求“一次跑通”那在这个领域里本来就少见。