Foundation Lab：把 Apple 端侧模型实验做成可复现的工程记录

Library、Playground、Runs 之间的数据流

把 Foundation Models 接进 App 本身不难，难的是三个月后回答一个问题：当时那版提示词配了哪些工具、采样参数是多少、模型输出了什么。Foundation Lab 把这件事拆成三个入口来管。Library 是入口清单，README 说这里放着 18 个可编辑 recipe、14 个 guided lab、三个 workshop、保存过的实验和一个 workspace。Playground 是编辑与运行的地方，提示词、instructions、模型与工具配置、流式响应、语音输入都在这里，改完能直接跑，也能导出 Swift。Runs 是记录层，README 列出的字段包括持久化的运行状态、配置、transcript 事件、工具调用、耗时和 token 用量。

它面向的是已经在写 SwiftUI 和 Foundation Models 代码的人，不是想找一个聊天客户端的人。Library 里的条目会标明自己怎么打开：Recipe 进 Playground，可编辑可保存；Guided Lab 用专门的界面演示某一个 API；Workshop 把相关的 schema、语言或 Xcode 27 示例归在一起，不额外占用顶层入口；Workspace 打开像 Adapter Comparison 这样的独立工具。这套分类本身就是它的产品判断：实验不是一种东西，需要不同粒度的界面。

跑起来之前，先确认你的 Xcode 能开出哪些 lab

从仓库结构看，代码被切成两层。顶层的 Foundation Lab 目录是可运行的原生 App，包含 Library、Playground、Runs、guided labs 和 workspaces；FoundationLabCore 是独立于 UI 的一层，README 描述它承载请求、结果、use case、provider 和实验模型。这个切分意味着实验配置不是绑死在某个 SwiftUI 视图里的状态，而是可以被非 UI 代码构造和消费的对象。对想把这套东西接进自己工程的人来说，这一层比界面更有参考价值。

工具走的是另一条路径。九个内置工具 recipe 共用 FoundationModelsTools 这个 package，覆盖天气（Open-Meteo）、无密钥的 Search1 网页搜索、通讯录、日历、提醒事项、位置与地点搜索、经授权的 HealthKit 数据、Apple Music 和网页元数据。README 特别说明，可能修改用户数据的工具必须经过 App 自己的确认流程。这是设计上的硬约束，不是可选项：工具调用链里插入了一个人工确认节点，因此这类 recipe 无法被改造成完全无人值守的批处理。

Runs 这一侧记录的是 transcript 事件、工具调用、耗时和 token 用量。README 没有给出这些字段的具体结构，也没有说明持久化格式，所以如果你打算把 Runs 的数据接进自己的分析管线，需要先读源码确认。

afm 已经搬走，fmas 还留在仓库里

README 给出的起步路径很直接。克隆仓库，进目录，打开工程：

git clone https://github.com/rudrankriyam/Foundation-Models-Framework-Lab.git cd Foundation-Models-Framework-Lab open FoundationLab.xcodeproj

命令行构建给了两条，分别针对 macOS 和 iOS 模拟器，都带 CODE_SIGNING_ALLOWED=NO：

xcodebuild -project FoundationLab.xcodeproj -scheme 'Foundation Lab' -destination 'generic/platform=macOS' CODE_SIGNING_ALLOWED=NO build

xcodebuild -project FoundationLab.xcodeproj -scheme 'Foundation Lab' -destination 'generic/platform=iOS Simulator' CODE_SIGNING_ALLOWED=NO build

这里最容易被忽略的是版本门槛。README 要求 iOS 26.0+ 或 macOS 26.0+、Apple Silicon、开启 Apple Intelligence，Xcode 侧则同时支持 26.6 和 27。随 OS 27 SDK 引入的 API 做了编译器和可用性双重门控，所以用 Xcode 26.6 构建时核心 App 仍然可用，只有换到 Xcode 27 才会露出最新的那批 lab，包括 PrivateCloudComputeLanguageModel、共享 LanguageModel 执行、图像附件与引用、显式工具调用模式、动态 profile 与推理控制、transcript 检查与历史变换、上下文预算可视化，以及自定义模型执行器（含一个视频能力的 provider bridge）。

