LiteRT-LM Swift API 实战在 iOS 与 macOS 应用中集成端侧大模型【免费下载链接】LiteRT-LMLiteRT-LM is Googles production-ready, high-performance, open-source inference framework for deploying Large Language Models on edge devices.项目地址: https://gitcode.com/GitHub_Trending/li/LiteRT-LM本文以仓库 samples/ios_and_mac/README.md 为骨架讲解如何使用 LiteRT-LM 的 Swift API通过 Swift Package ManagerSPM把.litertlm格式的端侧大模型如 Gemma 4 E2B原生集成进 iOS 15 与 macOS 12 应用覆盖依赖接入、模型打包、引擎初始化、对话创建与流式输出等完整链路并结合仓库内 Swift 封装层与 C 底层接口的源码说明每个 API 背后的实际调用与配置含义读完即可在 Xcode 中跑通一个 SwiftUI 聊天 Demo。前置条件官方示例目录要求的最低环境如下与仓库根目录 Package.swift 中声明的平台版本一致条件要求iOS15.0 或更高macOS12.0 或更高Xcode15.0 或更高模型文件一个.litertlm格式的模型文件例如 Gemma 系列.litertlm是 LiteRT-LM 的端侧模型封装格式包含模型权重、分词器与元数据。仓库中models/目录下有 gemma4、qwen3 等多个模型族的元数据与 chat template 示例runtime/testdata/下则有大量.litertlm测试模型可用于理解该格式的构成。第 1 步通过 SPM 添加 LiteRTLM 依赖在 Xcode 中按如下步骤把 LiteRTLM 的 Swift 包加入工程选择FileAdd Package Dependencies...在右上角搜索栏输入 LiteRT-LM 的 GitHub 仓库地址google-ai-edge/LiteRT-LM并回车从列表中选中该包点击Add Package勾选要添加依赖的目标 App点击Finish。仓库根目录的 Package.swift 就是 SPM 清单从中可以看到包的完整结构包名LiteRTLMswift-tools-version: 5.9同时支持.iOS(.v15)与.macOS(.v12)两个平台通过.binaryTarget分别声明了 iOSCLiteRTLM与 macOSCLiteRTLM_mac两个预编译的CLiteRTLM.xcframework二进制目标并带有校验和checksum用于完整性验证LiteRTLM目标封装 Swift 层源码位于 swift/ 目录Engine.swift、Conversation.swift、Config.swift、Message.swift等按平台条件依赖对应的 C 预编译库另有LiteRTLMFoundationModels库适配 Apple Foundation Models位于 swift/apple_fm/以及分布在 swift 目录下的多个独立测试 targetEngineTests、ConversationTests、MessageTests等。[!NOTE] 若添加包后出现no such module LiteRTLM报错说明 App target 还没有链接该库按以下步骤手动补上在项目导航器中点击你的工程选中你的 App target进入General标签页滚动到Frameworks, Libraries, and Embedded Content点击按钮选择LiteRTLM Package-LiteRTLM点击Add。第 2 步把模型文件加入 App Bundle获取一个兼容的.litertlm模型文件例如 Gemma 4 E2B可在模型社区搜索litert-community/gemma-4-E2B-it-litert-lm把模型文件拖入 Xcode 的项目导航器在弹出的对话框中确保勾选了你的 App target使其被复制进 App Bundle备选方案如果运行时找不到模型文件可到工程的Build PhasesCopy Bundle Resources中手动添加该文件。模型文件的文件名不含扩展名会在代码中作为Bundle.main.path(forResource:ofType:)的forResource参数使用。仓库示例 ContentView.swift 中使用的资源名是gemma-4-E2B-it、类型是litertlm实际使用时请替换为你自己模型的资源名。第 3 步编写 SwiftUI 聊天页面仓库的 samples/ios_and_mac/ContentView.swift 给出了一个可直接运行的 SwiftUI 聊天 Demo核心流程分为五步找模型 → 构造配置 → 初始化引擎 → 创建会话 → 流式发送消息。3.1 从 App Bundle 定位模型文件guard let modelPath Bundle.main.path( forResource: gemma-4-E2B-it, ofType: litertlm) else { statusMessage Model file not found in app bundle! return }forResource/ofType对应第 2 步添加到 Bundle 的模型文件名与扩展名。找不到文件时优先检查是否已通过Copy Bundle Resources正确打包。3.2 构造EngineConfig并初始化Enginelet fileManager FileManager.default guard let cacheDirectory fileManager.urls(for: .cachesDirectory, in: .userDomainMask).first else { fatalError(Could not find caches directory) } let config try EngineConfig( modelPath: modelPath, backend: .gpu, cacheDir: cacheDirectory.path) // let config try EngineConfig( // modelPath: modelPath, backend: .cpu(), cacheDir: cacheDirectory.path) let newEngine Engine(engineConfig: config) try await newEngine.initialize()这里有两个值得注意的实践点backend.gpu走 Metal 加速iOS/macOS 上的 GPU 后端.cpu()为 CPU 后端可通过Backend.cpu(threadCount:)指定线程数。两种后端的定义见 swift/Config.swift。cacheDir必须指向应用可写的目录如 Caches用于放置模型加载产生的缓存文件。若不传默认使用模型文件所在目录。Engine是一个actor见 swift/Engine.swiftinitialize()内部最终调用 C 层litert_lm_engine_settings_create(...)创建设置、litert_lm_engine_create(settings)创建原生引擎句柄。源码注释特别提醒初始化可能耗时较长视模型大小和硬件可达秒级不要在主线线程执行SwiftUI 的.task {}修饰符天然在后台执行正适合此场景。3.3 创建Conversation会话self.engine newEngine self.conversation try await newEngine.createConversation()createConversation()swift/Engine.swift内部做了这些事校验引擎已初始化否则抛LiteRTLMError.engine(.notInitialized)校验系统消息数量ConversationConfig中systemMessage与initialMessages里的 system 角色消息不能同时存在、且 system 消息不能多于一条否则抛LiteRTLMError.config(.multipleSystemMessages)把 sampler 参数topK/topP/temperature/seed、LoRA 路径、thinking 配置、工具描述等序列化后通过 C 接口写入会话配置最终调用litert_lm_conversation_create(engineHandle, cConversationConfig)创建原生会话。3.4 流式发送消息并实时渲染responseText for try await chunk in conversation.sendMessageStream(Message(prompt)) { if let firstContent chunk.contents.first { switch firstContent { case .text(let text): responseText text // Append the chunk live! default: break } } }sendMessageStream(_:)swift/Conversation.swift返回AsyncThrowingStreamMessage, Error每个 chunk 是一个Message其contents中.text类型的Content即增量文本。底层原理是Swift 层通过 C 回调函数streamCallbackswift/Conversation.swift接收原生流式分片把tool_calls缓存、把包含content或channels的 JSON 分片解析成Message后yield给AsyncThrowingStream最终在isFinal时结束流或继续执行工具调用循环。与之对应的还有同步接口sendMessage(_:)swift/Conversation.swift一次性返回完整回复sendMessage还内置了自动工具调用automaticToolCalling与重复工具调用上限recurringToolCallLimit 25的保护逻辑。运行 App在 iOS 真机上运行用数据线把 iPhone 连接到 Mac在 Xcode 窗口顶部中央的运行目标菜单中选择你的 iPhone 名称点击Run按钮或按Cmd R构建并安装到设备上运行。在 macOS 上运行在 Xcode 运行目标菜单中选择My Mac点击Run按钮或按Cmd R。常见问题排查[!IMPORTANT] 如果在 Mac 上使用本地构建的、未签名的库macOS 可能会弹出 “Malware”恶意软件警告阻止加载。仅用于本地测试时可在 Mac 终端执行以下命令解除隔离属性xattr -rd com.apple.quarantine path/to/CLiteRTLM.xcframework其中path/to/CLiteRTLM.xcframework替换为实际的 xcframework 路径。[!TIP] 如果真机的 iOS 版本低于 Xcode 中设置的部署目标Deployment Target可以到 target 的General标签页在Minimum Deployments或Deployment Info中把最低 iOS 版本调低到与设备版本一致即可继续运行。深入Swift API 与底层 C 接口的映射LiteRT-LM Swift 层是一层薄封装核心价值在于把 C 层的句柄式 API 转换为类型安全、并发友好的 Swift 接口。梳理 swift 目录可得如下对应关系Swift 层底层 C 接口说明EngineConfiglitert_lm_engine_settings_create/..._set_max_num_tokens/..._set_cache_dir/..._set_lora_rank等引擎级配置Engine.initialize()litert_lm_engine_create(settings)创建原生引擎持有OpaquePointer句柄Engine.createConversation()litert_lm_conversation_create(engineHandle, config)创建会话同时建立ToolManager与工具注册表Conversation.sendMessagelitert_lm_conversation_send_message同步推理返回完整 JSON 响应Conversation.sendMessageStreamlitert_lm_conversation_send_message_stream C 回调流式推理回调桥接AsyncThrowingStreamConversation.cancel()litert_lm_conversation_cancel_process取消进行中的推理Engine.deinitlitert_lm_engine_delete(handle)句柄释放防内存泄漏配置参数在底层的行为可以通过 swift/Engine.swift 中initializeInternal的实现确认maxNumTokens会映射为litert_lm_engine_settings_set_max_num_tokens等价于 KV Cache 的规模loraRank同时写入 rank 与supported_lora_ranksbenchmark 与 speculative decoding投机解码等实验能力通过ExperimentalFlags见 swift/ExperimentalFlags.swift按需开启。进阶EngineConfig 与 ConversationConfig 参数详解EngineConfigswift/Config.swift参数默认值含义与约束modelPath必填.litertlm模型文件路径backend.cpu()CPU 或 GPU 后端.cpu(threadCount:)可指定线程数visionBackendnil视觉执行器后端为nil时不初始化视觉能力多模态模型需要时设置audioBackendnil音频执行器后端为nil时不初始化音频能力maxNumTokensnil输入输出 token 总数上限等价于 KV Cache 大小nil时用模型/引擎默认值且必须 0否则构造抛错cacheDirnil缓存文件目录必须应用可写nil时使用模型文件所在目录loraRanknil文本 LoRA 权重 rank0 或nil表示禁用 LoRAaudioLoraRanknil音频 LoRA 权重 rank0 或nil表示禁用ConversationConfigswift/Config.swiftsystemMessage/initialMessages预设系统提示与初始对话历史system 消息只能有一条tools注册给模型调用的工具列表配合Tool/ToolManagerswift/Tool.swift、swift/ToolManager.swift使用automaticToolCalling默认为true模型发起工具调用后 SDK 会自动执行并把结果回传给模型samplerConfig采样参数见SamplerConfig包含topK0、topP∈[0,1]、temperature≥0与seed默认 0非法值会在构造时抛LiteRTLMError.configloraPath/audioLoraPath按会话加载 LoRA 权重文件thinkingConfig思维链/推理生成开关与 token 预算ThinkingConfigthinkingTokenBudget默认 -1 表示无限预算enableResponseFormat是否启用约束解码constrained decoding配合 swift/ResponseFormat.swift 使用底层走 llguidance 约束提供器默认falseenableToolCallStreaming、visualTokenBudget、enableSpeculativeDecoding分别控制工具调用流式化、视觉 token 预算与投机解码nil时继承引擎设置。生成期可选参数sendMessage/sendMessageStream还支持按次传入extraContext附加上下文、RepetitionPenaltyConfig重复惩罚支持 repetition/presence/frequency penalty 与窗口大小、NoRepeatNgramConfign-gram 禁止重复、SuppressTokensConfig按 token ID 屏蔽、maxOutputTokens输出上限对 thinking 模型思维 token 与最终回答共同计入该上限以及ResponseFormat。这些参数在 swift/Conversation.swift 中逐一映射为 C 层litert_lm_conversation_optional_args_*系列接口。Message与Content类型swift/Message.swift 定义了多模态消息模型Content支持.text、.imageData、.imageFile、.audioData、.audioFile与.toolResponse六种形态Message由ContentsRandomAccessCollection可容纳多个 Content、rolesystem/user/model/tool与可选的channels、toolCalls组成。也就是说同一个聊天框架天然支持图文混排与音频输入构造示例let textContent Content.text(这张图片里有什么) let imageContent Content.imageData(imageData) let message Message(of: textContent, imageContent)完整可运行 Demo 一览把上述步骤组装起来就是一个功能完整的 SwiftUI 流式聊天页面samples/ios_and_mac/ContentView.swift。其状态管理State持有engine/conversation、按钮禁用逻辑引擎就绪前Generate Response置灰与错误兜底初始化失败/推理失败均写回statusMessage均可直接复用。想进一步验证 Swift API 行为可参考仓库内对应的测试EngineTests.swift、ConversationTests.swift、MessageTests.swift它们展示了各 API 的典型调用方式与错误分支。小结集成路径总结为四步SPM 加包 → Bundle 放模型 → 初始化Engine→ 创建Conversation流式对话。其中no such module LiteRTLM、macOS 隔离警告、部署目标不匹配这三个高频问题按上文指引即可快速解决。若需要更细的配置能力LoRA、约束解码、工具调用、多模态输入、benchmark 等Swift 层全部以类型安全的方式暴露且每个参数都能在仓库 swift 目录的源码注释中找到默认值与取值范围是排查行为差异的第一手资料。【免费下载链接】LiteRT-LMLiteRT-LM is Googles production-ready, high-performance, open-source inference framework for deploying Large Language Models on edge devices.项目地址: https://gitcode.com/GitHub_Trending/li/LiteRT-LM创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考