用 Python 调用 Foundation Models：fm CLI

过去一年，Apple 的端侧大语言模型一直藏在一堵墙后面：你只能从 Swift 访问它，而且只能在你用 Xcode 构建的 app 内部访问¹。macOS 27 推倒了这堵墙。Apple 现在随操作系统预装了一个名为 fm 的命令行工具，还提供了一个用 pip 安装的面向 Python 的 Foundation Models SDK¹。从前需要一个工程、一次构建以及编译后的 Swift 中一个 LanguageModelSession 才能调用的模型，如今只需一行 shell 命令即可作答，还能在 Jupyter notebook 中运行。Foundation Models Framework 团队的工程师 Eric Gourlaouen 在 WWDC26 session 334 中直白地概括了这一转变：“在此之前，这些模型只能从 Swift 代码中使用”¹。这次的变化并不是推出了新模型，而是同一个端侧模型突然可以从 app 之外编写脚本、实现自动化并进行评估，既不需要 API key，也没有云端费用¹。

太长不看

• macOS 27 预装了 fm，这是一个面向端侧 Apple Foundation Model 的命令行工具。它的子命令包括 respond（一次性提示并输出到 stdout）、chat（交互式会话）和 schema（定义结构化输出）¹。
• fm respond 提供了若干选项：选择模型（切换到 Private Cloud Compute）、输入图像，以及为结构化输出指定 schema；其余选项可用 --help 列出¹。
• Python SDK 从 Python 触达同一个端侧模型，要求 Python 3.10 或更高版本、已安装 Xcode、一台 Apple Silicon Mac，通过 pip 或其他包管理器安装¹。
• 该 SDK 与 Swift 框架如出一辙：一个可以调用 respond 的 LanguageModelSession、工具调用，以及通过传给 fm.respond 的生成参数的 fm.generable 装饰器实现的引导式生成¹。
• 这两个接口都默认使用始终可用的端侧模型，也可以选用更大的 Private Cloud Compute 模型——后者能力更强，但带有使用上限¹。
• 它的价值在于原型设计与自动化：既有按含义对文件排序的 shell 脚本，也有用 Pandas 和 matplotlib 对提示词变体进行打分的 Python 评估流水线¹。

fm 命令行工具

在 macOS 27 上打开终端，输入 fm，工具便会打印出它支持的命令¹。Apple 重点介绍了三个。fm respond 向模型发出提示并返回响应。fm chat 启动一次交互式对话。fm schema 为结构化输出创建 schema¹。最简单的用法正是 Eric 首先演示的那种：输入 fm respond，输入一个提示，按下回车，片刻之后便能在终端里读到模型的回答¹。

两个顶层命令沿着一条清晰的界线分工：探索与脚本化。fm chat 用于初步感受模型。你提一个问题，再追问一个，对话会保持连贯，并拥有自己的斜杠命令：/model 把对话切换到 Private Cloud Compute 模型，/save 保存对话以便日后继续¹。当你更希望得到一个可以捕获的内联响应时——比如在脚本中——就该改用 fm respond，它会把模型的输出写到 stdout¹。

各种选项都集中在 fm respond 上。Eric 明确点出了三个。一个模型选项让提示发往 Private Cloud Compute 模型，而非默认的端侧模型。一个图像选项把图像纳入提示。还有一个 schema 选项，与 fm schema object 配合，把输出约束为你定义的结构¹。他指出还有更多选项，并提示用帮助选项把它们全部列出¹。文字记录是按选项的作用而非确切的标志拼写来逐一称呼它们的（屏幕上展示的唯一字面形式是 fm schema object），因此下文凡是我描述某个选项之处，描述的都是已记录的行为，而非杜撰的标志字符串。

模型的选择是最关键的决定。默认情况下，fm 使用随 macOS 一同提供的端侧模型，它始终可用¹。你可以切换到运行在 Private Cloud Compute 上的 Apple Foundation Model，Eric 形容它“比端侧模型大得多，因此在复杂问题上表现更好”，代价是它带有使用上限¹。默认选项是恰当的起点：免费、本地、没有上限。只有当任务确实难到需要它时，你才升级到 Private Cloud Compute。

构建自动化脚本

文件排序的演示，是“为何 CLI 重要”这一论点最清晰的佐证。Eric 有一个工程文件夹，里面塞满了各种草稿版和定稿版的素材，他想要一个可重复运行的脚本，保留定稿、做好备份，并把草稿移动到归档磁盘¹。难点不在于移动文件，而在于当文件名一团乱时判断哪个文件是草稿。正如他所说，从脚本调用语言模型，能让它“区分草稿版与定稿版文件”，即便“文件名混乱、难以可预测地排序”也无妨¹。