真机是另一道门槛。README 明确写实时模型执行需要兼容的物理设备，模拟器构建只用于编译和界面验证。另外 Tools/ImageInputProbe 这个图像输入探针，按 README 的说法是用来测量当前 SDK 实际可用的解码缓冲区边界的，属于那种必须自己跑一遍才有答案的测量，README 没有给出任何数值。

结构化输出与 RAG 是两条独立的能力线

命令行这块要分清楚。afm CLI 现在从独立仓库 rudrankriyam/Foundation-Models-Framework-CLI 发布，用的是公开的 FoundationModelsKit package，CLI 的发版节奏和 App 解耦。安装方式是 brew tap rudrankriyam/tap 之后 brew install afm，源码、文档、发版自动化和 server 模式的实现都在那个仓库里，不在本仓库。

留在本仓库的是 Adapter 训练与导出，走配套的 fmas CLI：

python3.11 -m venv .venv-fmas source .venv-fmas/bin/activate python -m pip install -e Tools/AdapterStudio fmas init fmas setup fmas train-adapter --help fmas export --help

README 把完整流程指向 Tools/AdapterStudio。注意这里出现了 Python 3.11 和 venv，也就是说这个仓库不是纯 Swift 工程，适配器训练那条线需要单独准备 Python 环境。App 侧的 Adapter Comparison 只在 macOS 上可用，导入 .fmadapter 包后用同一个提示词分别跑全新基座模型和适配器会话，界面同时显示两路流，并给出 time-to-first-token 和总耗时两项诊断指标。README 用 diagnostic 形容这两个数字，没有给基准值，也没有说它们是否稳定到可以做回归比较。

什么时候它不合适：真机、工具白名单与版本门控

结构化输出这条线覆盖 @Generable 模型和 @Guide 约束，示例包括动态 schema、嵌套对象、union、表单和发票抽取。多语言部分提供多语言会话和受支持语言的检查。RAG 部分做文档索引与语义检索，README 点名用了 LumoKit 和 VecturaKit 两个库；HealthKit 那边有一个仪表盘和只基于已授权健康数据的对话。

这里有一个值得直接指出的取舍。HealthKit 对话被限定在已授权数据范围内，这是一个安全边界，同时也意味着它的回答质量上限由授权范围决定，而不是由模型能力决定。想让这类会话给出更完整的答案，唯一的办法是扩大授权，而授权范围的扩大又会反过来影响用户是否愿意继续用。这个矛盾在 README 里没有被讨论，属于文档偏薄的地方。

RAG 同样如此。README 说明了用哪两个库做索引和检索，但没有给出分块策略、向量维度、检索条数这些会直接决定效果的参数。要评估这条线是否适合自己的数据，只能进代码看。

和 FoundationModelsBench 的分工：工作台与评测集不是一回事

第一个明确的失败场景是没有物理设备。README 说得很清楚，实时模型执行需要兼容的物理设备，模拟器只能做编译和界面验证。如果你的验证流程跑在 CI 上、或者团队里没有 Apple Silicon 真机，这个 App 能给你的只有编译通过这一条信息，而编译通过恰好是最不需要工作台来回答的问题。这种情况该用的是独立发布的 afm CLI，它至少是脚本化的。

第二个是工具白名单。九个内置工具 recipe 都基于同一个 FoundationModelsTools package，天气走 Open-Meteo，搜索走无密钥的 Search1，其余是系统数据源。如果你需要的是自有 API 或内部服务，这些 recipe 只能当模板读，不能当现成能力用。而且会改用户数据的工具必须走 App 自己的确认流程，这条约束让自动化场景基本出局。

