前阵子在整理相册归类功能的时候我一直被一个问题卡着图片理解必须在服务端做。电梯里没信号、地铁上断网App 里的“智能识别”直接变成摆设。后来我把目光放到了端侧小模型上试了一圈之后SmolVLM 这个系列让我眼前一亮——尤其是它 500M5亿参数这个档位压缩后模型文件不到 300MB在 iPhone 上跑起来完全可行。这篇文章就是我从模型选型、Swift 工程集成、图像预处理到本地推理全过程的实战记录代码也会一并贴出来。如果你也想在 iPhone/iPad 上离线跑一个能“看图说话”的模型或者正在做端侧多模态功能的调研这篇文章应该能帮你少踩很多坑。1. SmolVLM 是个什么模型为什么适合 iPhone1.1 先搞懂 VLM 到底在做什么VLMVision Language Model翻译过来就是“视觉语言模型”它和普通纯文本语言模型的区别在于输入端除了文字还能接收图像。你给它一张照片加一句“描述一下这张图”它能返回一段通顺的自然语言描述你给它一个截图加一句“图里这个报错信息是什么”它也能尝试把错误码和上下文解释出来。从工程实现角度理解这类模型内部其实由三部分组成一个视觉编码器负责把图片转成特征向量一个文本解码器负责生成答案两者之间再用一个投影层把视觉特征和文本语义空间对齐。这个结构理解起来不复杂但它决定了模型能不能在手机上跑——因为视觉编码器往往比文本模型还大一旦设计不好整个模型体积直接爆掉。1.2 SmolVLM 的“小”靠的是架构设计而不是蛮力压缩SmolVLM 是 Hugging Face 开源的一个小尺寸 VLM 系列主打方向就是让视觉语言模型能在消费级设备上运行。它有几个型号256M、500M、2.2B。这个“M”和“B”指的就是参数量500M 就是 5 亿参数2.2B 是 22 亿参数。模型小不只是“参数少”这么简单。SmolVLM 用了专门优化视觉 token 数量的技巧把每张图输入给文本模型的部分压缩到很紧凑的程度。传统视觉模型可能要把每张图切成上百上千个 patch 然后全部送入语言模型计算量非常大SmolVLM 则通过合并和裁剪语义相似区域的方式大幅度减少了视觉侧的计算开销。这也是它能在手机这类弱算力设备上流畅运行的根本原因。1.3 500M 档位手机端视觉模型的甜点位在三个型号里我最终选的是 500M 这个版本而不是 256M 或 2.2B原因很简单256M 虽然更小但视觉理解能力明显弱一截。实际测试中对复杂场景的描述经常出现“幻觉”比如明明没有猫它却自信地说画面上有一只猫。可能做 OCR、简单分类还凑合做开放域理解就力不从心了。2.2B 的能力确实更强但模型文件在 FP16 精度下接近 4.4GB部署到 iPhone 上对存储和内存压力都很大而且生成的推理速度会降到每秒几个 token体验非常差。500M 是个折中值FP16 精度下权重约 1GB量化到 INT4 后可以压到 300MB 以内在 A15 及以上芯片的 iPhone 上能做到每秒 20~40 个 token 的生成速度。这个速度虽然比不上云端但做交互式问答已经能接受。所以如果你的目标是“在 iPhone 上做一个离线可用的多模态 demo”500M 是当前最合理的起点。2. 几套技术方案对比我为什么会选 swift-transformers在确定模型之后接下来就是技术选型。标题里写了“Swift 代码”那跑模型的方式无非这么几条路Core ML 转换、llama.cpp 移植、HuggingFace 官方 Swift 库、自研推理引擎。我实际走了一遍之后结论很清楚。2.1 方案一原生 Core ML 转换第一反应可能是用 coremltools 把 PyTorch 模型转成 .mlpackage然后交给 Core ML 框架去跑这样能最大化利用 Apple 神经引擎ANE。这个思路对大模型不太友好。SmolVLM 不是单一大块网络它由视觉塔、投影层、文本塔、KV Cache 等多个子模块组成转换时要处理动态输入 shape、非标准 attention mask、缓存复用等一堆问题。我尝试转换过一次模型是可以导出但部署后速度和稳定性都不理想尤其是不同 iOS 系统版本对算子支持程度还不一样排错成本极高。Core ML 更适合卷积网络或者结构简单的模型对这类多模态 transformer 不是首选。2.2 方案二llama.cpp 移植llama.cpp 在 iOS 上确实有成熟的 Swift Package跑纯文本模型非常靠谱。多模态模型需要额外的视觉投影mmproj文件并且需要自己管理图像预处理、视觉 token 拼接和采样逻辑。实际体验下来llama.cpp 跑 SmolVLM 也不是不能通但过程绕。因为它本身是为推理效率和量化生态设计的API 更偏底层你得自己写图像编码结果与文本输入合并的逻辑。如果你是从零开始光是把 pipeline 跑通就需要研究好几天。2.3 方案三HuggingFace swift-transformersHuggingFace 官方维护了一个 Swift 库早期叫 swift-transformers现在的包名是 Transformers。它把模型加载、tokenizer、生成循环这些基础工作都封装好了甚至内置了 SmolVLM 的示例配置。这个方案最大的好处是“贴近原版模型”。你在 HuggingFace 拉下来的模型权重几乎不需要转换就能直接加载。模型内部做了 KV Cache 优化和自动内存管理对 iPhone 场景专门适配过。我最终就选了这一条路代码量最少也最快跑通。2.4 路线对比参考下面是我整理的一个对比表方便你判断自己的项目适合哪条路。方案集成难度推理性能可维护性适用场景Core ML 转换高中等但算子兼容问题多差系统升级可能挂模型结构简单、需要深度系统集成llama.cpp中高高量化生态成熟中需要关注上游更新熟悉 C/底层推理需要极致性能Swift Transformers低中上日常够用好跟随官方版本快速出原型注重开发效率3. 动手前的准备模型文件与工程骨架3.1 从模型仓库拉取文件先到 HuggingFace 上找到 SmolVLM 的官方仓库。注意有多个版本建议选带 Instruct 后缀的那个因为它是经过指令微调的对齐版本更适合直接做对话式问答。如果设备存储空间紧张优先找 INT4 量化版本如果你想保证效果上限可以先下 FP16 版本。对比下来我对 INT4 量化版和 FP16 版做了几组测试日常描述场景差异不大但如果任务涉及复杂推理FP16 的准确性会稍好一些。下载时注意文件结构关键要拿到这些内容config.json模型结构配置告诉库模型有多少层、多少维度tokenizer.json / tokenizer_config.json文本分词器模型权重文件通常是 .safetensors 格式针对 FP16 或者量化过的版本preprocessor_config.json图像预处理参数比如输入尺寸、均值方差3.2 创建 iOS 工程并引入依赖我用的 Xcode 15iOS 最低部署版本建议设成 17.0。原因有两个一是 swift-transformers 部分 API 依赖新版系统能力二是在 iOS 17 上神经引擎调度表现明显更稳定。创建好工程之后在 Xcode 菜单里选择 File - Add Package Dependencies填入 Swift Transformers 的仓库地址版本选最新稳定版。添加完成后在需要使用的 Swift 文件顶部写import Transformers编译一次确认没有报错这一步就算过了。如果你所在网络环境拉取依赖比较慢可以考虑先用命令行把代码克隆下来再本地引用方法不唯一。3.3 模型文件怎么组织到 App 里这里很容易踩坑我多说几句。模型文件不适合直接塞进 App Bundle。因为 Bundle 里的资源是只读的而且 Xcode 打包时会对资源做处理大文件会导致打包和安装时间变长。更合理的方案是首次启动时从网络下载到 Application Support 目录或者开发调试时直接把模型拖进模拟器/真机的 App 沙盒里。如果你只是本地测试我建议放在 App 沙盒 Documents 目录下路径类似这样...../Documents/smolvlm-500m-instruct-int4/ ...../Documents/smolvlm-500m-instruct-int4/tokenizer.json ...../Documents/smolvlm-500m-instruct-int4/model.safetensors代码里通过 URL 指向这个目录即可。如果是正式产品建议做成可随时更新的资源包放到 Application Support 目录并支持版本校验不要在启动流程里做同步下载之类容易卡界面的操作。4. Swift 实战让模型在手机上开口说话以下代码是在我实际项目里跑通的简化版本。不同版本的 Transformers 库 API 会略有变化但核心流程是一致的创建模型、加载图片、拼 prompt、逐 token 生成。4.1 初始化语言模型与视觉模型import Transformers import UIKit // 模型目录请根据你的实际沙盒路径修改 let modelDir URL.documentsDirectory .appendingPathComponent(smolvlm-500m-instruct-int4, isDirectory: true) let tokenizerPath modelDir .appendingPathComponent(tokenizer.json, isDirectory: false) // 创建语言模型 let modelConfig LanguageModel.Configuration( modelPath: modelDir, tokenizerPath: tokenizerPath, maxTokensPerSequence: 2048 ) let languageModel try await LanguageModel(config: modelConfig) // 创建视觉模型 let visionConfig VisionModel.Configuration( modelPath: modelDir, preprocessorPath: modelDir ) let visionModel try await VisionModel(config: visionConfig)注意这里LanguageModel和VisionModel是两套独立对象。调用时先让视觉模型把图片编码成视觉特征再把特征和文本输入一起丢给语言模型。4.2 传入图片与提示词SmolVLM 的消息格式和 OpenAI 的 Chat Completions 很接近。下面这段代码构造了一个“用户发图片 发文字问题”的输入let image UIImage(named: test_image)! let userMessage: [String: Any] [ role: user, content: [ [type: image, image: image], [type: text, text: 请用中文描述这张图片里的场景并尽量列出里面的物体。] ] ] let request TextInput.example(input: [userMessage])如果你的需求只是单轮图片问答这样写就够了。如果是多轮对话需要把历史消息也按相同格式拼进去并且第一轮放图片后续轮次直接放文本。4.3 逐 token 流式生成文本这一步体验很重要。如果等到全部生成完再显示在手机端可能要等 5 到 10 秒用户早就以为死机了。流式输出才能带来“正在思考”的反馈感。// 配置生成参数 let generationConfig TextGenerationConfiguration( maxNewTokens: 256, temperature: 0.6, topK: 40, topP: 0.9 ) var generatedText do { let stream try await languageModel.generate( config: generationConfig, input: request, visionModel: visionModel ) for try await token in stream { generatedText token // 这里刷新 UI比如 append 到 TextView DispatchQueue.main.async { self.outputTextView.text generatedText } } } catch { print(生成失败: \(error)) }temperature控制随机性在物体描述类任务里我建议调低到 0.6 左右减少胡编。maxNewTokens控制回答长度如果不限制页面字符太多手机 UI 也会卡。4.4 内存与生命周期注意点模型一旦加载就会常驻内存。500M 模型 INT4 量化后占用的内存大约 300 到 500MBFP16 则要 1GB 以上。如果你的 App 同时处理相册大图内存峰值很容易逼近系统警戒线。所以有两点我个人强烈建议尽量保持模型单例化不要在每次推理时重新加载一遍。生成完成后主动释放图像缓存必要时用autoreleasepool包住图像转 UIImage 的代码块把临时内存快速回收。一个简单的调用写法let output autoreleasepool { () - String in // 图像缩放、编码、推理 return generatedText }这样能把图片解码产生的临时内存及时归拢不会堆到后面。5. 实测下来的一些性能和调优经验代码跑通只是第一步真正进入“能用的状态”还差一轮性能调优。下面这些数字是我在多个机型上测试汇总出来的参考范围受系统版本、后台任务、散热状态影响很大不必当成精确基准。5.1 不同机型上的大致性能参考机型芯片生成速度INT4单图首token延迟iPhone 12A1412~18 tokens/s2.5s 左右iPhone 13A1518~28 tokens/s1.8s 左右iPhone 14 ProA1625~35 tokens/s1.4s 左右iPhone 15 ProA17 Pro30~45 tokens/s1.0s 左右iPad Pro M2M240~60 tokens/s0.8s 左右这个速度玩交互式问答是够用的。读一段 100 token 的图片描述iPhone 15 Pro 上大概 3 到 5 秒出完iPhone 12 可能要 6 到 8 秒。5.2 量化版本怎么选如果你追求极致的安装包体积和内存占用直接上 INT4。开发者模式下想调试效果建议先放 FP16因为转换/反量化的变量更少出问题容易排查。如果任务只涉及简短描述、看图找物体这种简单指令INT4 的退化不明显如果要做数学题、复杂推理、图表理解尽量用 FP16 或者至少 INT8。概括成一句话图片理解任务量化影响可控文本推理任务量化影响明显。5.3 影响速度的三个隐藏因素第一个是 CPU 占用。如果你在后台开着高消耗的动画或定位任务推理速度会明显下降。速度优先时最好把请求尽可能放到后台线程主线程保持空闲。第二个是系统内存压力。低内存状态下系统会频繁压缩 App 内存推理线程被调度到的概率就会降低速度直接掉一截。我碰到过一次连续推理多次后速度从 30 tokens/s 掉到 8 tokens/s重启 App 后才恢复。第三个是图片输入尺寸。虽然 SmolVLM 支持多分辨率输入但图片越复杂视觉编码阶段计算量就越大。很多场景下把长边缩到 512 或者 768 精度损失肉眼几乎看不出来速度却能提升 30% 以上。不要一上来就传原图。6. 常见问题与排查笔记这部分内容是实打实的踩坑记录建议收藏等真遇到了再回来看也行。6.1 模型加载失败 / 找不到文件最常见的原因是路径不对。尤其是用 Bundle 资源时文件名带不带扩展名、是不是被 Xcode 处理成了其他路径都会导致加载失败。调试技巧先打印出你最终传给模型的完整 URL然后去 App 沙盒里确认文件是否存在。如果模型是被 zip 解压出来的还要检查解压后是否多了一层同名目录。6.2 输出出现一堆奇怪 token这种情况通常是 tokenizer 与模型不匹配。SmolVLM 有几个不同版本如果你下载的是 base 版本却用了 Instruct 对应配置或者 tokenizer 文件混用了其他模型的就会出现乱码。处理办法很简单确保从同一个仓库下载全套文件尤其是 tokenizer.json 和 config.json不要跨模型混用。如果出现大量|endoftext|之类的 token说明最大长度设置不对或者模型没有正确加载特殊 token。6.3 内存暴涨或者直接闪退500M 模型单轮推理理论峰值内存通常还能接受但如果你在 SwiftUI 里把 UIImage 直接放在 State 里反复赋值图片解码数据会被复制多次内存直接翻几倍。我的建议是在往 UI 上放图片之前先把 UIImage 缩放到合理尺寸推理结束后立刻置空强引用模型对象保持全局单例不要每轮重建。如果仍然崩溃用 Instruments 里的 Allocations 工具看是哪一层分配过多大多数情况下都指向图像解码而不是模型本身。6.4 生成速度慢到没法用先检查是不是在模拟器上测试。模拟器没有神经引擎所有模型推理都走 CPU速度表现和真机完全不是一个量级。我在 M 系列芯片的 Mac 模拟器上跑时速度甚至不如两代前的 iPhone 真机。如果真机也慢检查是否走了 FP16 模型以及后台是不是有大量耗电任务。最后再考虑换更激进的量化版本或者把图片长边限制在 512 以下。6.5 模拟器和真机表现差异巨大模拟器可以用于功能调试但性能参考价值非常有限。尤其是图像推理这类涉及 ANE 的任务模拟器会绕过大部分硬件加速真正要验证流畅度一定要跑真机。这是我反复强调的一点项目排期如果有性能验证一定要把真机测试时间算进去。7. 接下来还可以怎么玩跑通基础的“图片问答”之后很多有意思的方向就打开了。第一个方向是多轮对话。目前示例代码只支持单轮询问你可以把历史消息缓存起来下一次请求时带上之前的图片和对话内容让模型基于上下文继续回答。这在分析设计稿、讲解截图文案、做学习助手时特别实用。第二个方向是接上相机。让模型对摄像头实时画面做描述可以用在前端无障碍辅助场景帮助视障用户理解周围环境。当然实时视频流要抽帧不能每一帧都送进去建议每秒抽 1 到 2 帧并且加一个防抖逻辑不然结果会非常跳跃。第三个方向是和系统能力结合。比如让模型从截图里提取地址后直接调起地图识别出快递单号后自动填充到备忘录。模型的输出不一定要停留在文本展示你完全可以用 Swift 解析它的结构把结果接进系统功能里。这比单纯做个聊天框有价值得多。我个人在实际操作中最深的一个体会是端侧小模型的优势不在于“什么都能干”而在于“随时可用、隐私可控、零延迟”。SmolVLM 在通用知识上的广度和深度当然比不过云端大模型但一旦它跑在你的 iPhone 上它就成了一个真正属于你自己的离线助手。如果你打算继续做下去我建议先从你生活或工作中最频繁的图片处理场景切入比如识别截图里的文字、整理相册里的内容、辅助阅读文档。跑通一个闭环之后再去折腾更复杂的模型和多模态交互你会明显感觉端侧应用的开发节奏和传统 App 完全不同。
Swift + SmolVLM 500M：iPhone 端侧离线多模态实战指南
前阵子在整理相册归类功能的时候我一直被一个问题卡着图片理解必须在服务端做。电梯里没信号、地铁上断网App 里的“智能识别”直接变成摆设。后来我把目光放到了端侧小模型上试了一圈之后SmolVLM 这个系列让我眼前一亮——尤其是它 500M5亿参数这个档位压缩后模型文件不到 300MB在 iPhone 上跑起来完全可行。这篇文章就是我从模型选型、Swift 工程集成、图像预处理到本地推理全过程的实战记录代码也会一并贴出来。如果你也想在 iPhone/iPad 上离线跑一个能“看图说话”的模型或者正在做端侧多模态功能的调研这篇文章应该能帮你少踩很多坑。1. SmolVLM 是个什么模型为什么适合 iPhone1.1 先搞懂 VLM 到底在做什么VLMVision Language Model翻译过来就是“视觉语言模型”它和普通纯文本语言模型的区别在于输入端除了文字还能接收图像。你给它一张照片加一句“描述一下这张图”它能返回一段通顺的自然语言描述你给它一个截图加一句“图里这个报错信息是什么”它也能尝试把错误码和上下文解释出来。从工程实现角度理解这类模型内部其实由三部分组成一个视觉编码器负责把图片转成特征向量一个文本解码器负责生成答案两者之间再用一个投影层把视觉特征和文本语义空间对齐。这个结构理解起来不复杂但它决定了模型能不能在手机上跑——因为视觉编码器往往比文本模型还大一旦设计不好整个模型体积直接爆掉。1.2 SmolVLM 的“小”靠的是架构设计而不是蛮力压缩SmolVLM 是 Hugging Face 开源的一个小尺寸 VLM 系列主打方向就是让视觉语言模型能在消费级设备上运行。它有几个型号256M、500M、2.2B。这个“M”和“B”指的就是参数量500M 就是 5 亿参数2.2B 是 22 亿参数。模型小不只是“参数少”这么简单。SmolVLM 用了专门优化视觉 token 数量的技巧把每张图输入给文本模型的部分压缩到很紧凑的程度。传统视觉模型可能要把每张图切成上百上千个 patch 然后全部送入语言模型计算量非常大SmolVLM 则通过合并和裁剪语义相似区域的方式大幅度减少了视觉侧的计算开销。这也是它能在手机这类弱算力设备上流畅运行的根本原因。1.3 500M 档位手机端视觉模型的甜点位在三个型号里我最终选的是 500M 这个版本而不是 256M 或 2.2B原因很简单256M 虽然更小但视觉理解能力明显弱一截。实际测试中对复杂场景的描述经常出现“幻觉”比如明明没有猫它却自信地说画面上有一只猫。可能做 OCR、简单分类还凑合做开放域理解就力不从心了。2.2B 的能力确实更强但模型文件在 FP16 精度下接近 4.4GB部署到 iPhone 上对存储和内存压力都很大而且生成的推理速度会降到每秒几个 token体验非常差。500M 是个折中值FP16 精度下权重约 1GB量化到 INT4 后可以压到 300MB 以内在 A15 及以上芯片的 iPhone 上能做到每秒 20~40 个 token 的生成速度。这个速度虽然比不上云端但做交互式问答已经能接受。所以如果你的目标是“在 iPhone 上做一个离线可用的多模态 demo”500M 是当前最合理的起点。2. 几套技术方案对比我为什么会选 swift-transformers在确定模型之后接下来就是技术选型。标题里写了“Swift 代码”那跑模型的方式无非这么几条路Core ML 转换、llama.cpp 移植、HuggingFace 官方 Swift 库、自研推理引擎。我实际走了一遍之后结论很清楚。2.1 方案一原生 Core ML 转换第一反应可能是用 coremltools 把 PyTorch 模型转成 .mlpackage然后交给 Core ML 框架去跑这样能最大化利用 Apple 神经引擎ANE。这个思路对大模型不太友好。SmolVLM 不是单一大块网络它由视觉塔、投影层、文本塔、KV Cache 等多个子模块组成转换时要处理动态输入 shape、非标准 attention mask、缓存复用等一堆问题。我尝试转换过一次模型是可以导出但部署后速度和稳定性都不理想尤其是不同 iOS 系统版本对算子支持程度还不一样排错成本极高。Core ML 更适合卷积网络或者结构简单的模型对这类多模态 transformer 不是首选。2.2 方案二llama.cpp 移植llama.cpp 在 iOS 上确实有成熟的 Swift Package跑纯文本模型非常靠谱。多模态模型需要额外的视觉投影mmproj文件并且需要自己管理图像预处理、视觉 token 拼接和采样逻辑。实际体验下来llama.cpp 跑 SmolVLM 也不是不能通但过程绕。因为它本身是为推理效率和量化生态设计的API 更偏底层你得自己写图像编码结果与文本输入合并的逻辑。如果你是从零开始光是把 pipeline 跑通就需要研究好几天。2.3 方案三HuggingFace swift-transformersHuggingFace 官方维护了一个 Swift 库早期叫 swift-transformers现在的包名是 Transformers。它把模型加载、tokenizer、生成循环这些基础工作都封装好了甚至内置了 SmolVLM 的示例配置。这个方案最大的好处是“贴近原版模型”。你在 HuggingFace 拉下来的模型权重几乎不需要转换就能直接加载。模型内部做了 KV Cache 优化和自动内存管理对 iPhone 场景专门适配过。我最终就选了这一条路代码量最少也最快跑通。2.4 路线对比参考下面是我整理的一个对比表方便你判断自己的项目适合哪条路。方案集成难度推理性能可维护性适用场景Core ML 转换高中等但算子兼容问题多差系统升级可能挂模型结构简单、需要深度系统集成llama.cpp中高高量化生态成熟中需要关注上游更新熟悉 C/底层推理需要极致性能Swift Transformers低中上日常够用好跟随官方版本快速出原型注重开发效率3. 动手前的准备模型文件与工程骨架3.1 从模型仓库拉取文件先到 HuggingFace 上找到 SmolVLM 的官方仓库。注意有多个版本建议选带 Instruct 后缀的那个因为它是经过指令微调的对齐版本更适合直接做对话式问答。如果设备存储空间紧张优先找 INT4 量化版本如果你想保证效果上限可以先下 FP16 版本。对比下来我对 INT4 量化版和 FP16 版做了几组测试日常描述场景差异不大但如果任务涉及复杂推理FP16 的准确性会稍好一些。下载时注意文件结构关键要拿到这些内容config.json模型结构配置告诉库模型有多少层、多少维度tokenizer.json / tokenizer_config.json文本分词器模型权重文件通常是 .safetensors 格式针对 FP16 或者量化过的版本preprocessor_config.json图像预处理参数比如输入尺寸、均值方差3.2 创建 iOS 工程并引入依赖我用的 Xcode 15iOS 最低部署版本建议设成 17.0。原因有两个一是 swift-transformers 部分 API 依赖新版系统能力二是在 iOS 17 上神经引擎调度表现明显更稳定。创建好工程之后在 Xcode 菜单里选择 File - Add Package Dependencies填入 Swift Transformers 的仓库地址版本选最新稳定版。添加完成后在需要使用的 Swift 文件顶部写import Transformers编译一次确认没有报错这一步就算过了。如果你所在网络环境拉取依赖比较慢可以考虑先用命令行把代码克隆下来再本地引用方法不唯一。3.3 模型文件怎么组织到 App 里这里很容易踩坑我多说几句。模型文件不适合直接塞进 App Bundle。因为 Bundle 里的资源是只读的而且 Xcode 打包时会对资源做处理大文件会导致打包和安装时间变长。更合理的方案是首次启动时从网络下载到 Application Support 目录或者开发调试时直接把模型拖进模拟器/真机的 App 沙盒里。如果你只是本地测试我建议放在 App 沙盒 Documents 目录下路径类似这样...../Documents/smolvlm-500m-instruct-int4/ ...../Documents/smolvlm-500m-instruct-int4/tokenizer.json ...../Documents/smolvlm-500m-instruct-int4/model.safetensors代码里通过 URL 指向这个目录即可。如果是正式产品建议做成可随时更新的资源包放到 Application Support 目录并支持版本校验不要在启动流程里做同步下载之类容易卡界面的操作。4. Swift 实战让模型在手机上开口说话以下代码是在我实际项目里跑通的简化版本。不同版本的 Transformers 库 API 会略有变化但核心流程是一致的创建模型、加载图片、拼 prompt、逐 token 生成。4.1 初始化语言模型与视觉模型import Transformers import UIKit // 模型目录请根据你的实际沙盒路径修改 let modelDir URL.documentsDirectory .appendingPathComponent(smolvlm-500m-instruct-int4, isDirectory: true) let tokenizerPath modelDir .appendingPathComponent(tokenizer.json, isDirectory: false) // 创建语言模型 let modelConfig LanguageModel.Configuration( modelPath: modelDir, tokenizerPath: tokenizerPath, maxTokensPerSequence: 2048 ) let languageModel try await LanguageModel(config: modelConfig) // 创建视觉模型 let visionConfig VisionModel.Configuration( modelPath: modelDir, preprocessorPath: modelDir ) let visionModel try await VisionModel(config: visionConfig)注意这里LanguageModel和VisionModel是两套独立对象。调用时先让视觉模型把图片编码成视觉特征再把特征和文本输入一起丢给语言模型。4.2 传入图片与提示词SmolVLM 的消息格式和 OpenAI 的 Chat Completions 很接近。下面这段代码构造了一个“用户发图片 发文字问题”的输入let image UIImage(named: test_image)! let userMessage: [String: Any] [ role: user, content: [ [type: image, image: image], [type: text, text: 请用中文描述这张图片里的场景并尽量列出里面的物体。] ] ] let request TextInput.example(input: [userMessage])如果你的需求只是单轮图片问答这样写就够了。如果是多轮对话需要把历史消息也按相同格式拼进去并且第一轮放图片后续轮次直接放文本。4.3 逐 token 流式生成文本这一步体验很重要。如果等到全部生成完再显示在手机端可能要等 5 到 10 秒用户早就以为死机了。流式输出才能带来“正在思考”的反馈感。// 配置生成参数 let generationConfig TextGenerationConfiguration( maxNewTokens: 256, temperature: 0.6, topK: 40, topP: 0.9 ) var generatedText do { let stream try await languageModel.generate( config: generationConfig, input: request, visionModel: visionModel ) for try await token in stream { generatedText token // 这里刷新 UI比如 append 到 TextView DispatchQueue.main.async { self.outputTextView.text generatedText } } } catch { print(生成失败: \(error)) }temperature控制随机性在物体描述类任务里我建议调低到 0.6 左右减少胡编。maxNewTokens控制回答长度如果不限制页面字符太多手机 UI 也会卡。4.4 内存与生命周期注意点模型一旦加载就会常驻内存。500M 模型 INT4 量化后占用的内存大约 300 到 500MBFP16 则要 1GB 以上。如果你的 App 同时处理相册大图内存峰值很容易逼近系统警戒线。所以有两点我个人强烈建议尽量保持模型单例化不要在每次推理时重新加载一遍。生成完成后主动释放图像缓存必要时用autoreleasepool包住图像转 UIImage 的代码块把临时内存快速回收。一个简单的调用写法let output autoreleasepool { () - String in // 图像缩放、编码、推理 return generatedText }这样能把图片解码产生的临时内存及时归拢不会堆到后面。5. 实测下来的一些性能和调优经验代码跑通只是第一步真正进入“能用的状态”还差一轮性能调优。下面这些数字是我在多个机型上测试汇总出来的参考范围受系统版本、后台任务、散热状态影响很大不必当成精确基准。5.1 不同机型上的大致性能参考机型芯片生成速度INT4单图首token延迟iPhone 12A1412~18 tokens/s2.5s 左右iPhone 13A1518~28 tokens/s1.8s 左右iPhone 14 ProA1625~35 tokens/s1.4s 左右iPhone 15 ProA17 Pro30~45 tokens/s1.0s 左右iPad Pro M2M240~60 tokens/s0.8s 左右这个速度玩交互式问答是够用的。读一段 100 token 的图片描述iPhone 15 Pro 上大概 3 到 5 秒出完iPhone 12 可能要 6 到 8 秒。5.2 量化版本怎么选如果你追求极致的安装包体积和内存占用直接上 INT4。开发者模式下想调试效果建议先放 FP16因为转换/反量化的变量更少出问题容易排查。如果任务只涉及简短描述、看图找物体这种简单指令INT4 的退化不明显如果要做数学题、复杂推理、图表理解尽量用 FP16 或者至少 INT8。概括成一句话图片理解任务量化影响可控文本推理任务量化影响明显。5.3 影响速度的三个隐藏因素第一个是 CPU 占用。如果你在后台开着高消耗的动画或定位任务推理速度会明显下降。速度优先时最好把请求尽可能放到后台线程主线程保持空闲。第二个是系统内存压力。低内存状态下系统会频繁压缩 App 内存推理线程被调度到的概率就会降低速度直接掉一截。我碰到过一次连续推理多次后速度从 30 tokens/s 掉到 8 tokens/s重启 App 后才恢复。第三个是图片输入尺寸。虽然 SmolVLM 支持多分辨率输入但图片越复杂视觉编码阶段计算量就越大。很多场景下把长边缩到 512 或者 768 精度损失肉眼几乎看不出来速度却能提升 30% 以上。不要一上来就传原图。6. 常见问题与排查笔记这部分内容是实打实的踩坑记录建议收藏等真遇到了再回来看也行。6.1 模型加载失败 / 找不到文件最常见的原因是路径不对。尤其是用 Bundle 资源时文件名带不带扩展名、是不是被 Xcode 处理成了其他路径都会导致加载失败。调试技巧先打印出你最终传给模型的完整 URL然后去 App 沙盒里确认文件是否存在。如果模型是被 zip 解压出来的还要检查解压后是否多了一层同名目录。6.2 输出出现一堆奇怪 token这种情况通常是 tokenizer 与模型不匹配。SmolVLM 有几个不同版本如果你下载的是 base 版本却用了 Instruct 对应配置或者 tokenizer 文件混用了其他模型的就会出现乱码。处理办法很简单确保从同一个仓库下载全套文件尤其是 tokenizer.json 和 config.json不要跨模型混用。如果出现大量|endoftext|之类的 token说明最大长度设置不对或者模型没有正确加载特殊 token。6.3 内存暴涨或者直接闪退500M 模型单轮推理理论峰值内存通常还能接受但如果你在 SwiftUI 里把 UIImage 直接放在 State 里反复赋值图片解码数据会被复制多次内存直接翻几倍。我的建议是在往 UI 上放图片之前先把 UIImage 缩放到合理尺寸推理结束后立刻置空强引用模型对象保持全局单例不要每轮重建。如果仍然崩溃用 Instruments 里的 Allocations 工具看是哪一层分配过多大多数情况下都指向图像解码而不是模型本身。6.4 生成速度慢到没法用先检查是不是在模拟器上测试。模拟器没有神经引擎所有模型推理都走 CPU速度表现和真机完全不是一个量级。我在 M 系列芯片的 Mac 模拟器上跑时速度甚至不如两代前的 iPhone 真机。如果真机也慢检查是否走了 FP16 模型以及后台是不是有大量耗电任务。最后再考虑换更激进的量化版本或者把图片长边限制在 512 以下。6.5 模拟器和真机表现差异巨大模拟器可以用于功能调试但性能参考价值非常有限。尤其是图像推理这类涉及 ANE 的任务模拟器会绕过大部分硬件加速真正要验证流畅度一定要跑真机。这是我反复强调的一点项目排期如果有性能验证一定要把真机测试时间算进去。7. 接下来还可以怎么玩跑通基础的“图片问答”之后很多有意思的方向就打开了。第一个方向是多轮对话。目前示例代码只支持单轮询问你可以把历史消息缓存起来下一次请求时带上之前的图片和对话内容让模型基于上下文继续回答。这在分析设计稿、讲解截图文案、做学习助手时特别实用。第二个方向是接上相机。让模型对摄像头实时画面做描述可以用在前端无障碍辅助场景帮助视障用户理解周围环境。当然实时视频流要抽帧不能每一帧都送进去建议每秒抽 1 到 2 帧并且加一个防抖逻辑不然结果会非常跳跃。第三个方向是和系统能力结合。比如让模型从截图里提取地址后直接调起地图识别出快递单号后自动填充到备忘录。模型的输出不一定要停留在文本展示你完全可以用 Swift 解析它的结构把结果接进系统功能里。这比单纯做个聊天框有价值得多。我个人在实际操作中最深的一个体会是端侧小模型的优势不在于“什么都能干”而在于“随时可用、隐私可控、零延迟”。SmolVLM 在通用知识上的广度和深度当然比不过云端大模型但一旦它跑在你的 iPhone 上它就成了一个真正属于你自己的离线助手。如果你打算继续做下去我建议先从你生活或工作中最频繁的图片处理场景切入比如识别截图里的文字、整理相册里的内容、辅助阅读文档。跑通一个闭环之后再去折腾更复杂的模型和多模态交互你会明显感觉端侧应用的开发节奏和传统 App 完全不同。