这个范式可以推广到任何“对列表做判断”的自动化场景。脚本加载工作目录中的文件，然后通过 fm respond 提示模型，把该列表分成两组：定稿文件和草稿文件¹。为了让输出可用，脚本预先用 fm schema object 定义一个 schema，描述两个字段——一个定稿列表和一个草稿列表——并通过 schema 选项把该 schema 传给 fm respond¹。模型以 JSON 形式返回它的答案，脚本读取后，将定稿复制到备份，把草稿移动到归档¹。

结构化输出这一步是承重的关键。自由文本式的回答会迫使脚本去解析散文，而这正是每条与 LLM 对话的 shell 流水线中最脆弱的环节。通过用 fm schema object 声明 schema 并取回 JSON，脚本就得到了一份可以直接据以行动的契约¹。这一模式正是 Swift 开发者所熟知的引导式生成，在这里以 CLI 选项的形式呈现¹。任何以“对模型的判断结果做某种确定性操作”收尾的任务，要的正是这种范式：提示、schema、JSON、行动。

Python SDK

第二个接口面向的是另一个时刻里的另一类人。正如 Eric 所说：“如果你是机器学习工程师，你用 Python 可能比 Swift 更多”，而这个 SDK“让在 Python 代码中使用端侧模型变得轻而易举”¹。它的卖点立足于 Python 的生态：“Python 拥有丰富的机器学习与数据科学开源包生态”，这意味着你可以编写评估流水线，“借助这些包来量化你功能的质量”¹。

安装有四项要求，session 中都已说明。你需要 Python 3.10 或更高版本、已安装 Xcode、一台 Apple Silicon Mac，并通过 pip 或你选择的任意其他包管理器来安装该 SDK¹。对 Apple Silicon 和 Xcode 的要求恰好表明，这个包是对操作系统所运行的同一端侧模型的绑定，而非一个托管 API。

对于用过 Swift 框架²的人来说，这套 API 会感觉很熟悉，这是有意为之：“这些 API 和抽象会很快让你感到熟悉”¹。你通过创建一个 LanguageModelSession 来发起提示，可选地传入 instructions，然后用你的提示调用 session.respond；结果中便包含模型的输出¹。该 SDK 把框架的核心特性悉数搬了过来：文本与图像输入、流式响应、让模型能与你的代码交互的工具调用，以及用于结构化输出的引导式生成¹。

其中两个特性得到了具体演示。在工具调用方面，Eric 定义了一个模型可以调用的工具，用来获取用户最近的几笔订单，“这样它就能提供更个性化的信息”，与 Swift 框架的 Tool 协议是同一模式¹。在引导式生成方面，他用 fm.generable 装饰器定义了期望的输出结构——一个 ItemsSuggestion 对象，并将其作为生成参数传给 fm.respond¹。这个装饰器是 Swift 中 @Generable 宏的 Python 对应物，而生成参数则是你把想要的返回结构交给模型的方式。由于文字记录只是按作用和对象名展示它们，并未打印完整的类体，因此请把 ItemsSuggestion 当作该示例对一个由你自己定义的结构所取的名字。

评估流水线：使用 Python 的真正理由

这个案例研究正是 Python SDK 从一种便利升华为一种方法之处。Eric 当时在构建一个功能，用来预测用户想往购物车里添加什么，而他手上有三种不同的提示实现：一个极简版、一个更详尽版，以及一个把整套规则一一列明的细致版¹。每个提示工程师都会面对的问题是：到底哪个最好？而诚实的答案需要测量，而非凭感觉。

对此，Apple 明确表示 Swift 开发者有自己的答案。Evaluations 框架随 Xcode 27 一同提供，让创建评估、并跨迭代追踪功能准确率变得轻而易举¹。Python SDK 则是为那些生活在 notebook 里的数据科学家准备的并行路径。Eric 整套分析全部在 Jupyter 中完成¹。

这条流水线读起来就是一个对准端侧模型的标准 ML 评估循环。首先，他用一个大型服务器模型生成评估数据，为每条数据给出输入和一个期望输出¹。然后，对每一条输入，他用三种提示实现各自生成输出，并把输入与输出作为行存入一个 Pandas DataFrame¹。接着，由服务器模型支撑的评判函数依据他选定的标准为每个输出打分，这些指标再回写到 DataFrame 中¹。最后，matplotlib 把这些分数化为图表¹。