第三个是版本门控。Xcode 27 才暴露的那批 lab 覆盖了 PrivateCloudComputeLanguageModel、图像附件、显式工具调用模式、上下文预算可视化等。用 Xcode 26.6 构建时这些内容看不到，README 的说法是核心 App 仍然可用。所以同一份代码在不同机器上能做的实验是不一样的，团队内部交流实验结论时需要把 Xcode 版本一起说清楚，否则会对不上。

最后是平台差异。Adapter Comparison 只在 macOS 上提供，iOS 侧没有对应的对比入口。做适配器评估的人需要一台 Mac。

维护成本、许可与上手前该验证的三件事

README 的仓库地图里列了一个外部项目 rudrankriyam/FoundationModelsBench，描述是质量、安全、工具使用、端侧等方向的评测。把它和 Foundation Lab 放在一起看，两者的差别不在功能多少，而在回答的问题不同。

Foundation Lab 是交互式工作台。你在 Playground 里改一个参数，立刻看输出，然后在 Runs 里翻这次运行的 transcript 和 token 用量，必要时导出 Swift 把配置带到别处。它的单位是「一次实验」，靠的是人对输出的判断。

FoundationModelsBench 走的是评测集路线，用固定的题目和指标去衡量模型在质量、安全、工具使用上的表现。它的单位是「一组样本上的分数」，靠的是统计而不是肉眼。

这个区别决定了它们各自的盲区。工作台跑不出可比较的分数，因为每次运行的配置都可能不同，Runs 里记录的耗时也只是单次观测；评测集则很难告诉你某个具体提示词为什么在某次交互里失效。如果你的问题是「这个改动让效果变好了还是变坏了」，工作台帮不上忙；如果你的问题是「这条提示词为什么在这台设备上返回了空结果」，评测集的平均分也帮不上忙。README 里 Adapter Comparison 的 time-to-first-token 和总耗时被明确称为诊断指标，这个措辞是准确的，别把它当成绩效基准。

谁该用，谁该绕开

仓库采用 MIT 许可。这意味着你可以把代码拿进自己的工程、修改、再分发，MIT 的常见义务是保留版权与许可声明；这不是法律意见，涉及具体产品时请自行确认合规要求。

维护成本主要来自三处外部依赖，而不是 App 本身。FoundationModelsKit 是外部 package，afm CLI 已经搬到独立仓库并独立发版，适配器训练链依赖 Python 3.11 加 Tools/AdapterStudio。也就是说这个仓库的版本号（最近三个 release 是 1.0.0、1.1.0、1.2.0）并不覆盖 CLI 的版本，两者会各自演进。升级 App 时，需要同时确认 FoundationModelsKit 和 afm 的版本是否还对得上。

上手前建议按顺序验证三件事。第一，用你手上的 Xcode 构建一次，看 Library 里实际出现了哪些 lab，尤其是 Xcode 27 专属的那批是否可见。第二，确认你要用的工具是否在那九个 recipe 之内，如果不在，评估自己写工具的成本。第三，如果要做适配器对比，确认手上有 macOS 设备和可用的 .fmadapter 包。这三件事任何一件不成立，这个工作台对你的价值都会明显缩水。

编辑结论

已经在做 Apple Intelligence 相关功能、并且手上有 Apple Silicon 真机的团队，可以把它当成一套可复现的实验记录工具：先用 Library 里 18 个可编辑 recipe 跑通流程，再用 Playground 改配置、用 Runs 对照 transcript 与 token 用量。没有真机、或者只需要在 CI 上做批量调用的人不要选它，README 明确写了实时模型执行需要兼容的物理设备，模拟器只能验证编译和界面；这种需求应该去看独立发布的 afm CLI。上手前先确认三件事：你的 Xcode 版本能开出哪些 lab（OS 27 SDK 的 API 是编译器与可用性双重门控的）、你要用的工具是否落在那九个内置 recipe 里、以及 .fmadapter 的对比是否必须依赖 macOS 上的 Adapter Comparison。

官方来源

1. Issues
2. License: MIT
3. README
4. Releases
5. rudrankriyam/Foundation-Models-Framework-Lab on GitHub