RunAnywhere Swift SDK 开发指南：XCFramework 桥接架构、两阶段初始化与后端注册模式

AI模型推理服务推理引擎本地部署多模态【免费下载链接】runanywhere-sdksProduction ready toolkit to run AI locally项目地址https://gitcode.com/gh_mirrors/ru/runanywhere-sdks点击查看免费下载RunAnywhere Swift SDK位于仓库 bindings/swift是面向 iOS 17.5 / macOS 14.5 的原生 AI 工具包将大语言模型、语音识别、语音合成、视觉语言模型等能力以 Swift API 形式暴露给 Apple 平台应用。本指南以 bindings/swift/AGENTS.md 为核心骨架深入讲解其C 内核 Swift 薄桥接的三层架构、两阶段初始化契约、后端模块注册机制与工程约束帮助你理解 SDK 的内部实现并在其上完成二次开发、调试与打包。阅读指引与文档体系在深入本文件之前建议先阅读仓库根目录的 AGENTS.md 以了解跨 SDK 的统一架构与分层规则。Swift 特有的更深入资料分散在三个文件中本文不再重复展开文档路径定位架构权威文档bindings/swift/ARCHITECTURE.md逐文件、带行号引用的详尽走查是本文任何细节的最终事实来源开发指南bindings/swift/docs/DEVELOPMENT.md首次环境搭建、完整命令参考、PR 流程消费方 READMEbindings/swift/README.md面向最终用户的安装/使用、能力表、Connect局域网会话共享功能构建命令一次完整的心跳体检Swift SDK 的开发构建围绕环境变量RUNANYWHERE_USE_LOCAL_NATIVES展开——它告诉 SwiftPM 使用本地暂存的 XCFramework 而非从远程下载。核心命令如下RUNANYWHERE_USE_LOCAL_NATIVES1 swift build # 构建需要 Binaries/见下文 RUNANYWHERE_USE_LOCAL_NATIVES1 swift test # 运行测试 swiftlint # 静态检查swiftlint --fix 自动修复 periphery scan # 未使用代码检测 ./scripts/package-sdk.sh --mode local # 基于 Binaries/ 的打包校验 xcodebuild build -scheme RunAnywhere -destination platformiOS Simulator,nameiPhone 16 Pro CODE_SIGNING_REQUIREDNOBinaries/ 前置条件Binaries/目录存放的是被 git 忽略的 XCFramework必须先通过./scripts/build-core-xcframework.sh生成否则swift build会直接失败。首次运行的完整序列见 bindings/swift/docs/DEVELOPMENT.md。该脚本会产出 SDK 及其后端所需的全部 Apple 切片包括RACommons.xcframework、RABackendLLAMACPP.xcframework、RABackendONNX.xcframework、RABackendSherpa.xcframework、RABackendNeuRT.xcframework、RABackendMLX.xcframework等同时还会把共享框架同步到 React Native 与 Flutter SDK 的插件目录。lint 的两个层级swiftlint analyze需要编译器日志--compiler-log-path xcodebuild.log。pre-commit 钩子运行的是swiftlint --strict这意味着警告级别的规则也会阻塞提交——例如自定义的TODO 必须引用 issue规则。开发时需注意区分普通swiftlint只报错误--strict连警告一起拦截。双 Package.swift 与包结构仓库中存在两份Package.swift职责截然不同清单用途仓库根 Package.swift面向外部 SPM 消费者从 GitHub Releases 下载 XCFrameworkbindings/swift/Package.swift面向 SDK 开发引用被 git 忽略的本地Binaries/远程产物是失败即关闭fail-closed的默认路径本地开发通过RUNANYWHERE_USE_LOCAL_NATIVES1显式选择脚本会显式设置该变量而绝不重写清单文件。从 bindings/swift/Package.swift 可以看到Swift tools 版本为 6.2平台底线为 iOS 17.5 / macOS 14.5。值得强调的是Xcode 26 是硬性下限——MLX 目标需要 6.2 工具链即使swift-tools-version声明为 5.9。产品Products矩阵产品目标能力RunAnywhereRunAnywhere仅核心模型生命周期、事件不注册任何后端时没有任何推理能力RunAnywhereLlamaCPPLlamaCPPRuntime经 llama.cpp 的 LLM VLMGGUFRunAnywhereONNXONNXRuntime经 ONNX Sherpa 的 STT/TTS/VADRunAnywhereMLXMLXRuntimeApple MLX 的 LLM/VLM/STT/TTSRunAnywhereNeuRTNeuRTRuntimeApple Neural Engine 文本生成 CoreML 扩散产品被设计为独立的静态库消费者按需链接让链接器可以丢弃未使用的后端代码。此外Generated/目录下存在三个.grpc.swift文件被排除在编译之外——它们需要 iOS 18/macOS 15高于 SDK 的平台底线取而代之的是进程内 C 回调路径由手写的LLMStreamAdapter/VoiceAgentStreamAdapter暴露同样的AsyncStream表面。从 bindings/swift/Package.swift 的注释还可以看到router.pb.swift被排除零消费方的死代码约 2154 行而diffusion_options.pb.swift被保留编译CoreML 稳定扩散门面需要它。三层架构设计业务逻辑全在 CSDK 的架构核心是一条铁律所有业务逻辑都住在 C 的RACommons.xcframework中Swift 只负责平台适配。调用链为公共 APIRunAnywhere 枚举 扩展 │ ▼ CppBridgeSwift 桥接命名空间 │ ▼ rac_* C ABI由 CRACommons 模块声明 │ ▼ RACommons.xcframeworkC 实现Swift 从不实现公共 API 调用CppBridgeCppBridge调用来自CRACommons模块的rac_*C ABI——这些 ABI 由预编译的 xcframework 实现绝不由 Swift 实现。这一分层保证了所有 SDKKotlin、Flutter、React Native、Web共享同一套 C 内核与行为。入口点与两阶段初始化enum RunAnywhere不可实例化的命名空间入口点是 Sources/RunAnywhere/Public/RunAnywhere.swift 中的public enum RunAnywhere第 59 行——一个无 case 的枚举充当不可实例化的命名空间所有 API 都是static方法或其扩展。全部内部状态initParams、currentEnvironment、isInitialized、hasCompletedServicesInit、servicesInitTask、lifetime等存放在私有SDKState结构体中由一个OSAllocatedUnfairLockSDKState第 78 行保护Phase 1 的并发初始化则由串行coreInitQueuecom.runanywhere.sdk.coreInit第 82 行线性化。公共表面遵循跨 SDK 的 v3 契约在 Public/API 下提供14 个命名空间llm、vlm、stt、tts、vad、embeddings、rerank、images、diarization、segmentation、voice、rag、models、lora外加核心成员initialize、reset、isReady、version、deviceId、events。各选项的默认值一律从 IDL 生成的defaults()读取从不手写拷贝——这样 idl/*.proto 始终是单一事实来源。Public/Extensions 则承载旧式的扁平动词loadModel、transcribe、ragQuery……作为available(*, deprecated)的前向转发器保留兼容新代码应使用命名空间。voice.createSession(...)与rag.open(...)会交还持有本地句柄的长生命周期会话对象VoiceSession、RagSession。Phase 1同步核心初始化约 1–5msPhase 1 在调用线程上同步完成具体步骤为幂等守卫isInitializedFlag已为 true 则直接返回写入环境与参数调用Logging.shared.applyEnvironmentConfiguration使后续日志携带正确的详细级别初始化 C 桥接CppBridge.initialize(environment:)——注册平台适配器文件 I/O、日志、Keychain、时钟、内存查询、遥测回调与设备回调必须先于任何 C ABI 调用发出 init-started 事件将凭据持久化到 Keychain.development环境跳过设置模型路径基目录CppBridge.ModelPaths.setBaseDirectory(documentsURL)调用CppBridge.SdkInit.phase1→rac_sdk_init_phase1_proto校验输入并运行rac_state_initialize安装 SDK 配置 / Keychain 认证存储置isInitializedFlag true发出 init-completed 事件含耗时派生 Phase 2 后台任务Task.detached(priority: .userInitiated)。任何一步失败都会清空initParams、保持isInitialized false、发出emitSDKInitFailed并重抛错误。从源码 RunAnywhere.swift 顶部注释可确认两阶段初始化由 commons 的rac_sdk_init.h拥有Swift 只保留无法移入 C 的部分——Task.detached派生、Swift 侧初始化状态、Keychain 参数持久化、主 actor 平台插件/回调注册、URLSession HTTP 传输实现与适配器配置。Phase 2异步服务初始化后台 TaskPhase 2 运行在由_servicesInitLock串行化的单一共享Task中并发调用者拿到的都是同一个 Task 并await其结果不会产生重复初始化。步骤HTTP 传输 认证.development环境尝试CppBridge.DevConfig.configureHTTP()从 C 配置读取 Supabasestaging/production 调用HTTP.shared.configure(baseURL:apiKey:)后执行Auth.authenticate(apiKey:)。失败可容忍——SDK 进入离线模式继续平台插件注册MainActor.run { CppBridge.initializeServices() }——Apple 平台插件要求主 actorC Phase 2CppBridge.SdkInit.phase2→rac_sdk_init_phase2_proto驱动设备注册、模型分配与 HTTP 状态快照开发模式设备注册仅.development且有可用配置时模型发现ModelRegistry.shared.discoverDownloadedModels()扫描文件系统置hasCompletedServicesInit true。每个公共 API 调用都会经过ensureServicesReady()——Phase 2 完成后它是 O(1) 的若 Phase 2 中 HTTP 曾失败则通过retryHTTPSetup()重试。CppBridgeSwift↔C 的全部接触面CppBridge.swift第 122 行的public enum CppBridge是一个单一命名空间其共享状态被OSAllocatedUnfairLockCppBridgeSharedState第 137 行守护。子命名空间以扩展形式分布在 Foundation/Bridge/Extensions 的 34 个CppBridge*.swift文件中覆盖 PlatformAdapter、Environment、DevConfig、Endpoints、Telemetry、Events、Device、State、HTTP、Auth、Services、ModelPaths、ModelRegistry、Download、Platform、LLM、STT、TTS、VAD、VoiceAgent、Storage、Strategy、FileManager、LoraRegistry、VLM 等。能力子命名空间actor 句柄模式大多数能力子命名空间是 Swiftactor每个封装一个不透明的rac_handle_t配以惰性getHandle()与destroy()LLM、STT、TTS、VAD、VLM、VoiceAgent、RAG、Diffusion、Rerank、Diarization、Storage、LoraRegistry、ModelRegistry、Download。其中VoiceAgent.getHandle()是async throws——它要先从四个组件 actor 收集句柄再组装复合句柄。其余PlatformAdapter、Environment、Events、Telemetry、Device、HTTP、Auth、ModelPaths、Connect等是普通命名空间无需 actor 隔离。CppBridge.shutdown()按固定顺序销毁 AI actorLLM → STT → TTS → VAD → VoiceAgent → VLM随后是 Telemetry 与 Events。这是因为销毁 actor 隔离组件需要await所以shutdown()是异步方法。通用句柄脚手架ComponentActor 与 ComponentVTableCppBridge.LLM/STT/TTS/VAD/VLM都基于泛型ComponentActorFoundation/Bridge/ComponentActor.swift它接受一个不可变的ComponentVTableFoundation/Bridge/ComponentVTable.swiftSendable结构体五个字段component、create、isLoaded、cleanup、destroy、可空的loadModel。五个静态实例把各模态绑定到对应 C 函数族实例组件C 函数绑定ComponentVTable.llm.llmrac_llm_component_*ComponentVTable.stt.sttrac_stt_component_*ComponentVTable.tts.ttsrac_tts_component_*loadModel槽映射到rac_tts_component_load_voiceComponentVTable.vad.vadrac_vad_component_*ComponentVTable.vlm.vlmrac_vlm_component_*loadModel的vision_projector_path传nilactor 隔离保证了句柄字段的单线程访问vtable的Sendable使 vtable 可以安全跨越并发边界。VoiceAgent不使用这套脚手架——它的句柄类型是rac_voice_agent_handle_t创建是异步复合的。C 到 Swift 互操作vtable 函数指针结构跨边界调用全部基于 vtable 化的函数指针结构vtable用途rac_platform_adapter_t文件操作、日志、Keychain、时钟、内存查询18 个函数指针槽 void* user_datarac_http_transport_ops_tURLSession HTTP 传输见下文rac_secure_storage_t认证令牌的安全存储rac_platform_llm/tts/diffusion_callbacks_tApple 平台服务rac_discovery_callbacks_t模型发现的文件系统回调异步 Swift 通过DispatchSemaphore或DispatchGroup.wait()桥接到同步的 C ABI。HTTP 传输URLSessionHttpTransportHttpTransport/URLSessionHttpTransport.swift 注册静态的rac_http_transport_ops_tvtable第 89 行nonisolated(unsafe) private static var opsC 的所有 HTTP 流量都经它流出request_send缓冲请求第 107 行绑定cRequestSend、request_stream逐块流式响应体第 107 行、request_resume带Range:头的可续传下载第 108 行。与它并列的HTTPClientAdapteractor别名HTTPService则独立封装rac_http_client_*处理 SDK 自身的请求认证、设备注册、遥测运行在并发DispatchQueue上默认超时 30 秒。后端模块注册模式每个后端都是一个薄public enum提供静态的register(priority:)/unregister()/autoRegister其工作就是调用rac_backend_*_register()。注册状态被 main-actor 隔离因此注册/注销不可能竞态。四个后端的注册面如下模块能力Framework caseLlamaCPPRuntimeLLM VLM统一 llama.cpp vtable.llamaCppONNXRuntimeEmbeddings Sherpa-ONNX 插件STT/TTS/VAD.onnx同时单独注册 SherpaMLXRuntimeLLM/VLM/embeddingsmlx-swift-lm STT/TTS/VADmlx-audio-swift.mlxNeuRTRuntimeApple Neural Engine 文本生成 CoreML 扩散.coreml——不是.neurt特别注意最后一个commons 将INFERENCE_FRAMEWORK_COREML映射到RAC_ENGINE_ID_NEURT但 Swift 端不存在.neurt这个 framework case。从 bindings/swift/Package.swift 可见ONNXRuntime目标同时也链接了RABackendNeuRTBinary——CoreML 插件一旦链接就以优先级 100 自动赢得 DIFFUSION 槽位。消费方在initialize之前按需注册例如LlamaCPP.register() // LLM VLM需要 RunAnywhereLlamaCPP 产品 ONNX.register() // STT TTS VAD需要 RunAnywhereONNX 产品 MLX.register() // MLX 各模态需要 RunAnywhereMLX 产品流式传输、事件与错误流式适配器单回调扇出多消费者LLMStreamAdapter/VoiceAgentStreamAdapter把每个句柄的单个 C 回调扇出到多个 SwiftAsyncStream消费者以 UUID 键控的 continuation 表由OSAllocatedUnfairLock守护事件用RALLMStreamEvent(serializedBytes:)/RAVoiceEvent(serializedBytes:)反序列化 proto 字节。事件总线EventBusPublic/Events/EventBus.swift 是 CombinePassthroughSubjectRASDKEvent, Never单例覆盖sdk、model、llm、stt、tts、voice、rag、storage、device、network、error类别经RunAnywhere.events访问。事件有两个来源C 原生订阅CppBridge.Events.subscribeSDKEvents闭包可在任意 C 线程回调Combine subject 内部锁保证并发 send 安全与 Swift 直接发布publish(_:)先走 C 路由返回 false 时直发 subject。deinit时若订阅 ID 非 0 会执行unsubscribeSDKEvents清理。错误模型SDKExceptionFoundation/Errors/SDKException.swift 包装 proto 生成的RASDKError构造时捕获Thread.callStackSymbols并提供类别工厂.stt(...)、.llm(...)、.network(...)。其中.cancelled/.streamCancelled被视为预期错误并抑制日志输出。类型体系proto 生成 别名proto 生成的RA*前缀类型Generated/下的.pb.swift是规范形态公开面用少量 typealias 去掉前缀如InferenceFramework RAInferenceFramework。扩展补充 C 桥接方法withCOptionsT(_:)、init(from cResult:)与Codable一致性——枚举的 Codable 编解码都经由wireString/from(wireString:)往返。模型管理、安全与日志模型路径与格式推断模型存放于Documents/RunAnywhere/Models/{framework}/{modelId}/。路径计算与文件扩展名 → 框架推断由 commons 侧完成经rac_model_paths_*.gguf/.bin→ LlamaCPP.onnx/.ort→ ONNX.mlmodelc/.mlpackage→ CoreML.jsonQNN 捆绑 → QHexRT。下载编排rac_http_download_execute运行在并发DispatchQueue上取消是通过OSAllocatedUnfairLockBool轮询由 C 进度回调读取。安全与设备身份KeychainManager使用kSecAttrAccessibleWhenUnlockedThisDeviceOnly不同步 iCloud服务名为com.runanywhere.sdk。DeviceIdentity.persistentUUID的解析链为Keychain →identifierForVendoriOS→ 新生成的 UUID。日志与脱敏SDKLogger包装Logging.shareddebug()是inlinable且在非DEBUG构建下为空操作。元数据键若包含key/secret/password/token/auth/credential会自动脱敏。C 日志经platformLogCallback到达解析结构化的message | keyvalue元数据格式。SwiftLint 强制的工程约定错误级规则同时阻塞 CI 与--strictpre-commit禁止print()/NSLog()/os_log()/debugPrint()/ 直接Logger(——一律走SDKLogger禁止as!、force_cast、force_try。警告级规则普通swiftlint不报但--strict会阻塞禁止Any/AnyObject/[String: Any]禁止隐式解包可选值IUOimport 排序TODO 必须引用 issue// TODO: #123 - description行宽150 警告 / 1500 错误文件 800 警告 / 1500 错误函数体 80 警告 / 300 错误圈复杂度 15 警告 / 30 错误。并发与命名永不使用NSLock——用OSAllocatedUnfairLock或 Swift actorC 回调 trampoline 是convention(c)无捕获的自由函数上下文用Unmanaged.passRetained/.release()平台实现类用显式前缀如AndroidTTSService每个领域一个CppBridge{Domain}.swiftPeriphery 扫描RunAnywhere、ONNXRuntime、LlamaCPPRuntime三个目标不含 MLX/NeuRT配置retain_public: true、retain_codable_properties: true见 .periphery.yml。关键文件地图文件用途Sources/RunAnywhere/Public/RunAnywhere.swiftSDK 入口点两阶段初始化Sources/RunAnywhere/Foundation/Bridge/CppBridge.swift桥接协调器init/shutdownSources/RunAnywhere/Foundation/Bridge/Extensions/CppBridge 领域扩展42 个文件Sources/RunAnywhere/Adapters/LLMStreamAdapter、VoiceAgentStreamAdapter、HTTPClientAdapterSources/RunAnywhere/HttpTransport/URLSessionHttpTransport.swiftHTTP vtable 实现Sources/RunAnywhere/Public/Extensions/公共 API 扩展每特性一个Sources/RunAnywhere/Generated/proto 生成的.pb.swift禁止手改Sources/RunAnywhere/CRACommons/RACommons.xcframework 的 C 头文件伞形模块Sources/{LlamaCPPRuntime,ONNXRuntime,MLXRuntime,NeuRTRuntime}/后端模块注册Sources/RunAnywhere/Features/平台服务音频采集/播放、系统 TTS、Foundation Models依赖清单包用途swift-crypto、swift-protobuf密码学操作proto 生成类型支持FilesJohnSundell文件系统抽象DeviceKit设备型号识别mlx-swift、mlx-swift-lmRunanywhereAI forkMLX 核心 LLM/VLM/embeddings——必须精确固定版本与 Generated/Versions.swift 中镜像的RAVersions保持一致当前为 mlx-swift 0.31.8、mlx-swift-lm 3.31.5见 Package.swiftmlx-audio-swiftRunanywhereAI forkMLX 的 STT/TTS/VAD/说话人分离exact 0.1.5swift-transformershuggingfaceMLX 分词器依赖版本策略采用.upToNextMinor而非开放的from:防止上游静默的大版本升级落入Package.resolvedMLX 相关包则用exact精确固定通过 scripts/release/sync-versions.sh 与根清单同步。能力说明与已知限制说话人分离RunAnywhere.diarization与语义分割RunAnywhere.segmentation各需对应后端已注册不存在唤醒词wake-word门面。三个规格字段因 commons 无对应发射器而读作缺省而非错误VoiceEvent无音频电平事件SegmentationOptions.includeDiagnosticImage在SegmentationResult上没有落点字段LoadOptions的contextLength、.threads、.useGpu会被记录日志后丢弃commons 的 load ABI 不携带它们。Connect可信局域网会话共享由 Public/Connect/ConnectSession.swift 实现服务类型为_runanywhere-connect._tcp第 549 行宿主导航权限归 commons 的platformPolicy()Swift 拥有 Bonjour 与分帧 TCP 适配器Host 仅限 macOSClient 为 iOS/iPadOS本版本无 TLS/配对仅限可信局域网。小结从构建命令到 vtable 级互操作Swift SDK 的全部设计都围绕一个原则Swift 是平台适配层C 是业务逻辑层。理解两阶段初始化同步 Phase 1 异步 Phase 2、CppBridge 的 actor/句柄模式、后端注册的优先级机制以及 SwiftLint 强制的并发与命名约定就能在 bindings/swift 内高效地排查问题、扩展平台能力并保持与跨 SDK v3 契约的一致。进一步深入可逐行对照 bindings/swift/ARCHITECTURE.md它是本 SDK 的权威架构事实来源。赞分享AI模型推理服务推理引擎本地部署多模态【免费下载链接】runanywhere-sdksProduction ready toolkit to run AI locally项目地址https://gitcode.com/gh_mirrors/ru/runanywhere-sdks点击查看免费下载相关推荐Joplin Data API 完全指南基于 Clipper 服务的 REST 接口开发实战Joplin Data API 完全指南基于 Clipper 服务的 REST 接口开发实战 Joplin 内置的 Data API 是围绕 ClipperAI模型推理服务推理引擎本地部署多模态RunAnywhere React Native SDK 架构解析基于 NitroModules 的端侧 AI 桥接与多后端引擎注册指南RunAnywhere React Native SDK 架构解析基于 NitroModules 的端侧 AI 桥接与多后端引擎注册指南 导读 本文面向在 RAI模型推理服务推理引擎本地部署多模态RunAnywhere Flutter SDK 开发指南从 FFI 桥接到多后端引擎的本地 AI 架构解析RunAnywhere Flutter SDK 开发指南从 FFI 桥接到多后端引擎的本地 AI 架构解析 本指南基于 bindings/flutter/CLAI模型推理服务推理引擎本地部署多模态上一篇figma-generate-library 技能实战20–100 次调用长链路构建的「错误恢复协议」全解析下一篇Skyvern 文档媒体 CDN 清单media-cdn-manifest解析内容寻址与不可变提交驱动的静态资源发布实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考