这些图表讲出了一个再怎么盯着提示也看不出的故事：细致版提示触发了很高的生成错误率，Eric 把这归因于触及了模型的最大上下文窗口大小；两个不那么详尽的提示往购物车里添加了多余的条目，而细致版添加得更少；细致版漏掉了更多期望中的条目；极简版则幻觉出的条目最多¹。每个提示都有不同的失败模式，而只有测量才能把它们浮现出来。这正是整套方法的论据所在。“有了 Python，我无需重建整个工程，就能直接在 notebook 里快速完成这些迭代，”Eric 说道¹。

何时该选用哪一个

从上述各项契约中，可以推出几条规则。

当 shell 脚本需要做一次判断时，选用 fm respond。 对杂乱的文件名排序、对一行输入进行分类、从非结构化文本中抽取一个字段。把它与 fm schema object 及 schema 选项搭配使用，让脚本据以行动的是 JSON，而不是去解析散文¹。

当你在探索而非编写脚本时，选用 fm chat。 这是初步感受模型如何处理你的提示的最快方式，配合 /model 升级到 Private Cloud Compute，配合 /save 保留会话¹。

当你想要测量、而不仅仅是调用时，选用 Python SDK。 一旦你手上不止一个提示，需要弄清哪个更好，那么 notebook 加 Pandas 加 matplotlib 的循环就是趁手的工具，因为端侧模型既免费又足够本地，足以跑完一整套评估集而不会产生账单¹。

默认使用端侧模型；要刻意地才升级到 Private Cloud Compute。 端侧模型始终可用且没有使用上限。Private Cloud Compute 更大，在复杂问题上更出色，但带有使用上限，所以把它留给那些配得上它的任务¹。

在这里做原型，到 Swift 里交付。 Eric 自己的说法是，你可以把这些工具“与你的 Xcode 工程并用，作为一种对提示进行原型设计和评估的方式”，也可以“单独使用它们，以新颖的方式调用模型”¹。购物 app 示例正是“在用 Swift 实现这些提示之前”，先在 Python 里对它们做原型¹。CLI 和 SDK 缩短了从想法到证据的循环；而功能最终落地的地方，仍然是 app。

常见问题

fm 命令行工具是什么？

fm 是一个随 macOS 27 预装的命令行工具，从终端 app 触达端侧 Apple Foundation Model¹。它的子命令包括用于提示模型并打印响应的 respond、用于开启交互式对话的 chat，以及用于定义结构化输出的 schema。运行它既不需要 API key，也没有云端费用，因为默认模型在端侧运行¹。

我该如何从 fm 取得结构化的 JSON？

用 fm schema object 定义一个 schema，然后通过 schema 选项把该 schema 传给 fm respond。模型会以匹配该 schema 的 JSON 形式返回它的答案，脚本可以直接据以行动，而无需解析自由文本¹。这一机制是框架引导式生成的 CLI 版本¹。

Foundation Models Python SDK 有哪些要求？

Python 3.10 或更高版本、已安装 Xcode，以及一台 Apple Silicon Mac¹。你通过 pip 或你选择的其他包管理器来安装它。对 Apple Silicon 和 Xcode 的要求，反映出该 SDK 绑定的是操作系统所运行的同一端侧模型，而不是去调用一个托管 API¹。

Python SDK 与 Swift 框架有何不同？

它是同一个模型，外加一套刻意保持熟悉的、换了语言的 API。你创建一个 LanguageModelSession，调用 respond，暴露工具，并通过作为生成参数传给 fm.respond 的 fm.generable 装饰器使用引导式生成¹。选择 Python 的理由在于生态：Pandas、matplotlib、Jupyter，以及数据科学技术栈的其余部分，能用来构建 Swift 难以如此直接触达的评估流水线¹。

我什么时候该用 Private Cloud Compute，而不是端侧模型？

fm 和 SDK 都默认使用端侧模型，它始终可用且没有使用上限¹。当一个问题复杂到需要更大的模型时，再通过 fm respond 的模型选项或 fm chat 的 /model 命令切换到 Private Cloud Compute，同时接受它带有使用上限这一点¹。

完整的 Apple 生态系列：Foundation Models 框架详解，介绍这些工具所效仿的 Swift 基础；iOS 27 工具调用控制，讲述模型如何使用工具；Foundation Models 智能体工作流，探讨端侧模型与更大模型之间的取舍；以及 Xcode 27 的编码智能体，呈现重度智能体工作流在 IDE 内的一面。中心枢纽位于 Apple 生态系列。若想了解用智能体构建 iOS 的更宏观图景，请参阅 iOS 智能体开发指南。