1. 背景 (Motivation)
随着端侧 AI 算力的提升，ELS (ETOS LLM Studio) 计划在现有云端 API 调用的基础上，引入完全离线的本地模型推理能力。本方案拟在 ELS 的 Shared Framework 层集成 llama.cpp，旨在为 iOS 提供满血的端侧推理链路，并在极其受限的 watchOS 环境下打通底层运行环境。
核心工程理念：ELS 仅负责提供底层运行环境与跨平台脚手架。关于模型的选取、量化版本以及上下文（KV Cache）大小等限制，完全交由用户通过现有 UI 设置自行调配。
2. 工程架构与集成方案 (Architecture & Integration)
为维持 ELS 现有的 MVVM 架构整洁，避免源码污染主工程，设计如下集成链路：
- Git Submodule 引入：通过 Fork 上游仓库，以
git submodule 的形式将代码挂载至根目录 Dependencies/llama.cpp。确保与上游代码平滑同步 (fetch/rebase)，且无缝兼容 Xcode Cloud 的自动化构建流。
- Shared Framework 封装：将纯 C/C++ 源文件隔离在 Shared 模块中。使用 Umbrella Header 桥接 C 语言接口，向上暴露纯 Swift 的
LocalLLMEngine 引擎类。
- UI 完全解耦：展现层仅负责传递模型文件的本地路径（iOS 通过文档选择器获取，watchOS 通过网络下载至沙盒），核心计算逻辑对平台 UI 完全透明。
3. iOS 端：Metal 硬件加速支持
在 iOS/macOS 环境下，目标是全面释放 Apple A/M 系列芯片的统一内存架构优势：
- 预处理宏：在 iOS Target 的 Build Settings 中启用
GGML_USE_METAL=1。
- 编译管线：引入
ggml-metal.metal 以生成 .metallib 二进制库，实现矩阵乘法等核心算子的 GPU 硬件加速。
- 系统权限：配置
Increased Memory Limit 等授权，为用户自行挂载大参数模型提供物理内存空间支持。
4. watchOS 端：arm64_32 ABI 适配与底层裁剪
watchOS 平台（以 Apple Watch S8 为例）的集成重点在于绕过编译期异常及底层物理限制：
- 编译期裁剪：通过
<TargetConditionals.h> 与 TARGET_OS_WATCH 宏，物理切除 watchOS 不支持的 Metal 逻辑，平滑回退至纯 CPU (ARM NEON) 计算。
arm64_32 指针缝合：watchOS 特有的 ILP32 数据模型会导致 32 位指针在转换为 uint64_t 时触发编译报错。拟在 Submodule 仓库中，通过 #if defined(__aarch64__) && defined(__ILP32__) 宏精准定位该架构，将所有引发精度丢失的地址强转替换为标准自适应整形 uintptr_t。- 运行期行为：引擎不预设内存天花板，相关 Context 限制读取用户在 ELS 中的配置。若用户加载的模型体积或上下文超出 watchOS 物理极限引发 Jetsam 机制强杀 (OOM)，视为预期内的系统行为。
1. 背景 (Motivation)
随着端侧 AI 算力的提升，ELS (ETOS LLM Studio) 计划在现有云端 API 调用的基础上，引入完全离线的本地模型推理能力。本方案拟在 ELS 的 Shared Framework 层集成
llama.cpp，旨在为 iOS 提供满血的端侧推理链路，并在极其受限的 watchOS 环境下打通底层运行环境。核心工程理念：ELS 仅负责提供底层运行环境与跨平台脚手架。关于模型的选取、量化版本以及上下文（KV Cache）大小等限制，完全交由用户通过现有 UI 设置自行调配。
2. 工程架构与集成方案 (Architecture & Integration)
为维持 ELS 现有的 MVVM 架构整洁，避免源码污染主工程，设计如下集成链路：
git submodule的形式将代码挂载至根目录Dependencies/llama.cpp。确保与上游代码平滑同步 (fetch/rebase)，且无缝兼容 Xcode Cloud 的自动化构建流。LocalLLMEngine引擎类。3. iOS 端：Metal 硬件加速支持
在 iOS/macOS 环境下，目标是全面释放 Apple A/M 系列芯片的统一内存架构优势：
GGML_USE_METAL=1。ggml-metal.metal以生成.metallib二进制库，实现矩阵乘法等核心算子的 GPU 硬件加速。Increased Memory Limit等授权，为用户自行挂载大参数模型提供物理内存空间支持。4. watchOS 端：
arm64_32ABI 适配与底层裁剪watchOS 平台（以 Apple Watch S8 为例）的集成重点在于绕过编译期异常及底层物理限制：
<TargetConditionals.h>与TARGET_OS_WATCH宏，物理切除 watchOS 不支持的 Metal 逻辑，平滑回退至纯 CPU (ARM NEON) 计算。arm64_32指针缝合：watchOS 特有的 ILP32 数据模型会导致 32 位指针在转换为uint64_t时触发编译报错。拟在 Submodule 仓库中，通过#if defined(__aarch64__) && defined(__ILP32__)宏精准定位该架构，将所有引发精度丢失的地址强转替换为标准自适应整形uintptr_t。